apress/deploy/uno-q/skills/arduino-uno-q/references/02-setup-and-os.md

UNO Q — Setup, Operating System & App Lab

The operating systems, restated

• MPU: full Debian Linux with a desktop. It has a package manager (apt), systemd services, users/permissions, a filesystem, networking — treat it like any Debian machine. Arduino App Lab is pre-installed.
• MCU: Zephyr OS running your Arduino sketch. You rarely interact with Zephyr directly; you write ordinary Arduino code and App Lab / the IDE handles the rest.

Two development environments

Arduino App Lab (primary)

• Pre-installed on the board. Also installable on your PC (Windows/macOS/Linux) from the Arduino software page for Network-Mode development.
• An App = a Python program (runs on Linux/MPU) + an Arduino sketch (runs on MCU) + Bricks.
• Bricks are reusable, pre-packaged building blocks (e.g. vision, audio, I/O helpers) you compose into an App — this is how App Lab gets you to AI/vision features quickly without writing everything from scratch.
• Runs two ways:
  • Single-Board-Computer (SBC) mode — App Lab runs on the board with a monitor/keyboard/mouse attached via the dongle.
  • Network Mode — App Lab runs on your PC and talks to the board over the LAN (see remote-access reference).

Arduino IDE (beta) — MCU only

• Programs only the STM32 microcontroller. It cannot program the Qualcomm processor. For anything touching Linux/Python, use App Lab.
• Install the core: Tools → Board → Boards Manager → search "UNO Q" → install "Arduino UNO Q Zephyr Core."
• If it doesn't appear, add this to File → Preferences → Additional Boards Manager URLs:

  https://downloads.arduino.cc/packages/package_zephyr_index.json
  

• Then select Tools → Board → Arduino UNO Q Board, pick the Port, and upload as usual. The classic File → Examples → 01.Basics → Blink works (LED_BUILTIN = the red channel of the built-in RGB LED).

First boot as a Single-Board Computer

1. Plug the USB-C dongle into the board's USB-C port.
2. Keyboard + mouse into the dongle's USB-A ports; monitor into the dongle's HDMI; power supply (+5 VDC / 3 A min) into the dongle.
3. It boots automatically. At the Debian login the default user is arduino; you set a password.
4. App Lab's first-run wizard walks through keyboard layout, board name, Wi-Fi, and login credentials. The board name becomes the mDNS hostname (<name>.local) used for Network Mode and SSH.

The preloaded desktop includes Chromium, a file manager, a terminal, Vim, and media playback. Install more software the normal Debian way, e.g. sudo apt install vlc.

Linux host setup (REQUIRED when driving the board from a Linux PC)

On a Linux PC, App Lab talks to the board over USB and needs udev permissions, or it fails silently and flashing throws permission errors. The board presents two USB identities:

• Operating mode: VID 2341, PID 0078
• Emergency Download (EDL) mode: VID 05c6, PID 9008

Install the udev rules (canonical one-liner)

echo \
'# Operating mode
SUBSYSTEMS=="usb", ATTRS{idVendor}=="2341", ATTRS{idProduct}=="0078", MODE="0660", TAG+="uaccess"
# EDL mode
SUBSYSTEMS=="usb", ATTRS{idVendor}=="05c6", ATTRS{idProduct}=="9008", MODE="0660", TAG+="uaccess"' \
| sudo tee "/etc/udev/rules.d/60-Arduino-UNO-Q.rules" \
&& sudo udevadm control --reload-rules \
&& sudo udevadm trigger

MODE="0660" sets the device-file permissions; TAG+="uaccess" grants the logged-in user access via systemd-logind.

Verify

cat /etc/udev/rules.d/60-Arduino-UNO-Q.rules
lsusb | grep -E "2341:0078|05c6:9008"
adb devices          # board should be listed
adb shell            # drops you into a shell on the board

Apply

Disconnect and reconnect the board (wait a few seconds), then restart App Lab so it re-reads permissions.

Alternative: official post-install script

From the ArduinoCore-zephyr repo — creates /etc/udev/rules.d/60-arduino-zephyr.rules:

cd ~/Downloads
wget https://raw.githubusercontent.com/arduino/ArduinoCore-zephyr/main/post_install.sh
chmod +x post_install.sh
sudo ./post_install.sh

(or curl -O <same URL>, or git clone https://github.com/arduino/ArduinoCore-zephyr.git then run post_install.sh). Reconnect the board afterward.

Hello World (Blink) to confirm the toolchain

In App Lab the Examples section opens on launch → open Blink LED → Run. Success = the red channel of the built-in RGB LED blinks 1 s on / 1 s off. That LED is driven by the STM32 via the sketch, so a successful blink proves the MCU side is programmable.

Running an App at startup (kiosk / standalone projects)

• You cannot set a built-in Example as the startup app directly — first copy it to a new App or create your own.
• In the App: click the ▼ arrow next to the Run button (top-right) → toggle Run at startup ON. A DEFAULT badge confirms it.
• CLI equivalent:

  arduino-app-cli properties set default user:<NAME_OF_YOUR_APP>
  

The App Lab CLI (arduino-app-cli)

Runs on the board (use it over SSH for headless control):

arduino-app-cli app start ~/ArduinoApps/<project-name>   # start an app
arduino-app-cli app logs  ~/ArduinoApps/<project-name>   # stream its logs
arduino-app-cli app stop  ~/ArduinoApps/<project-name>   # stop it
arduino-app-cli properties set default user:<app-name>   # set autostart app

Apps live under ~/ArduinoApps/ on the board.