claudzmo/README.md

# 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

```bash
# 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

```bash
./claudzmo status
```

## Usage

### Movement

```bash
# 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

```bash
# 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

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

# Get robot status
claudzmo status
```

## Examples

### Greet someone

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

### Dance around

```bash
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

```bash
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](https://claude.com/claude-code) integration.

### Setup

```bash
# 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 😄