Zigbee2MQTT в Home Assistant устанавливается за три шага: добавить брокер Mosquitto, подключить интеграцию MQTT и поставить add-on Zigbee2MQTT с указанием порта вашего Zigbee-стика. Устройства затем появляются в Home Assistant автоматически через MQTT Discovery. Ниже — установка с нуля, пример конфигурации, сопряжение датчиков и решение частых проблем.
1Что понадобится
- Home Assistant OS или Supervised (для установки add-on’ов). На Docker Zigbee2MQTT запускается отдельным контейнером.
- Zigbee-координатор: USB-стик или сетевой адаптер. Выбор описан в статье про Zigbee в Home Assistant.
- Брокер MQTT: Mosquitto broker из магазина дополнений.
- USB-удлинитель, чтобы убрать стик от портов USB 3.0.
Add-on Zigbee2MQTT не входит в стандартный магазин: его добавляют из репозитория разработчика. Актуальный адрес репозитория и инструкции смотрите на сайте zigbee2mqtt.io в разделе установки для Home Assistant, чтобы не ошибиться в ссылке.
2Шаг 1. Установите Mosquitto
- Откройте «Настройки» → «Дополнения» → «Магазин дополнений» и найдите Mosquitto broker.
- Установите дополнение, включите «Запускать при старте» и «Watchdog», затем запустите.
- Перейдите в «Настройки» → «Устройства и службы»: интеграция MQTT обычно появляется в списке найденных. Нажмите «Настроить» и подтвердите.
- Создайте отдельного пользователя Home Assistant для Zigbee2MQTT (в настройках раздела «Люди», вкладка пользователей) без прав администратора: аддон Mosquitto по умолчанию проверяет логины среди пользователей Home Assistant.
Подробнее о брокере, топиках и отладке читайте в статье про MQTT в Home Assistant.
3Шаг 2. Установите add-on Zigbee2MQTT
- В магазине дополнений откройте меню «Репозитории» и добавьте репозиторий Zigbee2MQTT из документации проекта.
- Установите Zigbee2MQTT и откройте вкладку «Конфигурация».
- Найдите порт стика: в «Настройки» → «Система» → «Оборудование» → «Все оборудование» ищите устройство вроде
/dev/serial/by-id/usb-.... Используйте путь by-id, он не меняется после перезагрузок. - Укажите данные брокера MQTT и сохраните.
- Запустите add-on и проверьте журнал: должны появиться сообщения о подключении к брокеру и запуске координатора.
4Пример конфигурации
Основной файл настроек configuration.yaml Zigbee2MQTT можно править в интерфейсе add-on’а. Ориентировочный вид для Home Assistant OS с Mosquitto:
version: 5
homeassistant:
enabled: true
mqtt:
base_topic: zigbee2mqtt
server: mqtt://core-mosquitto:1883
user: zigbee
password: !secret mqtt_password
serial:
port: /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2-if00-port0
adapter: ember
frontend:
enabled: true
port: 8099
advanced:
channel: 20
network_key: GENERATEПоле adapter зависит от чипа: ember — для Silicon Labs (EFR32), zstack — для Texas Instruments (CC26xx). Если указать неверно, координатор не стартует. Канал выбирайте так, чтобы он не пересекался с Wi-Fi 2,4 ГГц, и меняйте его до сопряжения устройств. Параметры могут слегка отличаться между версиями Zigbee2MQTT, поэтому сверяйтесь с документацией проекта.
Нет времени разбираться? Мы можем настроить Home Assistant под ключ: поднимем Zigbee2MQTT, MQTT и перенесём ваши датчики.
5Шаг 3. Подключите устройства
- Откройте веб-интерфейс Zigbee2MQTT (кнопка «Открыть веб-интерфейс» add-on’а или порт 8099).
- Нажмите «Разрешить подключение» (Permit join) вверху страницы. Режим включается ненадолго и выключается сам.
- Переведите датчик в режим сопряжения: обычно нужно удерживать кнопку 3–5 секунд, пока не замигает индикатор.
- Дождитесь, пока устройство появится в списке, и дайте ему понятное имя (Friendly name). Имя используется в топиках MQTT.
- Проверьте в Home Assistant, что устройство появилось в «Устройства и службы» → MQTT.
Если устройство не определяется, проверьте, есть ли оно в списке поддерживаемых устройств на сайте проекта. Для редких моделей иногда нужны внешние конвертеры.
6Полезные возможности
| Функция | Для чего нужна |
|---|---|
| Карта сети | Показывает связи между устройствами и качество сигнала (LQI) |
| OTA-обновления | Прошивка устройств по воздуху, если производитель выпустил обновление |
| Группы | Одна команда сразу нескольким лампам, быстрее и надёжнее |
| Привязки (binding) | Прямое управление пульт-лампа без участия Home Assistant |
| Журнал сообщений | Диагностика проблемного датчика |
Привязки особенно полезны: выключатель IKEA или Aqara может управлять лампой напрямую, и свет продолжает работать даже при остановке Home Assistant.
7Типичные проблемы
- Add-on не видит стик. Проверьте путь порта и пробросы для виртуальной машины; убедитесь, что другой процесс (например, ZHA) не занял тот же порт.
- Не подключается к MQTT. Проверьте адрес
core-mosquitto, пользователя и пароль, а также что интеграция MQTT настроена. - Устройства не появляются в Home Assistant. Убедитесь, что включён
homeassistant: enabled: trueи что в MQTT включён Discovery. - Сеть нестабильна. Добавьте роутеры (розетки, лампы), используйте удлинитель и смените канал.
8Как назвать устройства, чтобы потом не запутаться
Friendly name в Zigbee2MQTT определяет топик MQTT, поэтому менять его позже неудобно. Придумайте схему заранее: например, kuhnya/dvizhenie или spalnya_datchik_temperatury. Лучше использовать латиницу без пробелов и специальных символов. Для красивого отображения в интерфейсе Home Assistant можно давать устройствам русские имена уже на стороне Home Assistant, не трогая топики.
Если вы переименовываете устройство в Zigbee2MQTT, включите опцию обновления сущностей Home Assistant при переименовании (rename entity IDs): тогда идентификаторы сущностей изменятся одновременно, но нужно будет поправить автоматизации и дашборды, которые на них ссылались.
9Резервное копирование Zigbee2MQTT
Критичные файлы лежат в каталоге данных add-on’а: configuration.yaml, database.db, coordinator_backup.json. Если вы потеряете их вместе с координатором, придётся заново подключать каждый датчик. Полные резервные копии Home Assistant включают данные add-on’ов, поэтому достаточно регулярных бэкапов системы; но дополнительно скачивайте копию вручную перед обновлением мажорных версий и перед сменой стика.
При замене координатора на аналогичный чип можно восстановить сеть из coordinator_backup.json, и устройства продолжат работать без повторного сопряжения. Если чипы разные, сеть придётся перестраивать. Заранее проверьте это в документации проекта, прежде чем выбрасывать старый стик.
10Пример автоматизации с кнопкой Zigbee
Беспроводные кнопки удобны для сцен. Zigbee2MQTT передаёт действие в сущность event или sensor в зависимости от модели. Пример автоматизации по MQTT-сообщению кнопки:
alias: Кнопка у кровати выключает свет
triggers:
- trigger: mqtt
topic: zigbee2mqtt/spalnya_knopka/action
payload: single
actions:
- action: light.turn_off
target:
area_id: spalnya
mode: singleДля кнопок и пультов, которые отправляют несколько действий (одно нажатие, двойное, долгое), создайте отдельную ветку выбора действия внутри одной автоматизации через блок choose. Так один сценарий управляет всей кнопкой, а не десятком мелких правил, и проще проверять логику при ошибках. Проверяйте топик действия в разделе вкладки MQTT или в журнале Zigbee2MQTT: точное имя события зависит от модели устройства и версии конвертера.
Если нужна помощь с разработкой более сложных сценариев, мы поможем с автоматизацией на заказ: кнопки, шторы, климат и присутствие.
11Контрольный список после запуска
Когда первые датчики подключены, пройдитесь по чек-листу. Убедитесь, что брокер Mosquitto запускается вместе с системой, что у Zigbee2MQTT включён автозапуск и watchdog, что стик подключён через удлинитель, а канал не пересекается с Wi-Fi. Сохраните копию каталога данных и проверьте, что резервные копии Home Assistant включают данные add-on’ов. Затем протестируйте перезагрузку всей системы: после неё все датчики должны вернуться в сеть без вмешательства. Если какие-то остаются недоступными, добавьте рядом ретрансляторы и проверьте питание. Эти простые проверки избавят от большинства проблем в будущем.
12Частые вопросы
Можно ли перейти с ZHA на Zigbee2MQTT без переподключения?
Нет, как правило, придётся заново добавлять устройства: сетевой ключ и привязки хранятся в разных базах. Заранее подготовьте список устройств и имён.
Нужен ли пароль для Mosquitto?
Да, рекомендуется создавать отдельного пользователя и запрещать анонимные подключения.
Как обновлять Zigbee2MQTT?
Add-on обновляется из интерфейса Home Assistant. Перед обновлением сделайте копию каталога данных, так как формат конфигурации иногда меняется между мажорными версиями.
13Итог
Zigbee2MQTT требует больше шагов, чем ZHA, но взамен даёт гибкость, OTA, группы и независимость от Home Assistant. После запуска датчики удобно использовать в сценариях — соберите их в конструкторе автоматизаций или закажите автоматизацию на заказ.
