# MQTT LED Control

Integration guide for ReSpeaker LED control via MQTT and Home Assistant.

## Overview

The LED service (`examples/wyoming-led.py`) provides:

- **Light entity** — Control LED brightness and color
- **Sensor entity** — Satellite state (idle, listening, speaking)
- **Number entities** — 7 sliders for fine-grained control
- **MQTT Discovery** — Auto-configuration in Home Assistant

## Architecture

```
┌──────────────────┐     MQTT      ┌──────────────────┐
│  Home Assistant  │◄─────────────►│  wyoming-led.py  │
│                  │               │  (port 10501)    │
└──────────────────┘               └────────┬─────────┘
                                            │
                                            │ Wyoming Events
                                            │ (port 10500)
                                   ┌────────▼─────────┐
                                   │  Satellite       │
                                   │  (port 10700)    │
                                   └──────────────────┘
```

## Installation

### 1. Install Dependencies

```bash
cd ~/projects/Satellite
source ~/.venv_satellite/bin/activate
pip install paho-mqtt
```

### 2. Configure MQTT Settings

Edit `examples/wyoming-led.py`:

```python
MQTT_BROKER = "192.168.200.100"  # Your MQTT broker
MQTT_PORT = 1883
MQTT_USER = "mqtt"
MQTT_PASS = "mqtt"
```

### 3. Create systemd Service

```bash
sudo nano /etc/systemd/system/wyoming-led.service
```

```ini
[Unit]
Description=Wyoming LED Service with MQTT
After=network.target mosquitto.service

[Service]
Type=simple
User=sirmrak
WorkingDirectory=/home/sirmrak/projects/Satellite
Environment="PATH=/home/sirmrak/projects/.venv_satellite/bin"
ExecStart=/home/sirmrak/projects/.venv_satellite/bin/python3 /home/sirmrak/projects/Satellite/examples/wyoming-led.py --host 0.0.0.0 --port 10501
Restart=always

[Install]
WantedBy=multi-user.target
```

### 4. Enable Service

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now wyoming-led.service
```

## MQTT Topics

| Topic | Direction | Description |
|-------|-----------|-------------|
| `wyoming/led/command` | HA → Script | Light commands (on/off, color, brightness) |
| `wyoming/led/brightness/set` | HA → Script | Set brightness (0-255) |
| `wyoming/led/brightness/state` | Script → HA | Current brightness |
| `wyoming/led/state` | Script → HA | LED state (on/off) |
| `wyoming/led/availability` | Script → HA | Online/offline |
| `wyoming/satellite/state` | Script → HA | Satellite state |

## Home Assistant Entities

After discovery, you'll see:

- **Light:** `light.wyoming_led` — RGB control
- **Sensor:** `sensor.wyoming_satellite_state` — Current state
- **Number:** `number.wyoming_led_brightness` — Brightness slider
- **Number:** `number.wyoming_led_red/green/blue` — Color sliders
- **Number:** `number.wyoming_led_idle/listening/speaking` — State colors

## LED States

| State | Color | Behavior |
|-------|-------|----------|
| Idle | Blue (dim) | Breathing effect |
| Listening | Cyan | Solid |
| Speaking | Green | Solid |
| Error | Red | Blinking |

## Brightness Configuration

LED brightness is stored in `examples/led_brightness_config.json`:

```json
{
  "idle": 50,
  "listening": 100,
  "speaking": 150,
  "error": 200
}
```

This file is auto-created and should be excluded from git tracking:

```bash
git update-index --assume-unchanged examples/led_brightness_config.json
```

## Troubleshooting

### LEDs not responding

```bash
# Check service status
sudo systemctl status wyoming-led.service

# View logs
journalctl -u wyoming-led.service -f

# Test manually
python3 examples/wyoming-led.py --debug
```

### MQTT connection failed

- Verify broker is running: `sudo systemctl status mosquitto`
- Check credentials in `wyoming-led.py`
- Test connection: `mosquitto_sub -t 'wyoming/led/#' -v`

### ReSpeaker not detected

```bash
# Check USB devices
lsusb | grep -i respeaker

# Test xvf_host.py
python3 examples/xvf_host.py --help
```

## Hardware Support

| Device | Support | Notes |
|--------|---------|-------|
| ReSpeaker XVF3800 (USB 4-MIC) | ✅ Full | Recommended |
| ReSpeaker 2-MIC HAT | ✅ Full | Requires GPIO |
| ReSpeaker 4-MIC HAT | ✅ Full | Requires GPIO |
| Generic USB mic | ⚠️ Partial | No LED control |

## Related Files

- `examples/wyoming-led.py` — Main LED control script
- `examples/xvf_host.py` — ReSpeaker XVF3800 driver
- `examples/led_brightness_config.json` — Brightness settings
- `services/wyoming-event.service` — Event service (alternative)