satellite/docs/deployment/systemd-services.md

Настройка systemd сервисов

Подробное руководство по настройке и управлению systemd сервисами Wyoming Satellite.

Расположение файлов сервисов

Файлы сервисов находятся в директории services/:

services/
├── wyoming-event.service         # LED управление + MQTT
├── wyoming-satelite-vosk.service # Основной спутник
└── wyoming-wakeword-vosk.service # Детекция wake word

Скрипт установки

Скрипт install_systemd_services.sh автоматически:

1. Определяет путь к виртуальному окружению
2. Определяет текущего пользователя
3. Подставляет плейсхолдеры в файлы сервисов
4. Копирует сервисы в /etc/systemd/system/
5. Устанавливает wrapper satellite-python в /usr/local/bin/

Ручная установка

Если скрипт не работает, установите вручную:

# 1. Отредактируйте файлы сервисов, заменив плейсхолдеры:
#    __SAT_BASE_DIR__ → /home/sirmrak/projects/Satellite
#    __SAT_VENV__ → /home/sirmrak/.venv_satellite
#    __CURRENT_USER__ → sirmrak

# 2. Скопируйте в директорию systemd
sudo cp services/*.service /etc/systemd/system/

# 3. Перезагрузите systemd
sudo systemctl daemon-reload

# 4. Включите и запустите
sudo systemctl enable --now wyoming-satelite-vosk.service

Детали сервисов

wyoming-satelite-vosk.service

Основной сервис Wyoming Satellite. Подключается к:

• Микрофону (arecord)
• Динамику (aplay)
• Сервису wake word (опционально, порт 10400)
• Сервису событий (опционально, порт 10500)

Порты: 10700 (Wyoming protocol)

Зависимости: network.target

wyoming-wakeword-vosk.service

Сервис детекции wake word на основе Vosk. Слушает русские фразы:

• "привет дроид"
• "привет придурок"
• "привет жопа с ушами"

Порты: 10400 (Wyoming protocol)

Конфигурация: local/vosk-wake-dev/wyoming_vosk_wake/config.yaml

wyoming-event.service

LED управление и MQTT интеграция для ReSpeaker XVF3800.

Порты: 10500 (Wyoming event protocol)

Требования:

• ReSpeaker XVF3800 USB 4-MIC Array
• udev правила: SUBSYSTEM=="usb", ATTR{idVendor}=="2886", MODE="0666"

USB контроллер: Использует модуль wyoming_satellite.xvf_usb для прямого доступа к LED без subprocess.

MQTT топики:

• wyoming/led/command — Команды от Home Assistant
• wyoming/led/brightness/set — Установка яркости (0-255)
• wyoming/led/brightness/state — Текущая яркость
• wyoming/led/state — Состояние LED
• wyoming/led/availability — Статус онлайн/офлайн

Конфигурация яркости: examples/led_brightness_config.json (создаётся автоматически)

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

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

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

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

Подробности в MQTT LED документации.

Команды управления

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

# Просмотр логов (реальное время)
journalctl -u wyoming-satelite-vosk.service -f

# Перезапуск сервиса
sudo systemctl restart wyoming-satelite-vosk.service

# Отключение сервиса
sudo systemctl disable --now wyoming-satelite-vosk.service

# Перезагрузка systemd после изменений
sudo systemctl daemon-reload

Диагностика

Сервис не запускается

# Проверка статуса и последних ошибок
sudo systemctl status wyoming-satelite-vosk.service

# Просмотр полных логов
journalctl -u wyoming-satelite-vosk.service -n 100

# Проверка пути к Python
which satellite-python
satellite-python --version

Частые проблемы

Проблема	Решение
ModuleNotFoundError	Проверьте путь к venv в файле сервиса
arecord: command not found	Установите alsa-utils
Permission denied	Проверьте директиву User=
Порт уже используется	Проверьте, не запущен ли другой экземпляр

Wrapper скрипт

Wrapper satellite-python позволяет запускать Python из venv без указания полного пути:

# Установлен в /usr/local/bin/satellite-python
satellite-python --version  # Использует Python из venv

Используется в файлах сервисов:

ExecStart=satellite-python -m wyoming_satellite ...

---

🔗 Связанное

• Руководство по развёртыванию
• MQTT LED интеграция

---

TEST сервисы (для разработки)

Для тестирования новых функций без влияния на production службы созданы TEST сервисы.

Отличия от production

Сервис	Production	Test
Satellite	порт 10700	порт 10701 + WebSocket :8675
Wake Word	порт 10400	порт 10401
Event	порт 10500	порт 10501

Вариант 1: Установка TEST сервисов (рекомендуется)

Установка:

cd ~/projects/satellite-dev
sudo ./install_test_services.sh

Запуск:

# Запуск всех test сервисов
sudo systemctl start wyoming-event-test.service
sudo systemctl start wyoming-satelite-vosk-test.service
sudo systemctl start wyoming-wakeword-vosk-test.service

# Проверка статуса
sudo systemctl status wyoming-satelite-vosk-test.service

# Логи
journalctl -u wyoming-satelite-vosk-test.service -f

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

• ✅ Автоматический перезапуск при ошибке
• ✅ Production службы не затрагиваются
• ✅ Легко переключаться между test/prod

Вариант 2: Быстрый запуск в tmux

Требования: tmux установлен (sudo apt-get install tmux)

Запуск:

cd ~/projects/satellite-dev
./services/test/start_test.sh

Управление:

# Подключиться к сессии
tmux attach -t satellite-test

# Остановить все сервисы
tmux kill-session -t satellite-test

Структура окон:

• Окно 0: Wake Word (порт 10401)
• Окно 1: Event Service (порт 10501)
• Окно 2: Satellite (порт 10701 + WebSocket :8675)

Тестирование WebSocket

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

cd ~/projects/satellite-dev
source .venv/bin/activate

# Python тест клиент
python3 examples/websocket-service/test_client.py --uri ws://127.0.0.1:8675

# Или браузер
# Откройте examples/websocket-service/client.html

Проверка audio level:

// В browser console (client.html)
// Уровень микрофона должен обновляться 10 раз в секунду
// {"type": "audio-level", "data": {"level": 0.42}}

Остановка TEST сервисов

# systemd сервисы
sudo systemctl stop wyoming-event-test.service
sudo systemctl stop wyoming-satelite-vosk-test.service
sudo systemctl stop wyoming-wakeword-vosk-test.service

# tmux сессия
tmux kill-session -t satellite-test