feat(uno-q): ship the arduino-uno-q expert skill on every node by default
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
co-authored by
Claude Opus 4.8
Claude Opus 4.8
parent
7233a4b1c0
commit
d2135a1938
@@ -0,0 +1,96 @@
|
||||
# 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)
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
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`:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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):
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user