Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/openagen/zeroclaw/llms.txt

Use this file to discover all available pages before exploring further.

ZeroClaw’s hardware subsystem lets the agent directly control microcontrollers and SBCs by exposing each board’s capabilities as tools (gpio_read, gpio_write, adc_read, and more). The connection between ZeroClaw and a peripheral follows a defined Peripheral trait so new boards can be added without changing the agent loop.

​
Two modes of operation

​
Edge-native (standalone)

ZeroClaw runs directly on the device (ESP32, Raspberry Pi). The runtime spins up a local gRPC/nanoRPC server and communicates with peripherals over GPIO, I2C, and SPI. No host is required. Workflow:
  1. User sends a message: “Turn on LED on pin 13”
  2. ZeroClaw fetches board-specific docs from the local datasheet index (RAG pipeline)
  3. LLM synthesizes the action using retrieved register maps and pinout data
  4. GPIO is toggled; result returned to the user
  5. Optimized code is persisted for future identical requests

​
Host-mediated (development and debugging)

ZeroClaw runs on a host machine (macOS, Linux) and controls the target over USB, J-Link, or Aardvark. This is the standard path for STM32 Nucleo and other MCUs without WiFi. Workflow:
  1. User asks: “What readable memory addresses are on this USB device?”
  2. ZeroClaw identifies the connected hardware via VID/PID
  3. Performs memory mapping and returns available address spaces
  4. User can then flash firmware or issue GPIO commands
AspectEdge-nativeHost-mediated
ZeroClaw runs onDevice (ESP32, RPi)Host (Mac, Linux)
Hardware linkLocal (GPIO, I2C, SPI)USB, J-Link, Aardvark
Use caseProduction, standaloneDev, debug, introspection

​
STM32 Nucleo-F401RE setup

The Nucleo-F401RE ships with a built-in ST-Link debugger over USB, so no separate debug probe is needed. ZeroClaw includes Embassy-based firmware (firmware/nucleo/) and a flash-nucleo subcommand that builds and flashes it in one step.

​
Prerequisites

  • Nucleo-F401RE board with USB-A to Mini-USB cable
  • probe-rs CLI for flashing: cargo install probe-rs-tools --locked
The probe-rs crate is a library; the CLI tools are in probe-rs-tools. Install probe-rs-tools, not probe-rs.

​
Flashing firmware

1

Connect the Nucleo

Connect the board to your Mac or Linux host via USB. The ST-Link appears as a USB device; no additional driver is needed on modern systems.
2

Flash via ZeroClaw

From the repository root:
zeroclaw peripheral flash-nucleo
This builds firmware/nucleo targeting thumbv7em-none-eabihf and runs probe-rs run --chip STM32F401RETx. The firmware starts immediately after flashing.
flash-nucleo is available in repo builds only, not in crates.io installs. If you installed from crates.io, build from source: cargo run --features hardware -- peripheral flash-nucleo
3

Manual flash (alternative)

cargo build --release --target thumbv7em-none-eabihf
probe-rs run --chip STM32F401RETx target/thumbv7em-none-eabihf/release/nucleo
4

Find the serial port

ls /dev/cu.usbmodem*
# e.g. /dev/cu.usbmodem101
USART2 (PA2/PA3) is bridged through the ST-Link’s virtual COM port, so only one serial device appears on the host.
5

Configure ZeroClaw

Add the board to ~/.zeroclaw/config.toml:
[peripherals]
enabled = true

[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/cu.usbmodem101"   # adjust to your port
baud = 115200
6

Run and test

Start the daemon:
zeroclaw daemon --host 127.0.0.1 --port 42617
Or send a command directly to the agent:
zeroclaw agent --message "Turn on the LED on pin 13"
Pin 13 maps to PA5, which is the User LED (LD2) on the Nucleo-F401RE.

​
What’s included for Nucleo-F401RE

ComponentLocationPurpose
Firmwarefirmware/nucleo/Embassy Rust — USART2 at 115200 baud, gpio_read, gpio_write
Serial peripheralsrc/peripherals/serial.rsJSON-over-serial protocol (shared with Arduino and ESP32)
Flash commandzeroclaw peripheral flash-nucleoBuilds firmware and flashes via probe-rs

​
Serial protocol

Communication between ZeroClaw and the firmware uses newline-delimited JSON: 
{"id":"1","cmd":"gpio_write","args":{"pin":13,"value":1}}

​
Board info without flashing

ZeroClaw can read chip information over USB without any firmware on the board. From the CLI: 
cargo build --features hardware,probe
zeroclaw hardware info
zeroclaw hardware discover
Or via the Telegram bot, send: “What board info do I have?” — the agent uses hardware_board_info to return chip name, architecture, and memory map. With the probe feature enabled it reads live data via USB/SWD; without it, it returns static datasheet information.

​
Raspberry Pi GPIO

ZeroClaw runs natively on Raspberry Pi and accesses GPIO through rppal or sysfs. No separate firmware is needed.

​
Build with RPi GPIO support

cargo build --release --features hardware,peripheral-rpi

​
Configuration

[peripherals]
enabled = true

[[peripherals.boards]]
board = "rpi-gpio"
transport = "native"
With this configuration the agent exposes gpio_read and gpio_write tools over the Pi’s physical pins.

​
USB device discovery

ZeroClaw uses nusb for USB enumeration. It maps VID/PID to known boards (architecture, name, transport) via a built-in registry. 
# List all connected USB devices with VID/PID and matched board name
zeroclaw hardware discover

# Inspect a specific device for memory map and peripheral list
zeroclaw hardware introspect /dev/ttyACM0
USB discovery via nusb is not available when ZeroClaw is running on Android (target_os = "android"). Run discovery from a macOS or Linux host instead.

​
probe-rs memory introspection

With the probe feature, ZeroClaw can read live chip data over USB/SWD using probe-rs: 
cargo build --features hardware,probe
zeroclaw hardware info        # chip name, architecture, memory map
zeroclaw hardware introspect  # full peripheral and register list
The hardware_board_info agent tool uses probe-rs when the feature is present, falling back to static datasheet data otherwise.

​
Serial port peripheral (tokio-serial)

Serial communication for all boards (STM32, ESP32, Arduino) is handled by src/peripherals/serial.rs using tokio-serial. The same JSON-over-serial protocol works across all supported boards — only the board value in config changes.

​
Peripheral trait: extension points

To add a new board, implement Peripheral from src/peripherals/traits.rs: 
#[async_trait]
pub trait Peripheral: Send + Sync {
    fn name(&self) -> &str;
    fn board_type(&self) -> &str;
    async fn connect(&mut self) -> anyhow::Result<()>;
    async fn disconnect(&mut self) -> anyhow::Result<()>;
    async fn health_check(&self) -> bool;
    fn tools(&self) -> Vec<Box<dyn Tool>>;
}
Startup flow:
  1. ZeroClaw reads peripherals.boards from config
  2. Creates a Peripheral impl for each board and calls connect()
  3. Collects all tools from connected peripherals and merges them with the default tool set
  4. The agent loop calls gpio_write, sensor_read, etc. — these delegate to the peripheral impl
  5. On shutdown, disconnect() is called on each peripheral
See docs/contributing/adding-boards-and-tools.md in the repository for the step-by-step guide on registering new boards and datasheets.

​
Troubleshooting

This command is only available in repo builds. Build from source:
cargo run --features hardware -- peripheral flash-nucleo
Install the CLI tools crate (not the library):
cargo install probe-rs-tools --locked
Ensure the Nucleo is connected and try a different USB cable or port. The board must be powered (the ST-Link LED should be on).
Add your user to the dialout group, then log out and back in:
sudo usermod -a -G dialout $USER
Verify with zeroclaw peripheral list after reconnecting.
Check that the path in config.toml matches your actual serial port. Run zeroclaw peripheral list to see what ZeroClaw has detected.

Build docs developers (and LLMs) love

Get started for freeTalk to us