Zigbee2MQTT принимает данные Zigbee-устройств через координатор и передает их в Home Assistant через MQTT. Основной путь - приложение Zigbee2MQTT (add-on, аддон; в новых версиях Home Assistant аддоны переименованы в apps) для Home Assistant OS и Supervised: документация называет такой способ установки самым простым. Настройка занимает восемь шагов - от MQTT-брокера до первого сопряженного устройства.
Что понадобится
Для работы нужны координатор, MQTT-брокер и Home Assistant с поддержкой приложений.
- Zigbee-координатор (адаптер) из числа поддерживаемых; он должен быть прошит прошивкой координатора. Рекомендуемые стеки: zStack (Texas Instruments), EmberZNet (Silicon Labs), deCONZ (Dresden Elektronik). ZiGate не рекомендуется и не сопровождается, ZBOSS - экспериментальный.
- MQTT-брокер - сервер, через который Home Assistant и Zigbee2MQTT обмениваются сообщениями. По документации Home Assistant первый шаг - выбрать брокер; проще всего поставить официальное приложение Mosquitto Broker.
- Home Assistant OS или Supervised: установка приложением рассчитана на них. Для остальных систем есть другие способы установки, они перечислены в конце.
Установка и настройка
Сначала ставятся брокер и приложение, затем настраиваются адаптер и MQTT, после первого запуска включается discovery и подключается первое устройство.
Шаг 1. Установите брокер Mosquitto
Установите официальное приложение Mosquitto Broker из магазина приложений Home Assistant (App store) и запустите его. Если MQTT-брокер уже работает, шаг пропустите.
Шаг 2. Добавьте репозиторий и установите приложение
Добавьте репозиторий https://github.com/zigbee2mqtt/hassio-zigbee2mqtt в меню репозиториев магазина, затем установите приложение. Приложений два: стабильное Zigbee2MQTT и Edge.
Шаг 3. Запустите приложение и откройте веб-интерфейс
Запустите приложение со страницы Info и откройте Web UI: откроется страница onboarding, мастера первичной настройки. Ошибка 502: Bad Gateway означает, что приложение еще стартует: подождите и обновите страницу. Если это длится дольше примерно двух минут, откройте вкладку Log.
Бывает, что приложение вообще не стартует, в логе Error: spawn udevadm ENOENT. Тема поднималась в 4 ветках форума, и в каждой решение было своим, общего рецепта нет.
Шаг 4. Настройте порт и тип адаптера
На странице onboarding в большинстве сценариев достаточно выбрать адаптер в разделе Found Devices: порт и тип подставятся сами. Если автоопределение не сработало, заполните serial: port и serial: adapter вручную. В примере из документации порт указан как /dev/serial/by-id/<SERIAL_ID>; типичные порты - /dev/ttyACM0, /dev/ttyUSB0, /dev/ttyAMA0. Проверить, что видит система, можно командой ha hardware info. Пример секции из документации:
serial:
port: /dev/serial/by-id/<SERIAL_ID>Самая обсуждаемая ошибка установки выглядит так: Zigbee2MQTT не стартует и не может подключиться к адаптеру, в логе Error: Failed to connect to the adapter (Error: SRSP - SYS - ping after 6000ms) - 19 веток форума. Пользователям помогало явно указать тип адаптера в секции serial под чип донгла и убедиться, что ZHA не использует тот же координатор.
Другая частая ошибка запуска - Error: Failed to start EZSP layer with status=HOST_FATAL_ERROR. (16 веток). Помогало отключить ZHA и проверить тип адаптера, порт и baudrate (скорость соединения с адаптером). Подробнее - в разборе ошибки Failed to start EZSP layer with status=HOST_FATAL_ERROR.
Если тип адаптера не задан вовсе, Zigbee2MQTT тоже может не запуститься (7 веток). Помогало прописать serial: adapter: ember для чипов Silicon Labs, zstack для Texas Instruments.
После обновления прошивки координатора SLZB-06 Zigbee2MQTT может не стартовать или стартовать без устройств, в логе Error: network commissioning timed out - most likely network with the same panId or extendedPanId already exists nearby (4 ветки). Пользователям помогал откат прошивки координатора и восстановление папки zigbee2mqtt или базы данных из резервной копии, сделанной до обновления.
Шаг 5. Укажите брокер MQTT
Задайте адрес брокера в mqtt: server. Минимальный пример из документации - адрес вида mqtt://<IP_ADDRESS>:<PORT>:
mqtt:
server: mqtt://<IP_ADDRESS>:<PORT>Шаг 6. Пройдите первый запуск
Onboarding запускается при первом старте, когда еще нет configuration.yaml. Если проверка настроек не прошла, страница ошибки остается на экране, а onboarding повторится при следующем старте. Чтобы запустить его принудительно, задайте переменную окружения Z2M_ONBOARD_FORCE_RUN.
Если поля на странице onboarding серые и недоступные (4 ветки), пользователям помогало оставить поля serial и MQTT пустыми в конфигурации приложения и заполнить их прямо на странице onboarding.
Шаг 7. Включите интеграцию Home Assistant
Включите интеграцию homeassistant, чтобы устройства появлялись через discovery - так называется механизм, которым Zigbee2MQTT сам объявляет сущности в Home Assistant через MQTT. По умолчанию интеграция выключена:
homeassistant:
enabled: trueЕсли устройства так и не появились в Home Assistant (18 веток), пользователям помогало обновить Home Assistant до 2024.9 или новее. Подробности - в материале о том, почему устройства Zigbee2MQTT не появляются в Home Assistant.
После обновления до Zigbee2MQTT 2.0 действия кнопок и пультов могут пропасть из автоматизаций Home Assistant (14 веток). Пользователи выходили из положения двумя путями: переводили автоматизации на сущности событий с event_type или временно включали опцию legacy_action_sensor в настройках Home Assistant-интеграции Zigbee2MQTT. Документация помечает эту опцию как устаревшую и предупреждает, что ее уберут, поэтому надежнее перейти на сущности событий. Подробный разбор - на странице про кнопки после Zigbee2MQTT 2.0.
Шаг 8. Подключите первое устройство
Откройте сеть для сопряжения кнопкой joining в правом верхнем углу фронтенда: сеть открыта 254 секунды. Второй способ - отправить permit_join в MQTT. Перед сопряжением проверьте устройство в списке поддерживаемых; если модели в списке нет, попробуйте сброс к заводским настройкам. Успех виден в журнале: завершенный interview (опрос устройства при сопряжении) и сообщение о сопряжении.
Частые проблемы после установки
Большинство сбоев собрано вокруг адаптера и discovery. Решения в таблице - опыт пользователей форума, а не гарантированные рецепты.
| Проблема | Что помогало пользователям | Подробнее |
|---|---|---|
Zigbee2MQTT не стартует, нет соединения с адаптером: Error: Failed to connect to the adapter (Error: SRSP - SYS - ping after 6000ms) (19 веток) | Указать тип адаптера в секции serial под чип донгла; убедиться, что ZHA не заняла тот же координатор | |
| Устройства Zigbee2MQTT не появляются в Home Assistant (18 веток) | Включить интеграцию homeassistant: enabled: true; обновить Home Assistant до 2024.9 или новее | Разбор проблемы |
Zigbee2MQTT падает при старте: Error: Failed to start EZSP layer with status=HOST_FATAL_ERROR. (16 веток) | Отключить ZHA; проверить тип адаптера, порт и baudrate | Разбор ошибки |
| После обновления до Zigbee2MQTT 2.0 действия кнопок и пультов пропадают из автоматизаций Home Assistant (14 веток) | Перевести автоматизации на сущности событий с event_type; как временная мера - устаревшая опция legacy_action_sensor | Разбор проблемы |
| Zigbee2MQTT не стартует, тип адаптера не задан (7 веток) | Прописать serial: adapter: ember для Silicon Labs, zstack для Texas Instruments | |
После обновления прошивки SLZB-06 Zigbee2MQTT не стартует или стартует без устройств: Error: network commissioning timed out - most likely network with the same panId or extendedPanId already exists nearby (4 ветки) | Откатить прошивку и восстановить папку zigbee2mqtt или базу данных из резервной копии, сделанной до обновления | |
Приложение не стартует: Error: spawn udevadm ENOENT (4 ветки) | Общего рецепта нет: в ветках форума решение каждый раз было своим | |
| На странице onboarding серые недоступные поля (4 ветки) | Оставить поля serial и MQTT пустыми в конфигурации приложения и заполнить их на странице onboarding |
Другие способы установки
Кроме приложения, документация перечисляет другие способы установки: Linux (нативная установка), Docker, openHABian, Windows, FreeBSD jail, Kubernetes.
Частые вопросы
Можно ли держать ZHA и Zigbee2MQTT на одном координаторе?
Нет, ZHA и Zigbee2MQTT не должны использовать один координатор. Если Zigbee2MQTT не стартует, первым делом проверьте, не занимает ли координатор ZHA: на форуме это снимало и ошибку соединения с адаптером, и ошибку EZSP. Разбор по каждой ошибке - в шаге 4.
Какой Zigbee-координатор выбрать?
Выбирайте координатор из списка поддерживаемых, прошитый прошивкой координатора. Рекомендуемые стеки - zStack (Texas Instruments), EmberZNet (Silicon Labs) и deCONZ (Dresden Elektronik). ZiGate лучше не брать: он не рекомендуется и не сопровождается. ZBOSS считается экспериментальным. Конкретную модель проверяйте в документации адаптеров до покупки.
Обязательно ли ставить Mosquitto broker?
Нет, если у вас уже есть работающий MQTT-брокер. Брокер для Zigbee2MQTT нужен в любом случае, а Mosquitto - лишь самый простой вариант для Home Assistant. Если брокер уже развернут, ставьте приложение Zigbee2MQTT и указывайте в нем адрес действующего брокера (mqtt: server).
Сколько времени открыта сеть для сопряжения?
254 секунды с момента нажатия кнопки joining в правом верхнем углу фронтенда, так сказано в документации по сопряжению. Когда время выйдет, joining нужно нажать снова. Перед сопряжением найдите модель в списке поддерживаемых устройств: если ее там нет, попробуйте сброс устройства к заводским настройкам.
Нужно ли обновлять Home Assistant до 2024.9?
Да, если устройства Zigbee2MQTT не появляются в Home Assistant. В 18 ветках форума с этой проблемой пользователям помогало два действия: обновить Home Assistant до 2024.9 или новее и включить интеграцию homeassistant: enabled: true в настройках Zigbee2MQTT. Это опыт пользователей форума.
