admin/skill-lib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: refactor sgclaw around zeroclaw compat runtime

Browse Source
This commit is contained in:
zyl
2026-03-26 16:23:31 +08:00
parent bca5b75801
commit ff0771a83f
1059 changed files with 409460 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
third_party/zeroclaw/docs/hardware/README.md vendored Normal file
View File

@@ -0,0 +1,19 @@
# Hardware & Peripherals Docs
For board integration, firmware flow, and peripheral architecture.
ZeroClaw's hardware subsystem enables direct control of microcontrollers and peripherals via the `Peripheral` trait. Each board exposes tools for GPIO, ADC, and sensor operations, allowing agent-driven hardware interaction on boards like STM32 Nucleo, Raspberry Pi, and ESP32. See [hardware-peripherals-design.md](hardware-peripherals-design.md) for the full architecture.
## Entry Points
- Architecture and peripheral model: [hardware-peripherals-design.md](hardware-peripherals-design.md)
- Add a new board/tool: [../contributing/adding-boards-and-tools.md](../contributing/adding-boards-and-tools.md)
- Nucleo setup: [nucleo-setup.md](nucleo-setup.md)
- Arduino Uno R4 WiFi setup: [arduino-uno-q-setup.md](arduino-uno-q-setup.md)
## Datasheets
- Datasheet index: [datasheets](datasheets)
- STM32 Nucleo-F401RE: [datasheets/nucleo-f401re.md](datasheets/nucleo-f401re.md)
- Arduino Uno: [datasheets/arduino-uno.md](datasheets/arduino-uno.md)
- ESP32: [datasheets/esp32.md](datasheets/esp32.md)

100
third_party/zeroclaw/docs/hardware/android-setup.md vendored Normal file
View File

@@ -0,0 +1,100 @@
# Android Setup
ZeroClaw provides prebuilt binaries for Android devices.
## Supported Architectures
| Target | Android Version | Devices |
|--------|-----------------|---------|
| `armv7-linux-androideabi` | Android 4.1+ (API 16+) | Older 32-bit phones (Galaxy S3, etc.) |
| `aarch64-linux-android` | Android 5.0+ (API 21+) | Modern 64-bit phones |
## Installation via Termux
The easiest way to run ZeroClaw on Android is via [Termux](https://termux.dev/).
### 1. Install Termux
Download from [F-Droid](https://f-droid.org/packages/com.termux/) (recommended) or GitHub releases.
> ⚠️ **Note:** The Play Store version is outdated and unsupported.
### 2. Download ZeroClaw
```bash
# Check your architecture
uname -m
# aarch64 = 64-bit, armv7l/armv8l = 32-bit
# Download the appropriate binary
# For 64-bit (aarch64):
curl -LO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-aarch64-linux-android.tar.gz
tar xzf zeroclaw-aarch64-linux-android.tar.gz
# For 32-bit (armv7):
curl -LO https://github.com/zeroclaw-labs/zeroclaw/releases/latest/download/zeroclaw-armv7-linux-androideabi.tar.gz
tar xzf zeroclaw-armv7-linux-androideabi.tar.gz
```
### 3. Install and Run
```bash
chmod +x zeroclaw
mv zeroclaw $PREFIX/bin/
# Verify installation
zeroclaw --version
# Run setup
zeroclaw onboard
```
## Direct Installation via ADB
For advanced users who want to run ZeroClaw outside Termux:
```bash
# From your computer with ADB
adb push zeroclaw /data/local/tmp/
adb shell chmod +x /data/local/tmp/zeroclaw
adb shell /data/local/tmp/zeroclaw --version
```
> ⚠️ Running outside Termux requires a rooted device or specific permissions for full functionality.
## Limitations on Android
- **No systemd:** Use Termux's `termux-services` for daemon mode
- **Storage access:** Requires Termux storage permissions (`termux-setup-storage`)
- **Network:** Some features may require Android VPN permission for local binding
## Building from Source
To build for Android yourself:
```bash
# Install Android NDK
# Add targets
rustup target add armv7-linux-androideabi aarch64-linux-android
# Set NDK path
export ANDROID_NDK_HOME=/path/to/ndk
export PATH=$ANDROID_NDK_HOME/toolchains/llvm/prebuilt/linux-x86_64/bin:$PATH
# Build
cargo build --release --target armv7-linux-androideabi
cargo build --release --target aarch64-linux-android
```
## Troubleshooting
### "Permission denied"
```bash
chmod +x zeroclaw
```
### "not found" or linker errors
Make sure you downloaded the correct architecture for your device.
### Old Android (4.x)
Use the `armv7-linux-androideabi` build with API level 16+.

217
third_party/zeroclaw/docs/hardware/arduino-uno-q-setup.md vendored Normal file
View File

@@ -0,0 +1,217 @@
# ZeroClaw on Arduino Uno Q — Step-by-Step Guide
Run ZeroClaw on the Arduino Uno Q's Linux side. Telegram works over WiFi; GPIO control uses the Bridge (requires a minimal App Lab app).
---
## What's Included (No Code Changes Needed)
ZeroClaw includes everything needed for Arduino Uno Q. **Clone the repo and follow this guide — no patches or custom code required.**
| Component | Location | Purpose |
|-----------|----------|---------|
| Bridge app | `firmware/uno-q-bridge/` | MCU sketch + Python socket server (port 9999) for GPIO |
| Bridge tools | `src/peripherals/uno_q_bridge.rs` | `gpio_read` / `gpio_write` tools that talk to the Bridge over TCP |
| Setup command | `src/peripherals/uno_q_setup.rs` | `zeroclaw peripheral setup-uno-q` deploys the Bridge via scp + arduino-app-cli |
| Config schema | `board = "arduino-uno-q"`, `transport = "bridge"` | Supported in `config.toml` |
Build with `--features hardware` to include Uno Q support.
---
## Prerequisites
- Arduino Uno Q with WiFi configured
- Arduino App Lab installed on your Mac (for initial setup and deployment)
- API key for LLM (OpenRouter, etc.)
---
## Phase 1: Initial Uno Q Setup (One-Time)
### 1.1 Configure Uno Q via App Lab
1. Download [Arduino App Lab](https://docs.arduino.cc/software/app-lab/) (tar.gz on Linux).
2. Connect Uno Q via USB, power it on.
3. Open App Lab, connect to the board.
4. Follow the setup wizard:
- Set username and password (for SSH)
- Configure WiFi (SSID, password)
- Apply any firmware updates
5. Note the IP address shown (e.g. `arduino@192.168.1.42`) or find it later via `ip addr show` in App Lab's terminal.
### 1.2 Verify SSH Access
```bash
ssh arduino@<UNO_Q_IP>
# Enter the password you set
```
---
## Phase 2: Install ZeroClaw on Uno Q
### Option A: Build on the Device (Simpler, ~20–40 min)
```bash
# SSH into Uno Q
ssh arduino@<UNO_Q_IP>
# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source ~/.cargo/env
# Install build deps (Debian)
sudo apt-get update
sudo apt-get install -y pkg-config libssl-dev
# Clone zeroclaw (or scp your project)
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
# Build (takes ~15–30 min on Uno Q)
cargo build --release --features hardware
# Install
sudo cp target/release/zeroclaw /usr/local/bin/
```
### Option B: Cross-Compile on Mac (Faster)
```bash
# On your Mac — add aarch64 target
rustup target add aarch64-unknown-linux-gnu
# Install cross-compiler (macOS; required for linking)
brew tap messense/macos-cross-toolchains
brew install aarch64-unknown-linux-gnu
# Build
CC_aarch64_unknown_linux_gnu=aarch64-unknown-linux-gnu-gcc cargo build --release --target aarch64-unknown-linux-gnu --features hardware
# Copy to Uno Q
scp target/aarch64-unknown-linux-gnu/release/zeroclaw arduino@<UNO_Q_IP>:~/
ssh arduino@<UNO_Q_IP> "sudo mv ~/zeroclaw /usr/local/bin/"
```
If cross-compile fails, use Option A and build on the device.
---
## Phase 3: Configure ZeroClaw
### 3.1 Run Onboard (or Create Config Manually)
```bash
ssh arduino@<UNO_Q_IP>
# Quick config
zeroclaw onboard --api-key YOUR_OPENROUTER_KEY --provider openrouter
# Or create config manually
mkdir -p ~/.zeroclaw/workspace
nano ~/.zeroclaw/config.toml
```
### 3.2 Minimal config.toml
```toml
api_key = "YOUR_OPENROUTER_API_KEY"
default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4-6"
[peripherals]
enabled = false
# GPIO via Bridge requires Phase 4
[channels_config.telegram]
bot_token = "YOUR_TELEGRAM_BOT_TOKEN"
allowed_users = ["*"]
[gateway]
host = "127.0.0.1"
port = 42617
allow_public_bind = false
[agent]
compact_context = true
```
---
## Phase 4: Run ZeroClaw Daemon
```bash
ssh arduino@<UNO_Q_IP>
# Run daemon (Telegram polling works over WiFi)
zeroclaw daemon --host 127.0.0.1 --port 42617
```
**At this point:** Telegram chat works. Send messages to your bot — ZeroClaw responds. No GPIO yet.
---
## Phase 5: GPIO via Bridge (ZeroClaw Handles It)
ZeroClaw includes the Bridge app and setup command.
### 5.1 Deploy Bridge App
**From your Mac** (with zeroclaw repo):
```bash
zeroclaw peripheral setup-uno-q --host 192.168.0.48
```
**From the Uno Q** (SSH'd in):
```bash
zeroclaw peripheral setup-uno-q
```
This copies the Bridge app to `~/ArduinoApps/uno-q-bridge` and starts it.
### 5.2 Add to config.toml
```toml
[peripherals]
enabled = true
[[peripherals.boards]]
board = "arduino-uno-q"
transport = "bridge"
```
### 5.3 Run ZeroClaw
```bash
zeroclaw daemon --host 127.0.0.1 --port 42617
```
Now when you message your Telegram bot *"Turn on the LED"* or *"Set pin 13 high"*, ZeroClaw uses `gpio_write` via the Bridge.
---
## Summary: Commands Start to End
| Step | Command |
|------|---------|
| 1 | Configure Uno Q in App Lab (WiFi, SSH) |
| 2 | `ssh arduino@<IP>` |
| 3 | `curl -sSf https://sh.rustup.rs \| sh -s -- -y && source ~/.cargo/env` |
| 4 | `sudo apt-get install -y pkg-config libssl-dev` |
| 5 | `git clone https://github.com/zeroclaw-labs/zeroclaw.git && cd zeroclaw` |
| 6 | `cargo build --release --features hardware` |
| 7 | `zeroclaw onboard --api-key KEY --provider openrouter` |
| 8 | Edit `~/.zeroclaw/config.toml` (add Telegram bot_token) |
| 9 | `zeroclaw daemon --host 127.0.0.1 --port 42617` |
| 10 | Message your Telegram bot — it responds |
---
## Troubleshooting
- **"command not found: zeroclaw"** — Use full path: `/usr/local/bin/zeroclaw` or ensure `~/.cargo/bin` is in PATH.
- **Telegram not responding** — Check bot_token, allowed_users, and that the Uno Q has internet (WiFi).
- **Out of memory** — Keep features minimal (`--features hardware` for Uno Q); consider `compact_context = true`.
- **GPIO commands ignored** — Ensure Bridge app is running (`zeroclaw peripheral setup-uno-q` deploys and starts it). Config must have `board = "arduino-uno-q"` and `transport = "bridge"`.
- **LLM provider (GLM/Zhipu)** — Use `default_provider = "glm"` or `"zhipu"` with `GLM_API_KEY` in env or config. ZeroClaw uses the correct v4 endpoint.

37
third_party/zeroclaw/docs/hardware/datasheets/arduino-uno.md vendored Normal file
View File

@@ -0,0 +1,37 @@
# Arduino Uno
## Pin Aliases
| alias | pin |
|-------------|-----|
| red_led | 13 |
| builtin_led | 13 |
| user_led | 13 |
## Overview
Arduino Uno is a microcontroller board based on the ATmega328P. It has 14 digital I/O pins (0–13) and 6 analog inputs (A0–A5).
## Digital Pins
- **Pins 0–13:** Digital I/O. Can be INPUT or OUTPUT.
- **Pin 13:** Built-in LED (onboard). Connect LED to GND or use for output.
- **Pins 0–1:** Also used for Serial (RX/TX). Avoid if using Serial.
## GPIO
- `digitalWrite(pin, HIGH)` or `digitalWrite(pin, LOW)` for output.
- `digitalRead(pin)` for input (returns 0 or 1).
- Pin numbers in ZeroClaw protocol: 0–13.
## Serial
- UART on pins 0 (RX) and 1 (TX).
- USB via ATmega16U2 or CH340 (clones).
- Baud rate: 115200 for ZeroClaw firmware.
## ZeroClaw Tools
- `gpio_read`: Read pin value (0 or 1).
- `gpio_write`: Set pin high (1) or low (0).
- `arduino_upload`: Agent generates full Arduino sketch code; ZeroClaw compiles and uploads it via arduino-cli. Use for "make a heart", custom patterns — agent writes the code, no manual editing. Pin 13 = built-in LED.

22
third_party/zeroclaw/docs/hardware/datasheets/esp32.md vendored Normal file
View File

@@ -0,0 +1,22 @@
# ESP32 GPIO Reference
## Pin Aliases
| alias | pin |
|-------------|-----|
| builtin_led | 2 |
| red_led | 2 |
## Common pins (ESP32 / ESP32-C3)
- **GPIO 2**: Built-in LED on many dev boards (output)
- **GPIO 13**: General-purpose output
- **GPIO 21/20**: Often used for UART0 TX/RX (avoid if using serial)
## Protocol
ZeroClaw host sends JSON over serial (115200 baud):
- `gpio_read`: `{"id":"1","cmd":"gpio_read","args":{"pin":13}}`
- `gpio_write`: `{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}`
Response: `{"id":"1","ok":true,"result":"0"}` or `{"id":"1","ok":true,"result":"done"}`

16
third_party/zeroclaw/docs/hardware/datasheets/nucleo-f401re.md vendored Normal file
View File

@@ -0,0 +1,16 @@
# Nucleo-F401RE GPIO
## Pin Aliases
| alias | pin |
|-------------|-----|
| red_led | 13 |
| user_led | 13 |
| ld2 | 13 |
| builtin_led | 13 |
## GPIO
Pin 13: User LED (LD2)
- Output, active high
- PA5 on STM32F401

324
third_party/zeroclaw/docs/hardware/hardware-peripherals-design.md vendored Normal file
View File

@@ -0,0 +1,324 @@
# Hardware Peripherals Design — ZeroClaw
ZeroClaw enables microcontrollers (MCUs) and Single Board Computers (SBCs) to **dynamically interpret natural language commands**, generate hardware-specific code, and execute peripheral interactions in real-time.
## 1. Vision
**Goal:** ZeroClaw acts as a hardware-aware AI agent that:
- Receives natural language triggers (e.g. "Move X arm", "Turn on LED") via channels (WhatsApp, Telegram)
- Fetches accurate hardware documentation (datasheets, register maps)
- Synthesizes Rust code/logic using an LLM (Gemini, local open-source models)
- Executes the logic to manipulate peripherals (GPIO, I2C, SPI)
- Persists optimized code for future reuse
**Mental model:** ZeroClaw = brain that understands hardware. Peripherals = arms and legs it controls.
## 2. Two Modes of Operation
### Mode 1: Edge-Native (Standalone)
**Target:** Wi-Fi-enabled boards (ESP32, Raspberry Pi).
ZeroClaw runs **directly on the device**. The board spins up a gRPC/nanoRPC server and communicates with peripherals locally.
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ ZeroClaw on ESP32 / Raspberry Pi (Edge-Native) │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌─────────────────────────────────┐ │
│ │ Channels │───►│ Agent Loop │───►│ RAG: datasheets, register maps │ │
│ │ WhatsApp │ │ (LLM calls) │ │ → LLM context │ │
│ │ Telegram │ └──────┬───────┘ └─────────────────────────────────┘ │
│ └─────────────┘ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────────────────┐│
│ │ Code synthesis → Wasm / dynamic exec → GPIO / I2C / SPI → persist ││
│ └─────────────────────────────────────────────────────────────────────────┘│
│ │
│ gRPC/nanoRPC server ◄──► Peripherals (GPIO, I2C, SPI, sensors, actuators) │
└─────────────────────────────────────────────────────────────────────────────┘
```
**Workflow:**
1. User sends WhatsApp: *"Turn on LED on pin 13"*
2. ZeroClaw fetches board-specific docs (e.g. ESP32 GPIO mapping)
3. LLM synthesizes Rust code
4. Code runs in a sandbox (Wasm or dynamic linking)
5. GPIO is toggled; result returned to user
6. Optimized code is persisted for future "Turn on LED" requests
**All happens on-device.** No host required.
### Mode 2: Host-Mediated (Development / Debugging)
**Target:** Hardware connected via USB / J-Link / Aardvark to a host (macOS, Linux).
ZeroClaw runs on the **host** and maintains a hardware-aware link to the target. Used for development, introspection, and flashing.
```
┌─────────────────────┐ ┌──────────────────────────────────┐
│ ZeroClaw on Mac │ USB / J-Link / │ STM32 Nucleo-F401RE │
│ │ Aardvark │ (or other MCU) │
│ - Channels │ ◄────────────────► │ - Memory map │
│ - LLM │ │ - Peripherals (GPIO, ADC, I2C) │
│ - Hardware probe │ VID/PID │ - Flash / RAM │
│ - Flash / debug │ discovery │ │
└─────────────────────┘ └──────────────────────────────────┘
```
**Workflow:**
1. User sends Telegram: *"What are the readable memory addresses on this USB device?"*
2. ZeroClaw identifies connected hardware (VID/PID, architecture)
3. Performs memory mapping; suggests available address spaces
4. Returns result to user
**Or:**
1. User: *"Flash this firmware to the Nucleo"*
2. ZeroClaw writes/flashes via OpenOCD or probe-rs
3. Confirms success
**Or:**
1. ZeroClaw auto-discovers: *"STM32 Nucleo on /dev/ttyACM0, ARM Cortex-M4"*
2. Suggests: *"I can read/write GPIO, ADC, flash. What would you like to do?"*
---
### Mode Comparison
| Aspect | Edge-Native | Host-Mediated |
|------------------|--------------------------------|----------------------------------|
| ZeroClaw runs on | Device (ESP32, RPi) | Host (Mac, Linux) |
| Hardware link | Local (GPIO, I2C, SPI) | USB, J-Link, Aardvark |
| LLM | On-device or cloud (Gemini) | Host (cloud or local) |
| Use case | Production, standalone | Dev, debug, introspection |
| Channels | WhatsApp, etc. (via WiFi) | Telegram, CLI, etc. |
## 3. Legacy / Simpler Modes (Pre-LLM-on-Edge)
For boards without WiFi or before full Edge-Native is ready:
### Mode A: Host + Remote Peripheral (STM32 via serial)
Host runs ZeroClaw; peripheral runs minimal firmware. Simple JSON over serial.
### Mode B: RPi as Host (Native GPIO)
ZeroClaw on Pi; GPIO via rppal or sysfs. No separate firmware.
## 4. Technical Requirements
| Requirement | Description |
|-------------|-------------|
| **Language** | Pure Rust. `no_std` where applicable for embedded targets (STM32, ESP32). |
| **Communication** | Lightweight gRPC or nanoRPC stack for low-latency command processing. |
| **Dynamic execution** | Safely run LLM-generated logic on-the-fly: Wasm runtime for isolation, or dynamic linking where supported. |
| **Documentation retrieval** | RAG (Retrieval-Augmented Generation) pipeline to feed datasheet snippets, register maps, and pinouts into LLM context. |
| **Hardware discovery** | VID/PID-based identification for USB devices; architecture detection (ARM Cortex-M, RISC-V, etc.). |
### RAG Pipeline (Datasheet Retrieval)
- **Index:** Datasheets, reference manuals, register maps (PDF → chunks, embeddings).
- **Retrieve:** On user query ("turn on LED"), fetch relevant snippets (e.g. GPIO section for target board).
- **Inject:** Add to LLM system prompt or context.
- **Result:** LLM generates accurate, board-specific code.
### Dynamic Execution Options
| Option | Pros | Cons |
|-------|------|------|
| **Wasm** | Sandboxed, portable, no FFI | Overhead; limited HW access from Wasm |
| **Dynamic linking** | Native speed, full HW access | Platform-specific; security concerns |
| **Interpreted DSL** | Safe, auditable | Slower; limited expressiveness |
| **Pre-compiled templates** | Fast, secure | Less flexible; requires template library |
**Recommendation:** Start with pre-compiled templates + parameterization; evolve to Wasm for user-defined logic once stable.
## 5. CLI and Config
### CLI Flags
```bash
# Edge-Native: run on device (ESP32, RPi)
zeroclaw agent --mode edge
# Host-Mediated: connect to USB/J-Link target
zeroclaw agent --peripheral nucleo-f401re:/dev/ttyACM0
zeroclaw agent --probe jlink
# Hardware introspection
zeroclaw hardware discover
zeroclaw hardware introspect /dev/ttyACM0
```
### Config (config.toml)
```toml
[peripherals]
enabled = true
mode = "host" # "edge" | "host"
datasheet_dir = "docs/datasheets" # RAG: board-specific docs for LLM context
[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200
[[peripherals.boards]]
board = "rpi-gpio"
transport = "native"
[[peripherals.boards]]
board = "esp32"
transport = "wifi"
# Edge-Native: ZeroClaw runs on ESP32
```
## 6. Architecture: Peripheral as Extension Point
### New Trait: `Peripheral`
```rust
/// A hardware peripheral that exposes capabilities as tools.
#[async_trait]
pub trait Peripheral: Send + Sync {
fn name(&self) -> &str;
fn board_type(&self) -> &str; // e.g. "nucleo-f401re", "rpi-gpio"
async fn connect(&mut self) -> anyhow::Result<()>;
async fn disconnect(&mut self) -> anyhow::Result<()>;
async fn health_check(&self) -> bool;
/// Tools this peripheral provides (gpio_read, gpio_write, sensor_read, etc.)
fn tools(&self) -> Vec<Box<dyn Tool>>;
}
```
### Flow
1. **Startup:** ZeroClaw loads config, sees `peripherals.boards`.
2. **Connect:** For each board, create a `Peripheral` impl, call `connect()`.
3. **Tools:** Collect tools from all connected peripherals; merge with default tools.
4. **Agent loop:** Agent can call `gpio_write`, `sensor_read`, etc. — these delegate to the peripheral.
5. **Shutdown:** Call `disconnect()` on each peripheral.
### Board Support
| Board | Transport | Firmware / Driver | Tools |
|--------------------|-----------|------------------------|--------------------------|
| nucleo-f401re | serial | Zephyr / Embassy | gpio_read, gpio_write, adc_read |
| rpi-gpio | native | rppal or sysfs | gpio_read, gpio_write |
| esp32 | serial/ws | ESP-IDF / Embassy | gpio, wifi, mqtt |
## 7. Communication Protocols
### gRPC / nanoRPC (Edge-Native, Host-Mediated)
For low-latency, typed RPC between ZeroClaw and peripherals:
- **nanoRPC** or **tonic** (gRPC): Protobuf-defined services.
- Methods: `GpioWrite`, `GpioRead`, `I2cTransfer`, `SpiTransfer`, `MemoryRead`, `FlashWrite`, etc.
- Enables streaming, bidirectional calls, and code generation from `.proto` files.
### Serial Fallback (Host-Mediated, legacy)
Simple JSON over serial for boards without gRPC support:
**Request (host → peripheral):**
```json
{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}
```
**Response (peripheral → host):**
```json
{"id":"1","ok":true,"result":"done"}
```
## 8. Firmware (Separate Repo or Crate)
- **zeroclaw-firmware** or **zeroclaw-peripheral** — a separate crate/workspace.
- Targets: `thumbv7em-none-eabihf` (STM32), `armv7-unknown-linux-gnueabihf` (RPi), etc.
- Uses `embassy` or Zephyr for STM32.
- Implements the protocol above.
- User flashes this to the board; ZeroClaw connects and discovers capabilities.
## 9. Implementation Phases
### Phase 1: Skeleton ✅ (Done)
- [x] Add `Peripheral` trait, config schema, CLI (`zeroclaw peripheral list/add`)
- [x] Add `--peripheral` flag to agent
- [x] Document in AGENTS.md
### Phase 2: Host-Mediated — Hardware Discovery ✅ (Done)
- [x] `zeroclaw hardware discover`: enumerate USB devices (VID/PID)
- [x] Board registry: map VID/PID → architecture, name (e.g. Nucleo-F401RE)
- [x] `zeroclaw hardware introspect <path>`: memory map, peripheral list
### Phase 3: Host-Mediated — Serial / J-Link
- [x] `SerialPeripheral` for STM32 over USB CDC
- [ ] probe-rs or OpenOCD integration for flash/debug
- [x] Tools: `gpio_read`, `gpio_write` (memory_read, flash_write in future)
### Phase 4: RAG Pipeline ✅ (Done)
- [x] Datasheet index (markdown/text → chunks)
- [x] Retrieve-and-inject into LLM context on hardware-related queries
- [x] Board-specific prompt augmentation
**Usage:** Add `datasheet_dir = "docs/datasheets"` to `[peripherals]` in config.toml. Place `.md` or `.txt` files named by board (e.g. `nucleo-f401re.md`, `rpi-gpio.md`). Files in `_generic/` or named `generic.md` apply to all boards. Chunks are retrieved by keyword match and injected into the user message context.
### Phase 5: Edge-Native — RPi ✅ (Done)
- [x] ZeroClaw on Raspberry Pi (native GPIO via rppal)
- [ ] gRPC/nanoRPC server for local peripheral access
- [ ] Code persistence (store synthesized snippets)
### Phase 6: Edge-Native — ESP32
- [x] Host-mediated ESP32 (serial transport) — same JSON protocol as STM32
- [x] `esp32` firmware crate (`firmware/esp32`) — GPIO over UART
- [x] ESP32 in hardware registry (CH340 VID/PID)
- [ ] ZeroClaw *on* ESP32 (WiFi + LLM, edge-native) — future
- [ ] Wasm or template-based execution for LLM-generated logic
**Usage:** Flash `firmware/esp32` to ESP32, add `board = "esp32"`, `transport = "serial"`, `path = "/dev/ttyUSB0"` to config.
### Phase 7: Dynamic Execution (LLM-Generated Code)
- [ ] Template library: parameterized GPIO/I2C/SPI snippets
- [ ] Optional: Wasm runtime for user-defined logic (sandboxed)
- [ ] Persist and reuse optimized code paths
## 10. Security Considerations
- **Serial path:** Validate `path` is in allowlist (e.g. `/dev/ttyACM*`, `/dev/ttyUSB*`); never arbitrary paths.
- **GPIO:** Restrict which pins are exposed; avoid power/reset pins.
- **No secrets on peripheral:** Firmware should not store API keys; host handles auth.
## 11. Non-Goals (For Now)
- Running full ZeroClaw *on* bare STM32 (no WiFi, limited RAM) — use Host-Mediated instead
- Real-time guarantees — peripherals are best-effort
- Arbitrary native code execution from LLM — prefer Wasm or templates
## 12. Related Documents
- [adding-boards-and-tools.md](../contributing/adding-boards-and-tools.md) — How to add boards and datasheets
- [network-deployment.md](../ops/network-deployment.md) — RPi and network deployment
## 13. References
- [Zephyr RTOS Rust support](https://docs.zephyrproject.org/latest/develop/languages/rust/index.html)
- [Embassy](https://embassy.dev/) — async embedded framework
- [rppal](https://github.com/golemparts/rppal) — Raspberry Pi GPIO in Rust
- [STM32 Nucleo-F401RE](https://www.st.com/en/evaluation-tools/nucleo-f401re.html)
- [tonic](https://github.com/hyperium/tonic) — gRPC for Rust
- [probe-rs](https://probe.rs/) — ARM debug probe, flash, memory access
- [nusb](https://github.com/nic-hartley/nusb) — USB device enumeration (VID/PID)
## 14. Raw Prompt Summary
> *"Boards like ESP, Raspberry Pi, or boards with WiFi can connect to an LLM (Gemini or open-source). ZeroClaw runs on the device, creates its own gRPC, spins it up, and communicates with peripherals. User asks via WhatsApp: 'move X arm' or 'turn on LED'. ZeroClaw gets accurate documentation, writes code, executes it, stores it optimally, runs it, and turns on the LED — all on the development board.*
>
> *For STM Nucleo connected via USB/J-Link/Aardvark to my Mac: ZeroClaw from my Mac accesses the hardware, installs or writes what it wants on the device, and returns the result. Example: 'Hey ZeroClaw, what are the available/readable addresses on this USB device?' It can figure out what's connected where and suggest."*

147
third_party/zeroclaw/docs/hardware/nucleo-setup.md vendored Normal file
View File

@@ -0,0 +1,147 @@
# ZeroClaw on Nucleo-F401RE — Step-by-Step Guide
Run ZeroClaw on your Mac or Linux host. Connect a Nucleo-F401RE via USB. Control GPIO (LED, pins) via Telegram or CLI.
---
## Get Board Info via Telegram (No Firmware Needed)
ZeroClaw can read chip info from the Nucleo over USB **without flashing any firmware**. Message your Telegram bot:
- *"What board info do I have?"*
- *"Board info"*
- *"What hardware is connected?"*
- *"Chip info"*
The agent uses the `hardware_board_info` tool to return chip name, architecture, and memory map. With the `probe` feature, it reads live data via USB/SWD; otherwise it returns static datasheet info.
**Config:** Add Nucleo to `config.toml` first (so the agent knows which board to query):
```toml
[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200
```
**CLI alternative:**
```bash
cargo build --features hardware,probe
zeroclaw hardware info
zeroclaw hardware discover
```
---
## What's Included (No Code Changes Needed)
ZeroClaw includes everything for Nucleo-F401RE:
| Component | Location | Purpose |
|-----------|----------|---------|
| Firmware | `firmware/nucleo/` | Embassy Rust — USART2 (115200), gpio_read, gpio_write |
| Serial peripheral | `src/peripherals/serial.rs` | JSON-over-serial protocol (same as Arduino/ESP32) |
| Flash command | `zeroclaw peripheral flash-nucleo` | Builds firmware, flashes via probe-rs |
Protocol: newline-delimited JSON. Request: `{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}`. Response: `{"id":"1","ok":true,"result":"done"}`.
---
## Prerequisites
- Nucleo-F401RE board
- USB cable (USB-A to Mini-USB; Nucleo has built-in ST-Link)
- For flashing: `cargo install probe-rs-tools --locked` (or use the [install script](https://probe.rs/docs/getting-started/installation/))
---
## Phase 1: Flash Firmware
### 1.1 Connect Nucleo
1. Connect Nucleo to your Mac/Linux via USB.
2. The board appears as a USB device (ST-Link). No separate driver needed on modern systems.
### 1.2 Flash via ZeroClaw
From the zeroclaw repo root:
```bash
zeroclaw peripheral flash-nucleo
```
This builds `firmware/nucleo` and runs `probe-rs run --chip STM32F401RETx`. The firmware runs immediately after flashing.
### 1.3 Manual Flash (Alternative)
```bash
cd firmware/nucleo
cargo build --release --target thumbv7em-none-eabihf
probe-rs run --chip STM32F401RETx target/thumbv7em-none-eabihf/release/nucleo
```
---
## Phase 2: Find Serial Port
- **macOS:** `/dev/cu.usbmodem*` or `/dev/tty.usbmodem*` (e.g. `/dev/cu.usbmodem101`)
- **Linux:** `/dev/ttyACM0` (or check `dmesg` after plugging in)
USART2 (PA2/PA3) is bridged to the ST-Link's virtual COM port, so the host sees one serial device.
---
## Phase 3: Configure ZeroClaw
Add to `~/.zeroclaw/config.toml`:
```toml
[peripherals]
enabled = true
[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/cu.usbmodem101" # adjust to your port
baud = 115200
```
---
## Phase 4: Run and Test
```bash
zeroclaw daemon --host 127.0.0.1 --port 42617
```
Or use the agent directly:
```bash
zeroclaw agent --message "Turn on the LED on pin 13"
```
Pin 13 = PA5 = User LED (LD2) on Nucleo-F401RE.
---
## Summary: Commands
| Step | Command |
|------|---------|
| 1 | Connect Nucleo via USB |
| 2 | `cargo install probe-rs-tools --locked` |
| 3 | `zeroclaw peripheral flash-nucleo` |
| 4 | Add Nucleo to config.toml (path = your serial port) |
| 5 | `zeroclaw daemon` or `zeroclaw agent -m "Turn on LED"` |
---
## Troubleshooting
- **flash-nucleo unrecognized** — Build from repo: `cargo run --features hardware -- peripheral flash-nucleo`. The subcommand is only in the repo build, not in crates.io installs.
- **probe-rs not found** — `cargo install probe-rs-tools --locked` (the `probe-rs` crate is a library; the CLI is in `probe-rs-tools`)
- **No probe detected** — Ensure Nucleo is connected. Try another USB cable/port.
- **Serial port not found** — On Linux, add user to `dialout`: `sudo usermod -a -G dialout $USER`, then log out/in.
- **GPIO commands ignored** — Check `path` in config matches your serial port. Run `zeroclaw peripheral list` to verify.