Начните отсюда

Карта Bekoz

Bekoz — это три части, и у каждой своё место.

• Панель на стене — Android-панель с комнатами и плитками устройств. Подключается к дому кодом, обновляется сама.
• Хаб — домашний сервер в квартире: ядро Bekoz, брокер MQTT, zigbee2mqtt. Здесь хранятся устройства, комнаты, сцены, история и журнал. Здесь же живёт приложение дома и админка.
• Облако Bekoz ID — учётные записи, список домов и дорога к ним с улицы (релей), навык Алисы и зашифрованные копии базы. Ничего из вашего быта облако не хранит.

Адреса

Идентификатор дома — строка вида h7356ee1df71316ed. Он виден на странице дома в Bekoz ID и в админке (Настройки → Дом).

my.bekoz.ru

Bekoz ID и дом

Одна учётная запись на все ваши дома: с ней входят в приложение, подключают Алису и управляют домом как владелец.

Учётная запись

• Создать — my.bekoz.ru/register: почта и пароль, либо «Продолжить с Яндексом» / «Продолжить с Google».
• Войти — my.bekoz.ru/login. Забыли пароль — ссылка «Забыли пароль?» под формой.
• Учётка — страница, где можно привязать Яндекс или Google к учётке, заведённой по почте.

Дом и ключ хаба

1. «Мои дома» → Добавить дом. Название — любое; идентификатор можно не задавать, облако выпустит сам.
2. Нажмите Добавить и выпустить ключ. Ключ хаба показывается один раз — сохраните его.
3. В админке дома (http://<хаб>:3000/admin) откройте Настройки → Дом → «Ключ хаба и релей» и вставьте ключ. Хаб выйдет на релей сам — через минуту на странице дома в Bekoz ID появится «последний вход хаба».

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

Там же, на странице дома: Приложение дома (адрес, куда возвращает вход через Bekoz ID; по умолчанию https://app.bekoz.ru), Релей (журнал входов хаба и запросов Алисы), Сторож релея, Резервные копии, Локальный путь, Мой Яндекс и Алиса.

Жильцы и гости

• Владелец — тот, кто добавил дом. Ему открыта админка и всё в Bekoz ID.
• Жилец — видит весь дом в приложении и у Алисы.
• Гость — только те комнаты, которые открыл ему администратор дома (в админке, «Жители и гости»). Алису гость не подключает.

Пригласить: страница дома → «Жильцы» → почта и роль → Отправить приглашение. Если почта облака не настроена, появится ссылка — передайте её сами, она действует 7 дней. Приглашённый входит в Bekoz ID и нажимает «Принять». Роль можно поменять, жильца — убрать; у него сразу отключатся приложение и Алиса.

Домашний сервер

Хаб

Хаб — компьютер в квартире с Linux и Docker. На нём брокер MQTT (Mosquitto), zigbee2mqtt для Zigbee-устройств, при желании Node-RED для автоматики — и контур Bekoz:

• Ядро (bekoz-core) — живёт вместе с домом: MQTT, дворецкий в Telegram, мозг, журнал событий, поток панелей, релей. Переживает обновление интерфейсов.
• Приложение и админка (bekoz-web) — порт 3000.
• Мост Яндекса, супервизор адаптеров, шлюз камер (RTSP → картинка для браузера).

Установка

1. Разверните каталог web/ из поставки Bekoz на сервере (например, в /var/bekoz-web).
2. Скопируйте .env.example в .env и заполните: адрес брокера MQTT_URL, длинные случайные строки в BEKOZ_CORE_TOKEN и BEKOZ_PANEL_API_TOKEN, логин и пароль первого администратора (BEKOZ_ADMIN_USERNAME, BEKOZ_ADMIN_PASSWORD), адрес хаба в домашней сети BEKOZ_LAN_IP.
3. Запустите: docker compose up -d --build. Через минуту откройте http://<хаб>:3000/admin и войдите паролем администратора.
4. Вставьте ключ хаба из Bekoz ID (Настройки → Дом). С этого момента дом виден с улицы, а панели можно подключать кодом.

Обновление хаба — новое дерево web/ и снова docker compose up -d --build. Ядро при обновлении интерфейса не перезапускается; при пересборке самого ядра стена моргает на несколько секунд.

Релей и локальный путь

Релей — единственная дорога в дом с улицы. Хаб сам держит исходящее соединение с hub.bekoz.ru, поэтому входящие порты и «белый» адрес в квартире не нужны. Все запросы снаружи идут по пути hub.bekoz.ru/<дом>/…, и хаб принимает только свой префикс.

Локальный путь — для скорости и работы без интернета. Получив ключ хаба, облако выпускает имя <дом>.home.bekoz.ru, ведущее на адрес хаба в вашей сети, и настоящий сертификат для него. Приложение в домашней сети пробует этот путь первым и ходит в хаб напрямую по HTTPS (порт 3443); не отвечает — тихо уходит через свой сервер. Состояние — на странице дома в Bekoz ID, раздел «Локальный путь».

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

Резервные копии и сторож

• Копии — раз в сутки хаб снимает копию своей базы (последние семь лежат на хабе) и отправляет её в облако, зашифровав ключом из .env. Облако хранит последние тридцать и прочитать их не может. Скачать — страница дома в Bekoz ID; снять внеочередную — админка, Настройки → Дом → «Снять копию сейчас».
• Сторож релея — облако раз в минуту проверяет дом тем же путём, что и панели снаружи. Пропал на три минуты — сообщение в Telegram дома («Дом пропал с релея» в админке, Настройки → Уведомления); вернулся — ещё одно. Кнопка «Проверить оповещения» на странице дома шлёт пробное.

На стене

Панель

Настенная Android-панель Bekoz. Полное руководство — интерфейс, жесты, MQTT-контракт, Node-RED — в руководстве панели; здесь главное.

Подключение кодом

1. В админке: Панели → «Подключить панель» → имя панели (например kitchen) → появится шестизначный код. Код живёт 15 минут.
2. На панели, на экране «Подключение к дому», введите код и нажмите Подключить. Адреса хаба и релея и ключ панель получит сама.
3. Дом без интернета? На панели нажмите «Дом без интернета? Указать адрес хаба» и введите адрес вида 192.168.1.10 — код обменяется у самого хаба.

«Настроить вручную» спрятано глубже: там только адрес хаба, без схем и портов — на случай дома, который живёт исключительно локально. Имя панели — это имя железки: одно имя — одна панель; выпуск нового кода для того же имени перевыпускает её ключ.

Подключённая панель пустая, пока администратор не применит ей конфигурацию (Панели → панель → «Конфигурация»). Конфигурация — это разрешённые устройства и сцены, настройки экрана, раскладка, PIN и киоск. Одну конфигурацию можно применить к нескольким панелям: они становятся клонами, правка на одной появляется на остальных.

Экран и правка

• Свайп влево и вправо — комнаты, вверх и вниз — лента событий и режимы дома.
• Долгое нажатие — режим правки: плитки можно перетаскивать, менять размер и убирать с экрана. Убранные плитки ждут в списке «Не на экране» — тап, чтобы вернуть.
• Устройства и сцены на панели не добавляются и не удаляются — это делает администратор в конфигурации. Панель правит только вид, и он синхронизируется через хаб.
• Настройки панели закрыты PIN-кодом из конфигурации; киоск-режим не даёт выйти из приложения.

Обновления

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

app.bekoz.ru

Приложение

То же, что на стене, только в телефоне, планшете или на компьютере. Снаружи — app.bekoz.ru, в домашней сети — http://<хаб>:3000. Работает как PWA: в браузере телефона «Добавить на главный экран» — и это приложение с иконкой.

Вход

• Войти через Bekoz ID — с улицы это единственный способ. Вход выдаёт билет на месяц: приложение помнит вас, а хаб проверяет билет сам, даже без интернета.
• Логин и пароль дома — в домашней сети, для тех, кому администратор выдал ключ в «Жители и гости» (например, гостям без Bekoz ID). Администратор дома входит своим паролем сюда же.

Экран

• Шапка: время, связь с домом, режим дома; если панелей несколько — переключатель «Панель». Вы видите то, что разрешено вашему ключу: жилец — всё, гость — свои комнаты.
• Комнаты, плитки устройств, сцены; управление — в шторке по нажатию на плитку. Камеры показывают живую картинку с хаба.
• Мой экран (шестерёнка в шапке): стартовая комната, тема (авто, светлая, тёмная), компактные плитки, избранное — личная комната из ваших устройств и сцен. Это только ваши настройки, дом от них не меняется.
• «На весь экран» превращает планшет во вторую панель.
• Администратор дома видит в шапке кнопку Админка.

app.bekoz.ru/admin

Админка

Раздел /admin того же приложения: снаружи app.bekoz.ru/admin, дома http://<хаб>:3000/admin. Открыт владельцу дома (вход через Bekoz ID) и администраторам дома (пароль). Всем остальным кнопка не показывается, а по прямой ссылке — отказ.

Дом

• Панели — железки: в сети или нет, применённая конфигурация, код подключения, ключ потока, состояние обновления, удаление.
• Конфигурации — что панель показывает: разрешённые устройства и сцены, экран (раскладка, размеры, скрытые плитки), PIN настроек, киоск. У каждой конфигурации история версий: сравнить, восстановить, выгрузить, загрузить. Сцены создаются здесь же, есть захват текущих состояний.
• Устройства — реестр дома, один на все панели: обнаружение из zigbee2mqtt, устройства адаптеров, импорт из Яндекса. Здесь устройство заводят и удаляют; удаление чистит сцены и раскладки.
• Комнаты — названия и порядок листания; одна комната на все экраны.
• Сцены — все сцены дома и где они показаны.
• Обновления — публикация версии панели и отправка её панелям.

Хроника

• События — журнал дома: что и когда произошло, попытки панелей менять устройства, команды.
• ИИ дома — наблюдения за привычками и подсказки правил (по желанию, со своим ключом провайдера).
• История — версии конфигураций.

Настройки

• Дом — идентификатор, ключ хаба и релей, резервные копии, где дом виден снаружи.
• Внешний вид — тема админки.
• Уведомления — Telegram-бот дома (дворецкий): события, протечки, «дом пропал с релея». Повторы одного события схлопываются.
• Яндекс — состояние навыка Алисы, кто её подключил, как устройства выглядят у Яндекса, последние запросы; импорт из личного Яндекса.
• Жители и гости — ключи от дома по паролю: роль, панели и комнаты. Жильцы из Bekoz ID появляются здесь сами, их роль приходит из облака, а комнаты гостю открываются тут. Изменение прав завершает старые сеансы.
• Администраторы — учётки администраторов и смена пароля.

Голос

Алиса и Яндекс

Подключить Алису

1. Приложение Яндекса → Умный дом → добавить устройство → навык «Bekoz».
2. Войдите своей учётной записью Bekoz ID и выберите дом, если их несколько.
3. Алиса получает ровно то, что разрешено вам в доме: жильцу всё, гостю — ничего (гости Алису не подключают). Имена и комнаты берутся из дома.

Кто подключил Алису и что она спрашивала, видно в админке, «Яндекс». Навык один на все дома — запросы приходят в ваш дом через релей с вашим билетом Bekoz ID.

Мой Яндекс — устройства из личного аккаунта

Обратное направление: устройства, которые живут только у Яндекса (кондиционеры, чужие хабы), можно втянуть в дом обычными устройствами. На странице дома в Bekoz ID — «Подключить мой Яндекс» своей учёткой Яндекса; что именно добавить, выбирает администратор в админке. Такие устройства облачные: состояние приходит опросом, без интернета они недоступны.

Для интеграторов

Интеграции

• MQTT — единственный контракт. Устройства zigbee2mqtt подхватываются по friendly name, любые другие — через произвольные топики с payload в стиле z2m. Панель и хаб читают bekoz/<панель>/…. Формат снимка конфигурации, состояний и команд — в руководстве панели.
• Адаптеры. Адаптер — обычный процесс, который владеет железкой или сервисом и показывает их как устройства в топиках bekoz/adapters/<id>/…. Написать можно на чём угодно; в поставке Python-SDK и супервизор, который подхватывает папку адаптера из adapters/installed. Адаптер падает в одиночку и не роняет ядро.
• Node-RED — автоматика дома рядом с брокером: сцены, расписания, реакции на события. Примеры потоков — в руководстве панели.
• Камеры — RTSP-потоки превращаются в картинку для браузера шлюзом на хабе; адреса камер наружу не уходят.
• Безопасность. Панель ходит в хаб по своему ключу, приложение — сервисным токеном контейнера, люди — билетами Bekoz ID (подпись Ed25519, хаб проверяет офлайн по открытому ключу облака). С улицы открыты только релей и навык; всё остальное — в домашней сети.

Техническая документация (карта серверов, поток панели, облако, контракт MQTT, адаптеры, OTA) — в поставке Bekoz, файлы OPS.md, STREAM.md, CLOUD.md, MQTT.md, ADAPTERS.md, OTA.md.

Когда что-то не так

Частые вопросы

Пропал интернет — что работает?

Панель, приложение в домашней сети, автоматика и уже выданные билеты Bekoz ID. Не работают вход через Bekoz ID заново, Алиса и приложение с улицы.

Панель не принимает код

Код живёт 15 минут — выпустите новый. Дом без интернета — укажите на панели адрес хаба. Проверьте, что хаб на релее: админка → Настройки → Дом.

Панель подключилась, а экран пустой

Ей ещё не применили конфигурацию: Панели → панель → «Конфигурация».

Гость не видит комнату

Комнаты гостю открывает администратор: Настройки → Жители и гости.

В приложении не та панель или не тот дом

Панель — переключатель в шапке. Дом — выйдите и войдите через Bekoz ID заново, дом выбирается при входе.

Потерян ключ хаба

Страница дома в Bekoz ID → «Перевыпустить». Старый ключ отзывается, новый вставьте в админке.

Нужна кнопка «Админка», а её нет

Она видна владельцу дома (вход через Bekoz ID) и администраторам дома (пароль). Жильцам и гостям — нет.

Где посмотреть, что происходило

Админка → Хроника → События. Входы хаба и запросы Алисы — страница дома в Bekoz ID, «Релей».