satellite/DEPLOY.md

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

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

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

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

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 сервисов

sudo ./install_systemd_services.sh

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

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

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

# 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. Проверка

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

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

---

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

Руководство	Описание
systemd сервисы	Детальная настройка сервисов
Tutorials	Пошаговые руководства для разного оборудования
Архитектура	Как работает Wyoming Satellite
MQTT LED	LED управление с Home Assistant
Настройки	Шпаргалка по всем CLI флагам

Tutorials

• 2-MIC HAT — Raspberry Pi + ReSpeaker 2-MIC HAT
• Установщик — Руководство по интерактивному установщику

---

Требования

• 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:

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

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

# Проверка 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:

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

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

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

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

# Статус сервиса
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.

---

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

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

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

---

Wake words (русские)

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

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

---

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

• Wyoming Protocol
• Home Assistant Integration
• Vosk
• ReSpeaker 4-MIC Array