Raspberry Pi Setup

Raspberry Pi boards can run ZeroClaw natively with direct GPIO access—no firmware flashing required. This makes them ideal for edge-native AI agents and autonomous robots.

Supported Models

Model	RAM	Architecture	Status	Use Case
Raspberry Pi 5	4GB / 8GB	ARM Cortex-A76	✅ Recommended	Production robots, Ollama
Raspberry Pi 4	4GB / 8GB	ARM Cortex-A72	✅ Stable	General use
Raspberry Pi 3 B+	1GB	ARM Cortex-A53	✅ Stable	Light workloads
Raspberry Pi Zero 2 W	512MB	ARM Cortex-A53	✅ Stable	Constrained devices
Raspberry Pi Zero W	512MB	ARMv6	✅ Special build	Ultra-minimal

Quick Start

1. Build with GPIO Support

cd ~/zeroclaw

# Enable peripheral-rpi feature
cargo build --release --features peripheral-rpi

# Install binary
sudo cp target/release/zeroclaw /usr/local/bin/
zeroclaw --version

2. Configure GPIO Peripheral

# Add GPIO peripheral
zeroclaw peripheral add rpi-gpio native

# Or manually edit ~/.zeroclaw/config.toml

[peripherals]
enabled = true

[[peripherals.boards]]
board = "rpi-gpio"
transport = "native"  # No serial port needed

3. Set Up Permissions

# Add user to gpio group
sudo usermod -aG gpio $USER

# Logout and login for group change to take effect

4. Test GPIO

# Test GPIO read
zeroclaw agent -m "Read GPIO pin 17"

# Test GPIO write (LED on pin 18)
zeroclaw agent -m "Set GPIO pin 18 high"

GPIO Pin Reference

40-Pin Header (BCM Numbering)

ZeroClaw uses BCM pin numbering, not physical pin numbers.

     3V3  (1)  (2)  5V
   GPIO2  (3)  (4)  5V
   GPIO3  (5)  (6)  GND
   GPIO4  (7)  (8)  GPIO14
     GND  (9) (10)  GPIO15
  GPIO17 (11) (12)  GPIO18
  GPIO27 (13) (14)  GND
  GPIO22 (15) (16)  GPIO23
     3V3 (17) (18)  GPIO24
  GPIO10 (19) (20)  GND
   GPIO9 (21) (22)  GPIO25
  GPIO11 (23) (24)  GPIO8
     GND (25) (26)  GPIO7
   GPIO0 (27) (28)  GPIO1
   GPIO5 (29) (30)  GND
   GPIO6 (31) (32)  GPIO12
  GPIO13 (33) (34)  GND
  GPIO19 (35) (36)  GPIO16
  GPIO26 (37) (38)  GPIO20
     GND (39) (40)  GPIO21

Common Pins

Function	BCM Pins	Notes
General GPIO	2-27 (except special)	Any digital I/O
I2C	GPIO 2 (SDA), GPIO 3 (SCL)	Default I2C bus
SPI	GPIO 9 (MISO), GPIO 10 (MOSI), GPIO 11 (SCLK)	Hardware SPI0
PWM	GPIO 12, 13, 18, 19	Hardware PWM
UART	GPIO 14 (TX), GPIO 15 (RX)	Serial console

Do not use:

GPIO 0, 1: Reserved for HAT EEPROM
GPIO 14, 15: Serial console (unless disabled)
5V or 3.3V pins: Power only, not GPIO

Wiring Examples

LED Blink

Raspberry Pi         LED
────────────         ───
GPIO 18 ─────────┬──▶│
                 │    └─── GND
                 └─── 220Ω resistor

# Turn LED on
zeroclaw agent -m "Set GPIO 18 high"

# Turn LED off
zeroclaw agent -m "Set GPIO 18 low"

Button Input

Raspberry Pi         Button
────────────         ──────
GPIO 17 ─────────────┤  ├──── 3.3V
GND ─────────────────┤  ├
                     └──┘

# Read button state
zeroclaw agent -m "Read GPIO pin 17"

Motor Controller (L298N)

Raspberry Pi         L298N Motor Driver
────────────         ──────────────────
GPIO 12 (PWM) ──────▶ ENA
GPIO 17 ────────────▶ IN1
GPIO 27 ────────────▶ IN2
GPIO 13 (PWM) ──────▶ ENB
GPIO 22 ────────────▶ IN3
GPIO 23 ────────────▶ IN4
GND ────────────────── GND
5V (from battery) ──── 12V (motor power)

Building on Raspberry Pi Zero W

The Pi Zero W (512MB RAM, ARMv6) requires special consideration:

Add Swap Space

# Create 2GB swap file (mandatory for compilation)
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make persistent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Install Dependencies

sudo apt update
sudo apt install -y build-essential pkg-config libssl-dev git curl

Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Build for musleabihf (Recommended)

# Add musl target
rustup target add armv6l-unknown-linux-musleabihf

# Build (takes 30-60 minutes)
export CARGO_BUILD_JOBS=1
cargo build --release --target armv6l-unknown-linux-musleabihf --features peripheral-rpi

# Install
sudo cp target/armv6l-unknown-linux-musleabihf/release/zeroclaw /usr/local/bin/

Cross-compilation from a faster machine is highly recommended. See the Raspberry Pi Zero W Build Guide for details.

GPIO Tools

ZeroClaw exposes these GPIO tools to agents:

`gpio_read`

Read the value (0 or 1) of a GPIO pin. Parameters:

pin (integer): BCM GPIO pin number (2-27)

Example:

zeroclaw agent -m "What is the value of GPIO 17?"

`gpio_write`

Set a GPIO pin high (1) or low (0). Parameters:

pin (integer): BCM GPIO pin number
value (integer): 0 for LOW, 1 for HIGH

Example:

zeroclaw agent -m "Set GPIO 18 to high"

Robot Kit Integration

For building autonomous robots on Raspberry Pi, see the Robot Kit documentation. Key features:

Local Ollama for offline AI
Camera vision (moondream)
Speech (Whisper + Piper)
Motor control via GPIO
LIDAR obstacle avoidance

Troubleshooting

”Permission denied” when accessing GPIO

# Check groups
groups

# Add to gpio group
sudo usermod -aG gpio $USER

# Logout and login

”Failed to connect RPi GPIO”

# Verify rppal works
python3 << EOF
import RPi.GPIO as GPIO
GPIO.setmode(GPIO.BCM)
print("GPIO OK")
GPIO.cleanup()
EOF

# Ensure feature is enabled
cargo build --features peripheral-rpi

Pin already in use

# Check what's using GPIO
sudo lsof | grep gpiochip

# Kill process or reboot

Build fails on Pi Zero W

# Check swap is active
free -h

# Increase swap to 4GB if needed
sudo swapoff /swapfile
sudo rm /swapfile
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

Performance Tips

Use NVMe on Pi 5: Much faster than SD cards
Active cooling: Prevents thermal throttling
Overclock (optional): Add to /boot/config.txt:
```
arm_freq=2000  # Pi 5
over_voltage=6
```
Disable desktop: Use Raspberry Pi OS Lite
Static build: Use musleabihf target for smaller binaries

Overview

Peripherals

Robot Kit

Raspberry Pi Setup

Raspberry Pi Setup

Supported Models

Quick Start

1. Build with GPIO Support

2. Configure GPIO Peripheral

3. Set Up Permissions

4. Test GPIO

GPIO Pin Reference

40-Pin Header (BCM Numbering)

Common Pins

Wiring Examples

LED Blink

Button Input

Motor Controller (L298N)

Building on Raspberry Pi Zero W

Add Swap Space

Install Dependencies

Install Rust

Build for musleabihf (Recommended)

GPIO Tools

`gpio_read`

`gpio_write`

Robot Kit Integration

Troubleshooting

”Permission denied” when accessing GPIO

”Failed to connect RPi GPIO”

Pin already in use

Build fails on Pi Zero W

Performance Tips

Next Steps

Robot Kit Setup

Supported Boards

Hardware Architecture

Robot Kit API

Reference

Build docs developers (and LLMs) love

Overview

Peripherals

Robot Kit

Documentation Index

​Raspberry Pi Setup

​Supported Models

​Quick Start

​1. Build with GPIO Support

​2. Configure GPIO Peripheral

​3. Set Up Permissions

​4. Test GPIO

​GPIO Pin Reference

​40-Pin Header (BCM Numbering)

​Common Pins

​Wiring Examples

​LED Blink

​Button Input

​Motor Controller (L298N)

​Building on Raspberry Pi Zero W

​Add Swap Space

​Install Dependencies

​Install Rust

​Build for musleabihf (Recommended)

​GPIO Tools

​gpio_read

​gpio_write

​Robot Kit Integration

​Troubleshooting

​”Permission denied” when accessing GPIO

​”Failed to connect RPi GPIO”

​Pin already in use

​Build fails on Pi Zero W

​Performance Tips

​Next Steps

Robot Kit Setup

Supported Boards

Hardware Architecture

Robot Kit API

​Reference

Build docs developers (and LLMs) love

Raspberry Pi Setup

Supported Models

Quick Start

1. Build with GPIO Support

2. Configure GPIO Peripheral

3. Set Up Permissions

4. Test GPIO

GPIO Pin Reference

40-Pin Header (BCM Numbering)

Common Pins

Wiring Examples

LED Blink

Button Input

Motor Controller (L298N)

Building on Raspberry Pi Zero W

Add Swap Space

Install Dependencies

Install Rust

Build for musleabihf (Recommended)

GPIO Tools

`gpio_read`

`gpio_write`

Robot Kit Integration

Troubleshooting

”Permission denied” when accessing GPIO

”Failed to connect RPi GPIO”

Pin already in use

Build fails on Pi Zero W

Performance Tips

Next Steps

Reference