Adding Boards and Tools: ZeroClaw Hardware Guide

This guide explains how to add new hardware boards and custom tools to ZeroClaw.

Quick Start: Add a Board via CLI

sh

# Add a board
zeroclaw peripheral add nucleo-f401re /dev/ttyACM0
zeroclaw peripheral add arduino-uno /dev/cu.usbmodem12345
zeroclaw peripheral add rpi-gpio native   # for Raspberry Pi GPIO (Linux)

# Restart daemon to apply
zeroclaw daemon --host 127.0.0.1 --port 42617

Supported Boards

Boards are identified by USB VID/PID. The canonical registry:

Board	Architecture	USB VID:PID
`nucleo-f401re`	ARM Cortex-M4	`0x0483`:`0x374b`
`nucleo-f411re`	ARM Cortex-M4	`0x0483`:`0x3748`
`arduino-uno`	AVR ATmega328P	`0x2341`:`0x0043`
`arduino-uno`	Arduino Uno Q / ATmega328P	`0x2341`:`0x0078`
`arduino-mega`	AVR ATmega2560	`0x2341`:`0x0042`
`cp2102`	USB-UART bridge	`0x10c4`:`0xea60`
`cp2102n`	USB-UART bridge	`0x10c4`:`0xea70`
`esp32`	ESP32 (CH340)	`0x1a86`:`0x7523`
`esp32`	ESP32 (CH340)	`0x1a86`:`0x55d4`

The board value in [[peripherals.boards]] is matched against these registry names (and a few transport-specific aliases such as arduino-uno-q / rpi-gpio handled in peripherals/mod.rs).

Manual Config

Boards are configured under peripherals and peripherals.boards. See the Config reference for the full field index, including datasheet_dir (RAG source).

Place .md or .txt files in docs/datasheets/ (or your datasheet_dir). Name files by board: nucleo-f401re.md, arduino-uno.md. PDF datasheets are also indexed when ZeroClaw is built with the rag-pdf feature (this enables general PDF text extraction, not a hardware-specific capability; see Tools). Either way the files are extracted, chunked, and retrieved into the agent’s context for board-specific questions.

Pin Aliases (Recommended)

Add a ## Pin Aliases section so the agent can map “red led” → pin 13:

# My Board

## Pin Aliases

| alias       | pin |
|-------------|-----|
| red_led     | 13  |
| builtin_led | 13  |
| user_led    | 5   |

Or use key-value format:

## Pin Aliases
red_led: 13
builtin_led: 13

Adding a New Board Type

Create a datasheet: docs/datasheets/my-board.md with pin aliases and GPIO info.
Add to config: zeroclaw peripheral add my-board /dev/ttyUSB0
Implement a peripheral (optional): For custom protocols, implement the Peripheral trait in crates/zeroclaw-hardware/src/peripherals/ and register in create_peripheral_tools.

See docs/hardware/hardware-peripherals-design.md for the full design.

Adding a Custom Tool

Implement the Tool trait in crates/zeroclaw-tools/src/.
Register in create_peripheral_tools (for hardware tools) or the agent tool registry.
Add a tool description to the agent’s tool_descs in crates/zeroclaw-runtime/src/agent/loop_.rs.

CLI Reference

See the generated CLI reference for zeroclaw peripheral and zeroclaw hardware subcommands.

Troubleshooting

Serial port not found: On macOS use /dev/cu.usbmodem*; on Linux use /dev/ttyACM0 or /dev/ttyUSB0.
Build with hardware: cargo build --features hardware
Probe-rs for Nucleo: cargo build --features hardware,probe

ZeroClaw Docs