Claudzmo

CLI tool for controlling Anki Cozmo robot via PyCozmo.

Direct WiFi control - no phone or USB bridge required!

Features

• 🤖 Movement - Drive, turn, head/lift positioning
• 😊 Expressions - 15 preset emotions with smooth 30fps animations
• 🗣️ Speech - Text-to-speech with macOS voice synthesis
• 📷 Camera - Live 320x240 camera feed
• 🔋 Status - Battery, firmware, hardware info
• ⚡ Fast & Reliable - Fresh connection per command, audio works consistently

Quick Start

Prerequisites

1. Anki Cozmo robot (powered on)
2. Connect computer to Cozmo's WiFi network (Cozmo_XXXXX)
3. Python 3.6+ with pip

Installation

# Clone repository
git clone https://gitea.kostverse.com/matt/claudzmo.git
cd claudzmo

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Download PyCozmo resources (required!)
pycozmo_resources.py download

# Make executable
chmod +x claudzmo

# Optional: Add to PATH
ln -s $(pwd)/claudzmo ~/bin/claudzmo

Test Connection

./claudzmo status

Usage

Movement

# Move forward/backward
claudzmo move --distance 200 --speed 50

# Turn in place
claudzmo turn --angle 90

# Set head angle (-25 to 44 degrees)
claudzmo head --angle 30

# Set lift height (0 to 66mm)
claudzmo lift --height 50

# Emergency stop
claudzmo stop

Expressions & Speech

# Display facial expression
claudzmo expression --name happiness --duration 1500

# Available expressions:
# neutral, happiness, sadness, anger, surprise, disgust, fear,
# pleading, vulnerability, despair, guilt, amazement, excitement,
# confusion, skepticism

# Speak text
claudzmo speak --text "Hello Matt!"
claudzmo speak --text "I'm Claudzmo!" --volume 65535

Camera & Status

# Get camera image (returns JSON with base64 image)
claudzmo camera --format jpeg

# Get robot status
claudzmo status

Examples

Greet someone

claudzmo expression --name excitement --duration 1500
claudzmo speak --text "Hi Nicole, Matt got me Claudzmo to work with Claude!"

Dance around

claudzmo move --distance 100 --speed 50
claudzmo turn --angle 90
claudzmo head --angle 35
claudzmo lift --height 50
claudzmo expression --name happiness --duration 2000

Take a selfie

claudzmo head --angle 20
claudzmo expression --name happiness --duration 1000
claudzmo camera --format jpeg > cozmo_selfie.json

Claude Code Skill

Claudzmo includes a skill for Claude Code integration.

Setup

# Copy skill to Claude Code skills directory
cp claudzmo.skill.md ~/.claude/skills/claudzmo.md

# Restart Claude Code
claude /restart

Usage in Claude Code

Just ask Claude to control Cozmo:

• "Make Cozmo say hello"
• "Have Cozmo turn left and look up"
• "Show me what Cozmo's camera sees"
• "Make Cozmo do a happy dance"

Claude will automatically use the claudzmo skill to control the robot!

Architecture

Why CLI instead of MCP?

Originally built as an MCP server, but audio playback was unreliable with persistent connections. The CLI approach:

• ✅ Uses pycozmo.connect() context manager (proven reliable)
• ✅ Fresh connection per command (no state issues)
• ✅ Audio works 100% consistently
• ✅ Simpler to debug and test
• ✅ Fast enough (~1 second per command)

How It Works

1. Connection - Each command creates fresh pycozmo.Client() connection
2. Command execution - Sends appropriate PyCozmo API calls
3. Audio - Uses macOS say → convert to 22kHz 16-bit mono WAV → play via Cozmo
4. Expressions - Renders 128x64 procedural faces → downsample to 128x32 → animate at 30fps
5. Cleanup - Connection closes automatically (context manager)

Technical Details

Audio Format

Cozmo requires:

• Sample rate: 22,050 Hz
• Bit depth: 16-bit PCM
• Channels: Mono
• Format: WAV

The CLI handles conversion automatically using macOS afconvert.

Volume Range

Volume is 16-bit (0-65535):

• 65535 = Maximum volume
• 50000 = ~75% volume
• 32768 = ~50% volume

Connection

• IP: 172.31.1.1 (Cozmo's default)
• Port: 5106 (UDP)
• Auto-discovery via PyCozmo
• Firmware: 2381 (tested)

Troubleshooting

"Failed to connect to Cozmo"

1. Check Cozmo is powered on (press button on back)
2. Verify connected to Cozmo's WiFi network
3. Wait a moment between commands (connection cooldown)

Audio not playing

1. Check volume: --volume 65535 for max
2. Verify text is being spoken (test with macOS say command)
3. Ensure afconvert is available (comes with macOS)

"No camera image available"

Camera takes ~1 second to initialize. Wait and retry.

Development

Project Structure

claudzmo/
├── claudzmo              # Main CLI executable
├── requirements.txt      # Python dependencies
├── README.md            # This file
├── claudzmo.skill.md    # Claude Code skill
└── venv/                # Python virtual environment

Dependencies

• pycozmo - Pure-Python Cozmo SDK
• Pillow - Image processing for facial expressions
• numpy - Array operations for image conversion

Credits

• PyCozmo - https://github.com/zayfod/pycozmo (Pure-Python Cozmo library)
• Anki Cozmo - Original robot hardware and firmware
• Claude - AI assistant that helped build this! 🤖

License

MIT License

Links

• Repository: https://gitea.kostverse.com/matt/claudzmo
• PyCozmo Docs: https://pycozmo.readthedocs.io/
• Claude Code: https://claude.com/claude-code

---

Built with ❤️ by Matt & Claude • "Claudzmo" name suggested by Nicole 😄