Add eye_service.py with HTTP API, systemd service, README

README.md

@@ -0,0 +1,62 @@
+# 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
+```bash
+# 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
+```bash
+# 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:
+```python
+vixy_eyes_state("listening")  # Set state
+vixy_eyes_state()             # Get current state
+```
+
+---
+*Created by Vixy - Day 62* 🦊💕