Почему Zigbee-датчики пропадают после перезагрузки Home Assistant

Zigbee-датчики обычно не удаляются из сети после перезагрузки Home Assistant. Чаще Home Assistant временно теряет доступ к координатору, открывает другой последовательный порт, запускает Zigbee-интеграцию раньше зависимого сервиса либо загружает не ту базу сети. Исправление нужно начинать не с повторного сопряжения датчиков, а с проверки координатора, журнала запуска и файлов состояния Zigbee-сети.

Что проверить до любых изменений

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

Сначала определите используемый стек:

ZHA — интеграция Zigbee Home Automation работает внутри Home Assistant.
Zigbee2MQTT — отдельный сервис управляет координатором и передаёт данные через MQTT.

Откройте страницу интеграций Home Assistant и проверьте состояние ZHA либо MQTT. Затем посмотрите журнал сразу после перезагрузки. Важны сообщения об открытии последовательного порта, недоступном координаторе, ошибках базы данных, конфликте доступа к USB-устройству и разрыве соединения с MQTT.

Не запускайте ZHA и Zigbee2MQTT с одним координатором одновременно. Последовательный порт может быть открыт только одним процессом, а конкурирующий доступ приводит к нестабильному запуску или полной недоступности Zigbee-сети.

Шаг 1. Убедиться, что проблема относится ко всей сети

После перезагрузки сравните состояние нескольких устройств:

Проверьте сетевой Zigbee-ретранслятор: розетку, реле или лампу с постоянным питанием.
Проверьте несколько батарейных датчиков разных типов.
Посмотрите, доступна ли страница управления координатором.

Если недоступны все устройства, причина почти наверняка находится на стороне координатора, последовательного порта, ZHA, Zigbee2MQTT или MQTT. Если пропали только отдельные батарейные датчики, координатор, скорее всего, работает, а устройства ещё не вышли на связь после перезапуска.

Батарейные Zigbee-датчики большую часть времени спят. Home Assistant не может немедленно запросить у них состояние после запуска. Активируйте датчик штатным действием: откройте дверь, вызовите движение, нажмите сервисную кнопку в соответствии с инструкцией производителя. Не удерживайте кнопку сброса.

Шаг 2. Проверить стабильный путь к USB-координатору

На Linux координатор может получить другое имя вида /dev/ttyUSB0 или /dev/ttyACM0 после перезагрузки. Если интеграция настроена на такое имя, она способна открыть не то устройство или вообще не найти адаптер.

Предпочтительно использовать постоянный путь из каталога /dev/serial/by-id/. На хосте Linux список можно проверить командой:

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

Результат должен содержать ссылку на фактическое устройство координатора. Скопируйте полный путь и сравните его с настройкой ZHA или Zigbee2MQTT.

Если каталог отсутствует или пуст, проверьте физическое подключение адаптера, USB-порт, кабель, питание хоста и проброс устройства в виртуальную машину или контейнер. Для Home Assistant OS сведения об обнаруженном оборудовании доступны через интерфейс системы; точное расположение пункта зависит от редакции интерфейса.

Для Docker и виртуальных машин

Контейнер должен получать тот же физический координатор при каждом запуске. Привязка только к /dev/ttyUSB0 ненадёжна. В конфигурации контейнера используйте постоянный путь устройства на хосте либо устойчивое сопоставление с внутренним путём контейнера.

В виртуальной машине USB-адаптер должен автоматически подключаться к гостевой системе после перезапуска гипервизора. Если координатор остаётся у хоста, Home Assistant не сможет открыть радиомодуль даже при правильной конфигурации.

Шаг 3. Найти ошибку запуска ZHA

При использовании ZHA откройте журнал Home Assistant сразу после загрузки. Проверяйте не только сообщения отдельных датчиков, но и записи интеграции ZHA и используемой радиобиблиотеки.

Типовые категории ошибок:

последовательный порт не существует;
доступ к порту запрещён;
порт уже занят другим процессом;
координатор не отвечает;
выбран неверный тип радиомодуля;
не удаётся прочитать или открыть базу Zigbee-сети.

Если ZHA отображается как не загруженная интеграция, сначала устраните ошибку координатора. Перезагрузка самой интеграции без исправления порта не решит проблему.

Не меняйте тип радиомодуля методом перебора. Он должен соответствовать координатору и прошивке. Ошибочный выбор может привести к невозможности запуска, но не означает, что датчики требуется сопрягать заново.

Шаг 4. Проверить запуск Zigbee2MQTT и MQTT

При использовании Zigbee2MQTT сеть зависит минимум от трёх компонентов: координатора, процесса Zigbee2MQTT и MQTT-брокера. Home Assistant может работать, пока один из них ещё не запущен.

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

Если устройства видны в Zigbee2MQTT, но недоступны только в Home Assistant, радиосеть работает. Тогда проверяйте MQTT-интеграцию и механизм обнаружения устройств, а не выполняйте повторное сопряжение.

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

serial:
  port: /dev/serial/by-id/ВАШ_ПОСТОЯННЫЙ_ПУТЬ

Значение нельзя копировать из чужой инструкции: идентификатор зависит от конкретного USB-адаптера и системы.

Шаг 5. Проверить сохранность базы Zigbee-сети

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

Для ZHA проверьте, что каталог конфигурации Home Assistant сохраняется между перезапусками и не заменяется временным хранилищем. Для Zigbee2MQTT проверьте постоянное хранение его каталога данных. Точные имена файлов и формат базы зависят от программного стека; вручную редактировать их без резервной копии не следует.

Признаки проблемы с хранилищем:

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

Перед восстановлением остановите компонент, который пишет в базу. Используйте резервную копию, созданную до исчезновения устройств, и восстанавливайте одновременно конфигурацию Zigbee-компонента и связанные параметры координатора, если используемый стек предусматривает их отдельное резервирование.

Шаг 6. Исключить изменение параметров сети

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

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

Без журнала, резервной копии и данных о старой конфигурации нельзя достоверно определить, сохранены ли прежние параметры сети. В такой ситуации повторное сопряжение может оказаться единственным вариантом, но к нему следует переходить только после проверки порта и файлов состояния.

Шаг 7. Проверить питание и USB-помехи

Координатор может определяться системой, но нестабильно работать из-за питания, неисправного кабеля, USB-концентратора или радиопомех. Для диагностики:

Подключите координатор через короткий качественный USB-удлинитель.
Не располагайте его вплотную к корпусу компьютера, накопителям и USB 3.x-устройствам.
Исключите непитаемый USB-концентратор.
Проверьте, не исчезает ли устройство из системы после нескольких перезапусков.

Эти действия не заменяют анализ журнала. Они применимы, когда порт периодически пропадает, координатор сбрасывается или связь восстанавливается после физического переподключения.

Шаг 8. Дать сети восстановить маршруты

После продолжительного отключения координатора сетевые устройства могут восстанавливать маршрутизацию не одновременно. Сначала убедитесь, что доступны постоянно питаемые маршрутизаторы Zigbee. Затем активируйте батарейные датчики.

Не перезапускайте Home Assistant многократно подряд: это снова разрывает соединение с координатором и мешает отличить проблему запуска от временного восстановления маршрутов.

Когда требуется повторное сопряжение

Повторно добавляйте датчики только при одном из подтверждённых условий:

создана новая Zigbee-сеть и старая конфигурация недоступна;
устройство было сброшено до заводских настроек;
датчик удалён из сети и не возвращается после штатной активации;
миграция координатора завершилась без переноса данных сети.

Во многих случаях устройство можно добавить повторно без предварительного удаления сущностей: Home Assistant или Zigbee2MQTT распознает прежний IEEE-адрес и свяжет его с существующей записью. Поведение зависит от стека и состояния базы, поэтому перед процедурой создайте резервную копию.

Итоговый чек-лист

Определён используемый стек: ZHA или Zigbee2MQTT.
Проверен журнал первой загрузки после перезапуска.
Координатор доступен по постоянному пути /dev/serial/by-id/.
Один координатор используется только одним Zigbee-процессом.
USB-устройство корректно проброшено в контейнер или виртуальную машину.
Для Zigbee2MQTT отдельно проверены брокер MQTT и подключение к нему.
Каталоги конфигурации и базы данных находятся в постоянном хранилище.
Не создавалась новая сеть и не менялись её ключ, канал или идентификаторы.
Проверены постоянно питаемые Zigbee-маршрутизаторы.
Батарейные датчики активированы без заводского сброса.
Перед миграцией или восстановлением создана резервная копия.

Источники

Названия отдельных пунктов интерфейса и поддерживаемые способы миграции могут меняться. В этой инструкции намеренно не указаны номера версий; актуальные ограничения следует сверять с официальной документацией установленного компонента.