harald/zeroclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 3
zeroclaw/docs/adding-boards-and-tools.md
ehu shubham shaw de3ec87d16
Ehu shubham shaw contribution --> Hardware support (#306) 
* feat: add ZeroClaw firmware for ESP32 and Nucleo

* Introduced new firmware for ZeroClaw on ESP32 and Nucleo-F401RE, enabling JSON-over-serial communication for GPIO control.
* Added `zeroclaw-esp32` with support for commands like `gpio_read` and `gpio_write`, along with capabilities reporting.
* Implemented `zeroclaw-nucleo` firmware with similar functionality for STM32, ensuring compatibility with existing ZeroClaw protocols.
* Updated `.gitignore` to include new firmware targets and added necessary dependencies in `Cargo.toml` for both platforms.
* Created README files for both firmware projects detailing setup, build, and usage instructions.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

* feat: enhance hardware peripheral support and documentation

- Added `Peripheral` trait implementation in `src/peripherals/` to manage hardware boards (STM32, RPi GPIO).
- Updated `AGENTS.md` to include new extension points for peripherals and their configuration.
- Introduced comprehensive documentation for adding boards and tools, including a quick start guide and supported boards.
- Enhanced `Cargo.toml` to include optional dependencies for PDF extraction and peripheral support.
- Created new datasheets for Arduino Uno, ESP32, and Nucleo-F401RE, detailing pin aliases and GPIO usage.
- Implemented new tools for hardware memory reading and board information retrieval in the agent loop.

This update significantly improves the integration and usability of hardware peripherals within the ZeroClaw framework.

* feat: add ZeroClaw firmware for ESP32 and Nucleo

* Introduced new firmware for ZeroClaw on ESP32 and Nucleo-F401RE, enabling JSON-over-serial communication for GPIO control.
* Added `zeroclaw-esp32` with support for commands like `gpio_read` and `gpio_write`, along with capabilities reporting.
* Implemented `zeroclaw-nucleo` firmware with similar functionality for STM32, ensuring compatibility with existing ZeroClaw protocols.
* Updated `.gitignore` to include new firmware targets and added necessary dependencies in `Cargo.toml` for both platforms.
* Created README files for both firmware projects detailing setup, build, and usage instructions.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

* feat: enhance hardware peripheral support and documentation

- Added `Peripheral` trait implementation in `src/peripherals/` to manage hardware boards (STM32, RPi GPIO).
- Updated `AGENTS.md` to include new extension points for peripherals and their configuration.
- Introduced comprehensive documentation for adding boards and tools, including a quick start guide and supported boards.
- Enhanced `Cargo.toml` to include optional dependencies for PDF extraction and peripheral support.
- Created new datasheets for Arduino Uno, ESP32, and Nucleo-F401RE, detailing pin aliases and GPIO usage.
- Implemented new tools for hardware memory reading and board information retrieval in the agent loop.

This update significantly improves the integration and usability of hardware peripherals within the ZeroClaw framework.

* feat: Introduce hardware auto-discovery and expanded configuration options for agents, hardware, and security.

* chore: update dependencies and improve probe-rs integration

- Updated `Cargo.lock` to remove specific version constraints for several dependencies, including `zerocopy`, `syn`, and `strsim`, allowing for more flexibility in version resolution.
- Upgraded `bincode` and `bitfield` to their latest versions, enhancing serialization and memory management capabilities.
- Updated `Cargo.toml` to reflect the new version of `probe-rs` from `0.24` to `0.30`, improving hardware probing functionality.
- Refactored code in `src/hardware` and `src/tools` to utilize the new `SessionConfig` for session management in `probe-rs`, ensuring better compatibility and performance.
- Cleaned up documentation in `docs/datasheets/nucleo-f401re.md` by removing unnecessary lines.

* fix: apply cargo fmt

* docs: add hardware architecture diagram.

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-16 11:40:10 -05:00

3.3 KiB
Raw Blame History

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

# Add a board (updates ~/.zeroclaw/config.toml)
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 8080

Supported Boards

Board Transport Path Example
nucleo-f401re serial /dev/ttyACM0, /dev/cu.usbmodem*
arduino-uno serial /dev/ttyACM0, /dev/cu.usbmodem*
arduino-uno-q bridge (Uno Q IP)
rpi-gpio native native
esp32 serial /dev/ttyUSB0

Manual Config

Edit ~/.zeroclaw/config.toml:

[peripherals]
enabled = true
datasheet_dir = "docs/datasheets"   # optional: RAG for "turn on red led" → pin 13

[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200

[[peripherals.boards]]
board = "arduino-uno"
transport = "serial"
path = "/dev/cu.usbmodem12345"
baud = 115200

Adding a Datasheet (RAG)

Place .md or .txt files in docs/datasheets/ (or your datasheet_dir). Name files by board: nucleo-f401re.md, arduino-uno.md.

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

PDF Datasheets

With the rag-pdf feature, ZeroClaw can index PDF files:

cargo build --features hardware,rag-pdf

Place PDFs in the datasheet directory. They are extracted and chunked for RAG.

Adding a New Board Type

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

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

Adding a Custom Tool

  1. Implement the Tool trait in src/tools/.
  2. Register in create_peripheral_tools (for hardware tools) or the agent tool registry.
  3. Add a tool description to the agent's tool_descs in src/agent/loop_.rs.

CLI Reference

Command Description
zeroclaw peripheral list List configured boards
zeroclaw peripheral add <board> <path> Add board (writes config)
zeroclaw peripheral flash Flash Arduino firmware
zeroclaw peripheral flash-nucleo Flash Nucleo firmware
zeroclaw hardware discover List USB devices
zeroclaw hardware info Chip info via probe-rs

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