Диагностика хаба

Начните с диагностики

Хаб умеет проверить себя сам. Команда обходит всё по порядку — инструменты, настройки, координатор, контейнеры, часы, связь с облаком, место на диске — и не останавливается на первой поломке, а показывает список целиком:

cd /opt/rocket-home
make doctor
Вывод make doctor: все проверки пройдены

Если всё зелёное, а устройства всё равно не появляются в кабинете, добавьте сквозную проверку make smoke: она проходит путь «локальный брокер → мост → облако» и говорит, на каком участке обрывается.

Стик не найден

Перед запуском стек проверяет координатор и отказывается стартовать, если с ним что-то не так. Отказ всегда объясняет причину и даёт команду:

Отказ запуска: координатор по указанному пути не найден

Четыре случая:

zigbee-стик не выбран

В настройках пусто. Найдите: make detect-device, запишите: make env-set KEY=ZIGBEE_DEVICE_HOST VALUE=/dev/ttyUSB0.

не найден

Путь указан, но устройства там нет: стик выдернули, он сменил имя после перезагрузки или путь скопирован с другой машины. make detect-device найдёт заново.

symlink

Указана «ссылка» вместо самого устройства — Docker такие не принимает. В ZIGBEE_DEVICE_HOST нужен реальный путь (/dev/ttyUSB0), а устойчивое имя из /dev/serial/by-id/… хранится отдельно, в ZIGBEE_DEVICE_BYID.

не character device

Указан обычный файл или каталог. Нужен путь вида /dev/ttyUSB0.

Проверку можно пропустить:

SKIP_DEVICE_CHECK=1 make up

Предупреждение

Так поднимается узел-мост: локальный брокер и мост в облако, без ZigBee2MQTT — его контейнеру нужно устройство, которого нет. Это рабочая конфигурация, если устройства публикуются по MQTT сами, без Zigbee: make status и make doctor о ZigBee2MQTT не ругаются, а make smoke пропускает его проверку и остаётся зелёным.

Вставите координатор и укажете его в .env — ZigBee2MQTT поднимется со следующим make up сам, ничего больше включать не нужно.

Установщик просит перезайти

Сообщение docker недоступен: перелогиньтесь и запустите: rocket обычно означает, что пользователя только что добавили в группу docker, а текущая сессия об этом ещё не знает. Выйдите, зайдите снова и запустите rocket.

Сообщение npm так и не появился — редкий случай, когда в системе нет ни npm, ни возможности поставить Node.js из репозитория. Поставьте Node.js 18 или новее вручную и повторите установку; на работу самого хаба это не влияет, без Node недоступно только меню rocket.

ZigBee2MQTT не стартует: «No valid USB adapter found»

В логах (make logs SERVICE=zigbee2mqtt) — USB adapter discovery error (No valid USB adapter found). Specify valid 'adapter' and 'port' in your configuration, контейнер падает сразу после старта.

Версии ZigBee2MQTT 2.x не угадывают тип координатора: его нужно назвать явно. За это отвечает строка adapter в настройках, а она берётся из ключа Z2M_ADAPTER в .env:

cd /opt/rocket-home
make detect-firmware                     # покажет семейство: ember, zstack, …
make env-set KEY=Z2M_ADAPTER VALUE=ember
FORCE=1 make gen-configs                 # без FORCE настройки не переписываются
make up

Обычно тип адаптера проставляет make update сам. Руками это нужно, если версию ZigBee2MQTT меняли в обход матрицы или правили configuration.yaml вручную — см. управление хабом.

Мост не подключён

Состояние моста показывает make status. Что делать, зависит от того, что написал фоновый агент:

needs_relink

Токены больше не действуют (доступ отозвали в кабинете, или хаб не выходил в сеть больше года). Привяжите заново: make relink.

wrong_location

Хаб закреплён за локацией, которой нет в выданном доступе, — обычно после того, как привязку делали под другим аккаунтом. Проверьте CLOUD_LOCATION_ID в .env и выполните make relink.

bridge_down

Мост отвалился, агент поднимает его сам — с паузами 1,5, 5 и 15 минут. Если состояние держится дольше, проверьте интернет и доступность mq.rocket-home.ru:8883.

tokens.json нет

Привязки не было вовсе: make oauth-link.

Устройства не появляются в кабинете

Проверяйте по цепочке, сверху вниз:

  1. Устройство в сети хаба? Откройте веб-интерфейс ZigBee2MQTT (адрес и токен входа — в make status) и найдите его в списке. Нет — значит дело в сопряжении: Сопряжение Zigbee-устройств. Мигает, а в сети так и не появляется — это связь, а не хаб: Устройство мигает, но не появляется.

  2. Мост поднят? make status → «мост подключён».

  3. Устройство заведено в кабинете? Облако не создаёт устройства само: их добавляют вручную (Подключение устройства) или находят через Радар. Имя в кабинете должно совпадать с friendly_name в ZigBee2MQTT.

Если устройство в списке есть, но не отвечает, смотрите логи: make logs SERVICE=zigbee2mqtt FOLLOW=1. Строки вида MAC no ack означают, что до устройства не достучаться — обесточено, далеко от ближайшего узла сети или выпало из неё.

Часы и место на диске

Две проверки make doctor, на которые легко не обратить внимания:

  • часы. Защищённое соединение с облаком и ключи доступа завязаны на время. Часы, ушедшие на несколько минут, выглядят как «мост не встаёт» без внятной причины.

  • место. Меньше гигабайта свободного — и обновление, и резервная копия оборвутся на середине. Место занимают в основном старые образы: docker image prune вернёт его.

Если ничего не помогло

Напишите нам: rocket-home-ru@yandex.ru или в телеграм — https://t.me/RocketHome. К письму приложите вывод make doctor — он отвечает на большую часть вопросов, которые мы иначе зададим.

См. также

Нашли ошибку на странице или не получилось? Напишите нам: rocket-home-ru@yandex.ru или в Telegram-группу https://t.me/RocketHome — укажите адрес страницы и что пошло не так.