Datos en vivo sin sondeo
⚠️ Esta página trata del firmware independiente del hub. Un hub que ejecuta el paquete de ESPHome no tiene API REST, ni WebSocket, ni MQTT: es un dispositivo ESPHome, y Home Assistant se comunica con él a través del panel de RBgrid y la acción
rbgrid_cmd. Todo lo que sigue supone que el hub sirve su propia aplicación web. → Run it inside Home Assistant
El hub envía los datos por sí mismo. Abra un WebSocket a /ws-telemetry y las lecturas llegan a medida que el hub
las produce, en lugar de pedirlas una y otra vez y recibir una copia que siempre va algo atrasada.
Esto es lo que usa la propia aplicación. Si está creando un panel, un flujo de Node-RED o cualquier cosa que necesite un valor en vivo en una pantalla, este es el medio de transporte; para algo que necesite un registro en lugar de un valor, use el historial por HTTP.
La lista de rutas y la referencia de campos en vivo están en la referencia de API generada, un archivo del repositorio, generado a partir del esquema propio del hub en cada versión. Esta página no las repite: una lista de campos copiada a mano queda obsoleta en silencio, y una lista obsoleta es peor que ninguna, porque resulta creíble.
Entrar desde un navegador sin poner un token en la URL
Una dirección WebSocket no lleva cabeceras, así que la solución obvia es poner el token en la cadena de consulta, y así es como los tokens acaban en el historial del navegador, en los registros del servidor y en las capturas de pantalla.
El hub le ofrece una alternativa:
POST /api/v1/ws-ticketpor HTTP, con su token.- Recibe un ticket de uso único, válido durante 30 segundos.
- Abra el socket con el ticket.
Treinta segundos es deliberadamente poco, y el uso único significa que un ticket capturado ya está gastado. Pida uno por cada conexión, incluidas las reconexiones, en lugar de guardarlo.
⚠️ Un ticket no es una sesión. Autoriza la apertura de un único socket. Si lo guarda en caché, su reconexión fallará en el peor momento, que es justo cuando reconecta: después de que algo haya salido mal.
Para un cliente del lado del servidor que no es un navegador, este procedimiento no es necesario: envíe el token de la forma habitual.
Las lecturas necesitan el token de lectura una vez que el hub tiene configurados ambos tokens. → Settings
Iniciar y detener el flujo
El socket no es una manguera a la que simplemente se conecta. Admite tres mensajes:
| Mensaje | Función |
|---|---|
get_telemetry |
un fotograma, ahora |
start_telemetry |
empezar a enviar |
stop_telemetry |
dejar de enviar, mantener el socket |
Deténgalo cuando su página esté oculta y vuelva a iniciarlo cuando se muestre. Una pestaña del navegador abierta toda la noche con un flujo activo le cuesta trabajo real al hub sin beneficio para nadie, y el hub además sirve la aplicación, mantiene la conexión con el broker y ejecuta el bucle de medición.
Un socket por cliente. Varios sockets desde una misma página es un error que parece un problema de rendimiento: cada uno es un flujo que el hub debe llenar.
Cuánto envía el hub
La telemetría tiene dos perfiles, lean y full, configurados en el hub (/api/system/telemetry-config). Lean es
el fotograma más pequeño; full incluye todo lo que el hub puede informar. El fotograma también tiene un tamaño máximo
que el hub no supera.
Elija lean salvo que use campos que solo tiene full. Un panel que muestra potencia y coste por punto no necesita full, y la diferencia son bytes por su red cada pocos segundos, mientras dure el cliente.
Leer lo que llega
Tres cosas que hacer; las dos primeras son las que suelen omitir las integraciones:
Conserve la calidad. Los fotogramas en vivo y los registros dicen lo que el hub piensa de sus propias cifras: parcial, estimado, recalculado, de una interrupción. Un panel que descarta esos indicadores es un panel que no puede explicar después una cifra extraña, y la explicación suele estar justo en ese indicador. → History
Confíe en la hora del hub, no en la suya. Los periodos, los días y las zonas tarifarias los sitúa el reloj y la zona horaria propios del hub. Un cliente que vuelve a marcar la hora al recibir los datos no coincidirá con el hub sobre a qué hora pertenece una lectura, y la diferencia no se ve hasta un cambio de día. → Time
Trate un campo que falta como ausente, no como cero. Un punto sin módulo de tensión no informa de ninguna energía, en lugar de una energía calculada a partir de una tensión nominal; el hub se niega a inventarla, y usted debería hacer lo mismo.
Reconectar
El socket se cerrará: el hub se reinicia para una actualización, la Wi-Fi se cae, un router se reinicia. Prevéalo en lugar de llevarse una sorpresa:
- Pida un ticket nuevo en cada intento. El anterior está gastado o caducado.
-
Espere entre intentos, y siga esperando más. Un cliente que reintenta en un bucle cerrado contra un hub que se está reiniciando llega justo cuando menos puede responder.
-
Vuelva a enviar
start_telemetry. Un socket nuevo no emite datos hasta que se lo pide. - Suponga que se ha perdido cosas. El flujo son valores en vivo, no una cola; nada se reproduce. Si lo que se perdió importa, está en el historial, que se guarda, y en el registro de precios, que se guarda durante 40 días.
Cuándo usar otra cosa
| Lo que quiere | Utilice |
|---|---|
| un valor en vivo en una pantalla | esto |
| Home Assistant, o cualquier cosa que ya esté en un broker | MQTT — con descubrimiento incluido |
| "¿la energía está barata ahora?" | la notificación de precio retenida por MQTT: un estado, no un flujo → Knowing when energy is cheapest |
| periodos cerrados, costes, un mes de datos | HTTP o export.csv |
Para la notificación de precio en concreto, no la construya sobre este socket. Es un estado que el hub vuelve a publicar en cada límite de periodo de 15 minutos y siempre que algo cambia, y por MQTT se retiene, así que un cliente que se conecta tarde recibe igualmente el estado actual. Un cliente WebSocket que estuvo desconectado durante una transición simplemente la perdió.
Cuando no funciona: qué comprobar
El socket se abre y se cierra de inmediato. El ticket ya se usó o tiene más de 30 segundos. Pida uno por cada conexión.
El socket se mantiene abierto y no llega nada.
No se envió start_telemetry. Un socket nuevo está en silencio hasta que se le pide.
Funcionó, y luego se detuvo tras una actualización del hub. El hub se reinició y el socket se fue con él. Reconecte con un ticket nuevo e inicie el flujo de nuevo.
Llegan valores, pero no el dinero. No hay tarifa configurada, o el hub sigue con el plan de ejemplo de fábrica. → Tariffs
Un punto envía corriente pero nunca energía. No tiene tensión detrás. El hub muestra la potencia en vivo como estimación a partir de la tensión nominal y no contabiliza energía, por diseño. → Remote nodes
Mis totales por hora no coinciden con los de la aplicación por una hora. Está marcando las lecturas con su propio reloj. El hub decide en qué hora cae una lectura. → Time
Un cliente de navegador es rechazado mientras un script en la misma máquina funciona. El navegador aplica reglas de origen que el script no tiene. Permita su origen en el hub. → Talking to the hub over HTTP
⚠️ Para cualquier trabajo dentro de un cuadro eléctrico, llame a un electricista cualificado.