docs/book/src/hardware/hardware-peripherals-design.md
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.
Goal: ZeroClaw acts as a hardware-aware AI agent that:
Mental model: ZeroClaw = brain that understands hardware. Peripherals = arms and legs it controls.
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:
All happens on-device. No host required.
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:
Or:
Or:
| 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. |
For boards without WiFi or before full Edge-Native is ready:
Host runs ZeroClaw; peripheral runs minimal firmware. Simple JSON over serial.
ZeroClaw on Pi; GPIO via rppal or sysfs. No separate firmware.
| 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.). |
| 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.
See the CLI reference for zeroclaw hardware / zeroclaw peripheral subcommands and the Config reference for the [peripherals] and [[peripherals.boards]] fields.
Peripheral/// 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>>;
}
peripherals.boards.Peripheral impl, call connect().gpio_write, sensor_read, etc. — these delegate to the peripheral.disconnect() on each peripheral.| 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 |
For low-latency, typed RPC between ZeroClaw and peripherals:
GpioWrite, GpioRead, I2cTransfer, SpiTransfer, MemoryRead, FlashWrite, etc..proto files.Simple JSON over serial for boards without gRPC support:
Request (host → peripheral):
{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}
Response (peripheral → host):
{"id":"1","ok":true,"result":"done"}
thumbv7em-none-eabihf (STM32), armv7-unknown-linux-gnueabihf (RPi), etc.embassy or Zephyr for STM32.Peripheral trait, config schema, CLI (zeroclaw peripheral list/add)--peripheral flag to agentzeroclaw hardware discover: enumerate USB devices (VID/PID)zeroclaw hardware introspect <path>: memory map, peripheral listSerialPeripheral for STM32 over USB CDCgpio_read, gpio_write (memory_read, flash_write in future)Usage: zeroclaw config set peripherals.datasheet-dir docs/datasheets. 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.
esp32 firmware crate (firmware/esp32) — GPIO over UARTUsage: Flash firmware/esp32 to ESP32, add board = "esp32", transport = "serial", path = "/dev/ttyUSB0" to config.
path is in allowlist (e.g. /dev/ttyACM*, /dev/ttyUSB*); never arbitrary paths."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."