Устройства спарены с Zigbee2MQTT и видны в его веб-интерфейсе, но в Home Assistant их нет среди устройств и сущностей. Это проблема discovery - механизма, которым Zigbee2MQTT сообщает Home Assistant о новых устройствах через MQTT. Чаще всего помогает включение опции homeassistant в конфиге Zigbee2MQTT, обновление Home Assistant до 2024.9 или новее и совпадение discovery-префикса с префиксом интеграции MQTT.
Как выглядит проблема
Проблема проявляется по-разному, в ветках форума встречаются такие варианты:
- устройства публикуются в MQTT discovery, но не появляются как устройства или сущности Home Assistant;
- в списке устройств виден только координатор или один bridge Zigbee2MQTT;
- старые устройства работают, а новые не добавляются, переименования не синхронизируются;
- сущности пропадали после обновления Home Assistant или после отключения питания, при этом в веб-интерфейсе Zigbee2MQTT и в MQTT Explorer устройства оставались и управлялись;
- устройств нет в интеграции MQTT, поэтому их не видно в дашбордах и нельзя передать в Alexa.
Может встречаться и такая ошибка:
extra keys not allowed @ data['device']['model_id']Если же сам Zigbee2MQTT не запускается и пишет Failed to start EZSP layer with status=HOST_FATAL_ERROR - это отдельная проблема, у нее есть свой разбор.
Быстрое решение
Начните с трех шагов, у них больше всего подтверждений.
- Включите интеграцию Home Assistant в Zigbee2MQTT, в 2.x это опция
enabled: trueв блокеhomeassistant(документация). Помогло в 4 ветках из 6, где это пробовали. - Обновите Home Assistant до 2024.9 или новее, этого требует Zigbee2MQTT 2.0 (примечания к релизу). Помогло в 4 ветках из 4.
- Сверьте discovery-префикс Zigbee2MQTT с префиксом, который слушает интеграция MQTT (документация). Помогло в 3 ветках из 3.
Подробности настройки configuration.yaml собраны в гайде по установке и настройке Zigbee2MQTT в Home Assistant.
Причины
Причин набралось десять, чаще всего это устаревший Home Assistant и выключенная интеграция.
| Причина | Веток | Как проверить | Что сделать |
|---|---|---|---|
| Home Assistant старше 2024.9 и не принимает discovery-сообщения Zigbee2MQTT 2.x | 5 | Посмотреть версию Home Assistant | Обновить до 2024.9 или новее |
| Интеграция Home Assistant выключена в Zigbee2MQTT, опция homeassistant не задана | 4 | Открыть configuration.yaml Zigbee2MQTT | Включить enabled: true в блоке homeassistant |
| Discovery-префикс Zigbee2MQTT не совпадает с префиксом интеграции MQTT | 2 | Сверить discovery_topic (по умолчанию homeassistant) с настройкой интеграции MQTT | Привести оба значения к одному |
| Интеграция MQTT не установлена в Home Assistant | 1 | Проверить Настройки → Устройства и службы (Settings → Devices & Services) | Установить интеграцию MQTT |
| Интеграция MQTT указывает на другой брокер (сервер, который принимает и раздает MQTT-сообщения), не тот, куда пишет Zigbee2MQTT | 1 | Сравнить адрес брокера в интеграции MQTT и в конфиге Zigbee2MQTT | Направить все на один брокер или связать брокеры мостом |
| Второй Raspberry Pi с тестовым Home Assistant конфликтует по MQTT после отключения питания | 1 | Поискать в сети второй работающий сервер | Выключить второй Raspberry Pi |
| Два экземпляра Zigbee2MQTT публикуют в один и тот же MQTT-топик | 1 | Проверить, сколько экземпляров запущено | Дать экземплярам разные топики (без подтверждения) |
| В брокере остались retained discovery-конфиги (сообщения, которые брокер хранит и выдает подписчикам) | 1 | Посмотреть retained-топики в брокере | Сверить discovery-префикс с настройкой интеграции MQTT |
| Discovery-сообщения удалены очисткой топиков в MQTT Explorer | 1 | Вспомнить, очищали ли топики в MQTT Explorer | Перезагрузить хост целиком (частичный результат) или нажать Reconfigure у одного устройства в Zigbee2MQTT (без подтверждения) |
| У датчика нет discovery-топика в MQTT | 1 | Посмотреть топик homeassistant/sensor/ | Спарить датчик заново рядом с координатором (помогло в одной ветке, в документации не описано) |
Все решения
Сначала самые частые решения, в конце - те, что помогли только один раз.
Включить интеграцию Home Assistant в Zigbee2MQTT
Помогло в 4 ветках из 6, где это пробовали. Пример для configuration.yaml:
homeassistant:
enabled: trueДокументация подтверждает, что по умолчанию интеграция выключена - «Enable the integration (default: false)». Как настроить, написано на странице конфигурации Home Assistant в документации Zigbee2MQTT.
Обновить Home Assistant до 2024.9 или новее
Помогло в 4 ветках из 4. Zigbee2MQTT 2.0 требует минимум Home Assistant 2024.9 - это указано в примечаниях к релизу: «For Home Assistant users: this version requires at least Home Assistant 2024.9». С более старым Home Assistant discovery-сообщения Zigbee2MQTT 2.x отклоняются, и обновление решало проблему.
Сверить discovery-префикс
Помогло в 3 ветках из 3. На стороне Zigbee2MQTT префикс задает опция discovery_topic, значение по умолчанию - homeassistant. Он должен совпадать с префиксом, который слушает интеграция MQTT в Home Assistant. Проверьте оба значения и приведите их к одному.
Проверить интеграцию MQTT и брокер
Это опыт пользователей, в документации он не описан. Помогло в 2 ветках из 2: нужно убедиться, что интеграция MQTT установлена в Home Assistant и указывает на тот же MQTT-брокер, что и Zigbee2MQTT.
Помогло однократно
У остальных решений по одной ветке подтверждения.
- Заново спарить датчики: держать их рядом с координатором и дать имена по последним трем цифрам IEEE. Помогло в одной ветке.
- Выключить второй Raspberry Pi с тестовым Home Assistant, который конфликтовал по MQTT после отключения питания. Одна ветка.
- Для контейнера Home Assistant использовать тег
:latestвместо:stable:
image: "ghcr.io/home-assistant/home-assistant:latest"Одна ветка, она относится к причине «Home Assistant старше 2024.9». В ней же упоминается https://version.home-assistant.io/stable.json.
- Связать два MQTT-брокера мостом (bridge: один брокер пересылает сообщения другому), если интеграция MQTT смотрит не на тот брокер, куда публикует Zigbee2MQTT. Одна ветка.
Где проявляется
Проблема встречалась на Home Assistant 2024.1.1, 2024.1.5, 2024.5.1, 2024.7.4, 2025.1, 2025.3.1 и 2025.5.3. В одной ветке до обновления стояла 2024.5, после обновления - 2024.9 или новее. По типу установки: 6 веток - Container, 1 ветка - HAOS, еще в 11 ветках тип установки неизвестен. Container встречается чаще, но данные неполные, делать выводы только по ним нельзя. Устройства разные: розетка Tuya TS011F, датчики Aqara, дымовой извещатель Develco SMSZB-120, кнопка MOES TS0044, драйвер IKEA TRADFRI и другие.
Если не помогло
Вот что пробовали без результата и что предлагали без подтверждений.
Не помогло:
- переименовать устройство в Zigbee2MQTT (в одной ветке не помогло, в другой помогло частично);
- перезапустить Zigbee2MQTT;
- перезапустить Home Assistant, Zigbee2MQTT и Mosquitto, затем перезагрузить интеграцию MQTT;
- удалить датчик из списка deleted_devices в core.device_registry и перезагрузить Home Assistant;
- удалить устройство в Zigbee2MQTT и добавить заново;
- восстановить последнюю резервную копию;
- удалить интеграцию MQTT и заново спарить устройство.
Предлагали без подтверждения:
- дать двум экземплярам Zigbee2MQTT разные MQTT-топики;
- проверить в MQTT Explorer, что существует топик
homeassistant/sensor/<IEEE>; - удалить устройство из ZHA и заново спарить его с Zigbee2MQTT (частичный результат);
- проверить фильтр сущностей в конфигурации Alexa smart home;
- перезагрузить хост целиком, а не только Home Assistant (частичный результат);
- нажать Reconfigure у одного устройства в Zigbee2MQTT, проверить, что оно появилось, и повторить для остальных;
- поискать устройство в разделе Настройки → Устройства и службы (Settings → Devices & Services) → MQTT → Entities.
Частые вопросы
Устройства управляются из веб-интерфейса Zigbee2MQTT. Значит ли это, что сеть в порядке?
Да, сопряжение прошло, и сеть Zigbee работает. В описанных ветках устройства были видны в Zigbee2MQTT, а сбой возникал на пути от него к Home Assistant - через MQTT discovery. Поэтому проверяйте в первую очередь версию Home Assistant, опцию homeassistant и discovery-префикс.
После обновления Home Assistant пропали устройства Zigbee2MQTT. Это та же проблема?
Это та же проблема, но причины в таких ветках были разные. После отключения питания виноват оказался второй Raspberry Pi с тестовым Home Assistant, в другой ветке discovery-сообщения удалили очисткой топиков в MQTT Explorer. Новые устройства не появлялись после обновления, пока в контейнере не сменили тег :stable на :latest. Восстановление последней резервной копии в одной ветке не помогло.
Как проверить, что Zigbee2MQTT публикует discovery-сообщения?
Через MQTT Explorer. Совет из форума - найти топик homeassistant/sensor/<IEEE> и убедиться, что конфигурация датчика в нем есть. Если топика нет, начните с опции homeassistant и discovery-префикса. Сам совет остался без подтверждения: у автора той ветки разобраться не получилось.
Почему устройства Zigbee2MQTT не попадают в Alexa?
Потому что в Home Assistant их нет в интеграции MQTT: в описанной ветке Alexa получала устройства через Home Assistant. Сначала добейтесь, чтобы устройство появилось в интеграции MQTT. Если оно уже есть, а в Alexa его нет, проверьте фильтр в конфигурации Alexa smart home: список include_entities мог не включать нужные сущности.
Нужно ли удалять устройство из ZHA перед переносом в Zigbee2MQTT?
Подтвержденного ответа нет. На форуме советовали полностью удалить устройство из ZHA и заново спарить его с Zigbee2MQTT. Результат в той ветке был частичным. Если устройство раньше работало в ZHA, попробуйте удалить его там и спарить заново - это один из непроверенных вариантов.
