Документация: рефакторинг структуры docs/ и очистка мусора
- Перемещена документация в docs/ с четкой структурой: - tutorials/ — пошаговые руководства (2mic-hat, installer) - integration/ — техническая интеграция (vad-wakeword, mqtt-led) - deployment/ — развёртывание (systemd-services) - architecture/ — архитектура проекта (overview) - Обновлён README.md с навигацией по документации - DEPLOY.md сокращён до quick start с ссылками на docs/ - Добавлен docs/README.md — индекс документации - Создан QWEN.md — контекст для ИИ-ассистента - Удалён мусор: - wyoming_satellite.zip (build artifact) - wyoming-led.service, wyoming-satellite.service (дубликаты) - .qwen/settings.json.orig (бэкап) - .lgd-nfy0 (пустой файл) - docker/run (заглушка) - Обновлён .gitignore: - examples/led_brightness_config.json (автогенерируемый конфиг) - *.old, *.bak, *~ (бэкапы) - *.zip (архивы) - .qwen/settings.json.orig - *.lgd-* (пустые файлы) - led_brightness_config.json исключён из отслеживания (assume-unchanged) Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
This commit is contained in:
Qwen-Coder
@@ -0,0 +1,175 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user