zeroclaw/crates/robot-kit/README.md

ZeroClaw Robot Kit

A complete toolkit for building AI-powered robots with ZeroClaw. Designed for Raspberry Pi deployment with offline Ollama inference.

Features

Tool	Description
drive	Omni-directional movement (forward, strafe, rotate)
look	Camera capture + vision model description
listen	Speech-to-text via Whisper.cpp
speak	Text-to-speech via Piper TTS
sense	LIDAR, motion sensors, ultrasonic distance
emote	LED expressions and sound effects

Architecture

┌─────────────────────────────────────────────────────────┐
│                 ZeroClaw + Ollama                       │
│              (High-Level AI Brain)                      │
└─────────────────────┬───────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        ▼             ▼             ▼
   ┌─────────┐  ┌──────────┐  ┌──────────┐
   │ drive   │  │  look    │  │  speak   │
   │ sense   │  │  listen  │  │  emote   │
   └────┬────┘  └────┬─────┘  └────┬─────┘
        │            │             │
        ▼            ▼             ▼
   ┌─────────────────────────────────────┐
   │        Hardware Layer               │
   │  Motors, Camera, Mic, Speaker, LEDs │
   └─────────────────────────────────────┘

Hardware Requirements

Minimum

• Raspberry Pi 4 (4GB) or Pi 5
• USB webcam
• USB microphone
• Speaker with amp
• Motor controller (L298N, TB6612, etc.)
• 4 DC motors + omni wheels

Recommended

• Raspberry Pi 5 (8GB)
• RPLidar A1 for obstacle avoidance
• LED matrix (8x8) for expressions
• PIR motion sensors
• HC-SR04 ultrasonic sensor

Software Dependencies

# Install on Raspberry Pi OS

# Audio
sudo apt install alsa-utils pulseaudio

# Camera
sudo apt install ffmpeg fswebcam

# Ollama (local LLM)
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama3
ollama pull moondream  # Vision model

# Whisper.cpp (speech-to-text)
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp && make
sudo cp main /usr/local/bin/whisper-cpp
bash ./models/download-ggml-model.sh base

# Piper TTS (text-to-speech)
pip install piper-tts
# Or download binary from github.com/rhasspy/piper/releases

# ROS2 (optional, for advanced robotics)
# See: docs.ros.org/en/humble/Installation.html

Quick Start

1. Build ZeroClaw with robot tools

# Clone and build
git clone https://github.com/your/zeroclaw
cd zeroclaw
cargo build --release

# Copy robot kit to src/tools/
cp -r examples/robot_kit src/tools/
# Add to src/tools/mod.rs (see Integration section)

2. Configure

# Copy config
mkdir -p ~/.zeroclaw
cp examples/robot_kit/robot.toml ~/.zeroclaw/
cp examples/robot_kit/SOUL.md ~/.zeroclaw/workspace/

# Edit for your hardware
nano ~/.zeroclaw/robot.toml

3. Test

# Start Ollama
ollama serve &

# Test in mock mode
./target/release/zeroclaw agent -m "Say hello and show a happy face"

# Test with real hardware
# (after configuring robot.toml)
./target/release/zeroclaw agent -m "Move forward 1 meter"

Integration

Add to src/tools/mod.rs:

mod robot_kit;

pub fn robot_tools(config: &RobotConfig) -> Vec<Arc<dyn Tool>> {
    vec![
        Arc::new(robot_kit::DriveTool::new(config.clone())),
        Arc::new(robot_kit::LookTool::new(config.clone())),
        Arc::new(robot_kit::ListenTool::new(config.clone())),
        Arc::new(robot_kit::SpeakTool::new(config.clone())),
        Arc::new(robot_kit::SenseTool::new(config.clone())),
        Arc::new(robot_kit::EmoteTool::new(config.clone())),
    ]
}

Usage Examples

Play Hide and Seek

User: Let's play hide and seek!
Robot:
  1. emote(expression="excited")
  2. speak(text="Okay! I'll count to 20. Go hide!")
  3. [waits 20 seconds]
  4. speak(text="Ready or not, here I come!")
  5. sense(action="scan")
  6. drive(action="forward", distance=1)
  7. look(action="find", prompt="a child hiding")
  ...

Patrol Mode

User: Patrol the living room
Robot:
  1. sense(action="scan", direction="all")
  2. drive(action="forward", distance=2)
  3. sense(action="motion")
  4. look(action="describe")
  5. [repeat]

Interactive Conversation

User: [speaks] "Hey Buddy, what do you see?"
Robot:
  1. listen(duration=5) → "Hey Buddy, what do you see?"
  2. look(action="describe")
  3. speak(text="I see a couch, a TV, and some toys on the floor!")
  4. emote(expression="happy")

Creating a Bootable USB Tarball

# Package everything needed
mkdir zeroclaw-robot-kit
cp -r target/release/zeroclaw zeroclaw-robot-kit/
cp -r examples/robot_kit zeroclaw-robot-kit/
cp -r ~/.zeroclaw zeroclaw-robot-kit/dot-zeroclaw

# Include models
mkdir -p zeroclaw-robot-kit/models
cp ~/.zeroclaw/models/ggml-base.bin zeroclaw-robot-kit/models/
# Note: Ollama models are large, may want to download on target

# Create tarball
tar -czvf zeroclaw-robot-kit.tar.gz zeroclaw-robot-kit/

# Copy to USB
cp zeroclaw-robot-kit.tar.gz /media/usb/TarBalls/

Safety Notes

1. Test in mock mode first - Always verify behavior before enabling real motors
2. Set conservative speed limits - Start with max_speed = 0.3
3. Use emergency stop - Wire a physical E-stop button to the GPIO pin
4. Supervise with children - Robot is a toy, not a babysitter
5. Obstacle avoidance - Enable LIDAR if available, or keep confirm_movement = true

License

MIT - Same as ZeroClaw