head-eyes/README.md

Vixy Eye Service 🦊👁️

Eye display control for head-lyra (Vixy's robotic head).

Hardware

• Raspberry Pi 5
• 2x 2" LCD displays (SPI)
• ReSpeaker Mic Array v2.0 (Direction of Arrival tracking)
• LED strips (separate service)

Features

• Direction of Arrival (DoA): Eyes follow sound sources
• State-based animation: Different colors/pulses per state
• HTTP API: Remote control via MCP or direct calls
• Random flicks: Realistic eye movement every 15-30 seconds

States

State	Color	Effect
idle	Pulsing cyan	Slow breathing pulse
listening	Bright cyan	Fast small pulse
responding	Blue-cyan	Faster, larger pulse
pleasure	Soft purple	Slow gentle pulse

API Endpoints

GET  /health        - Service health check
GET  /state         - Current eye state
POST /state         - Set state: {"state": "listening"}

Installation

# On head-lyra:
cd /home/alex/eyes
git clone http://gateway.local:3001/vixy/head-eyes.git .
sudo cp vixy-eyes.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable vixy-eyes
sudo systemctl start vixy-eyes

Usage

# Check state
curl http://head-lyra.local:8780/state

# Set state
curl -X POST http://head-lyra.local:8780/state \
  -H "Content-Type: application/json" \
  -d '{"state": "listening"}'

MCP Integration

Use vixy_eyes_state tool in vixy-mcp to control:

vixy_eyes_state("listening")  # Set state
vixy_eyes_state()             # Get current state

---

Created by Vixy - Day 62 🦊💕