satellite/DEPLOY.md

# Руководство по развёртыванию

Быстрый старт для развёртывания Wyoming Satellite.

## Быстрый старт

### 1. Клонирование и установка

```bash
git clone <repository-url> ~/projects/Satellite
cd ~/projects/Satellite

# Создание виртуального окружения
python3 -m venv ~/.venv_satellite
source ~/.venv_satellite/bin/activate

# Установка зависимостей
pip install -r requirements.txt

# Установка пакета в режиме разработки (для доступа к wyoming_satellite.xvf_usb)
pip install -e .
```

### 2. Установка systemd сервисов

```bash
sudo ./install_systemd_services.sh
```

**Важно:** После установки пакета в режиме editable (`pip install -e .`), новый модуль `wyoming_satellite.xvf_usb` будет автоматически доступен. Если вы добавляете новые модули в `wyoming_satellite/`, убедитесь, что они видны:

```bash
# Проверка доступности модуля
source ~/.venv_satellite/bin/activate
python3 -c "from wyoming_satellite.xvf_usb import XVF3800Controller; print('OK')"
```

### 3. Запуск сервисов

```bash
# LED управление (опционально, требуется ReSpeaker)
sudo systemctl enable --now wyoming-event.service

# Wyoming Satellite
sudo systemctl enable --now wyoming-satelite-vosk.service

# Детекция wake word (Vosk)
sudo systemctl enable --now wyoming-wakeword-vosk.service
```

### 4. Проверка

```bash
sudo systemctl status wyoming-satelite-vosk.service
journalctl -u wyoming-satelite-vosk.service -f
```

В Home Assistant: **Настройки → Устройства и сервисы → Найдено → Wyoming Satellite → Настроить**

---

## Полная документация

| Руководство | Описание |
|-------------|----------|
| [**systemd сервисы**](docs/deployment/systemd-services.md) | Детальная настройка сервисов |
| [**Tutorials**](docs/tutorials/) | Пошаговые руководства для разного оборудования |
| [**Архитектура**](docs/architecture/overview.md) | Как работает Wyoming Satellite |
| [**MQTT LED**](docs/integration/mqtt-led.md) | LED управление с Home Assistant |
| [**Настройки**](docs/settings-cheatsheet.md) | Шпаргалка по всем CLI флагам |

### Tutorials

- [**2-MIC HAT**](docs/tutorials/2mic-hat.md) — Raspberry Pi + ReSpeaker 2-MIC HAT
- [**Установщик**](docs/tutorials/installer.md) — Руководство по интерактивному установщику

---

## Требования

- **Python 3.9+**
- **Linux** (протестировано на Raspberry Pi OS)
- **Микрофон** (USB или HAT)
- **Опционально:** ReSpeaker XVF3800 USB 4-MIC Array (для LED управления)

---

## Обзор сервисов

| Сервис | Порт | Описание |
|--------|------|----------|
| `wyoming-satelite-vosk.service` | 10700 | Основной Wyoming спутник |
| `wyoming-wakeword-vosk.service` | 10400 | Детекция wake word (Vosk) |
| `wyoming-event.service` | 10500 | LED управление + MQTT события |

---

## LED управление (ReSpeaker XVF3800)

Сервис `wyoming-event.service` использует прямой USB доступ к XVF3800 через модуль `wyoming_satellite.xvf_usb`.

### Требования

- **ReSpeaker XVF3800 USB 4-MIC Array** (VID=0x2886, PID=0x0018 или 0x001A)
- **udev правила** для доступа к USB:

```bash
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="2886", ATTR{idProduct}=="0018", MODE="0666", GROUP="plugdev"' | sudo tee /etc/udev/rules.d/99-respeaker.rules
sudo udevadm trigger
```

### Проверка подключения

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

# Тест контроллера
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')"
```

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

Яркость для каждого состояния настраивается в `examples/led_brightness_config.json`:

```json
{
  "idle": 80,
  "listening": 120,
  "wake": 200,
  "thinking": 150,
  "speaking": 140,
  "paused": 40,
  "error": 255,
  "global_multiplier": 1.0
}
```

Файл создаётся автоматически при первом запуске. Исключите его из git tracking:

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

### Диагностика LED сервиса

```bash
# Статус сервиса
sudo systemctl status wyoming-event.service

# Логи
journalctl -u wyoming-event.service -f

# Тест вручную
source ~/.venv_satellite/bin/activate
cd ~/projects/Satellite/examples
python3 wyoming-led.py --debug
```

### Преимущества прямого USB доступа

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

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

Подробности в [документации MQTT LED](docs/integration/mqtt-led.md).

---

## Конфигурация

Файлы сервисов используют плейсхолдеры, которые автоматически заменяются при установке:

| Плейсхолдер | Описание |
|-------------|----------|
| `__SAT_BASE_DIR__` | Путь к репозиторию Satellite |
| `__SAT_VENV__` | Путь к виртуальному окружению |
| `__CURRENT_USER__` | Имя текущего пользователя |
| `__HOME_DIR__` | Домашняя директория пользователя |

---

## Wake words (русские)

Отредактируйте `start_satellite.sh`:

```bash
--wake-word-name "привет дроид"
--wake-word-name "привет придурок"
--wake-word-name "привет жопа с ушами"
```

---

## Внешние ресурсы

- [Wyoming Protocol](https://github.com/rhasspy/wyoming)
- [Home Assistant Integration](https://www.home-assistant.io/integrations/wyoming)
- [Vosk](https://alphacephei.com/vosk/)
- [ReSpeaker 4-MIC Array](https://github.com/respeaker/usb_4mic_array)