Arduino UNO Q Setup¶

Use this guide when you want the Linux side of an Arduino UNO Q to run the IINTS digital patient runtime and the STM32 side to act as a simple LED / buzzer bridge.

This page is intentionally simple. If you only want one recommended path, use the method below exactly as written.

Recommended Method¶

For Arduino UNO Q, the easiest method is:

install the SDK from the repository source tree
generate the UNO Q scaffold
start the Linux-side runtime
flash the STM32 bridge sketch
test the bridge from the CLI
run the bridge forwarder from the CLI

Why this is the recommended method:

it matches the current docs exactly
it avoids CLI version mismatch
it guarantees the iints edge ... commands are present

If You See `No such command 'edge'`¶

If this happens:

Error: No such command 'edge'

your installed iints CLI is older than the current docs.

Do this instead:

use the source-install method below
do not continue with cd iints_uno_q_demo until iints edge setup ... succeeds

Copy-Paste Method¶

Run this from the SDK repository root, the folder that contains pyproject.toml:

cd /path/to/IINTS-SDK
python3 -m venv .venv_unoq
source .venv_unoq/bin/activate
python -m pip install -U pip
python -m pip install -U -e ".[edge,mdmp]"
hash -r

iints edge setup --output-dir iints_uno_q_demo --board uno_q
cd iints_uno_q_demo
iints edge up --project-dir .

In a second terminal, run:

cd /path/to/IINTS-SDK/iints_uno_q_demo
source ../.venv_unoq/bin/activate
iints edge status --project-dir .
iints edge bridge-test --port /dev/ttyACM0

Success looks like:

daemon_status is running
iints edge up --project-dir . works
uno_q_bridge/iints_supervisor_bridge.ino exists
the kiosk is available at http://127.0.0.1:8765/kiosk

Security defaults:

the Linux-side dashboard stays on 127.0.0.1 unless you opt into remote binding
remote binding now requires both --allow-remote-api and a token source
bridge flashing and bridge testing do not require remote API exposure

Quick Path¶

If you want the fastest possible route to a working baseline, follow these four blocks first.

Step 1 - Install IINTS on the Linux side

Recommended for UNO Q: install from the SDK repository root, not from an older global install.

cd /path/to/IINTS-SDK
python3 -m venv .venv_unoq
source .venv_unoq/bin/activate
python -m pip install -U pip
python -m pip install -U -e ".[edge,mdmp]"
hash -r

Success looks like:

iints doctor --smoke-run works
python -c "import iints; print(iints.__version__)" prints a version
iints edge doctor --board uno_q explains the next fixes in plain language instead of leaving you guessing

Before you create the project, run:

iints edge doctor --board uno_q

Step 2 - Generate the UNO Q project

Run:

iints edge setup --output-dir iints_uno_q_demo --board uno_q
cd iints_uno_q_demo

Success looks like:

run_edge_patient.sh exists
uno_q_bridge/iints_supervisor_bridge.ino exists
EDGE_SETUP.md exists

Step 3 - Start the Linux runtime

Run:

iints edge up --project-dir .
iints edge status --project-dir .

Success looks like:

daemon_status is running
the kiosk opens at http://127.0.0.1:8765/kiosk
you can keep the dashboard local and still present it through Raspberry Pi Connect or another local screen-sharing path

Step 4 - Flash and test the STM32 bridge

Flash the sketch with Arduino IDE or:

iints edge bridge-flash --project-dir . --port /dev/ttyACM0 --fqbn <your-board-fqbn>

Then test it with:

iints edge bridge-test --port /dev/ttyACM0

Or open Serial Monitor at 115200 baud and send:

OK
OVERRIDE
CRITICAL

Success looks like:

OK turns the built-in status LED on
OVERRIDE turns the red LED on
CRITICAL turns the red LED on and chirps the buzzer

Once those four blocks work, you have a real working UNO Q baseline.

What Works Today¶

The current UNO Q path gives you:

a working Linux-side IINTS edge runtime
a generated STM32 sketch scaffold for the bridge side
a simple serial protocol for bridge testing
a kiosk dashboard and persistent runtime workspace

Important:

the Linux runtime works out of the box
the STM32 sketch works as a serial target out of the box
the Linux runtime can forward status to the STM32 side with iints edge bridge-run

So the first success target is:

get the Linux runtime running
flash the STM32 bridge sketch
verify the bridge from the CLI
run the live bridge forwarder

That gives you a solid working baseline on UNO Q.

Before You Start¶

You need:

an Arduino UNO Q with access to both the Linux side and the STM32 side
Python 3.10+ on the Linux side
Arduino IDE for flashing the STM32 sketch
a USB cable and a serial port that reaches the STM32 side

Optional hardware for the bridge demo:

status LED: built-in LED_BUILTIN
red LED on pin 6
buzzer on pin 9

Notes:

on some UNO Q boards the built-in status LED appears blue instead of green
the bridge latches the last state it received, so a bridge test that ends on CRITICAL can leave LEDs lit until you send OK

If you do not wire an external red LED or buzzer yet, you can still complete the setup and verify the sketch through the built-in LED plus serial output.

Step 1: Install The Edge Runtime On The Linux Side¶

For UNO Q, the safest method is to install from the SDK repository root so the CLI matches the docs.

Open a terminal on the Linux side of the UNO Q and run:

cd /path/to/IINTS-SDK
python3 -m venv .venv_unoq
source .venv_unoq/bin/activate
python -m pip install -U pip
python -m pip install -U -e ".[edge,mdmp]"
hash -r

Verify the install:

iints doctor --smoke-run
python -c "import iints; print(iints.__version__, iints.__file__)"
iints --help

If that succeeds, the SDK is installed correctly on the Linux side.

If iints edge is still missing, run:

which -a iints

and confirm that your shell is using the iints binary from the virtual environment you just activated.

Step 2: Generate A UNO Q Edge Project¶

Create the edge scaffold:

iints edge setup --output-dir iints_uno_q_demo --board uno_q
cd iints_uno_q_demo

This creates:

algorithms/example_algorithm.py
patient_runtime/patient_runtime_config.json
run_edge_patient.sh
launch_kiosk.sh
update_edge_runtime.sh
EDGE_SETUP.md
uno_q_bridge/iints_supervisor_bridge.ino
uno_q_bridge/README.md
uno_q_bridge/bridge_protocol.txt

If you only want the MCU bridge scaffold without the full edge project, you can also run:

iints edge hardware-bridge --board uno_q --output-dir uno_q_bridge

Linux Runtime API Security¶

For most UNO Q setups, keep the Linux-side dashboard local:

use the default 127.0.0.1
open the browser on the device itself
avoid exposing the dashboard port to the LAN unless you truly need it

If you do need a remote browser or tool to reach the Linux-side dashboard directly, start it with an explicit token:

export IINTS_PATIENT_API_TOKEN="replace-this-with-a-random-secret"

iints patient start \
  --algo algorithms/example_algorithm.py \
  --workspace patient_runtime \
  --scenario-profile normal_day \
  --mode demo-time \
  --speed 60x \
  --api-host 0.0.0.0 \
  --allow-remote-api \
  --api-token-env IINTS_PATIENT_API_TOKEN

When token protection is enabled:

browser access can use http://<host>:8765/kiosk?token=<your-token>
CLI and scripted access should prefer Authorization: Bearer <token>
control endpoints still require the extra X-IINTS-Control: 1 header

Important:

this protection is for the Linux dashboard/API only
the STM32 serial bridge still uses the separate UNO Q bridge protocol

Step 3: Start The Linux-Side Digital Patient¶

From inside iints_uno_q_demo, start the runtime:

iints edge up --project-dir .

In a second terminal, check status:

iints edge status --project-dir .

What you want to see:

daemon_status shows running
a dashboard URL is printed
the workspace contains patient_state.db

If that works, the Linux side is ready.

Step 4: Open The Kiosk Dashboard¶

Launch the local kiosk view:

iints edge kiosk --project-dir .

Or open the dashboard manually:

http://127.0.0.1:8765/kiosk

At this point you should have a working UNO Q Linux-side demo.

Step 5: Flash The STM32 Bridge Sketch¶

CLI method with Arduino CLI:

iints edge bridge-flash --project-dir . --port /dev/ttyACM0 --fqbn <your-board-fqbn>

If you prefer Arduino IDE, open this file:

iints_uno_q_demo/uno_q_bridge/iints_supervisor_bridge.ino

Then:

Select the correct Arduino UNO Q board target in Arduino IDE.
Select the correct serial port.
Upload the sketch to the STM32 side.
Open Serial Monitor.
Set the baud rate to 115200.
Set line ending to Newline.

If the upload worked, you should see:

IINTS UNO Q supervisor bridge ready

Step 6: Verify The Bridge¶

CLI method:

iints edge bridge-test --port /dev/ttyACM0

Manual method:

Send these commands one by one:

OK
OVERRIDE
CRITICAL

Expected behavior:

OK
built-in status LED on
OVERRIDE
red LED on
CRITICAL
red LED on
buzzer chirps

The sketch also prints confirmations such as:

STATE=OK
STATE=OVERRIDE
STATE=CRITICAL

The CLI bridge test now waits for the USB serial reset cycle and accepts the sketch acknowledgements after startup. If the response column still shows - but the LEDs react, the board is receiving commands and the remaining issue is the serial echo path, not the runtime or flashing path.

If this works, the STM32 side is ready.

Step 7: Run The Live Bridge Forwarder¶

Start the live status forwarder:

iints edge bridge-run --project-dir . --port /dev/ttyACM0

This command watches the runtime status and sends:

OK
OVERRIDE
CRITICAL

to the STM32 side automatically.

Step 8: Day-To-Day Commands On The Linux Side¶

Useful commands once the runtime is running:

iints edge status --project-dir .
iints edge kiosk --project-dir .
iints edge reset --project-dir .
iints edge stop --project-dir .
iints edge service --project-dir .
iints edge bundle --project-dir . --output edge_bundle.zip

Use these to:

check whether the runtime is alive
reopen the kiosk view
reset to a known demo state
export systemd service notes
export the runtime bundle back to a workstation

Step 9: Optional Auto-Start¶

If the Linux side should come back after reboot:

iints edge service --project-dir .

Then install the generated service:

sudo cp patient_runtime/iints-digital-patient.service /etc/systemd/system/iints-digital-patient.service
sudo systemctl daemon-reload
sudo systemctl enable iints-digital-patient.service
sudo systemctl start iints-digital-patient.service
systemctl status iints-digital-patient.service

Troubleshooting¶

`iints` command not found¶

Activate the virtual environment again:

source .venv/bin/activate

The runtime does not start¶

Check the workspace:

iints edge status --project-dir .
ls patient_runtime

You should see patient_state.db after a successful start.

The dashboard does not open¶

Open the URL manually:

http://127.0.0.1:8765/dashboard

If that works in the browser but not through iints edge kiosk --project-dir ., the runtime is fine and the issue is only the browser launcher.

Or use:

iints edge kiosk --project-dir .

The STM32 sketch uploads, but the LED test does nothing¶

Check these items:

Serial Monitor baud rate is 115200
line ending is Newline
you are sending exactly OK, OVERRIDE, or CRITICAL
your red LED and buzzer wiring matches pin 6 and pin 9
if you use the CLI test, check that the serial port is correct

`iints edge bridge-flash` fails¶

Check these items:

arduino-cli is installed
the board package for UNO Q is installed in Arduino CLI
you passed the correct --fqbn
you passed the correct --port

I only want a stable UNO Q demo quickly¶

Use this order:

get the Linux kiosk working with iints edge up --project-dir .
flash the STM32 sketch
run iints edge bridge-test --port ...
run iints edge bridge-run --project-dir . --port ...

That is the fastest path to a dependable Maker Faire or classroom demo.

Arduino UNO Q Setup¶

Recommended Method¶

If You See No such command 'edge'¶

Copy-Paste Method¶

Quick Path¶

What Works Today¶

Before You Start¶

Step 1: Install The Edge Runtime On The Linux Side¶

Step 2: Generate A UNO Q Edge Project¶

Linux Runtime API Security¶

Step 3: Start The Linux-Side Digital Patient¶

Step 4: Open The Kiosk Dashboard¶

Step 5: Flash The STM32 Bridge Sketch¶

Step 6: Verify The Bridge¶

Step 7: Run The Live Bridge Forwarder¶

Step 8: Day-To-Day Commands On The Linux Side¶

Step 9: Optional Auto-Start¶

Troubleshooting¶

iints command not found¶

The runtime does not start¶

The dashboard does not open¶

The STM32 sketch uploads, but the LED test does nothing¶

iints edge bridge-flash fails¶

I only want a stable UNO Q demo quickly¶

If You See `No such command 'edge'`¶

`iints` command not found¶

`iints edge bridge-flash` fails¶