Skip to content

index.md

Latest commit

 

History

History
104 lines (71 loc) · 3.74 KB

index.md

File metadata and controls

104 lines (71 loc) · 3.74 KB
Raw

Hardware — Overview

ZeroClaw's hardware subsystem lets the agent control microcontrollers, SBCs, and peripherals directly. Enable with --features hardware.

What's supported

Target Protocol Page
STM32 Nucleo (F401RE, others) Serial / OpenOCD STM32 Nucleo
Arduino Uno Q Serial / USB Arduino Uno Q
Raspberry Pi GPIO / I2C / SPI (via /dev/gpiochip*, /dev/i2c-*, /dev/spidev*) Covered by peripherals design
Aardvark I2C/SPI host adapter USB Aardvark
Android (via Termux) Serial-over-USB / Bluetooth Android
Generic boards Peripheral trait Adding boards & tools

See Peripherals design for the architecture.

Enabling

At compile time:

cargo build --release --features hardware

Or, if you want only specific boards:

cargo build --release --features "hardware board-nucleo board-arduino"

Runtime tools

With the feature enabled, the agent gains these tools:

  • gpio_read / gpio_write — digital I/O
  • i2c_read / i2c_write — I2C bus access
  • spi_transfer — SPI transfers
  • adc_read — analogue reads (where supported)
  • peripheral_probe — discover attached boards and sensors
  • peripheral_flash — flash firmware to a connected microcontroller

All tool invocations go through the same security policy as any other tool. Hardware tools only reach the device paths explicitly listed in [[peripherals.boards]] entries:

[peripherals]
enabled = true

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

Running on a Raspberry Pi

The most common hardware target. A minimal setup:

# install
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash

# add yourself to hardware groups (re-login after)
sudo usermod -aG gpio,spi,i2c $USER

# install as user service (ensures hardware group membership is inherited)
zeroclaw service install

The stock systemd unit sets SupplementaryGroups=gpio spi i2c.

Safety

Hardware tools can brick things. Real, expensive things.

  • peripheral_flash writes firmware — a bad image can brick the board. The tool requires operator approval at Supervised autonomy regardless of autonomy level; there's no way to auto-approve it.
  • i2c_write / spi_transfer to device addresses the agent doesn't know can damage sensors.
  • GPIO writes that conflict with external drivers (voltage fights) damage pins.

For production deployments with untrusted channels exposed, disable hardware tools per channel:

[channels.public-discord]
tools_deny = ["gpio_write", "i2c_write", "spi_transfer", "peripheral_flash"]

Datasheets

Per-board pin maps and electrical characteristics:

Adding new hardware

See Adding boards & tools for the step-by-step. TL;DR: implement the Peripheral trait from crates/zeroclaw-hardware/src/, add a board-specific feature flag, write a probe routine that identifies the board from USB descriptors or serial handshake.

See also