Omar SobhandClaude Opus 4.8
d2135a1938
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]>
97 lines
5.4 KiB
Markdown
97 lines
5.4 KiB
Markdown
# 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.
|