Google Assistant на Raspberry Pi

diy-home-assistant-raspi

В последние годы голосовые ассистенты стали обычной частью умного дома. Многие используют Alexa или Google Home для управления освещением, медиаплеерами и таймерами. Технологии, стоящие за этими устройствами, в значительной мере доступны — Google предоставляет Assistant SDK, который позволяет запускать ассистента на собственных устройствах.

Эта подробная инструкция объясняет, как развернуть Google Assistant на Raspberry Pi и настроить голосовое управление светодиодом через GPIO. Я описываю все этапы — от аппаратного обеспечения и настройки звука до изменения скрипта для работы с пином GPIO 18.

Что вам понадобится

Raspberry Pi Google Assistant Required Equipment

Raspberry Pi с чистой установкой Raspbian на SD-карте.
USB-вебкамера или отдельный микрофон (в примере использовалась вебкамера только за её микрофон).
Внешний динамик (в примере используется выход 3.5 мм, но можно использовать HDMI при корректировке конфигурации).
Опционально: светодиод, резистор и проводка согласно руководству по подключению LED к Raspberry Pi.
Браузер, авторизованный в Google-аккаунте для работы с Google Action Console.

Важно: совместимость микрофона и динамика с Raspberry Pi может варьироваться. Если вы используете HDMI-аудио, потребуется поправить конфигурацию звука ниже.

План действий (коротко)

Подключить микрофон и динамик; при необходимости собрать схему с LED.
Настроить аудиоустройства в системе (arecord, aplay, .asoundrc).
Зарегистрировать проект в Google Action Console и включить Google Assistant API.
Скопировать скачанный JSON-файл с учётными данными на Pi и создать виртуальное окружение Python.
Установить зависимости и SDK, пройти OAuth-аутентификацию для Pi.
Запустить ассистента и протестировать голосовые команды.
(Бонус) Изменить скрипт hotword.py для управления GPIO и включить trait OnOff в консоли.

Настройка звука на Raspberry Pi

Инструкцию можно выполнять непосредственно на Pi или удалённо через SSH. В любом случае начнём с терминала.

Подключите USB-вебкамеру (или микрофон) и динамик.
Выполните в терминале:

arecord -l
aplay -l

Эти команды выведут список доступных устройств для записи и воспроизведения. Обратите внимание на номера card и device для микрофона и динамика — они понадобятся для конфигурации.

Check the Playback and Recording devices

Важно: в примере USB-вебкамера отображается как card 1 device 0. У вас номера могут отличаться.

Убедитесь, что находитесь в каталоге /home/pi и создайте файл .asoundrc:

sudo nano /home/pi/.asoundrc

Пример содержимого .asoundrc (адаптируйте card/device под своё устройство):

pcm.usbplay {
  type hw
  card 1
  device 0
}

pcm.!default {
  type asym
  playback.pcm { type plug; slave.pcm "usbplay" }
  capture.pcm { type plug; slave.pcm "hw:1,0" }
}

Если вы хотите использовать HDMI, измените секцию playback на соответствующую карту/устройство HDMI.

Сохраните Ctrl+X, затем Y и Enter.

Проверьте запись и воспроизведение: запишите короткий фрагмент и проиграйте его.

arecord -D plughw:1,0 -f cd -d 5 test.wav
aplay test.wav

Если громкость микрофона слишком низкая или высокая, откройте alsamixer и нажмите F6 для переключения между устройствами.

alsamixer

Совет: для постоянной настройки звука можно сохранить настройки с помощью alsactl store.

Важно: если вы используете HDMI как выход, возможны дополнительные настройки в /boot/config.txt и в ALSA/ PulseAudio.

Создание проекта в Google Action Console

Откройте браузер на Pi или на локальной машине и перейдите в Google Action Console.
Нажмите New Project и создайте проект. Подождите несколько секунд, страница перенаправит вас в консоль.

Create a new Google Project

Оставьте вкладку открытой — дальше нужно включить API и настроить разрешения активности.

Включение Google Assistant API и разрешений активности

Перейдите на страницу Google Assistant API и нажмите Enable.

Enable the Google Assistant API

Зайдите в Activity Controls (Контроль активности) и убедитесь, что включены:

Web & App Activity (включая историю Chrome)
Device Information
Voice and Audio Activity

Changing Google Activity settings

Это требуется для корректной работы ассистента и регистрации устройства.

Регистрация Raspberry Pi как устройство

В Action Console выберите Device registration.
Создайте продукт: задайте понятное имя и укажите производителя (можно любое значение). Тип устройства выберите Auto.

Нажмите Register Model, затем Download OAuth 2.0 Credentials — скачивается JSON-файл client_secret_XXXXX.json.

Рекомендуем переместить файл в /home/pi.

Если вы работаете через SSH и скачали JSON на локальную машину, скопируйте его на Pi командой scp:

scp ~/Downloads/client_secret_client-id.json pi@:/home/pi/

Замените на IP вашей платы и укажите правильный путь к локальному файлу.

Copy the Secret Cient ID to the PI

На Pi выполните ls -l в /home/pi и убедитесь, что файл присутствует.

Установка SDK и окружения Python

Рекомендуется создать виртуальное окружение Python и работать в нём.

Создайте и активируйте виртуальное окружение env:

python3 -m venv env
source env/bin/activate
python -m pip install --upgrade pip setuptools wheel

Установите системные зависимости для работы звука и криптографии:

sudo apt-get update
sudo apt-get install -y portaudio19-dev libffi-dev libssl-dev libmpg123-dev

Установите библиотеки Google Assistant SDK и инструменты аутентификации:

python -m pip install --upgrade google-assistant-library
python -m pip install --upgrade "google-assistant-sdk[samples]"
python -m pip install --upgrade "google-auth-oauthlib[tool]"

Если какая-либо установка завершилась ошибкой, проверьте сообщения об ошибках, свободное место и корректность pip/apt источников.

Аутентификация Raspberry Pi (OAuth)

Используйте утилиту google-auth-oauthlib[tool] для аутентификации устройства с помощью скачанного JSON-файла:

google-oauthlib-tool --scope https://www.googleapis.com/auth/assistant-sdk-prototype \
  --scope https://www.googleapis.com/auth/gcm \
  --save --headless --client-secrets /home/pi/YOUR_CLIENT_SECRET_ID.json

Замените YOUR_CLIENT_SECRET_ID.json на точное имя файла, которое вы скачали.

Утилита выдаст ссылку: откройте её в браузере, выберите аккаунт и скопируйте код авторизации. Вставьте код в терминал. После успешной авторизации вы увидите сообщение “Credentials Saved: /home/pi/…”.

Generating the Authorization link from the command line.

Запуск и тестирование Google Assistant

Запустите ассистент с передачей project-id и device-model-id:

googlesamples-assistant-hotword --project-id my-dev-project --device-model-id my-model

Замените my-dev-project и my-model на значения из настроек Action Console (Project ID и Device model id).

Скажите «OK Google» и задайте вопрос. В терминале будет вывод, показывающий распознанную речь и ответ ассистента.

Terminal output for Google Assistant

Если уровень звука низкий, можно попросить ассистента увеличить громкость: «Hey Google, turn your volume up to 80%.»

Бонус — голосовое управление GPIO (LED)

Вы можете управлять светодиодом через GPIO, добавив обработку команды OnOff из Google Assistant. Для этого включите trait OnOff в консоли и модифицируйте скрипт hotword.py.

В Action Console откройте Device registration, выберите своё устройство и включите trait OnOff. Сохраните изменения.

Activating the OnOff Assistant trait

Убедитесь, что вы в виртуальном окружении env, и клонируйте SDK-примеры:

git clone https://github.com/googlesamples/assistant-sdk-python

Установите библиотеку для работы с GPIO:

pip install rpi.gpio

Перейдите в каталог с файлом hotword.py:

cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/library

Откройте hotword.py в редакторе и добавьте импорт RPi.GPIO:

import RPi.GPIO as GPIO

Инициализируйте пин 18 в main() до начала обработки событий:

GPIO.setmode(GPIO.BCM)
GPIO.setup(18, GPIO.OUT, initial=GPIO.LOW)

В функции process_event замените или откомментируйте старый print и добавьте логику для команды OnOff:

# print('Do command', command, 'with params', str(params))
if command == "action.devices.commands.OnOff":
    if params['on']:
        print('---------------')
        print('Led turned on')
        print('---------------')
        GPIO.output(18, GPIO.HIGH)
    else:
        print('---------------')
        print('Led turned off')
        print('---------------')
        GPIO.output(18, GPIO.LOW)

Сохраните изменения и запустите модифицированный скрипт, указав device-model-id:

python hotword.py --device-model-id YOUR-MODEL-ID-HERE

Теперь при команде «OK Google, turn on» ассистент распознает запрос и изменит состояние пина GPIO, включая или выключая светодиод.

Terminal Message showing

Voice activated LED.

Примечание: изображение демонстрирует вывод в терминале и результат работы скрипта — светодиод загорается при команде.

Практические советы и отладка

Если ассистент не реагирует, проверьте последовательно:

Правильность .asoundrc и выбранных карт устройств (arecord/aplay).
Работоспособность микрофона (arecord выводит звук) и динамика (aplay воспроизводит файл).
Наличие и корректность client_secret JSON в /home/pi и правильность пути при вызове google-oauthlib-tool.
Правильность project-id и device-model-id при запуске googlesamples-assistant-hotword.
Наличие прав и модулей RPi.GPIO при управлении GPIO; исполнительный пользователь должен иметь доступ к GPIO (обычно pi).

Типичные ошибки и решения:

“Device not found” при arecord/aplay: проверьте USB-подключение и dmesg на предмет ошибок.
“Credentials not found” при auth: убедитесь, что имя JSON-файла совпадает и вы запустили команду из /home/pi.
Низкий уровень громкости: используйте alsamixer или голосовую команду ассистенту для увеличения громкости.

Критерии приёмки

Чтобы считать установку успешной, выполните следующие проверки:

Системная проверка звука: arecord -l и aplay -l показывают ожидаемые устройства.
Тестовая запись и воспроизведение прошли успешно (команды arecord/aplay).
OAuth прошёл успешно и в /home/pi появились сохранённые креденшелы от google-oauthlib-tool.
Ассистент запускается и отвечает на «OK Google» в терминале.
(Для GPIO) При голосовой команде включения/выключения светодиод реагирует корректно и стабильно.

Чек-листы по ролям

Новичок:

Убедиться, что Raspberry Pi обновлён: sudo apt-get update && sudo apt-get upgrade
Подключить микрофон и динамик, выполнить arecord/aplay
Создать Google-проект и скачать client_secret JSON
Запустить пример ассистента и проверить реакцию на голос

Продвинутый пользователь / разработчик:

Настроить виртуальное окружение и запустить SDK-образцы
Изменить hotword.py для работы с GPIO
Интегрировать дополнительные traits (таймеры, уведомления)

Администратор / безопасность:

Настроить пользователя с минимальными правами для запуска ассистента
Ограничить доступ к JSON-файлам учётных данных (chmod 600)
Настроить брандмауэр и мониторинг сетевого трафика

Модель действий (mini-methodology)

Plan — определить цели (воспроизведение аудио, голосовые команды, управление GPIO).
Prepare — собрать оборудование, подготовить SD-карту и аккаунт Google.
Implement — настроить звук, создать проект в Google, установить SDK.
Verify — пройти OAuth, запустить ассистента, проверить голосовые команды.
Harden — отключить ненужные службы, защитить секреты и обновить систему.

Тест-кейсы и критерии приёмки (короткая подборка)

Тест микрофона: записать 5-секундный файл, воспроизвести, убедиться в слышимости.
Тест ассистента: фраза «OK Google, whats the weather?» должна вызвать ответ (в терминале виден лог и слышен ответ).
Тест GPIO: голос «turn on» → светодиод включился; голос «turn off» → светодиод выключился. Повторить 5 раз без ошибок.

Когда это может не сработать (ограничения и исключения)

Google Assistant SDK может изменяться; описанные API и флаги могут устареть — проверяйте официальную документацию.
Некорректно собранная схема с LED или неправильное подключение пинов может повредить Raspberry Pi. Соблюдайте правила работы с электроникой.
Некоторые USB-микрофоны требуют специфичных драйверов, отсутствующих в Raspbian по умолчанию.
Для коммерческого использования может потребоваться отдельная проверка лицензий и согласование с политиками Google.

Безопасность и конфиденциальность

Храните clientsecret JSON в защищённом каталоге и ограничьте права: chmod 600 /home/pi/client_secret*.json.
Если устройство работает круглосуточно, подумайте о физической защите микрофона и индикаторах активности, чтобы пользователи знали, когда устройство слушает.
Обращайте внимание на включённые активности в аккаунте Google (Voice and Audio Activity) — это сохраняет голосовые записи в аккаунте.
Для соответствия требованиям GDPR в коммерческих проектах потребуется информирование пользователей и управление хранением данных.

Совместимость и миграционные заметки

Инструкции ориентированы на Raspbian / Raspberry Pi OS и Python 3.
Если вы используете Raspberry Pi OS Bullseye/Bookworm и новее, проверьте совместимость пакетов portaudio и rpi.gpio; для некоторых версий используется библиотека gpiozero.
При переходе на другую версию Python не забывайте пересоздать виртуальное окружение и переустановить зависимости.

Матрица принятия решений (Mermaid)

flowchart TD
  A[Начало: подключить оборудование] --> B{arecord/aplay показывают устройства?}
  B -- Да --> C{Скачан client_secret.json?}
  B -- Нет --> D[Проверить USB и dmesg]
  C -- Да --> E{OAuth пройден?}
  C -- Нет --> F[Скачать и переместить JSON на /home/pi]
  E -- Да --> G[Запустить ассистента]
  E -- Нет --> H[Запустить google-oauthlib-tool и пройти авторизацию]
  G --> I{Работает ли распознавание?}
  I -- Да --> J[Если нужен GPIO — включить trait OnOff и модифицировать hotword.py]
  I -- Нет --> K[Проверить .asoundrc и alsamixer]

Резюме и дальнейшие шаги

Поздравляю — вы установили Google Assistant на Raspberry Pi и научились управлять светодиодом голосом. Дальше можно расширять функциональность:

Добавить управление несколькими GPIO-устройствами через разные traits.
Интегрировать Home Assistant или Node-RED для сложных сценариев автоматизации.
Создать пользовательский интерфейс или web-панель для управления и мониторинга устройства.

Короткий список полезных команд

arecord -l — список устройств записи
aplay -l — список устройств воспроизведения
alsamixer — настройка уровней звука
google-oauthlib-tool … — OAuth аутентификация
googlesamples-assistant-hotword –project-id –device-model-id — запуск ассистента

Краткая глоссарий (1 линия)

OAuth — протокол авторизации, позволяющий приложению получить доступ к API от имени пользователя.
trait — в контексте Google Actions — функциональная возможность устройства (например, OnOff).
GPIO — общие входы/выходы для взаимодействия с внешней электроникой на Raspberry Pi.

Ваш проект с Google Assistant на Raspberry Pi — отличная отправная точка для домашней автоматизации и экспериментов с голосовым вводом. Начните с базовой настройки, затем добавляйте функции по мере уверенности и следите за безопасностью и конфиденциальностью данных.