Управление хабом

После установки инструмент лежит в каталоге /opt/rocket-home. Управлять хабом можно двумя способами: через меню rocket или командами make напрямую. Это не два разных инструмента — каждый пункт меню печатает и выполняет ту же самую make-команду, поэтому всё, что делает меню, воспроизводимо и в скрипте.

Меню rocket

Запускается одноимённой командой из любого каталога:

rocket
Меню rocket: статус, логи, permit join, обновление, облако, doctor, бэкапы, настройки

В шапке — текущая конфигурация: режим входа в облако, зафиксированная версия ZigBee2MQTT и выбранный координатор. Опасные действия (восстановление из бэкапа) переспрашивают дважды.

Примечание

Меню требует Node.js. Если его нет, доступны все те же операции командами make — make help покажет список.

Состояние хаба

cd /opt/rocket-home
make status
Вывод make status: контейнеры, мост в облако, токены и адрес веб-интерфейса

Здесь же печатается адрес веб-интерфейса ZigBee2MQTT и токен входа в него — если вы потеряли токен из финального экрана мастера, он всегда есть тут.

Веб-интерфейс ZigBee2MQTT со списком подключённых устройств

Полная диагностика — make doctor, она описана на странице диагностики.

Основные команды

cd /opt/rocket-home

make status                              # контейнеры, мост, токены, фронт
make logs                                # логи всех сервисов
make logs SERVICE=zigbee2mqtt FOLLOW=1   # логи одного сервиса в реальном времени
make up                                  # запустить или пересоздать стек
make down                                # остановить (данные сохраняются)
make doctor                              # диагностика всего хаба
make smoke                               # сквозная проверка: брокер → мост → облако
make update                              # обновить ZigBee2MQTT по матрице совместимости
make backup                              # резервная копия
make restore ARCHIVE=<путь.tar.gz>       # восстановление из копии

make up не просто перезапускает контейнеры, а пересоздаёт их: только так применяются новые настройки и смена координатора.

Все команды

Команда

Что делает

Параметры

make help

Список всех команд

make check-tools

Проверяет docker, jq, envsubst и остальное; для недостающего печатает команду установки

make env-init

Создаёт .env из шаблона и генерирует пароли

make env-set

Записывает одну настройку в .env

KEY=, VALUE=

make udev-install

Ставит udev-правила координатора и добавляет пользователя в нужные группы (нужен sudo)

make detect-device

Ищет подключённые Zigbee-координаторы

make detect-firmware

Определяет семейство и версию прошивки координатора

DEVICE=

make resolve-tag

Подбирает версию ZigBee2MQTT по матрице совместимости

FAMILY=, FIRMWARE=

make oauth-link

Привязка к облаку по ссылке

make relink

Привязка заново с перезапуском моста

make import-legacy

Переносит хаб со старой, «ручной» установки ZigBee2MQTT

LEGACY_DIR=, LEGACY_CONTAINER=

make gen-configs

Генерирует конфигурацию из шаблонов, сохраняя прежнюю рядом

FORCE=1

make up / make down

Запуск (с пересозданием) и остановка стека

SKIP_DEVICE_CHECK=1

make status

Состояние контейнеров, моста и токенов

make logs

Логи

SERVICE=, TAIL=, FOLLOW=1

make smoke / make doctor

Сквозная проверка и диагностика

make permit-join-on / -off

Открыть и закрыть сеть для новых устройств

TIME= (секунды)

make update

Обновление ZigBee2MQTT по матрице

TAG=, FORCE=1

make backup / make restore

Резервная копия и восстановление

BACKUP_DIR=, ARCHIVE=, CONFIRM=1

make gen-configs

Сгенерировать настройки ZigBee2MQTT и моста

FORCE=1 (переписать существующие)

make setup

Мастер первичной настройки (то же самое делает rocket → «Установка (визард)»)

Добавление устройств

cd /opt/rocket-home
make permit-join-on TIME=254   # открыть сеть на 254 секунды
make permit-join-off           # закрыть досрочно

Сеть закроется сама по истечении TIME — держать её открытой постоянно не нужно и не стоит. Пошаговое сопряжение — Сопряжение ZigBee устройств.

Связь с облаком

По умолчанию хаб входит в облако по ссылке (протокол OAuth) — ни логина, ни пароля вводить не нужно. Привязка делается в мастере, а повторно — командой:

cd /opt/rocket-home
make oauth-link      # привязать
make relink          # привязать заново и перезапустить мост

Токены сохраняются в secrets/tokens.json (доступ только владельцу). Дальше ими занимается фоновый агент внутри контейнера брокера, вмешательство не требуется:

  • каждые 35 минут выписывает мосту свежий ключ — без перезапуска брокера, связь не рвётся;

  • продлевает доступ заранее, за месяц до истечения;

  • если мост отвалился, поднимает его сам, с паузами 1,5 → 5 → 15 минут (чтобы не долбиться в недоступное облако);

  • пишет своё состояние в data/mosquitto/agent-status.json — его показывает make status.

Локация хаба закреплена в настройке CLOUD_LOCATION_ID. Сменить её (например, переставили хаб на другой объект):

cd /opt/rocket-home
make env-set KEY=CLOUD_LOCATION_ID VALUE=<идентификатор локации>
make relink

Альтернатива — логин и пароль MQTT

Вместо входа по ссылке мост можно авторизовать статическими учётными данными. В файле /opt/rocket-home/.env задайте CLOUD_AUTH_MODE=static, заполните CLOUD_MQTT_USERNAME и CLOUD_MQTT_PASSWORD и примените: make gen-configs && make up.

Логин и пароль возьмите в личном кабинете:

  1. Откройте rocket-home.ru/settings/mqtt.

  2. Выберите вариант:

    • Существующий аккаунт — скопируйте логин. Пароль утерян: «Установить пароль» напротив нужного аккаунта.

    • Новый аккаунт — «Добавить». Пароль показывается один раз, сохраните сразу.

Совет

Эти же данные подойдут для прямого подключения своего устройства по MQTT — через драйвер generic, без ZigBee2MQTT. Пример: DIY-измеритель CO₂ на ESPHome.

Обновление ZigBee2MQTT

cd /opt/rocket-home
make update

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

Примечание

Прежний configuration.yaml остаётся рядом с суффиксом .bak-…, а данные сети — устройства, группы и ключ сети — переносятся в новый. Если что-то пойдёт не так, команда сама напечатает строку отката.

Поставить версию в обход матрицы — make update TAG=2.6.0 FORCE=1. Без FORCE=1 команда откажется: ручной выбор версии обходит проверку совместимости и делается на свой риск.

Резервные копии

make backup                               # копия ложится в /opt/rocket-home/backups/
make restore ARCHIVE=<путь.tar.gz> CONFIRM=1

В копию попадают настройки, данные ZigBee2MQTT (в том числе база сети и ключи координатора) и токены облака. На время архивации ZigBee2MQTT останавливается — иначе база может попасть в копию в несогласованном виде.

Переезд со старой установки

Если ZigBee2MQTT у вас уже работал — поставленный руками или прежним менеджером, — переносить устройства заново не нужно:

docker stop z2m-zigbee2mqtt-1   # остановить старый ZigBee2MQTT
cd /opt/rocket-home
make import-legacy              # забрать состояние прямо из его контейнера

Переносятся база сети, ключи координатора, список устройств с их настройками и расширения — устройства не придётся сопрягать заново. Если старого контейнера уже нет, укажите каталог с данными ZigBee2MQTT: make import-legacy LEGACY_DIR=<путь к /app/data>; если контейнер называется иначе — LEGACY_CONTAINER=<имя>.

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

Старый ZigBee2MQTT обязательно остановить до импорта. У работающего база сети и состояние расширений расходятся с тем, что уже произошло в сети, — импорт «на ходу» перенесёт устаревший снимок.

Node-RED

Ставится по желанию — в мастере или позже:

cd /opt/rocket-home
make env-set KEY=COMPOSE_PROFILES VALUE=nodered
make up
sudo chown -R 1000:1000 data/nodered && docker restart rocket-home-nodered-1

Третья команда нужна из-за прав: каталог data/nodered создаёт docker, и создаёт его от root, а Node-RED внутри контейнера работает не под ним. Без неё контейнер уходит в бесконечный перезапуск, а в make logs SERVICE=nodered видно EACCES на /data/settings.js.

Подробности — Сценарии в Node-RED.

Автоматизации на этом хабе

Привязанный хаб умеет не только передавать устройства в облако, но и сам исполнять автоматизации — тогда они продолжают работать при пропавшем интернете. Перенос делается из кабинета, в окне автоматизации: раздел «Исполнение» → «Перенести на хаб». Что переносится, как вернуть обратно и что делать, если хаб перестал отвечать, — Исполнение на локальном хабе.

Что где лежит

Путь

Что это

/opt/rocket-home/.env

Настройки хаба: координатор, версия ZigBee2MQTT, режим входа в облако, локация

/opt/rocket-home/data/

Данные сервисов: база сети ZigBee2MQTT, состояние моста, Node-RED

/opt/rocket-home/secrets/

Токены облака

/opt/rocket-home/backups/

Резервные копии (make backup; каталог меняется параметром BACKUP_DIR=)

Веб-интерфейсы и порты:

  • ZigBee2MQTT — http://IP_ADDRESS:4000 (вход по токену из make status);

  • Node-RED, если включён — http://IP_ADDRESS:1880;

  • локальный MQTT-брокер — порт 1883.