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. Установка зависимостей

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

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

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

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

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

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

```ini
[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. Включение сервиса

```bash
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`:

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

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

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

## Диагностика

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

```bash
# Проверка статуса сервиса
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 не обнаружен

```bash
# Проверка 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 и временных файлов

**Пример использования:**
```python
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)
```

---

## 🔗 Связанное

- [Руководство по развёртыванию](../../DEPLOY.md)
- [Настройка systemd сервисов](deployment/systemd-services.md)