de3ec87d16
* 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>
116 lines
3.3 KiB
Markdown
116 lines
3.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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`:
|
|
|
|
```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:
|
|
|
|
```markdown
|
|
# My Board
|
|
|
|
## Pin Aliases
|
|
|
|
| alias | pin |
|
|
|-------------|-----|
|
|
| red_led | 13 |
|
|
| builtin_led | 13 |
|
|
| user_led | 5 |
|
|
```
|
|
|
|
Or use key-value format:
|
|
|
|
```markdown
|
|
## Pin Aliases
|
|
red_led: 13
|
|
builtin_led: 13
|
|
```
|
|
|
|
### PDF Datasheets
|
|
|
|
With the `rag-pdf` feature, ZeroClaw can index PDF files:
|
|
|
|
```bash
|
|
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`
|