satellite/docs/integration/mqtt-led.md

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

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

2. Configure MQTT Settings

Edit examples/wyoming-led.py:

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

3. Create systemd Service

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

[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

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:

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

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

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

Troubleshooting

LEDs not responding

# 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

# 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)