Hardware — Overview

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

What's supported

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. Restrict device access via:

[security.sandbox]
allow_devices = ["/dev/gpiochip0", "/dev/i2c-1", "/dev/ttyUSB0"]

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:

• STM32 Nucleo-F401RE: https://www.st.com/en/evaluation-tools/nucleo-f401re.html
• Arduino Uno Q: https://docs.arduino.cc/hardware/uno-q
• Raspberry Pi GPIO: https://www.raspberrypi.com/documentation/computers/raspberry-pi.html#gpio
• ESP32: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf

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

• Peripherals design — the architecture
• Adding boards & tools — implementation guide
• Aardvark — USB I2C/SPI host adapter setup