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/`

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

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

```bash
# 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` (создаётся автоматически)

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

```bash
# Проверка статуса
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 документации](../integration/mqtt-led.md).

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

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

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

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

```bash
# Проверка статуса и последних ошибок
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 без указания полного пути:

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

Используется в файлах сервисов:
```ini
ExecStart=satellite-python -m wyoming_satellite ...
```

---

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

- [Руководство по развёртыванию](../../DEPLOY.md)
- [MQTT LED интеграция](integration/mqtt-led.md)

---

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

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

### Отличия от production

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

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

**Установка:**

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

**Запуск:**

```bash
# Запуск всех 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`)

**Запуск:**

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

**Управление:**

```bash
# Подключиться к сессии
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

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

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

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

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

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