Initial commit - Claudzmo CLI tool
Claudzmo is a CLI tool for controlling Anki Cozmo robot via PyCozmo. Features: - Movement control (drive, turn, head, lift) - Facial expressions (15 presets with 30fps animation) - Text-to-speech via macOS voice synthesis - Camera access (320x240 live feed) - Status monitoring (battery, firmware, hardware) - Claude Code skill integration Architecture: - Fresh connection per command using pycozmo.connect() - Reliable audio playback (100% consistent) - Simple CLI interface with argparse - Fast execution (~1 second per command) Built with ❤️ by Matt & Claude 🤖 Generated with Claude Code (https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Matt Kost
254
README.md
Normal file
254
README.md
Normal file
@@ -0,0 +1,254 @@
|
||||
# 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 😄
|
||||
Reference in New Issue
Block a user