apress/deploy/uno-q/skills/arduino-uno-q/SKILL.md

name, description

name

description

arduino-uno-q

Expert working knowledge of the Arduino UNO Q dual-brain single-board computer (Qualcomm Dragonwing QRB2210 Linux microprocessor + STM32U585 microcontroller). Use this skill whenever the user works with, teaches, prototypes on, or troubleshoots an Arduino UNO Q — any mention of 'UNO Q', App Lab, Bricks, the Bridge/RPC library, the arduino-router, connecting the Linux side to the Arduino/MCU side, running Python plus a sketch together, SSHing into the board, Network Mode, flashing or running apps, wiring or controlling sensors/actuators/LEDs/motors/shields, GPIO/ADC/DAC/PWM/SPI/I2C/Qwiic/UART pins, Wi-Fi or Bluetooth on the board, or preparing a workshop around it. Trigger even when the user doesn't say 'UNO Q' but is clearly on this board. Prefer this over generic Arduino advice — the UNO Q's two-processor architecture makes most single-MCU instructions wrong or incomplete.

Arduino UNO Q

The UNO Q is not a normal Arduino. It is two computers on one classic UNO-shaped board, and almost every mistake people make with it comes from forgetting that. Internalize the architecture first; everything else follows from it.

The one mental model that matters

The board carries two processors that run at the same time:

• The MPU (the "Linux side") — a Qualcomm Dragonwing QRB2210, quad-core Arm Cortex-A53 @ 2.0 GHz, running a full Debian Linux OS. This is where Python, AI/vision, networking, the desktop, SSH, and the Arduino App Lab live. Think of it as a Raspberry-Pi-class computer.
• The MCU (the "Arduino side") — an STM32U585, Arm Cortex-M33 @ 160 MHz, running your Arduino sketch on top of Zephyr OS. This is where real-time, deterministic pin control lives: GPIO, ADC, DAC, PWM, SPI, I2C, UART. Think of it as a classic Arduino.

They are wired together internally and talk to each other over a dedicated serial link managed by a Linux service called the arduino-router. The library layer on top of that link is the Bridge (RPC) library. This bridge is the heart of the board — "connect the Linux side to the Arduino side" always means "use the Bridge / arduino-router," never physical jumper wires.

Decision rule you will use constantly:

• Needs precise timing, or reads/writes a physical pin (a sensor, a motor driver, an LED, a shield)? → MCU / sketch.
• Needs Python, the network, a filesystem, heavy compute, a camera, or AI? → MPU / Linux.
• Needs both to cooperate (the usual case)? → run code on each side and connect them with the Bridge.

If you only remember one thing: you don't control an attached component "from Linux" directly. You write a sketch on the MCU that owns the pin, expose a function over the Bridge, and call it from Python on the Linux side. The Bridge reference shows exactly how.

Two ways to develop, and where the code runs

• Arduino App Lab is the primary environment and comes pre-installed on the board. An "App" bundles a Python program (Linux/MPU) and an Arduino sketch (MCU) together, plus reusable building blocks called Bricks. Use App Lab whenever the project uses the Linux side at all (Python, AI, networking) or needs both processors. It can run on the board itself (Single-Board-Computer mode, with a monitor/keyboard) or from your PC over the network (Network Mode).
• Arduino IDE (beta) programs only the MCU (STM32). It cannot touch the Qualcomm processor. Use it only for pure-microcontroller sketches when you don't need Linux at all.

So: if a workshop exercise involves Python or the network, it is an App Lab project. If it is "just blink an LED / read a sensor with a sketch," either tool works, but App Lab keeps everything in one place.

How to help with this board

1. Locate the work on the right processor(s) using the decision rule above. State it explicitly to the user — it prevents 80% of confusion.
2. If the two sides must cooperate, design the Bridge contract first: which functions does the MCU provide(), and what does the Python side call()? Then write each side.
3. For anything physical (wiring a component, choosing a pin), go to the pin/peripheral reference for exact pin mappings, voltage levels, and library usage — the UNO Q has real gotchas (3.3 V logic, active-low LEDs, reserved Serial1//dev/ttyHS1, fixed 500 Hz PWM).
4. For remote/headless workshop setups, use SSH + Network Mode + the CLI so students can work from their own laptops.
5. Verify against the reference files rather than reciting generic Arduino knowledge from memory — the details on this board are specific and easy to get wrong.

Reference map — read the file that fits the task

Load these as needed; each is self-contained. Don't dump all of them into context at once — pick the one the current question is about.

• references/01-hardware-specs.md — Full architecture, exact chip/model numbers, memory/storage variants, power options, USB-C capabilities, dimensions, onboard UI (8×13 LED matrix, 4 RGB LEDs, power button, debug UART). Read for "what is on the board / what can it do / how do I power it."
• references/02-setup-and-os.md — First boot, Debian, installing/using App Lab, Bricks & Apps model, Linux host udev setup (required for Linux PCs), running an App at startup, the arduino-app-cli, Arduino IDE core install. Read for "getting started / install / it won't connect / autostart."
• references/03-remote-access.md — SSH, Network Mode (mDNS), finding the board's IP, adb, copying files with scp, running/stopping apps remotely. Read for "access the board remotely / headless / from my laptop / over the network."
• references/04-bridge-rpc.md — The Linux↔MCU bridge: the arduino-router service, the Bridge/RPC API, provide() vs provide_safe(), call()/notify(), complete Python-side and sketch-side examples, the raw Unix-socket/MessagePack path, and the reserved-resource warnings. Read for "make Python talk to the sketch / call an Arduino function from Linux / control a pin from Python."
• references/05-io-and-peripherals.md — Every pin table (digital/analog/PWM), ADC/DAC, SPI, I2C, Qwiic, UART, and how to actually drive attached components (sensors, actuators, LEDs, shields). Read for "wire up / control / read a component / which pin."
• references/06-wireless.md — Wi-Fi (incl. WPA2-Enterprise / eduroam), Bluetooth, and reaching the network from the MCU via the Bridge. Read for "get it online / connect to Wi-Fi / Bluetooth."
• references/07-workshop-playbook.md — Opinionated setup checklist, common failure modes and fixes, and a canonical "Python button → Arduino LED" starter that ties the whole model together. Read when planning or running a hands-on session.

Quick reference (the things people look up most)

• Board name over the network: the hostname you set during setup, reachable as <name>.local via mDNS; default Linux user is arduino.
• SSH in: ssh arduino@<BOARD_IP> (find IP with ip addr show → look under wlan0).
• Router service: systemctl status arduino-router · logs: journalctl -u arduino-router -f. Never open /dev/ttyHS1 (Linux) or Serial1 (MCU) yourself — the router owns them.
• Bridge socket (advanced): /var/run/arduino-router.sock (MessagePack-RPC).
• Logic level on the pins: the MCU I/O is 3.3 V; the Qwiic connector is 3.3 V only. The onboard RGB LEDs are active-low.
• Serial for debugging: on the MCU, plain Serial.print() shows up in the App Lab console (platform ≥ 0.55.0); Serial1 is the physical D0/D1 UART.