Установка и настройка 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 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 роутеров.

Установка Zigbee2MQTT
Все мои проекты крутятся в Docker, и умный дом не исключение, поэтому все сервисы описываю в Docker Compose. Если у вас Home Assistant OS - Mosquitto и Zigbee2MQTT есть там в виде готовых аддонов, суть настроек та же.
docker-compose.yml
# Перед раскаткой обязательно создаем сеть:# docker network create --driver bridge home-networknetworks: 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 привязан к серийному номеру стика и не меняется. Посмотреть свой путь:
ls -l /dev/serial/by-id/Настройка Mosquitto
У меня брокер работает внутри домашней сети, поэтому конфиг минимальный - без пользователей и паролей:
persistence truepersistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log
# Разрешаем анонимные подключенияallow_anonymous true
# Веб-сокетыlistener 9001protocol websockets
# Основной TCP-листенерlistener 1883persistence нужен, чтобы брокер сохранял retained-сообщения (последние состояния устройств) на диск и не терял их после перезапуска. Листенер 9001 - MQTT поверх WebSocket для браузерных клиентов, Z2M и HA ходят по обычному 1883.
Если брокер доступен не только из домашней сети - анонимный доступ стоит выключить и завести пользователей через password_file.
Настройка Zigbee2MQTT
homeassistant: enabled: truemqtt: base_topic: zigbee2mqtt server: '!secret server' client_id: zigbeeserial: adapter: ezsp port: /dev/ttyACM0frontend: enabled: true port: 8020version: 4server: mqtt://mosquitto:1883Z2M и Mosquitto в одной Docker-сети home-network, поэтому брокер доступен по имени контейнера. Секции devices и groups Z2M дописывает в конфиг сам, по мере добавления устройств.
Запускаем и смотрим лог:
docker compose up -ddocker logs -f zigbee2mqttВ логе должна появиться версия прошивки координатора и строка Zigbee2MQTT started!. После этого веб-интерфейс доступен на http://<ip-сервера>:8020.

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

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

Первые устройства
- В Z2M слева под меню нажимаем Разрешить подключение - сеть откроется для новых устройств на таймер (по умолчанию 254 секунды). Можно открыть сопряжение только через конкретный роутер - удобно, когда датчик далеко от координатора.
- Переводим устройство в режим сопряжения - обычно для этого зажимаем кнопку на 5-10 секунд, пока не замигает.
- Z2M начинает интервью - опрашивает устройство, что оно умеет. Дожидаемся сообщения, что устройство подключено.
- Переименовываем устройство в человекочитаемый формат.
Имя лучше задать сразу: от него строятся MQTT-топик и ID сущностей в HA. Если переименовать потом, придётся править автоматизации. Я использую схему “Комната: Устройство” - “Ванная: Датчик протечки стиралка”, “Прихожая: Основной свет”. В списке устройств всё сразу группируется по комнатам.
В каком порядке добавлять
В 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.
Полезные ссылки: