clawverse/apress
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(uno-q): ship the arduino-uno-q expert skill on every node by default

Browse Source 
Vendors the comprehensive UNO Q skill (SKILL.md + 7 references/*.md) and installs
it into EVERY agent's workspace on each board, so agents know this board's
specifics (dual-brain arch, Bridge/RPC, pin tables, LED matrix + the
ArduinoGraphics-not-installed gotcha) instead of guessing generic Arduino.

Why per-agent workspace: ZeroClaw's read_skill returns only SKILL.md; the agent
reads references/*.md via the workspace-sandboxed file_read tool, so references
are only reachable under ~/.zeroclaw/agents/<alias>/workspace/skills/. A
shared/skills bundle surfaces the skill but its references get sandbox-blocked.

- push-skill.sh installs a SKILL.md+references skill into every agent workspace
  (discovers aliases from the board); provision-fleet runs it per board.
- config.template risk profile now allows + auto-approves read_skill + file_read
  so agents load skills without a human approver (webhook path is non-interactive).
- Flattened the folded 'description: >-' to single-line (ZeroClaw's frontmatter
  parser is a flat scanner, not full YAML).

Verified on board 65301572 with cloud/Sonnet-5: discovered arduino-uno-q →
read_skill(SKILL.md) → file_read references/04-bridge-rpc.md → correct
board-specific answer citing the file.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
This commit is contained in:
Omar Sobh
2026-07-16 09:14:00 -07:00
co-authored by Claude Opus 4.8
parent 7233a4b1c0
commit d2135a1938
12 changed files with 877 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
deploy/uno-q/skills/arduino-uno-q/SKILL.md
+61
View File
@@ -0,0 +1,61 @@
---
name: arduino-uno-q
description: 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](references/04-bridge-rpc.md) 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](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](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](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](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](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](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](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.