Живые данные без опроса
⚠️ Эта страница относится к автономной прошивке хаба. Хаб, работающий с пакетом ESPHome, не имеет REST API, WebSocket и MQTT — это устройство ESPHome, и Home Assistant общается с ним через панель RBgrid и действие
rbgrid_cmd. Всё ниже предполагает, что хаб отдаёт собственное веб-приложение. → Запуск внутри Home Assistant
Хаб сам передаёт данные. Откройте одно WebSocket-соединение с /ws-telemetry, и показания приходят по мере того, как хаб их получает, — вместо того чтобы вы раз за разом запрашивали их и получали копию, которая всегда немного устарела.
Именно это использует само приложение. Если вы строите панель, поток Node-RED или что-то, что должно показывать живое число на экране, это правильный транспорт; если же нужна не текущая величина, а запись, используйте историю по HTTP.
Список маршрутов и справочник живых полей находятся в сгенерированном справочнике API, файле в репозитории, который создаётся из собственной схемы хаба при каждом релизе. Эта страница их не повторяет: вручную переписанный список полей устаревает незаметно, а устаревший список хуже отсутствующего, потому что выглядит правдоподобно.
Вход из браузера без токена в адресе
Адрес WebSocket не несёт заголовков, поэтому очевидный ход — поместить токен в строку запроса. Именно так токены попадают в историю браузера, серверные журналы и на скриншоты.
Хаб даёт альтернативу:
POST /api/v1/ws-ticketпо HTTP, с вашим токеном.- Вы получаете тикет: одноразовый, действует 30 секунд.
- Откройте сокет с тикетом.
Тридцать секунд намеренно коротко, а одноразовость означает, что перехваченный тикет уже израсходован. Запрашивайте тикет на каждое соединение, включая каждое переподключение, а не храните его.
⚠️ Тикет — это не сессия. Он разрешает открыть один сокет. Если его закешировать, переподключение не удастся в самый неподходящий момент — как раз тогда, когда вы переподключаетесь: после какого-то сбоя.
Для серверного клиента, который не является браузером, эта процедура не нужна — передавайте токен обычным способом.
Чтения требуют токен чтения, когда на хабе заданы оба токена. → Настройки
Запуск и остановка потока
Сокет — не пожарный шланг, к которому вы просто подключаетесь. Он принимает три сообщения:
| Сообщение | Действие |
|---|---|
get_telemetry |
один кадр, сейчас |
start_telemetry |
начать передачу |
stop_telemetry |
остановить передачу, сохранить сокет |
Останавливайте поток, когда страница скрыта, и запускайте снова, когда она показана. Вкладка браузера, оставленная открытой на всю ночь с работающим потоком, загружает хаб ни для чего: хаб одновременно обслуживает приложение, соединение с брокером и цикл измерений.
Один сокет на клиента. Несколько сокетов с одной страницы — это ошибка, которая выглядит как проблема производительности: каждый сокет — поток, который хаб должен наполнять.
Сколько отправляет хаб
У телеметрии два профиля, lean (экономный) и full (полный), задаются на хабе (/api/system/telemetry-config). Кадр lean меньше; full содержит всё, что хаб может сообщить. У кадра также есть верхний предел размера, который хаб не превысит.
Выбирайте lean, если вам не нужны поля, которые есть только в full. Панели, показывающей мощность и стоимость по каждой точке, full не нужен, а разница — это байты в вашей сети каждые несколько секунд, пока работает клиент.
Чтение того, что приходит
Три вещи, и первые две обычно пропускают интеграции:
Сохраняйте качество. И живые кадры, и записи говорят, что хаб думает о своих числах: неполные, оценённые, пересчитанные, из-за сбоя. Панель, которая отбрасывает эти признаки, не сможет объяснить странную цифру позже, а объяснение обычно как раз в признаке. → История
Доверяйте времени хаба, а не своему. Периоды, дни и тарифные зоны определяются собственными часами хаба и его часовым поясом. Клиент, который перестанавливает метку времени при получении, не согласится с хабом, к какому часу относится показание, и это расхождение незаметно до границы суток. → Время
Пропавшее поле считайте отсутствующим, а не нулём. Точка без модуля напряжения не сообщает энергию вовсе, а не энергию, вычисленную по номинальному напряжению; хаб отказывается её выдумывать, и вам тоже не следует.
Переподключение
Сокет будет закрываться: хаб перезапускается для обновления, пропадает Wi-Fi, перезагружается роутер. Закладывайте это заранее, а не удивляйтесь:
- Запрашивайте свежий тикет на каждую попытку. Старый израсходован или истёк.
- Делайте паузы между попытками и продолжайте их увеличивать. Клиент, который повторяет попытки в тесном цикле против хаба в процессе перезапуска, приходит именно тогда, когда тот меньше всего способен ответить.
- Отправляйте
start_telemetryзаново. Новый сокет не передаёт поток, пока вы его не попросите. - Считайте, что вы что-то пропустили. Поток — это живые значения, а не очередь; ничего не воспроизводится. Если пропущенное важно, оно есть в истории, которая хранится, и в журнале цен, который хранится 40 дней.
Когда использовать что-то другое
| Вам нужно | Используйте |
|---|---|
| живое число на экране | это |
| Home Assistant или всё, что уже подключено к брокеру | MQTT — включая обнаружение |
| «дешёвая ли энергия прямо сейчас» | сохранённое уведомление о цене по MQTT: состояние, а не поток → Когда энергия дешевле всего |
| закрытые периоды, затраты, месяц данных | HTTP или export.csv |
Для уведомления о цене не стройте его на этом сокете. Это состояние, которое хаб публикует заново на каждой границе 15-минутного периода и при любом изменении, а по MQTT оно сохраняется — поэтому клиент, подключившийся позже, всё равно получит текущее состояние. Клиент WebSocket, который был недоступен во время перехода, просто пропустит его.
Если не работает: что проверить
Сокет открывается и тут же закрывается. Тикет уже использован или старше 30 секунд. Запрашивайте тикет на каждое соединение.
Сокет открыт, но ничего не приходит.
Не отправлено start_telemetry. Новый сокет молчит, пока его не попросят.
Работало, а после обновления хаба перестало. Хаб перезапустился, и сокет вместе с ним. Переподключитесь с новым тикетом и запустите поток заново.
Значения приходят, а деньги — нет. Тариф не задан или хаб всё ещё на плане из примера с завода. → Тарифы
Точка передаёт ток, но никогда энергию. К ней не подключено напряжение. Хаб показывает живую мощность как оценку по номинальному напряжению и не записывает энергию — так задумано. → Удалённые узлы
Мои итоги за час расходятся с приложением на один час. Вы ставите метки времени по собственным часам. Хаб решает, к какому часу относится показание. → Время
Клиент в браузере отклоняется, а скрипт на той же машине работает. Браузер применяет правила происхождения, которых у скрипта нет. Разрешите ваш источник на хабе. → Работа с хабом по HTTP
⚠️ Для любых работ внутри электрощитка вызовите квалифицированного электрика.