MQTT-брокер

Хаб может публиковать свои живые измерения в MQTT-брокер в вашей сети и принимать от него команды. Home Assistant использует то же соединение: хаб объявляет свои датчики через MQTT discovery.

MQTT выключен, пока вы не задали брокер. Хаб подключается к нему, только когда он в вашей домашней Wi-Fi-сети, а не когда работает лишь в собственной точке доступа.

Подключение хаба к брокеру

В приложении откройте Настройки → Home Assistant и заполните форму MQTT-брокер: адрес брокера, порт (обычно 1883), логин и пароль. Сохраните и перезагрузите хаб, когда приложение это попросит; настройки брокера применяются после перезагрузки.

Через API то же самое: POST /api/system/mqtt-config с {"broker_uri":"mqtt://user:password@host:1883"}. При чтении обратно пароль скрыт.

Используйте обычный адрес mqtt:// или mqtts:// для защищённого соединения:

• начиная с v1.1.7, с сертификатом от публичного центра сертификации — из списка корневых сертификатов Mozilla, например Let's Encrypt или DigiCert — который совпадает с именем узла брокера;
• начиная с v1.1.8, также с вашим собственным центром сертификации: домашний брокер с частным УЦ или самоподписанный сертификат, что покрывает Mosquitto внутри Home Assistant с собственным сертификатом. См. Собственный УЦ брокера ниже.

На v1.1.7 частный или самоподписанный сертификат вообще нельзя было использовать, и такой брокер требовал обычного адреса mqtt:// в сети, которой вы доверяете.

Собственный УЦ брокера

В Настройки → Home Assistant есть карточка Сертификат УЦ брокера (для mqtts). Пока ничего не загружено, она показывает «Не загружен: хаб доверяет только публичным удостоверяющим центрам.» Загрузить сертификат УЦ принимает PEM-файл вашего центра — тот, который начинается с -----BEGIN CERTIFICATE-----, — и хаб отвечает «Сертификат сохранён на хабе. Он начнёт действовать после перезагрузки.» Затем карточка показывает, что хранится: субъект, издатель и даты действия.

Хаб не принимает неподходящий файл и говорит, почему:

⚠️ Удаление УЦ отрезает брокер, который от него зависит. Удалить сертификат УЦ брокера? предупреждает: «После перезагрузки хаб будет подключаться только к брокерам с публичным сертификатом. Брокер с этим УЦ перестанет подключаться.» После удаления: «Сертификат удалён. После перезагрузки хаб будет доверять только публичным удостоверяющим центрам.»

Загруженный УЦ заменяет публичный набор, а не дополняет его, и действует при следующей перезагрузке. Через API: POST /api/system/mqtt-ca с PEM, GET, чтобы увидеть, что хранится, DELETE, чтобы вернуться к публичному набору.

Почему защищённое соединение отклонено

Начиная с v1.1.8 хаб проверяет даты сертификата, а также его центр и имя узла, и сообщает, что нашёл. Карточка показывает одно из этих состояний:

⚠️ Хаб без часов не откроет TLS-соединение вовсе, и это намеренно. Не установленные часы делают каждый сертификат «ещё не действующим», поэтому начиная с v1.1.8 хаб ждёт, пока узнает время — по NTP или установленное вручную — прежде чем пробовать. Журнал событий пишет «mqtt: TLS broker — waiting for the clock». Обычный брокер mqtt:// не задерживается. → Время

Каждый отказ также пишет строку в журнал событий. Через API то же состояние находится в GET /api/system/mqtt-config → tls: {state, ca, ca_uploaded}, где state — это ok, expired, not_yet_valid, name_mismatch, unknown_ca, waiting_clock, connecting, tls_error или off для обычного соединения, а ca — это custom или bundle.

Если хаб не может проверить брокер, он продолжает повторять попытки, и ничто другое не останавливается: Настройки → MQTT показывает MQTT как не подключённый, а журнал событий хаба называет причину. → События

Держите брокер закрытым. Любой, кто может читать и писать в брокер, может читать настройки хаба через командный канал, а админ-токен, отправленный с командой, виден каждому клиенту, подписанному на неё. Используйте брокер со своими пользователями и правилами доступа (ACL) в собственной сети: дайте хабу собственного пользователя брокера и ограничьте доступ к rbgrid/<mac>/# хабом и доверенными клиентами. Никогда не используйте публичный брокер.

Темы

<mac> — это MAC-адрес Wi-Fi хаба: 12 шестнадцатеричных цифр в нижнем регистре, например a0b1c2d3e4f5. Хаб подключается с идентификатором клиента rbgrid-<mac>.

Кадр телеметрии

Каждый кадр — это один JSON-объект. Основные поля:

Значения энергии (e_in, e_out, e_day_in, e_day_out) — в Вт·ч; денежные значения (cost_*, rev_*) — в валюте тарифа. У модулей, которые считают энергию на борту ("energy_mode": "on_device"), итоги энергии растут раз в 15-минутный период; мощность, ток и напряжение обновляются каждые 3 секунды. Кадры отправляются, только пока хаб подключён. Если брокер недоступен, живые кадры отбрасываются (ничего не буферизуется и не воспроизводится повторно). История остаётся на хабе и может быть прочитана позже по HTTP или командой history.

Пример

Реальный кадр с тестового хаба, сокращённый до одной точки: кухонная линия, потребляющая около 400 Вт. По сети это одна компактная строка. Итог энергии всё ещё мал, потому что эта точка считает энергию на модуле, а 15-минутный период с нагрузкой ещё не закрылся.

{
  "v": 2,
  "sntp": 1793756448,
  "tq": 1,
  "time_src": "sntp",
  "seq": 707,
  "boot_id": 1158837418,
  "freq": 50,
  "system": {
    "tariff": {
      "zone": "NIGHT",
      "buy_rate": 0.2,
      "sell_rate": 0.12,
      "buy_rate_all_in": 0.27104,
      "currency": "EUR",
      "placeholder": true
    },
    "units": 3,
    "present": 2
  },
  "units": {
    "0102": {
      "point": "kitchen",
      "v": 222.85,
      "i": 1.804,
      "p_act": 402.22,
      "p_rea": 0,
      "pf": 1,
      "dir": 1,
      "present": true,
      "module": 1,
      "ch": 0,
      "ch_label": "I0",
      "energy_mode": "on_device",
      "e_in": 0.0223,
      "e_day_in": 0.0223,
      "e_out": 0,
      "e_day_out": 0,
      "load_pct": 6,
      "type": "CURRENT_LOAD",
      "role": "DEVICE_LOAD"
    }
  },
  "main_unit": "0006",
  "vbus_unit": "0007"
}

"placeholder": true здесь означает, что на тестовом хабе ещё стоял заводской примерный тариф.

Home Assistant discovery

При каждом подключении хаб публикует retained-сообщения discovery, поэтому Home Assistant создаёт устройства и датчики сам. Каждый датчик берёт значение из темы телеметрии, а доступность — из темы статуса (датчик становится недоступным примерно через 30 секунд после того, как хаб перестаёт отправлять данные).

• Каждая точка измерения: ток (А), мощность (Вт), реактивная мощность (вар), коэффициент мощности, энергия на входе и на выходе (Вт·ч, за всё время и за сегодня).
• Хаб: чистая мощность (Вт) и частота (Гц).
• Шина напряжения: напряжение (В).

Датчики энергии (total_increasing, Вт·ч) попадают прямо на панель энергии; см. Интеграции.

Когда вы удаляете (или отвязываете) точку, хаб очищает её сообщения discovery, а Home Assistant удаляет её сущности. Это работает, только пока хаб подключён к брокеру. Если вы удаляете точку, когда MQTT выключен или брокер недоступен, её сущности остаются в Home Assistant как недоступные: удалите устройство вручную (Настройки → Устройства и службы → MQTT, устройство, Удалить).

Команды

Опубликуйте JSON-команду в rbgrid/<mac>/cmd с id по вашему выбору. Ответ приходит в rbgrid/<mac>/cmd/resp с тем же id. Несколько клиентов могут использовать общий cmd/resp, поэтому сопоставляйте ответы по id.

Чтение данных:

{"cmd": "get", "section": "summary", "unit": "0x0100", "period": "day", "id": "q1"}

section может быть system, telemetry (настройки), telemetry_data (живой кадр), sensors, units, tariff, schema, summary (с unit, period = hour|day|week|month|year, необязательными from/to в формате Unix time) или economics (с unit).

Чтение истории:

{"cmd": "history", "unit": "0x0100", "period": "hour", "type": "energy", "offset": 0, "limit": 50, "id": "h1"}

type — это electrical, energy, economics, quality или direction; limit — до 720. Ответ — тот же JSON, что и у GET /api/v1/history.

Задать тариф:

{"cmd": "set", "section": "tariff", "data": { "...": "the same body as the HTTP tariff call" }, "token": "<admin token>", "id": "t1"}

token нужен, когда на хабе задан админ-токен. Помните, что он виден всем, кто подписан на cmd.

Успешный ответ — тот же JSON, что и у соответствующей HTTP-конечной точки. Ошибка выглядит так:

{"type": "cmd_ack", "data": {"cmd": "frobnicate", "result": "error", "message": "unknown cmd (use 'get' / 'set' / 'history')"}, "id": "q2"}

Определяйте хабы по <mac> в теме: device_id внутри ответов одинаков на каждом хабе.

Чтение данных без токена в адресе

Начиная с v1.1.7, чтение по MQTT требует токен чтения, когда на хабе заданы токены чтения и администратора, так же как чтение по HTTP: cmd get и history без него отклоняются. Для браузерного клиента, который не должен носить токен в адресе, POST /api/v1/ws-ticket возвращает билет одноразового использования, действующий 30 секунд. → Настройки → Безопасность

Решение проблем

В брокер ничего не приходит

• Проверьте, что адрес брокера, порт, логин и пароль верны и что вы перезагрузили хаб после их сохранения.
• Хаб должен быть в вашей домашней Wi-Fi-сети; в режиме только точки доступа MQTT не запускается.
• Проверьте rbgrid/<mac>/status: online означает, что хаб подключён.

Home Assistant показывает датчики как недоступные

• Хаб ничего не отправляет: проверьте тему статуса и соединение с брокером. Датчики вернутся, как только снова начнут приходить кадры.