hermes-petpi

A voice-controlled AI companion for Raspberry Pi Zero W with the PiSugar WhisPlay board. Press a button, speak, and get a streamed response from Hermes Agent displayed on a 1.54" LCD — all while a cute animated pet expresses the AI's state in real-time.

Forked from pizero-openclaw and adapted for Hermes Agent.

Quick Start

# 1. Clone and install dependencies
git clone https://github.com/<your-org>/hermes-petpi.git
cd hermes-petpi
cp .env.example .env
# Edit .env with your OpenAI key and Hermes Agent URL
pip3 install -r requirements.txt

# 2. Deploy to your Pi
./sync.sh pi@pizero.local

# 3. Watch it run
ssh pi@pizero.local 'sudo journalctl -u hermes-petpi -f'

Hardware

Component	Details
Board	Raspberry Pi Zero 2 W (or Pi Zero W)
Display + Input	PiSugar WhisPlay — 1.54" 240×240 LCD, push-to-talk button, speaker, mic
Power	PiSugar battery (optional) — charge level shown on-screen

How It Works

1. Press & hold button
   └→ LCD shows pet "listening" animation
2. Speak
   └→ Audio recorded via ALSA arecord (16 kHz, mono)
3. Release button
   └→ WAV sent to OpenAI Whisper for transcription (~0.7 s)
4. Transcript + conversation history sent to Hermes Agent
   └→ Pet shows "thinking" animation
5. Response tokens stream to LCD in real-time
   └→ If TTS enabled, OpenAI speaks each sentence aloud
      └→ Pet mouth moves in sync with audio (RMS-driven)
6. Final response stays on screen for 30 s (configurable)
   └→ Pet shows "happy" face
7. Display auto-sleeps after 60 s idle
   └→ Press any button to wake

Software Requirements

• Raspberry Pi OS Bookworm (32-bit) — Lite recommended
• Python 3.11+
• PiSugar WhisPlay drivers — installed at /home/pi/Whisplay/Driver/
• OpenAI API key — for Whisper transcription and TTS
• Hermes Agent instance — reachable at HERMES_BASE_URL (must support streaming chat)

Configuration

All settings via environment variables loaded from .env:

Variable	Default	Description
HERMES_BASE_URL	http://localhost:8000	Hermes Agent HTTP endpoint
HERMES_API_TOKEN	(none)	Bearer token if Hermes requires auth
HERMES_MODEL	claude-3-opus-20240229	Model identifier for Hermes
OPENAI_API_KEY	(required)	OpenAI API key
ENABLE_TTS	true	Speak responses aloud?
OPENAI_TTS_VOICE	alloy	TTS voice: alloy, echo, fable, onyx, nova, shimmer
AUDIO_DEVICE	plughw:1,0	ALSA input device (WhisPlay mic)
LCD_BACKLIGHT	70	Screen brightness (0–100)
PET_THEME	hermes-messenger	Pet sprite: hermes-messenger, kiki-friend, mira-cat
PET_COLOR_PRIMARY	200,130,50	Primary RGB color for pet (gold)
PET_COLOR_ACCENT	0,150,255	Accent RGB color (cyan)
RESPONSE_HOLD_TIMEOUT	30	Seconds response stays before returning to idle

See .env.example for the full list.

Pet Themes

hermes-petpi ships with three animated pet styles:

Theme	Description
hermes-messenger	Winged messenger sprite (gold + cyan), inspired by Hermes mythology
kiki-friend	Cute blob (Kirby-style) with pink/cyan colors
mira-cat	Tabby cat with ears, whiskers, and a tiny nose

Configure via PET_THEME in .env. You can also customize colors.

Development on Host (without Pi)

Test the UI and logic on your laptop before flashing the Pi:

# Dry-run mode — no API calls, raw text input instead of audio
DRY_RUN=true PET_THEME=mira-cat python3 main.py

# Or use a virtual display
xvfb-run -a python3 main.py

You'll need to mock the WhisPlay board driver or set PYTHONPATH to skip import errors. See display.py — the WhisPlayBoard import is only used for I/O; for host testing you can patch it.

Systemd Service

# On the Pi
sudo systemctl enable hermes-petpi
sudo systemctl start hermes-petpi
sudo systemctl status hermes-petpi

# View logs
sudo journalctl -u hermes-petpi -f

Service file: hermes-petpi.service — auto-restarts on failure.

Troubleshooting

"arecord not found"

sudo apt install alsa-utils

"No module named 'WhisPlay'"

The PiSugar WhisPlay driver is not installed or not at /home/pi/Whisplay/Driver/. Follow the official setup guide.

Audio but no response

1. Check Hermes Agent is running and reachable at HERMES_BASE_URL
2. Verify OpenAI API key is set
3. View logs: sudo journalctl -u hermes-petpi -f

Display remains black

• Check backlight: HERMES_BACKLIGHT should be 0–100 (70 default)
• Ensure the WhisPlay board drivers loaded: lsmod | grep -i pisugar
• Test with: python3 -c "from display import Display; Display().set_idle_screen()"

TTS is quiet or distorted

Adjust OPENAI_TTS_GAIN_DB (default 9 ≈ 2.8× software gain). Also try setting AUDIO_OUTPUT_CARD to your ALSA card index.

Customization

Pet Sprite Design

The sprite system lives in display.py under PetSpriteRenderer. Each theme defines:

• _HERMES_BODY, _HERMES_WINGS, _HERMES_HAT, etc. (sets of grid cells)
• _hermes_color() — per-cell coloring
• A palette of frame functions (_hermes_mouth_smile, _hermes_eyes_wide, etc.)

Want to create your own pet?

1. Choose a theme name
2. Define body/hair/accessory cell sets as (x, y) pairs in the 30×30 grid
3. Implement _mytheme_color() to return RGB tuples
4. Add frame functions and a _generate_frames() case
5. Submit a PR!

Backend Swap

Replace hermes_client.py with your own API client (e.g., Groq, Together, Ollama). Just implement stream_response(user_text, history) that yields text deltas.

Project Structure

main.py                 — Entry point and state machine
display.py              — LCD rendering, sprites, text layout
hermes_client.py        — Hermes Agent streaming client
transcribe_openai.py    — Whisper API wrapper
tts_openai.py           — TTS + lip-sync pipeline
record_audio.py         — ALSA audio capture
button_ptt.py           — Push-to-talk button handler
config.py               — Configuration from .env + defaults
requirements.txt        — Python dependencies
hermes-petpi.service    — Systemd unit
sync.sh                 — One-command deploy to Pi
DESIGN.md               — Architecture deep-dive
PET_SPRITE_DESIGN.md    — Sprite design spec

Differences from pizero-openclaw

Feature	pizero-openclaw	hermes-petpi
LLM Backend	OpenClaw gateway (custom)	Hermes Agent (Claude)
Pet Theme	Kirby-style blob	Hermes messenger (winged) + 3 themes
API	Proprietary OpenClaw SSE	OpenAI-compatible SSE (portable)
System Status	Basic clock/battery	+ Hermes connectivity indicator (future)
Extensibility	Closed gateway	Open client — plug any OpenAI-compatible API

License

MIT — same as the upstream openclaw project.

Acknowledgments

• sebastianvkl/pizero-openclaw — original hardware/software design
• PiSugar/whisplay-ai-chatbot — WhisPlay board drivers and reference implementation
• Hermes Agent team — Claude-based AI that powers the companion

---

Built with ❤️ for tiny screens and big conversations.