Настройка Zigbee2MQTT в Home Assistant: установка и подключение

Zigbee2MQTT в Home Assistant — популярная альтернатива встроенной интеграции ZHA: программа работает с Zigbee-координатором независимо от Home Assistant, поддерживает очень широкий список устройств и показывает подробную карту сети. В статье разберём настройку Zigbee2MQTT в Home Assistant: установку брокера Mosquitto, дополнения (add-on) и вариант в Docker, конфигурацию, подключение первых устройств, сравнение с ZHA и типичные ошибки.

1Кратко

• Схема состоит из четырёх звеньев: Zigbee-координатор, Zigbee2MQTT, MQTT-брокер (Mosquitto) и Home Assistant с интеграцией MQTT.
• На Home Assistant OS проще всего поставить Mosquitto и Zigbee2MQTT как дополнения; на Container и Core всё разворачивается отдельно, например через Docker Compose.
• В настройках указывайте стабильный путь к адаптеру вида /dev/serial/by-id/..., а не ttyUSB0 или ttyACM0.
• Один стик не может работать одновременно в ZHA и Zigbee2MQTT: старую интеграцию ZHA нужно удалить.
• Канал сети и ключи выбирайте и сохраняйте до подключения устройств, иначе придётся сопрягать всё заново.

Оговорка: Zigbee2MQTT выпускает версии часто, а в 2.x заметно изменились некоторые параметры конфигурации. Названия пунктов меню Home Assistant тоже меняются. Если на экране что-то выглядит иначе, ориентируйтесь на смысл шага и на документацию на сайте zigbee2mqtt.io.

2Как это устроено: координатор, Zigbee2MQTT, брокер и Home Assistant

1. Zigbee-координатор — USB-стик или сетевой шлюз, который создаёт сеть и общается с устройствами по радио.
2. Zigbee2MQTT — программа-переводчик: работает с координатором и превращает события Zigbee в сообщения протокола MQTT.
3. MQTT-брокер — «почтовое отделение», через которое сообщения ходят между программами. Для Home Assistant стандартный выбор — дополнение Mosquitto broker.
4. Home Assistant — получает сообщения через интеграцию MQTT и автоматически создаёт устройства и сущности благодаря автообнаружению (MQTT discovery).

Преимущество схемы в том, что Zigbee-сеть живёт отдельно: Home Assistant можно перезапускать, обновлять и переустанавливать, а сопряжённые устройства останутся в сети Zigbee2MQTT. Поддержка новых устройств нередко появляется в Zigbee2MQTT раньше, чем в ZHA.

3Что понадобится

• Zigbee-координатор с подходящей прошивкой. Обычно используют адаптеры на чипах Texas Instruments серии CC26x2 и Silicon Labs серии EFR32. Если стик ещё не выбран, проверьте список поддерживаемых адаптеров на сайте проекта.
• Сервер для Zigbee2MQTT: на Home Assistant OS или Supervised это дополнение, на других типах установки — отдельный контейнер или установка из исходников.
• Если Home Assistant работает в виртуальной машине, стик нужно пробросить в неё средствами гипервизора.
• Стик, свободный от ZHA. Если ZHA уже настроена на этом адаптере, удалите её интеграцию до начала работ, иначе возникнет конфликт доступа к порту.
• Резервная копия Home Assistant.

4Какой способ установки выбрать

Способ	Для кого	Плюсы	Минусы
Дополнение (add-on) в Home Assistant OS или Supervised	Большинство новичков	Установка из интерфейса, автоматическое обновление, данные попадают в резервные копии Home Assistant	Привязано к Home Assistant; нужен магазин дополнений
Docker Compose рядом с Home Assistant Container	Те, кто уже живёт в Docker	Независимость от Home Assistant, простое обновление образа, переносимость	Всё настраивается вручную, в том числе брокер
Установка из исходников (Node.js)	Опытные пользователи, нестандартные системы	Полный контроль	Больше обслуживания: зависимости, автозапуск, обновления вручную

Дальше подробно разберём дополнение, а затем коротко покажем вариант в Docker.

5Шаг 1. Установка MQTT-брокера Mosquitto

Сначала поставим брокер: без него Zigbee2MQTT не сможет передавать данные в Home Assistant.

1. Откройте Настройки > Дополнения > Магазин дополнений. В свежих версиях раздел может называться «Приложения».
2. Найдите официальное дополнение Mosquitto broker и нажмите «Установить».
3. Запустите его и включите автозапуск; полезна также отметка «Watchdog» (перезапуск при сбое).
4. Откройте Настройки > Устройства и службы. Обычно Home Assistant сам находит брокер и предлагает добавить интеграцию MQTT. Нажмите «Настроить» и подтвердите; если плитки нет, добавьте MQTT вручную через «Добавить интеграцию».

Для входа в этот брокер по умолчанию используются локальные учётные записи Home Assistant. Лучше завести для Zigbee2MQTT отдельного пользователя: Настройки > Люди > Пользователи (вкладка «Пользователи» доступна в расширенном режиме профиля). Создайте учётную запись, например mqtt_z2m, с надёжным паролем и без прав администратора. Если путь в меню у вас другой, найдите управление пользователями через поиск по настройкам. Точная схема авторизации описана в документации дополнения — при сомнениях сверьтесь с ней.

6Шаг 2. Добавьте репозиторий и установите дополнение Zigbee2MQTT

Zigbee2MQTT не входит в официальный магазин, поэтому сначала подключается репозиторий сообщества.

1. В магазине дополнений нажмите значок с тремя точками в правом верхнем углу и выберите «Репозитории».
2. Добавьте адрес https://github.com/zigbee2mqtt/hassio-zigbee2mqtt и нажмите «Добавить».
3. Закройте окно и обновите страницу магазина: появится раздел «Zigbee2MQTT». Если в репозитории несколько вариантов дополнения, выбирайте основной, пока нет особых причин для другого.
4. Нажмите «Установить» и дождитесь окончания загрузки. Пока не запускайте.

7Шаг 3. Найдите путь к Zigbee-адаптеру

Zigbee2MQTT должна знать, на каком порту находится стик. Надёжнее указывать постоянный путь вида /dev/serial/by-id/usb-..., а не /dev/ttyUSB0 или /dev/ttyACM0: последние могут меняться при перезагрузке или смене порта, и сеть внезапно «осиротеет».

Где его посмотреть:

• В Home Assistant: Настройки > Система > Оборудование > Все оборудование. Найдите стик и скопируйте путь с by-id. Название пункта могло измениться.
• В настройках дополнения Zigbee2MQTT: в поле порта может быть выпадающий список устройств.
• В терминале: команда ls -l /dev/serial/by-id/ покажет постоянные имена и то, на какое устройство они указывают.

Если стик не отображается, проверьте физическое подключение. Для адаптеров рекомендуется USB-удлинитель, чтобы отнести стик от корпуса компьютера и портов USB 3.0, создающих помехи в диапазоне 2,4 ГГц. В виртуальной машине убедитесь, что устройство проброшено.

8Шаг 4. Настройте Zigbee2MQTT

Откройте вкладку «Конфигурация» дополнения. В зависимости от версии доступен формат YAML либо отдельные поля. Основные параметры:

• serial: port — путь к адаптеру, найденный на предыдущем шаге.
• serial: adapter — тип адаптера. Для стиков на Texas Instruments обычно zstack, для Silicon Labs EFR32 — ember (в старых версиях встречается ezsp). Новые версии пытаются определить тип сами, но если запуск завершается ошибкой, укажите его явно по странице вашего адаптера в документации.
• mqtt: server, user, password — параметры брокера. Для Mosquitto из Home Assistant сервер обычно имеет вид mqtt://core-mosquitto:1883, а логин и пароль — данные пользователя из первого шага. В ряде версий дополнение подхватывает настройки брокера автоматически, но проверить их полезно.
• homeassistant — автообнаружение, чтобы устройства автоматически появлялись в Home Assistant. Для дополнения оно обычно включено по умолчанию.

Пример фрагмента (значения подставьте свои, структура зависит от версии):

serial:
  port: /dev/serial/by-id/usb-ВАШ_АДАПТЕР
mqtt:
  server: mqtt://core-mosquitto:1883
  user: mqtt_z2m
  password: ВАШ_ПАРОЛЬ
homeassistant:
  enabled: true

На вкладке «Информация» включите автозапуск и отображение в боковой панели, затем нажмите «Запустить» и откройте журнал. В нём должны появиться сообщения о запуске координатора и о подключении к MQTT-брокеру.

Выбор канала Zigbee

По умолчанию сеть создаётся на канале 11, который часто пересекается с Wi-Fi. Если ваш Wi-Fi работает на каналах 1, 6 или 11 диапазона 2,4 ГГц, рекомендуют Zigbee-каналы 15, 20 или 25. Выбирайте канал до подключения устройств: смена потом сложнее. Параметр находится в блоке advanced конфигурации. Точное соответствие каналов Wi-Fi и Zigbee зависит от ширины канала Wi-Fi, поэтому для плотной сети сверьтесь с документацией проекта.

Ключ сети и резервные копии

При первом запуске Zigbee2MQTT создаёт параметры сети: PAN ID и сетевой ключ. Не меняйте их и не удаляйте файлы данных после подключения устройств, иначе всё придётся добавлять заново. Периодически копируйте каталог данных (в нём конфигурация и база устройств). Резервные копии Home Assistant обычно захватывают данные дополнений, но проверьте это в настройках копии.

9Вариант для Docker: Zigbee2MQTT с Home Assistant Container

Если Home Assistant работает в контейнере, Zigbee2MQTT удобно запускать рядом через Docker Compose. Брокер Mosquitto тоже ставится отдельным контейнером или на сервере. Пример сервиса:

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: koenkk/zigbee2mqtt
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - 8080:8080
    environment:
      - TZ=Europe/Moscow
    devices:
      - /dev/serial/by-id/usb-ВАШ_АДАПТЕР:/dev/ttyACM0

Снаружи контейнера стик указан по постоянному пути by-id, а внутри он виден как /dev/ttyACM0, и именно этот путь вписывается в serial: port файла data/configuration.yaml. Туда же добавляются адрес брокера (например, mqtt://ИМЯ_ИЛИ_IP_БРОКЕРА:1883), логин и пароль. Запуск и проверка журнала:

docker compose up -d
docker logs -f zigbee2mqtt

Веб-интерфейс будет доступен на порту 8080 сервера. Если порт занят другой службой, смените его слева в блоке ports. Для варианта «из исходников» последовательность другая: Node.js, клонирование репозитория проекта, установка зависимостей, запуск и автозапуск через systemd. Подробная инструкция есть в документации проекта.

Предостережение по безопасности: в учебных примерах брокер часто разрешает анонимный доступ на порту 1883. Это допустимо только в закрытой домашней сети; если брокер доступен снаружи, отключите анонимный доступ и заведите учётные записи.

10Шаг 5. Интерфейс Zigbee2MQTT и подключение первых устройств

Откройте веб-интерфейс через пункт боковой панели или кнопку «Открыть веб-интерфейс» на странице дополнения. Там список устройств, карта сети и журнал событий.

Теперь о том, как добавить Zigbee-устройства в Home Assistant через Zigbee2MQTT:

1. В интерфейсе нажмите «Разрешить подключение» (Permit join). Режим отключается автоматически через несколько минут. В версиях 2.x постоянное разрешение подключения из конфигурации убрано, поэтому включать его нужно кнопкой.
2. Переведите устройство в режим сопряжения. Для большинства датчиков нужно зажать кнопку на корпусе на несколько секунд до мигания индикатора; у ламп иногда используется многократное включение питания. Способ зависит от модели — смотрите страницу устройства в каталоге Zigbee2MQTT.
3. Дождитесь появления устройства. Zigbee2MQTT пройдёт этап интервью, определит модель и покажет параметры.
4. Дайте устройству понятное имя. Оно влияет на тему MQTT и название в Home Assistant; при переименовании включите опцию обновления идентификатора в Home Assistant, если она есть.
5. Откройте Настройки > Устройства и службы > MQTT: новые устройства появятся сами.

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

Если устройство не подключается

• Убедитесь, что Permit join включён, а устройство действительно в режиме сопряжения (индикатор мигает).
• Если устройство раньше было привязано к чужому шлюзу или другой сети, сначала сбросьте его к заводским настройкам по инструкции производителя.
• Поднесите его вплотную к координатору или маршрутизатору.
• Проверьте, что модель есть в каталоге поддерживаемых; для недавних моделей может потребоваться обновление Zigbee2MQTT.
• Не пробуйте несколько устройств одновременно: подключайте по одному.

11ZHA или Zigbee2MQTT: что выбрать

ZHA — встроенная интеграция Home Assistant: настройка занимает несколько кликов, ничего дополнительного не требуется. Для небольшой сети из популярных устройств этого часто достаточно. Zigbee2MQTT требует больше действий, но даёт другие преимущества.

Критерий	ZHA	Zigbee2MQTT
Установка	Встроенная интеграция, брокер не нужен	Отдельное дополнение или контейнер и MQTT-брокер
Независимость от Home Assistant	Сеть управляется самим Home Assistant	Сеть живёт отдельно и переживает переустановку Home Assistant
Список устройств	Широкий, часть моделей требует доработок (квирков)	Очень широкий каталог с описанием каждой модели
Веб-интерфейс сети	Базовые инструменты внутри Home Assistant	Отдельный интерфейс с картой сети и журналом
Прошивка устройств по воздуху (OTA)	Поддерживается для части устройств	Встроена, с отдельным разделом в интерфейсе
Группы и привязки	Есть, но возможностей меньше	Развитые группы и привязки (binding)
Сложность	Ниже	Выше

Переход с ZHA на Zigbee2MQTT автоматически не выполняется: устройства обычно приходится сопрягать заново, а затем переписывать автоматизации под новые идентификаторы сущностей. Поэтому выбирайте систему сразу, до накопления большого числа устройств.

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

Проблема	Возможная причина	Решение
Дополнение не стартует, в журнале ошибка порта	Неверный путь к адаптеру, адаптер занят ZHA или не проброшен в ВМ	Проверьте путь by-id, удалите ZHA, проверьте проброс USB
Ошибка подключения к MQTT	Неверные адрес, логин или пароль, брокер не запущен	Запустите Mosquitto, проверьте учётную запись и адрес core-mosquitto
Координатор не отвечает, запуск зависает	Указан неверный тип адаптера или не та прошивка	Сверьтесь с документацией: тип (zstack или ember) и версия прошивки
Устройства не появляются в Home Assistant	Выключено автообнаружение или нет интеграции MQTT	Проверьте блок homeassistant и наличие интеграции MQTT
Устройство не сопрягается	Не включён Permit join или устройство не в режиме сопряжения	Включите Permit join, сбросьте устройство, держите его рядом с координатором
Датчики часто отваливаются	Помехи от Wi-Fi и USB 3.0, мало маршрутизаторов	Вынесите стик на удлинителе, смените канал, добавьте сетевые устройства-маршрутизаторы
Порт адаптера «ушёл» после перезагрузки	В настройках указан ttyUSB0/ttyACM0, а нумерация изменилась	Используйте путь /dev/serial/by-id/...
Интерфейс недоступен в Docker	Не проброшен порт или он занят другой службой	Проверьте блок ports и свободные порты на сервере
После переустановки все устройства пропали	Потеряны файлы данных с сетевым ключом	Восстановите каталог данных из копии; без него устройства сопрягаются заново

Если причина неочевидна, повысьте детализацию журнала в настройках Zigbee2MQTT и изучите последние строки: сообщения проекта обычно хорошо описывают проблему. Затем верните уровень, чтобы журнал не разрастался.

13Обновление и обслуживание

Обновления дополнения приходят через Home Assistant, а образ в Docker обновляется командами docker compose pull и docker compose up -d. Перед обновлением сделайте резервную копию и прочитайте заметки к выпуску: в крупных версиях меняются формат конфигурации и названия параметров. После обновления проверьте журнал и убедитесь, что устройства отвечают. Прошивку самих устройств Zigbee2MQTT обновляет по воздуху, если производитель поддерживает такую возможность, — делайте это рядом с координатором и не прерывайте процесс.

Чтобы перенести сеть на другой сервер, остановите Zigbee2MQTT, скопируйте каталог данных, подключите стик к новому месту и запустите программу с тем же каталогом: ключи сети и список устройств сохранятся.

14Полезные настройки после запуска

• Понятные имена устройств. Называйте по месту и назначению: «Датчик движения коридор», «Розетка чайник». Через полгода это сильно упростит автоматизации.
• Группы. Zigbee2MQTT объединяет лампы в группы, которыми управляют одной командой на уровне сети. Это быстрее и надёжнее, чем отправлять команды каждой лампе из автоматизации.
• Привязки (binding). Беспроводной выключатель и лампу можно связать напрямую, тогда свет работает, даже если Home Assistant временно недоступен.
• Карта сети. Раздел с картой показывает связи и уровень сигнала (LQI): слабые узлы подскажут, где нужен ещё один маршрутизатор.
• Тема MQTT. Базовую тему (по умолчанию zigbee2mqtt) без причины не меняйте.
• Сетевой координатор. Если стик вынесен по Ethernet, порт указывается в виде tcp://адрес:порт вместо пути к устройству.

15Итог

Для связки Zigbee2MQTT и Home Assistant нужны три компонента: стик с подходящей прошивкой, брокер Mosquitto и сама Zigbee2MQTT в виде дополнения или контейнера. Порядок действий: поставить брокер и интеграцию MQTT, добавить репозиторий, указать путь by-id и параметры MQTT, запустить и подключать устройства через Permit join. Выберите канал и сохраните данные сети до начала работы — это убережёт от самых неприятных проблем. Если важна максимальная простота, подойдёт ZHA; если нужны гибкость, независимость сети и подробный контроль — Zigbee2MQTT.