Установка и настройка Zigbee2MQTT в Home Assistant

·

Мысли о переходе

Zigbee - очень распространённый протокол для домашних датчиков и реле: устройства дешёвые, работают без облака и без Wi-Fi, живут на батарейке годами и сами строят mesh-сеть, где каждое устройство с питанием от розетки ретранслирует сигнал дальше.

Но сами по себе Zigbee-устройства с Home Assistant не могут общаться. Нужен координатор - радиомодуль (обычно USB-стик) - и программа, которая этим координатором управляет: принимает устройства в сеть, переводит их сообщения в понятный вид и отправляет им команды.

В Home Assistant для этого есть два основных варианта:

  • ZHA (Zigbee Home Automation) - встроенная интеграция HA;
  • Zigbee2MQTT - отдельный сервис, который общается с HA через MQTT.

У меня дома более 30 Zigbee-устройств - свет, реле, розетки, датчики протечки, движения, дыма, климата. Раньше всё это работало через ZHA.

Как-то стал замечать, что датчики климата отдают данные с заметными задержками. Например, была автоматизация: при повышении влажности в ванной включать вытяжку, но срабатывала она хаотично, могла и через 2-4 минуты. Потом наткнулся на статью, где у автора стоит Zigbee2MQTT и такой же датчик, как у меня, отдаёт больше информации. Поресерчил, понял, что у перехода на Zigbee2MQTT есть плюсы и что как минимум ничего не потеряю.

Что такое Zigbee2MQTT

Zigbee2MQTT (дальше Z2M) - open source мост между Zigbee и MQTT. Он управляет координатором и Zigbee-сетью, а каждое устройство превращает в MQTT-топик: состояние приходит JSON-ом в zigbee2mqtt/<имя устройства>, команды отправляются в zigbee2mqtt/<имя устройства>/set.

// zigbee2mqtt/Ванная: Климат
{"temperature": 24.3, "humidity": 61, "battery": 100, "linkquality": 87}

Home Assistant подписывается на эти топики через свою MQTT-интеграцию и автоматически создаёт сущности. Но HA тут - всего лишь один из клиентов брокера. Те же данные могут читать Node-RED, Grafana, свой скрипт на Python - кто угодно, кто умеет в MQTT.

Схема: ZHA работает внутри Home Assistant, Zigbee2MQTT - отдельный сервис, который отдаёт данные через MQTT-брокер любым клиентам

Ключевая разница видна на схеме: в ZHA Zigbee-сеть живёт внутри Home Assistant, в Z2M - рядом с ним. Но это не единственное различие.

Почему Zigbee2MQTT, а не ZHA

Подробное сравнение тянет на отдельную статью, здесь - коротко, что я получил сам:

  • Zigbee не зависит от Home Assistant. Перезапуск или обновление HA не трогает Zigbee-сеть, а связанные напрямую устройства (binding) продолжают работать.
  • Шире поддержка устройств. Особенно Tuya: под одним modelId TS0601 прячутся десятки разных железок со своим протоколом поверх Zigbee. В Z2M у каждой модели есть страница с тем, что она умеет, - список поддерживаемых удобно смотреть до покупки. Нет устройства в базе - его можно описать самому внешним конвертером.
  • Удобные инструменты. Binding, группы, OTA-обновления, карта сети и лог сообщений - отдельными вкладками в веб-интерфейсе.
  • Данные в MQTT доступны не только HA, но и любому другому клиенту.

Минус - два лишних сервиса (брокер и сам Z2M), которые надо обновлять и бэкапить.

Больше данных с тех же устройств

До января 2026 года мои устройства работали через ZHA. После переезда на Z2M те же самые устройства стали отдавать в HA больше:

  • датчик протечки Tuya TS0207 - тампер (вскрытие корпуса) и флаг низкого заряда;
  • датчик дыма Tuya TS0601 - отключение звука сирены и самотест;
  • выключатели без нуля Tuya TS0011/TS0012 - поведение после пропадания питания: включиться, выключиться или вернуть прошлое состояние;
  • датчик открытия Aqara MCCGQ11LM - счётчик срабатываний.

ZHA у меня был на HA 2024.12, с тех пор часть этого в нём могли добавить.

Карточка "Прихожая: Датчик открытия двери"

Моя конфигурация

  • Сервер: мини-ПК MRZNVMS на Ryzen R1505G (hostname home, 192.168.1.2), Ubuntu, Docker. Весь стек умного дома (HA, Z2M, Mosquitto, ESPHome) крутится на нём, процессор почти не нагружен.
  • Координатор: Sonoff Zigbee 3.0 USB Dongle Plus V2.
  • Устройства: 30+, из них 5 роутеров.

Мой мини-ПК home с подключённым Sonoff Zigbee 3.0 USB Dongle Plus V2

Установка Zigbee2MQTT

Все мои проекты крутятся в Docker, и умный дом не исключение, поэтому все сервисы описываю в Docker Compose. Если у вас Home Assistant OS - Mosquitto и Zigbee2MQTT есть там в виде готовых аддонов, суть настроек та же.

docker-compose.yml

docker-compose.yml
# Перед раскаткой обязательно создаем сеть:
# docker network create --driver bridge home-network
networks:
home-network:
driver: bridge
external: true
services:
zigbee2mqtt:
container_name: zigbee2mqtt
image: koenkk/zigbee2mqtt
restart: unless-stopped
devices:
- /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_<serial>-if00-port0:/dev/ttyACM0
ports:
- "8020:8020"
volumes:
- ./zigbee2mqtt:/app/data
- /run/udev:/run/udev:ro
- /etc/localtime:/etc/localtime:ro # Прокидываем часовой пояс
- /dev/ttyUSB0:/dev/ttyUSB0 # Прокидывает USB драйвер
networks:
- home-network
depends_on:
- mqtt
mqtt:
image: eclipse-mosquitto:2.0
container_name: mosquitto
restart: unless-stopped
ports:
- "1883:1883" # MQTT over TCP
- "9001:9001" # MQTT over WebSockets
volumes:
# Основной конфиг брокера
- ./mqtt/config/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
# Папка для файлов паролей/ACL (не обязательна)
- ./mqtt/config/:/mosquitto/config/
# Данные (retained‑сообщения, персистент‑store)
- ./mqtt/data/:/mosquitto/data/
# Логи
- ./mqtt/log/:/mosquitto/log/
networks:
- home-network

И да, все контейнеры я закидываю в одну сеть home-network - мне так проще.

Стик пробрасываю по пути из /dev/serial/by-id/, а не как /dev/ttyUSB0. Номер ttyUSB* может поменяться после перезагрузки или если воткнуть ещё одно USB-устройство, а by-id привязан к серийному номеру стика и не меняется. Посмотреть свой путь:

Terminal window
ls -l /dev/serial/by-id/

Настройка Mosquitto

У меня брокер работает внутри домашней сети, поэтому конфиг минимальный - без пользователей и паролей:

mqtt/config/mosquitto.conf
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
# Разрешаем анонимные подключения
allow_anonymous true
# Веб-сокеты
listener 9001
protocol websockets
# Основной TCP-листенер
listener 1883

persistence нужен, чтобы брокер сохранял retained-сообщения (последние состояния устройств) на диск и не терял их после перезапуска. Листенер 9001 - MQTT поверх WebSocket для браузерных клиентов, Z2M и HA ходят по обычному 1883.

Если брокер доступен не только из домашней сети - анонимный доступ стоит выключить и завести пользователей через password_file.

Настройка Zigbee2MQTT

zigbee2mqtt/configuration.yaml
homeassistant:
enabled: true
mqtt:
base_topic: zigbee2mqtt
server: '!secret server'
client_id: zigbee
serial:
adapter: ezsp
port: /dev/ttyACM0
frontend:
enabled: true
port: 8020
version: 4
zigbee2mqtt/secret.yaml
server: mqtt://mosquitto:1883

Z2M и Mosquitto в одной Docker-сети home-network, поэтому брокер доступен по имени контейнера. Секции devices и groups Z2M дописывает в конфиг сам, по мере добавления устройств.

Запускаем и смотрим лог:

Terminal window
docker compose up -d
docker logs -f zigbee2mqtt

В логе должна появиться версия прошивки координатора и строка Zigbee2MQTT started!. После этого веб-интерфейс доступен на http://<ip-сервера>:8020.

Главная страница веб-интерфейса Z2M со списком устройств

Подключение Z2M к Home Assistant

Настройки → Устройства и службы → Добавить интеграцию → MQTT. Брокер - адрес сервера, например 192.168.1.2 (если HA в host-сети, то можно localhost), порт 1883, логин и пароль - если задавали, в моём примере они не нужны.

Подключение MQTT в HA

Всё. Благодаря homeassistant.enabled: true Z2M сам публикует описания устройств, и они появляются в HA вместе со всеми сущностями - ничего руками прописывать не нужно.

Интеграция MQTT в HA - список устройств, пришедших из Zigbee2MQTT

Первые устройства

  1. В Z2M слева под меню нажимаем Разрешить подключение - сеть откроется для новых устройств на таймер (по умолчанию 254 секунды). Можно открыть сопряжение только через конкретный роутер - удобно, когда датчик далеко от координатора.
  2. Переводим устройство в режим сопряжения - обычно для этого зажимаем кнопку на 5-10 секунд, пока не замигает.
  3. Z2M начинает интервью - опрашивает устройство, что оно умеет. Дожидаемся сообщения, что устройство подключено.
  4. Переименовываем устройство в человекочитаемый формат.

Имя лучше задать сразу: от него строятся MQTT-топик и ID сущностей в HA. Если переименовать потом, придётся править автоматизации. Я использую схему “Комната: Устройство” - “Ванная: Датчик протечки стиралка”, “Прихожая: Основной свет”. В списке устройств всё сразу группируется по комнатам.

В каком порядке добавлять

Схема Zigbee mesh-сети: координатор, роутеры и конечные устройства

В Zigbee-сети есть роутеры - всё с постоянным питанием (розетки, реле, лампы, репитеры), они ретранслируют сигнал, - и конечные устройства на батарейке, которые только спят и шлют данные через ближайший роутер. Поэтому сначала добавляем роутеры, начиная с ближних к координатору и постепенно расширяя ими сеть в дальние комнаты. Датчики - в последнюю очередь и уже на месте, где они будут висеть: к этому моменту рядом с ними уже есть роутер, и даже дальние подключатся без проблем.

Нюанс: выключатели без нулевого провода (у меня Tuya TS0011/TS0012) - тоже конечные устройства, хоть и висят в стене: питания им хватает только на себя. Поэтому из 30+ устройств роутеров у меня всего 5.

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

Бэкап

Всё состояние Z2M - в его директории:

  • configuration.yaml, secret.yaml - конфиг и пароли;
  • database.db - список устройств и что они умеют;
  • coordinator_backup.json - бэкап сети координатора (ключи, PAN ID, канал);
  • state.json - последние состояния устройств;
  • external_converters/ - свои конвертеры.

Бэкап - это копия всей папки. Если стик умрёт, coordinator_backup.json позволит поднять сеть на новом координаторе той же платформы без перепривязки устройств.

Этот же бэкап - способ переехать на другой сервер. Я так перевозил весь стек со старого ноутбука на мини-ПК: остановил контейнер, скопировал папку, переткнул стик, поднял compose - все устройства на месте, без перепривязки.

Обновления

Образ latest, обновляю через docker compose pull && docker compose up -d. Перед обновлением с одной мажорной версии на другую (как было с переходом на 2.x) стоит прочитать changelog: там бывают ломающие изменения в конфиге. Например, в 2.x permit_join из конфига убрали, а внешние конвертеры теперь просто кладутся в папку external_converters/. Сам Z2M при старте мигрирует конфиг и оставляет рядом configuration_backup_v*.yaml.

Итог

Цена перехода - пара дополнительных сервисов: брокер и сам Z2M, их нужно поднять и обновлять. Взамен Zigbee-сеть живёт отдельно от Home Assistant, с тех же датчиков приходит больше данных и настроек, а binding, группы и диагностика всегда под рукой в веб-интерфейсе Z2M.

Полезные ссылки:

Также читайте