Установка хаба

Хаб — это компьютер у вас дома (Raspberry Pi, мини-ПК, NUC), который держит связь с Zigbee-устройствами и мостом подключается к облаку Рокет Хоум. Управление и автоматизации работают в домашней сети, облако нужно для голоса, телефона и удалённого доступа.

Установка

На машине под Ubuntu или Debian выполните одну команду:

curl -fsSL https://rocket-home.ru/install.sh | bash

Установщик всё поставит сам и запустит мастер первичной настройки. Ваше участие нужно на одном шаге — вход в аккаунт по ссылке.

Примечание

Если терминала нет — например, команду выполняет скрипт автоматизации или ssh без -t, — установка всё равно завершится, а мастер скажет об этом и предложит запустить себя позже командой rocket. Поставить сразу без мастера: добавьте -s -- --headless.

Примечание

Готовить машину заранее не нужно: Docker и Node.js ставит установщик. Нужны Ubuntu или Debian на процессоре amd64 или arm64 и около гигабайта свободного места. Что ещё понадобится — Предварительные требования.

Что делает установщик

1. Ставит пакеты: make, curl, git, jq, gettext-base, udev.

2. Ставит Docker (официальный скрипт get.docker.com), если его ещё нет.

3. Ставит Node.js 22 LTS, если в системе нет Node 18 или новее. Отдельно проверяет npm: в Debian пакет nodejs идёт без него.

4. Добавляет пользователя в группы docker и dialout (доступ к контейнерам и к USB-координатору).

5. Скачивает инструмент в каталог /opt/rocket-home и переключает его на последний выпущенный релиз — не на «то, что сейчас в разработке».

6. Заводит команду rocket.

Примечание

Группа docker начинает действовать только в новой сессии. Если rocket жалуется, что docker недоступен, — выйдите, зайдите снова и повторите. На свежей машине перезайти нужно почти всегда.

Мастер первичной настройки

Мастер идёт девятью шагами и показывает, на каком вы сейчас: Установка Rocket Home hub · шаг 3/9 · Прошивка. Перед каждым действием он печатает эквивалентную команду (→ make detect-device) — то же самое можно сделать руками, без мастера.

Шаг 1. Тулинг. Проверяет, что docker, jq, envsubst и остальное на месте, и создаёт файл настроек .env, сгенерировав пароли локального брокера.

Шаг 2. Координатор. Ищет подключённые Zigbee-стики (в мастере координатор так и называется — «стик») и предлагает выбрать нужный. Если его в списке нет, путь можно указать вручную или отложить настройку.

Примечание

«Пропустить (настрою позже)» доводит мастер только до шага 8: без координатора стек не поднимается, и мастер честно останавливается. Это нормальный исход, если координатор вы ждёте с доставкой, — вернётесь к мастеру, когда он приедет. Что при этом всё-таки можно запустить — диагностика.

Следом мастер предложит установить udev-правила: они закрепляют за координатором постоянное имя /dev/zigbee, и оно не «уедет», если переткнуть стик в другой порт.

Шаг 3. Прошивка. Сначала спрашивает разрешение — определение поднимает служебный контейнер и занимает около минуты, а работающий ZigBee2MQTT на это время останавливается (последовательный порт занимает кто-то один). Согласитесь: от ответа зависит следующий шаг. Если определить не удалось, семейство выбирается из списка вручную.

Шаг 4. Версия ZigBee2MQTT. По матрице совместимости подбирает версию под вашу прошивку и предлагает её зафиксировать. Если семейство осталось неизвестным, мастер выберет консервативную версию и предложит обновиться позже — командой make update.

Шаг 5. Облако. Спрашивает, как хаб будет входить в облако: войти через rocket-home.ru (рекомендуется), логин и пароль MQTT, либо совсем без облака. При первом варианте мастер покажет ссылку:

Откройте ссылку на телефоне или компьютере и подтвердите вход. Код вводить не нужно — он уже в ссылке.

На открывшейся странице сверьте три вещи: доступ запрашивает Rocket Home Installer, показан ваш адрес почты и напечатан тот же код, что и в терминале. Что-то не совпало — закройте страницу и прервите привязку (Ctrl+C в терминале). Ввода код не требует нигде: он уже передан ссылкой, и страница печатает его только для сверки.

Вкладка «Ограничение доступа» на той же странице позволяет сузить доступ до одной локации — полезно, если в аккаунте их несколько, а хаб ставится в одну. Сужение действует на доступ к устройствам, но сам хаб об этом не узнает: список локаций он всё равно покажет целиком.

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

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

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

Шаг с локацией пропускать не стоит. Без неё облако заведёт хабу новую локацию «Дом», и устройства появятся не там, где вы их ждёте.

Шаг 6. Дополнения. Предлагает поставить Node-RED (локальные сценарии). По умолчанию — нет; включить его можно в любой момент позже.

Шаг 7. Конфигурация. Генерирует настройки ZigBee2MQTT и моста. Прежние версии файлов сохраняются рядом с суффиксом .bak-…. Уже существующий configuration.yaml мастер не трогает — переписать его можно только явно, FORCE=1 make gen-configs.

Шаг 8. Запуск. Поднимает контейнеры. Первый раз это несколько минут: образы скачиваются и собираются.

Шаг 9. Проверка. Сквозная проверка: локальный брокер → мост в облако → веб-интерфейс ZigBee2MQTT. В конце мастер печатает адрес этого интерфейса и токен входа в него — сохраните их.

Примечание

Проверка дожидается, пока ZigBee2MQTT поднимется (до трёх минут — после пересоздания контейнеров это нормально). Если она всё же покажет красное, установка на этом не обрывается: стек уже запущен, а повторить проверку можно командой make smoke.

Если мастер прервался, запустите его заново командой rocket → «Установка (визард)». Пройденные шаги он спросит снова — в том числе вход в облако, и код привязки будет новый.

Обновление хаба

Та же команда, что и при установке, но с флагом --headless — чтобы не запускался мастер:

curl -fsSL https://rocket-home.ru/install.sh | bash -s -- --headless

На уже установленной машине она не ставит всё заново, а обновляет /opt/rocket-home до последнего выпущенного релиза. Настройки, данные и токены (.env, data/, secrets/) не трогаются, контейнеры не перезапускаются. Чтобы применить обновление к работающему стеку, выполните make up.

Обновление самого ZigBee2MQTT — отдельная операция, по матрице совместимости: make update (см. Управление хабом).

Для опытных пользователей

Установщик принимает флаги — их передают после -s --:

# без мастера: только поставить и настроить окружение (годится для обновления)
curl -fsSL https://rocket-home.ru/install.sh | bash -s -- --headless

# зафиксировать конкретную версию инструмента
curl -fsSL https://rocket-home.ru/install.sh | bash -s -- --version=v0.2.4

# поставить в другой каталог
curl -fsSL https://rocket-home.ru/install.sh | bash -s -- --dir=/srv/rocket-home

Мастер — не единственный путь: то же самое делается руками теми командами, которые он и печатает.

cd /opt/rocket-home
make env-init                    # создать .env
make detect-device               # найти координатор → путь для ZIGBEE_DEVICE_HOST
make detect-firmware             # семейство и версия прошивки
nano .env                        # ZIGBEE_DEVICE_HOST, Z2M_ADAPTER, режим облака
make oauth-link                  # вход в аккаунт (если облако нужно)
make gen-configs up smoke

Важно

Z2M_ADAPTER (ember, zstack, deconz, zigate) заполняйте обязательно: из него берётся строка adapter в настройках ZigBee2MQTT, а без неё версии 2.x отказываются стартовать — No valid USB adapter found.

Совет

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

Исходный код установщика открыт: rocket-home/rocket-installer.