Переход с ZHA на Zigbee2MQTT
ZHA — это собственный Zigbee в Home Assistant. ZigDash работает с Zigbee2MQTT, поэтому не может показать устройства, которые находятся в ZHA. Переход означает, что устройства нужно заново сопрячь с Zigbee2MQTT. Home Assistant и дальше будет ими пользоваться — через свою интеграцию MQTT.
Перед началом
- Какая у вас установка? Если в меню Настройки в Home Assistant есть пункт Apps (Add-ons в старых версиях), у вас Home Assistant OS: см. с приложениями. Если нет, Home Assistant работает в Docker (Container): см. Docker.
- Какой адаптер? Откройте Настройки › Устройства и службы › Zigbee Home Automation. В разделе Hubs адаптер указан по модели, например SONOFF ZBDongle-E. Затем посмотрите раздел Ваш адаптер.
- Сделайте резервную копию ZHA. На той же странице нажмите ⚙ рядом с Zigbee Home Automation, затем Download backup. Сохраните файл. В Network information на той же странице указаны канал, тип радио и последовательный порт.
- Что изменится в Home Assistant. Устройства вернутся как новые MQTT-устройства с новыми ID сущностей. Автоматизации, скрипты и панели, которые их используют, нужно будет перенастроить на новые устройства, а их история начнётся заново. Группы и привязки, созданные в ZHA, создаются заново в Zigbee2MQTT.
- Время. Каждое устройство сбрасывается и сопрягается заново, по одному. Честных оценок времени у нас пока нет; на небольшой дом заложите вечер, на большой — больше.
Два способа перехода
| Второй адаптер | Тот же адаптер | |
|---|---|---|
| Стоимость | Новый адаптер, примерно 30–60 € (например, Home Assistant Connect ZBT-2 или SMLIGHT SLZB-06M либо SLZB-07) | Бесплатно |
| Во время перехода | Всё продолжает работать: у ZHA остаётся старый адаптер | Zigbee не работает, пока каждое устройство не будет сопряжено заново |
| Темп | Комната за комнатой, хоть несколько дней | Всё сразу |
| Возврат назад | Легко: отключите новый адаптер, ZHA и не останавливалась | Восстановите резервную копию ZHA (см. Как вернуться назад) |
Второй адаптер
- Настройте Zigbee2MQTT на новом адаптере (с приложениями или Docker) с собственной сетью. Выберите всё это до первого запуска Zigbee2MQTT, потому что смена канала потом может потребовать повторного сопряжения:
- оставьте ключ сети и PAN ID на
GENERATE(по умолчанию); - выберите канал, отличный от канала ZHA (его видно в ⚙ › Network information у ZHA); Home Assistant советует 15, 20 или 25.
- оставьте ключ сети и PAN ID на
- Держите адаптеры подальше друг от друга, каждый на своём USB-удлинителе.
- В Home Assistant OS при подключении нового адаптера Home Assistant может предложить настроить его для ZHA или Thread. Не обращайте внимания: адаптер нужен для Zigbee2MQTT.
- Переносите по одной комнате: сначала сопрягите устройства с питанием от сети (лампы, розетки, встраиваемые выключатели — это роутеры), потом устройства на батарейках.
- Когда все устройства перенесены, отключите ZHA (см. ниже), а старый адаптер оставьте про запас.
Тот же адаптер
- Скачайте резервную копию ZHA (см. Перед началом) прямо перед началом.
- Отключите ZHA: Настройки › Устройства и службы › Zigbee Home Automation, ⋮ рядом с Zigbee Home Automation › Disable. Не Delete.
- Настройте Zigbee2MQTT на том же адаптере (с приложениями или Docker), оставив ключ сети и PAN ID на
GENERATE. - Обесточьте устройства Zigbee с питанием от сети — выключателем на стене или автоматом в щитке. Иначе они продолжат искать старую сеть.
- Включайте их обратно по одному и сопрягайте каждое, как только оно включится. Потом сопрягите устройства на батарейках.
Ваш адаптер
- Silicon Labs (Home Assistant Connect ZBT-1 и ZBT-2, Home Assistant Yellow, Sonoff ZBDongle-E, SMLIGHT SLZB-06M и SLZB-07):
adapter: ember. Для ZBT-2 нужен ещёbaudrate: 460800; для ZBDongle-E —rtscts: false; для SLZB-06M нужна прошивка 20240510 или новее. - Texas Instruments (Sonoff ZBDongle-P, SMLIGHT SLZB-06 и SLZB-06P7):
adapter: zstack. - ConBee или RaspBee:
adapter: deconz. - CC2531 или ZiGate: слишком старые или больше не поддерживаются, чтобы построить хорошую сеть Zigbee2MQTT. Используйте способ со вторым адаптером, то есть новый адаптер.
- Сетевой адаптер (SMLIGHT SLZB-06, SLZB-06M, SLZB-07, MR series): ZHA показывает его как
socket://IP:6638; в Zigbee2MQTT этоtcp://IP:6638, а для Docker строка USB не нужна. - Multiprotocol (ZBT-1 или Yellow, на которых Zigbee и Thread работают вместе; это указано на странице оборудования в Home Assistant): Zigbee2MQTT не умеет работать с прошивкой multiprotocol. Для способа с тем же адаптером отключите multiprotocol ещё на ZHA, по инструкции самого Home Assistant (ZBT-1, Yellow). Устройства Thread, которые через него работали, перестанут работать, пока их не возьмёт другой пограничный маршрутизатор Thread. Для способа со вторым адаптером ничего не трогайте, а новый адаптер купите только для Zigbee.
Подробности — на страницах адаптеров Zigbee2MQTT.
Home Assistant с приложениями (Home Assistant OS)
- В разделе Настройки › Apps установите и запустите Mosquitto broker. Затем Home Assistant предложит интеграцию MQTT в разделе Настройки › Устройства и службы: примите её.
- Добавьте репозиторий Zigbee2MQTT (в магазине приложений: ⋮ › Repositories:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt), затем установите Zigbee2MQTT. - На его вкладке Configuration укажите последовательный порт и адаптер из раздела Ваш адаптер, например:
Для способа со вторым адаптером укажите также канал (см. выше) до первого запуска.port: /dev/serial/by-id/usb-... adapter: ember - Запустите Zigbee2MQTT и откройте его веб-страницу со страницы приложения. Затем сопрягите устройства.
Home Assistant в Docker (без приложений)
Без приложений Mosquitto и Zigbee2MQTT работают в отдельных контейнерах рядом с Home Assistant. В новой папке:
1. compose.yaml (укажите путь к адаптеру в devices; его покажет ls /dev/serial/by-id/):
services:
mosquitto:
image: eclipse-mosquitto:2
restart: unless-stopped
ports:
- 1883:1883
volumes:
- ./mosquitto/config:/mosquitto/config
- ./mosquitto/data:/mosquitto/data
zigbee2mqtt:
image: ghcr.io/koenkk/zigbee2mqtt
restart: unless-stopped
depends_on:
- mosquitto
ports:
- 8080:8080
volumes:
- ./zigbee2mqtt:/app/data
- /run/udev:/run/udev:ro
environment:
- TZ=Europe/Berlin
devices:
- /dev/serial/by-id/usb-...:/dev/ttyACM0
С сетевым адаптером уберите devices и строку с udev.
2. mosquitto/config/mosquitto.conf:
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
Создайте пользователя MQTT (пароль спросят дважды; файл должен принадлежать собственному пользователю Mosquitto, иначе Mosquitto не запустится):
docker run -it --rm -v "$PWD/mosquitto/config:/mosquitto/config" eclipse-mosquitto:2 \
sh -c "mosquitto_passwd -c /mosquitto/config/passwd zigbee && chown mosquitto:mosquitto /mosquitto/config/passwd"
3. zigbee2mqtt/configuration.yaml (строки адаптера — из раздела Ваш адаптер):
homeassistant:
enabled: true
frontend:
enabled: true
port: 8080
mqtt:
server: mqtt://mosquitto:1883
user: zigbee
password: your-password
serial:
port: /dev/ttyACM0 # a network adapter: tcp://IP:6638
adapter: ember
advanced:
network_key: GENERATE
pan_id: GENERATE
ext_pan_id: GENERATE
channel: 20 # second adapter: not ZHA's channel
4. Для способа с тем же адаптером ZHA к этому моменту уже отключена (см. выше). Если контейнер самого Home Assistant пробрасывает адаптер, уберите эту строку из его compose-файла или docker run: адаптер может использовать только один контейнер.
5. docker compose up -d, затем откройте http://the-machine:8080: это веб-страница Zigbee2MQTT.
6. В Home Assistant: Настройки › Устройства и службы › Добавить интеграцию › MQTT. Broker: IP-адрес машины, порт 1883, пользователь zigbee и пароль.
Сопряжение устройств
- На веб-странице Zigbee2MQTT нажмите Permit join (открыто примерно четыре минуты). Чтобы сопрягать через роутер рядом с устройством, выберите этот роутер в меню permit join: это полезно для Aqara и других капризных устройств.
- Переведите устройство в режим сопряжения так, как указывает производитель: долгое нажатие у большинства датчиков, несколько циклов включения и выключения у ламп, серия переключений у некоторых встраиваемых выключателей.
- Когда оно появится, дайте ему имя и комнату в Zigbee2MQTT. Затем переходите к следующему.
Сначала устройства с питанием от сети, потом на батарейках, чтобы у новой сети были маршруты.
После перехода
- ZigDash: откройте приложение и нажмите Найти мою систему. Оно найдёт Mosquitto в вашей сети; войдите с пользователем MQTT. Или выберите Home Assistant и войдите: теперь это тоже работает, потому что в Home Assistant есть интеграция MQTT.
- Имена и комнаты: в ZigDash пункт Настройки › Импорт из Home Assistant переносит имена и комнаты, которые вы дали новым устройствам в Home Assistant.
- Home Assistant: перенастройте автоматизации, скрипты и панели на новые устройства. Когда будете уверены, удалите интеграцию ZHA.
Как вернуться назад
- Второй адаптер: остановите Zigbee2MQTT и отключите новый адаптер. ZHA и не останавливалась. Устройства, которые вы уже перенесли, нужно снова сопрячь с ZHA.
- Тот же адаптер: остановите Zigbee2MQTT, затем на странице ZHA нажмите Enable. ZHA сообщит "Network settings do not match most recent backup" (настройки сети не совпадают с последней резервной копией), потому что на адаптере теперь сеть Zigbee2MQTT. Откройте Настройки › Repairs › "Zigbee network settings have changed" (настройки сети Zigbee изменились) и выберите Restore backup (recommended). Сеть ZHA вернётся в прежнем виде. Устройства, которые вы сопрягли с Zigbee2MQTT, нужно снова сопрячь с ZHA. Если такого пункта в Repairs нет, используйте ⚙ › Migrate adapter со скачанной резервной копией.
Сохранить сеть без повторного сопряжения
Есть и третий способ: скопировать сеть ZHA в Zigbee2MQTT, чтобы устройства не пришлось сопрягать заново. Zigbee2MQTT его не поддерживает, неверное значение может стереть сеть, и смысл в этом есть только для больших домов (скажем, больше 60 устройств). Если хотите почитать об этом: ответ сопровождающего Zigbee2MQTT, а также отчёты сообщества в обсуждении 24478 и обсуждении 26716.