satellite/docs/integration/mqtt-led.md

MQTT LED Управление

Руководство по интеграции LED управления ReSpeaker через MQTT и Home Assistant.

Обзор

LED сервис (examples/wyoming-led.py) предоставляет:

• Light сущность — Управление яркостью и цветом LED
• Sensor сущность — Состояние спутника (ожидание, слушание, говорение)
• Number сущности — 7 слайдеров для точной настройки
• MQTT Discovery — Авто-конфигурация в Home Assistant

Архитектура

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

Установка

1. Установка зависимостей

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

2. Настройка MQTT

Отредактируйте examples/wyoming-led.py:

MQTT_BROKER = "192.168.200.100"  # Ваш MQTT брокер
MQTT_PORT = 1883
MQTT_USER = "mqtt"
MQTT_PASS = "mqtt"

3. Создание systemd сервиса

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

[Unit]
Description=Wyoming LED Service с 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. Включение сервиса

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

MQTT топики

Топик	Направление	Описание
wyoming/led/command	HA → Скрипт	Команды света (вкл/выкл, цвет, яркость)
wyoming/led/brightness/set	HA → Скрипт	Установка яркости (0-255)
wyoming/led/brightness/state	Скрипт → HA	Текущая яркость
wyoming/led/state	Скрипт → HA	Состояние LED (вкл/выкл)
wyoming/led/availability	Скрипт → HA	Онлайн/офлайн статус
wyoming/satellite/state	Скрипт → HA	Состояние спутника

Сущности Home Assistant

После discovery вы увидите:

• Light: light.wyoming_led — RGB управление
• Sensor: sensor.wyoming_satellite_state — Текущее состояние
• Number: number.wyoming_led_brightness — Слайдер яркости
• Number: number.wyoming_led_red/green/blue — Слайдеры цвета
• Number: number.wyoming_led_idle/listening/speaking — Цвета состояний

Состояния LED

Состояние	Цвет	Поведение
Ожидание (Idle)	Синий (тусклый)	Дыхательный эффект
Слушание (Listening)	Голубой	Постоянный
Говорение (Speaking)	Зелёный	Постоянный
Ошибка (Error)	Красный	Мигание

Настройка яркости

Яркость LED хранится в examples/led_brightness_config.json:

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

Этот файл создаётся автоматически и должен быть исключён из git tracking:

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

Диагностика

LED не реагирует

# Проверка статуса сервиса
sudo systemctl status wyoming-led.service

# Просмотр логов
journalctl -u wyoming-led.service -f

# Тест вручную
python3 examples/wyoming-led.py --debug

MQTT подключение не удалось

• Проверьте, что брокер запущен: sudo systemctl status mosquitto
• Проверьте учётные данные в wyoming-led.py
• Тест подключения: mosquitto_sub -t 'wyoming/led/#' -v

ReSpeaker не обнаружен

# Проверка USB устройств
lsusb | grep -i 2886

# Тест USB контроллера
source ~/.venv_satellite/bin/activate
python3 -c "from wyoming_satellite.xvf_usb import XVF3800Controller; c = XVF3800Controller(); print('OK' if c.is_connected() else 'Not found')"

Поддерживаемое оборудование

Устройство	Поддержка	Примечания
ReSpeaker XVF3800 (USB 4-MIC)	✅ Полная	Рекомендуется
ReSpeaker 2-MIC HAT	✅ Полная	Требуется GPIO
ReSpeaker 4-MIC HAT	✅ Полная	Требуется GPIO
Обычный USB микрофон	⚠️ Частичная	Без LED управления

Связанные файлы

• examples/wyoming-led.py — Основной скрипт LED управления
• wyoming_satellite/xvf_usb.py — USB контроллер XVF3800 (прямой доступ без subprocess)
• examples/led_brightness_config.json — Настройки яркости
• services/wyoming-event.service — Сервис событий (альтернатива)

Архитектура USB контроллера

Начиная с версии 2026.05, wyoming-led.py использует прямой USB доступ через модуль wyoming_satellite.xvf_usb:

Преимущества:

• ✅ Быстрее: ~1ms на команду (нет накладных расходов subprocess)
• ✅ Надёжнее: контроль USB подключения с авто-переподключением
• ✅ Чище: нет процессов subprocess и временных файлов

Пример использования:

from wyoming_satellite.xvf_usb import XVF3800Controller, EFFECT_BREATH, rgb_to_bgr_int

controller = XVF3800Controller()
controller.set_led_effect(EFFECT_BREATH)
controller.set_led_color(rgb_to_bgr_int(0, 188, 212))  # бирюзовый
controller.set_led_brightness(150)

---

🔗 Связанное

• Руководство по развёртыванию
• Настройка systemd сервисов