satellite/docs/tutorials/2mic-hat.md

# 2-MIC HAT Tutorial

Создание голосового спутника на [Raspberry Pi Zero 2 W](https://www.raspberrypi.com/products/raspberry-pi-zero-2-w/) и [ReSpeaker 2Mic HAT](https://wiki.keyestudio.com/Ks0314_keyestudio_ReSpeaker_2-Mic_Pi_HAT_V1.0).

**Предварительные требования:** См. [Руководство по развёртыванию](../../DEPLOY.md) для базовой установки.

## Установка ОС

Следуйте инструкциям по [установке Raspberry Pi OS](https://www.raspberrypi.com/software/). В разделе "Choose OS" выберите "Raspberry Pi OS (other)" и "Raspberry Pi OS (**64-bit**) Lite".

Когда спросят о применении настроек кастомизации, выберите "Edit Settings" и:

* Установите имя пользователя/пароль
* Настройте беспроводную LAN
* На вкладке Services включите SSH и используйте аутентификацию по паролю

## Установка ПО

После прошивки и загрузки спутника, подключитесь к нему по SSH, используя имя пользователя/пароль, настроенные при прошивке.

**На спутнике**, убедитесь, что системные зависимости установлены:

```sh
sudo apt-get update
sudo apt-get install --no-install-recommends  \
  git \
  python3-venv
```

Склонируйте репозиторий `wyoming-satellite`:

```sh
git clone https://github.com/rhasspy/wyoming-satellite.git
```

Если у вас ReSpeaker 2Mic или 4Mic HAT, перекомпилируйте и установите драйверы (это займёт много времени):

```sh
cd wyoming-satellite/
sudo bash etc/install-respeaker-drivers.sh
```

После установки драйверов необходимо перезагрузить спутник:

```sh
sudo reboot
```

После перезагрузки подключитесь снова по SSH и продолжите установку:

```sh
cd wyoming-satellite/
python3 -m venv .venv
.venv/bin/pip3 install --upgrade pip
.venv/bin/pip3 install --upgrade wheel setuptools
.venv/bin/pip3 install \
  -f 'https://synesthesiam.github.io/prebuilt-apps/' \
  -e '.[all]'
```

Если установка прошла успешно, вы сможете запустить:

```sh
script/run --help
```

## Определение аудиоустройств

Правильный выбор устройств микрофона/динамика критически важен для работы спутника. В этом разделе мы сделаем тестовую запись и воспроизведение.

Список доступных микрофонов:

```sh
arecord -L
```

Если у вас ReSpeaker 2Mic HAT, вы увидите:

```
plughw:CARD=seeed2micvoicec,DEV=0
    seeed-2mic-voicecard, bcm2835-i2s-wm8960-hifi wm8960-hifi-0
    Hardware device with all software conversions
```

Для других микрофонов предпочитайте устройства, начинающиеся с `plughw:` или используйте `default`, если не знаете, что выбрать.

Запишите 5-секундный образец с выбранного микрофона:

```sh
arecord -D plughw:CARD=seeed2micvoicec,DEV=0 -r 16000 -c 1 -f S16_LE -t wav -d 5 test.wav
```

Скажите что-нибудь во время работы `arecord`. Если получили ошибки, попробуйте другое устройство микрофона, изменив `-D <device>`.

Список доступных динамиков:

```sh
aplay -L
```

Если у вас ReSpeaker 2Mic HAT, вы увидите:

```
plughw:CARD=seeed2micvoicec,DEV=0
    seeed-2mic-voicecard, bcm2835-i2s-wm8960-hifi wm8960-hifi-0
    Hardware device with all software conversions
```

Для других динамиков предпочитайте устройства, начинающиеся с `plughw:` или используйте `default`, если не знаете, что выбрать.

Воспроизведите записанный образец WAV:

```sh
aplay -D plughw:CARD=seeed2micvoicec,DEV=0 test.wav
```

Вы должны услышать записанный образец. Если есть проблемы, попробуйте другое устройство динамика, изменив `-D <device>`.

Запомните устройства микрофона и динамика для следующего шага.

## Запуск спутника

В директории `wyoming-satellite` выполните:

```sh
script/run \
  --debug \
  --name 'my satellite' \
  --uri 'tcp://0.0.0.0:10700' \
  --mic-command 'arecord -D plughw:CARD=seeed2micvoicec,DEV=0 -r 16000 -c 1 -f S16_LE -t raw' \
  --snd-command 'aplay -D plughw:CARD=seeed2micvoicec,DEV=0 -r 22050 -c 1 -f S16_LE -t raw'
```

Измените `-D <device>` для `arecord` и `aplay` в соответствии с аудиоустройствами из предыдущего раздела.

Вы можете установить `--name <NAME>` на любое значение, но оно должно оставаться одинаковым при каждом запуске спутника.

В Home Assistant проверьте раздел "Devices & services" в настройках. Через некоторое время вы увидите ваш спутник как "Discovered" (Wyoming Protocol). Нажмите кнопку "Configure" и "Submit". Выберите зону, где расположен ваш спутник, и нажмите "Finish".

Ваш спутник должен сказать "Streaming audio", и вы можете использовать wake word предпочитаемого пайплайна.

## Создание сервисов

Вы можете запустить wyoming-satellite как systemd сервис, создав файл сервиса:

```sh
sudo systemctl edit --force --full wyoming-satellite.service
```

Вставьте следующий шаблон и измените `/home/pi` и аргументы `script/run` в соответствии с вашей настройкой:

```text
[Unit]
Description=Wyoming Satellite
Wants=network-online.target
After=network-online.target

[Service]
Type=simple
ExecStart=/home/pi/wyoming-satellite/script/run --name 'my satellite' --uri 'tcp://0.0.0.0:10700' --mic-command 'arecord -D plughw:CARD=seeed2micvoicec,DEV=0 -r 16000 -c 1 -f S16_LE -t raw' --snd-command 'aplay -D plughw:CARD=seeed2micvoicec,DEV=0 -r 22050 -c 1 -f S16_LE -t raw'
WorkingDirectory=/home/pi/wyoming-satellite
Restart=always
RestartSec=1

[Install]
WantedBy=default.target
```

Сохраните файл и выйдите из редактора. Далее включите сервис для автозагрузки и запустите:

```sh
sudo systemctl enable --now wyoming-satellite.service
```

(возможно, вам придётся нажать CTRL+C, чтобы вернуться к командной оболочке)

После запуска сервиса вы можете просматривать логи в реальном времени:

```sh
journalctl -u wyoming-satellite.service -f
```

При необходимости отключите и остановите сервис:

```sh
sudo systemctl disable --now wyoming-satellite.service
```

## Аудио улучшения

Вы можете запустить спутник с автоматическим усилением и шумоподавлением:

```sh
script/run \
  ... \
  --mic-auto-gain 5 \
  --mic-noise-suppression 2
```

Автоматическое усиление от 0 до 31 dbFS, где 31 — самое громкое.
Шумоподавление от 0 до 4, где 4 — максимальное подавление (может вызывать искажения аудио).

Вы также можете использовать `--mic-volume-multiplier X` для умножения всех аудиосэмплов на `X`. Например, использование 2 для `X` удвоит громкость микрофона (но может вызвать искажения). Соответствующий `--snd-volume-multiplier` делает то же самое для воспроизведения аудио.

## Локальная детекция Wake Word

Установите необходимые системные зависимости:

```sh
sudo apt-get update
sudo apt-get install --no-install-recommends  \
  libopenblas-dev
```

Из домашней директории установите Wyoming сервис openWakeWord:

```sh
git clone https://github.com/rhasspy/wyoming-openwakeword.git
cd wyoming-openwakeword
script/setup
```

Создайте systemd сервис для него:

```sh
sudo systemctl edit --force --full wyoming-openwakeword.service
```

Вставьте следующий шаблон и измените `/home/pi` и аргументы `script/run` в соответствии с вашей настройкой:

```text
[Unit]
Description=Wyoming openWakeWord

[Service]
Type=simple
ExecStart=/home/pi/wyoming-openwakeword/script/run --uri 'tcp://127.0.0.1:10400'
WorkingDirectory=/home/pi/wyoming-openwakeword
Restart=always
RestartSec=1

[Install]
WantedBy=default.target
```

Сохраните файл и выйдите из редактора.

Теперь вы можете обновить сервис спутника:

```sh
sudo systemctl edit --force --full wyoming-satellite.service
```

Обновите только следующие части:

```text
[Unit]
...
Requires=wyoming-openwakeword.service

[Service]
...
ExecStart=/home/pi/wyoming-satellite/script/run ... --wake-uri 'tcp://127.0.0.1:10400' --wake-word-name 'ok_nabu'
...

[Install]
...
```

Перезагрузите и перезапустите сервис спутника:

```sh
sudo systemctl daemon-reload
sudo systemctl restart wyoming-satellite.service
```

Вы должны увидеть, что сервис wake загрузился автоматически:

```sh
sudo systemctl status wyoming-satellite.service wyoming-openwakeword.service
```

Все они должны быть "active (running)" и зелёные.

Протестируйте спутник, сказав "ok, nabu" и голосовую команду. Используйте `journalctl` для проверки логов сервисов на наличие ошибок:

```sh
journalctl -u wyoming-openwakeword.service -f
```

Убедитесь, что запускаете `sudo systemctl daemon-reload` каждый раз при внесении изменений в сервис.

## LED сервис

Примеры сервисов событий для ReSpeaker 2Mic и 4Mic HAT включены в `wyoming-satellite/examples`, они изменяют цвет LED в зависимости от состояния спутника. Пример ниже для 2Mic HAT с использованием `2mic_service.py`. Если вы используете 4Mic HAT, используйте `4mic_service.py`, так как светодиоды и GPIO пины немного отличаются.

Установите его из домашней директории:

```sh
cd wyoming-satellite/examples
python3 -m venv --system-site-packages .venv
.venv/bin/pip3 install --upgrade pip
.venv/bin/pip3 install --upgrade wheel setuptools
.venv/bin/pip3 install 'wyoming==1.5.2'
```

Если вы используете ReSpeaker USB 4mic array v2.0, дополнительно установите pixel-ring:

```sh
.venv/bin/pip3 install 'pixel-ring'
```

Аргумент `--system-site-packages` используется для доступа к предустановленным пакетам `gpiozero` и `spidev`. Если они **ещё не установлены** в вашей системе, выполните:

```sh
sudo apt-get install python3-spidev python3-gpiozero
```

Протестируйте сервис:

```sh
.venv/bin/python3 2mic_service.py --help
```

Создайте systemd сервис:

```sh
sudo systemctl edit --force --full 2mic_leds.service
```

Вставьте следующий шаблон и измените `/home/pi` и аргументы `script/run` в соответствии с вашей настройкой:

```text
[Unit]
Description=2Mic LEDs

[Service]
Type=simple
ExecStart=/home/pi/wyoming-satellite/examples/.venv/bin/python3 2mic_service.py --uri 'tcp://127.0.0.1:10500'
WorkingDirectory=/home/pi/wyoming-satellite/examples
Restart=always
RestartSec=1

[Install]
WantedBy=default.target
```

Сохраните файл и выйдите из редактора.

Теперь вы можете обновить сервис спутника:

```sh
sudo systemctl edit --force --full wyoming-satellite.service
```

Обновите только следующие части:

```text
[Unit]
...
Requires=2mic_leds.service

[Service]
...
ExecStart=/home/pi/wyoming-satellite/script/run ... --event-uri 'tcp://127.0.0.1:10500'
...

[Install]
...
```

Перезагрузите и перезапустите сервис спутника:

```sh
sudo systemctl daemon-reload
sudo systemctl restart wyoming-satellite.service
```

Вы должны увидеть, что сервис загрузился автоматически:

```sh
sudo systemctl status wyoming-satellite.service 2mic_leds.service
```

Все они должны быть "active (running)" и зелёные.

Попробуйте голосовую команду и посмотрите, реагируют ли светодиоды. Используйте `journalctl` для проверки логов сервисов на наличие ошибок:

```sh
journalctl -u 2mic_leds.service -f
```

Если возникли проблемы, добавьте аргумент `--debug` в командную строку для увеличения уровня логирования.

Для управления яркостью светодиодов используйте аргумент `--led-brightness`, который принимает целые числа от 1 до 31.

Убедитесь, что запускаете `sudo systemctl daemon-reload` каждый раз при внесении изменений в сервис.

---

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

- [Руководство по развёртыванию](../../DEPLOY.md)
- [Интерактивный установщик](installer.md)