Установка Alexa (MMM-awesome-alexa) на Magic Mirror

Быстрые ссылки

Материалы, которые понадобятся
Установка зависимостей модуля
Загрузка кода модуля
Настройка модуля Alexa
Добавление модуля Alexa в конфигурацию Magic Mirror
Отладка, безопасность и альтернативы

Если вы уже собрали «умное зеркало», у вас есть доступ к календарям, погоде и новостям. Но возможности можно расширить: программное обеспечение Magic Mirror позволяет подключать модули для дополнительных функций, например, голосового управления через Alexa.

Разработчики сообщества создают такие модули. Опции варьируются от утилитарных (Alexa, детекция присутствия через камеру или датчик PIR) до развлекательных (снежинки, информация о воспроизведении Spotify).

Мы рекомендуем модуль mmm-awesome-alexa — он поддерживается активным разработчиком, однако существуют и другие модули Alexa для Magic Mirror.

Если вы предпочитаете Google Assistant, у Google есть официальный пошаговый урок по установке Assistant на Raspberry Pi. В то же время некоторые модули Google Assistant для Magic Mirror нестабильны: они могут падать или перекрывать UI зеркала. Для простоты чаще рекомендуют добавить комплект Google AIY и следовать его инструкции.

Общие шаги установки любого модуля:

Скачивание кода модуля с GitHub
Настройка опций, специфичных для модуля
Добавление модуля в конфигурацию Magic Mirror

В зависимости от модуля шаги 2 и 3 могут быть проще или сложнее. Настройка Alexa требует больше конфигурации, чем, скажем, добавление снежинок. Этот конкретный модуль требует установки дополнительных зависимостей перед загрузкой.

Материалы, которые понадобятся

Набор Google AIY для голосового управления с Raspberry Pi

Это руководство предполагает, что Smart Mirror уже собран. Если нет — сначала соберите зеркало, но заранее учитывайте дополнительные материалы и расходы.

Минимум понадобится:

Собранное Smart Mirror (с Raspberry Pi и дисплеем)
Микрофон
Динамик

Для микрофона и динамика рекомендован оригинальный Google AIY Voice Kit. По состоянию на момент написания руководства комплект стоит примерно $16 — это один из самых недорогих собранных вариантов с микрофоном и динамиком. Коробку из картона можно не использовать; часто компоненты размещают отдельно вне корпуса зеркала для лучшего качества звука.

Вторая версия Google AIY дороже и содержит Raspberry Pi Zero, который недостаточно мощный для wake-word и работы Magic Mirror — поэтому её стоит пропустить.

Подключите динамик и микрофон и переходите к установке модуля Alexa. Если вы используете Google AIY, следуйте его руководству по сборке для подключения микрофона и динамика.

Установка зависимостей модуля

Прежде чем скачивать и настраивать mmm-awesome-alexa, нужно установить системные и node-зависимости. Рекомендуется обновить Raspberry Pi перед установкой новых пакетов. Запустите в терминале:

sudo apt update && sudo apt upgrade

После обновления выполните команды по очереди (введите одну строку, дождитесь завершения, затем следующую):

sudo apt-get install sox libsox-fmt-all

sudo apt-get install swig3.0 python-pyaudio python3-pyaudio sox

pip install pyaudio

sudo apt-get install libasound-dev portaudio19-dev libportaudio2 libportaudiocpp0 ffmpeg libav-tools

sudo apt-get install libatlas-base-dev

Каждая команда устанавливает требуемую зависимость. Важно выполнять их одну за другой и разрешать установку, когда система запросит подтверждение.

Примечание: если у вас используются альтернативные менеджеры пакетов или вы работаете на другой версии Raspbian/OS, названия пакетов и команды могут отличаться. В этом случае сначала проверьте официальную документацию своей ОС.

Загрузка кода модуля

Первый шаг при добавлении любого модуля — скачать код из GitHub. Подключитесь к Raspberry Pi (локально или по SSH), откройте терминал и перейдите в папку модулей Magic Mirror:

cd ~/MagicMirror/modules

Скачайте репозиторий модуля:

git clone https://github.com/dolanmiu/MMM-awesome-alexa.git

Перейдите в папку модуля:

cd MMM-awesome-alexa

Установите node-зависимости (только для production):

npm install --only=prod

Затем перейдите в папку node_modules внутри модуля:

cd node_modules

Удалите поставленный пакет snowboy — требуется более свежая версия:

rm -rf snowboy

Скачайте актуальную версию snowboy:

git clone https://github.com/Kitt-AI/snowboy.git

Перейдите в папку snowboy:

cd snowboy

Внутри папки snowboy удалите node_modules и установите дополнительные зависимости. Важно не менять директорию до завершения шагов. Выполните команды по очереди:

rm -rf node_modules

npm install nan --save

npm install node-pre-gyp@0.12.0 --save

npm install

npm run prepublish

npm install --save-dev electron-rebuild

npm install nan

./node_modules/.bin/electron-rebuild

После этого модуль и его зависимости должны быть полностью установлены.

Важно: сборка снежка (snowboy) может требовать наличия build-утилит и заголовков ядра. Если вы увидите ошибки компиляции, установите пакеты типа build-essential и python-dev, затем повторите npm install.

Настройка модуля Alexa

Диалог конфигуратора для MMM-awesome-alexa

Теперь необходимо настроить модуль. Перейдите в корневую папку модуля и запустите помощник конфигурации:

cd ~/MagicMirror/modules/MMM-awesome-alexa

npm run config-helper

Помощник запросит Client ID. Для этого нужно создать «устройство» в Alexa Developer Console.

Откройте браузер и войдите в Alexa Developer Console под своей учётной записью Amazon.
Нажмите Get Started, затем перейдите в раздел Products и выберите Create Product.
Назовите продукт и задайте product ID. Рекомендуемые примеры: “Magic_Mirror_Alexa” (имя) и “YourFirstName_MM_Alexa” (ID). Категория — Smart Home. Включите hands-free и far-field.
На серии вопросов ответьте “No” (если вы не используете внешние сертификации) и нажмите Next.
На странице security profile создайте новый профиль, используя тот же product ID, затем продолжите и завершите процесс.

После создания продукта и security profile вы получите Client ID и Client Secret.

Страница с Client ID и Client Secret в Alexa Developer Console

В поле Allowed Return URLs добавьте:

https://magic-mirror-avs.github.io/Alexa-Web-Helper/authresponse

Сохраните изменения (Update).

Вернитесь в терминал, вставьте Client ID, затем Client Secret, когда помощник это запросит. При запросе Device ID введите ваш product ID (например, Magic_Mirror_Alexa). Когда спросят Return URL, введите:

https://magic-mirror-avs.github.io/Alexa-Web-Helper/authresponse

После этого терминал выдаст ссылку для авторизации — скопируйте её и откройте в браузере. Войдите в Amazon, затем нажмите Allow на странице разрешений.

Запрос разрешений голосовых сервисов Alexa с кнопкой Allow

На странице браузера вы можете увидеть ошибку — это ожидаемо. В адресной строке найдите параметр “code=…” и скопируйте значение (буквы и цифры между code= и &scope). Примерная позиция на скриншоте ниже.

URL с кодом устройства Alexa

Вставьте этот код в терминал и нажмите Enter. Когда помощник спросит, хотите ли вы сгенерировать конфигурацию для MagicMirror — введите Y и нажмите Enter. Выберите слово пробуждения (по умолчанию Alexa) и ответьте No на вопросы про lite mode и визуализацию, если не нужна визуализация аудиопотока.

Помощник сгенерирует блок конфигурации модуля наподобие:

{

module: "MMM-awesome-alexa",

position: "bottom_bar",

config: {

wakeWord: "Alexa",

clientId: "YOUR_CLIENT_ID",

clientSecret: "YOUR_CLIENT_SECRET",

deviceId: "YOUR_DEVICE_ID",

refreshToken: "YOUR_REFRESH_TOKEN",

lite: false,

isSpeechVisualizationEnabled: false

}

}

Скопируйте этот блок — он потребуется для config.js Magic Mirror.

Добавление модуля в конфигурацию Magic Mirror

Перейдите в папку конфигурации и откройте config.js:

cd ~/MagicMirror/config

nano config.js

Найдите место, где перечислены другие модули. После завершения предыдущего модуля (там, где встречается },) нажмите Enter, чтобы создать пустую строку перед началом нового модуля ({).

Вставьте блок конфигурации, сгенерированный помощником. Обратите внимание: авто-сгенерированный блок иногда не содержит завершающей запятой , после закрывающей фигурной скобки модуля — добавьте её вручную, чтобы конфигурация оставалась корректным JSON-подобным объектом в файле config.js. Пример:

},

{
  module: "MMM-awesome-alexa",
  position: "bottom_bar",
  config: {
    wakeWord: "Alexa",
    clientId: "...",
    clientSecret: "...",
    deviceId: "...",
    refreshToken: "...",
    lite: false,
    isSpeechVisualizationEnabled: false
  }
},

Сохраните файл: Ctrl+X → Y → Enter.

Перезапустите Magic Mirror менеджером процессов:

pm2 restart mm

После перезапуска Alexa должна работать на вашем зеркале.

Отладка и устранение проблем

Важно: этот модуль — один из сложных для настройки. Ниже — набор типичных проблем и способы их решения.

Ошибка при npm install (компиляция snowboy):
- Убедитесь, что установлены build-essential, python-dev и заголовки для node-gyp. Выполните:

sudo apt-get install build-essential python-dev

Затем повторите npm install внутри проблемного каталога.

Проблемы с pyAudio или доступом к микрофону:
- Проверьте, что микрофон корректно подключён и виден в списке ALSA:

arecord -l

Убедитесь, что user, под которым запускается Magic Mirror, имеет доступ к аудиоустройствам (возможно, нужны группы audio).

Не удаётся пройти OAuth (код в URL не найден):
- Скопируйте весь URL строки, ищите “code=” и скопируйте значение до следующего &.
Alexa не реагирует на wake word:
- Проверьте логи модуля (pm2 logs mm или логи в директории модуля).
- Убедитесь, что snowboy успешно собран и подключён — наличие ошибки сборки приведёт к неработающему распознаванию.
Модуль падает и скрывает интерфейс зеркала:
- Запустите Magic Mirror в режиме разработки (без pm2) или проверьте pm2 logs mm для трассировки стека.

Полезные команды для диагностики:

pm -v
node -v
pm2 logs mm --lines 200
journalctl -u your-service-name (если вы используете systemd)

Когда это не сработает (контр-примеры)

Raspberry Pi Zero (из AIY v2) — недостаточно мощный для wake-word и стабильной работы Alexa вместе с Magic Mirror.
Низкокачественные USB-микрофоны с нестабильными драйверами могут выдавать искажения и частые сбои.
Сетевые ограничения (файрволы, прокси) могут блокировать OAuth-поток и доступ к Alexa Voice Service.

Если вы попали в одну из этих ситуаций, рассмотрите альтернативные подходы (ниже).

Альтернативные подходы

Google Assistant с Google AIY: имеет официальную документацию по установке Assistant на Raspberry Pi и может быть проще, если вы предпочитаете экосистему Google.
Использовать отдельное устройство Echo (Amazon Echo Dot) и связать его с зеркалом — простой путь получать голосовой контроль без установки AVS на Pi.
Локальные решения для wake-word (Porcupine, Snowboy альтернативы) — для повышения приватности и локальной обработки.

Методика установки (шпаргалка)

Краткая методология в 6 шагов для повторного использования:

Подготовьте оборудование: Pi, микрофон, динамик, сеть.
Обновите систему: apt update && apt upgrade.
Установите системные зависимости (sox, portaudio и т.д.).
Скачайте модуль в ~/MagicMirror/modules и установите npm-зависимости.
Настройте Alexa Developer Console и пройдите OAuth через config-helper.
Вставьте блок в config.js и перезапустите Magic Mirror.

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

Чек-лист для сборщика (Maker):

Собрать и установить Raspberry Pi в корпус зеркала
Подключить микрофон и динамик, проверить запись/воспроизведение
Убедиться в стабильном подключении к сети
Сборка/установка snowboy в модуле выполнена успешно

Чек-лист для администратора (Ops):

Настроить обновления безопасности на Raspberry Pi
Ограничить SSH доступ (ключи вместо паролей)
Проверить логи pm2 и настроить ротацию логов
Проверить, что Client Secret хранится в защищённом месте (не в общедоступном репозитории)

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

Система можно считать корректно установленной если:

После перезапуска pm2 restart mm модуль загружается без ошибок в логах.
Alexa отвечает на wake word и воспроизводит ответ аудио через подключённый динамик.
Распознанные команды корректно обрабатываются и не приводят к падениям процесса.

Тест‑кейсы / Критерии приёмки

Тест «Wake word»:
- Шаги: Произнести wake word (Alexa). Ожидаемый результат: модуль активируется, последующий голосовой ввод обрабатывается.
Тест «OAuth»:
- Шаги: Пройти авторизацию через сгенерированную ссылку и вставить код в терминал. Ожидаемый результат: config-helper получает refresh token.
Тест «Стабильность»:
- Шаги: Оставить зеркало включённым 24 часа. Ожидаемый результат: модуль работает без аварийных остановок.

Модель принятия решений (Mermaid)

flowchart TD
  A[Нужна голосовая ассистентка?] -->|Да| B{Использовать Alexa или Google?}
  B -->|Alexa| C[Использовать mmm-awesome-alexa]
  B -->|Google| D[Рассмотреть Google AIY или официальный Assistant]
  A -->|Нет| E[Оставить текущую конфигурацию]
  C --> F{Raspberry Pi модель}
  F -->|Pi 3/4| G[Поддержка OK]
  F -->|Pi Zero| H[Не рекомендуется]

(Скопируйте и отобразите mermaid-диаграмму в поддерживающем редакторе.)

Риски и меры смягчения

Риск: Утечка Client Secret или refresh token
- Митигирование: хранить конфигурацию на локальном устройстве, не коммитить config.js в публичные репозитории.
Риск: Перегрузка CPU при распознавании речи
- Митигирование: использовать более мощные модели Pi (3B/4) и оптимизировать запущенные модули.
Риск: Частые падения из-за несовместимых версий пакетов
- Митигирование: фиксировать версии node/npm и использовать nvm для управления версиями.

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

Голосовые данные обычно отправляются в облако (Alexa Voice Service). Если конфиденциальность критична, рассмотрите локальные wake-word решениия и минимизацию передачи аудиопотока.
Ключи и секреты: храните clientSecret и refreshToken локально и не публикуйте в открытых репозиториях.
GDPR/локальные законы: если зеркалом пользуются другие люди, уведомите их об активной записи голоса и настройте политику хранения данных.

Совместимость и миграция

Рекомендуемые платформы: Raspberry Pi 3 и 4. Pi Zero — не рекомендуется.
Node.js: используйте версии, совместимые с Electron и с собранными версиями модулей; при проблемах попробуйте nvm и тестируйте на чистой системе.
Snowboy: проект устаревший, поэтому для будущих миграций рассмотрите альтернативы по wake-word (Porcupine от Picovoice и др.).

Факты и полезные числа

Примерная стоимость Google AIY Voice Kit: ~ $16 (указана в оригинальном материале).
Рекомендуемая Raspberry Pi: Pi 3 или Pi 4 для надежной работы wake-word и AVS.

Глоссарий (1 строка)

AVS — Alexa Voice Service, облачный сервис Amazon для голосовых взаимодействий.
Snowboy — локальная библиотека для обнаружения wake-word (часто требует сборки).
Client ID/Secret — учётные данные приложения в Alexa Developer Console, необходимые для OAuth.

Краткая сводка

Установка модуля требует системных и node-зависимостей, загрузки репозитория и регистрации в Alexa Developer Console.
Важные этапы: подготовка микрофона/динамика, установка sox/portaudio/nan, сборка snowboy и завершение настройки через config-helper.
Альтернативы: Google AIY / Assistant или использование отдельного Echo-устройства.

Сводка ключевых шагов:

Обновить систему → установить пакеты → клонировать MMM-awesome-alexa → npm install → собрать snowboy → npm run config-helper → добавить в config.js → pm2 restart mm

Если возникнут ошибки, проверьте логи pm2 и убедитесь, что все системные зависимости установлены.