Dados em direto sem polling
⚠️ Esta página trata do firmware autónomo do hub. Um hub que corre o pacote ESPHome não tem API REST, nem WebSocket, nem MQTT — é um dispositivo ESPHome, e o Home Assistant comunica com ele através do painel RBgrid e da ação
rbgrid_cmd. Tudo o que se segue pressupõe que o hub serve a sua própria aplicação web. → Run it inside Home Assistant
O hub envia dados por iniciativa própria. Abra um WebSocket para /ws-telemetry e as leituras chegam à medida que o hub as produz — em vez de as pedir repetidamente e receber uma cópia que está sempre um pouco desatualizada.
É isto que a própria aplicação usa. Se estiver a construir um painel, um fluxo no Node-RED ou algo que precise de um valor em tempo real num ecrã, este é o transporte; para algo que precise de um registo em vez de um valor, use o histórico por HTTP.
A lista de rotas e a referência dos campos em tempo real estão na referência da API gerada, um ficheiro do repositório, produzido a partir do schema do próprio hub em cada versão. Esta página não as repete: uma lista de campos copiada à mão fica desatualizada em silêncio, e uma lista desatualizada é pior do que nenhuma, porque parece credível.
Entrar a partir de um navegador, sem pôr um token no URL
Um endereço WebSocket não transporta cabeçalhos, por isso a solução óbvia seria pôr o token na query string — e é assim que os tokens acabam no histórico do navegador, nos registos do servidor e em capturas de ecrã.
O hub oferece uma alternativa:
POST /api/v1/ws-ticketpor HTTP, com o seu token.- Recebe um ticket: uso único, válido por 30 segundos.
- Abra o socket com o ticket.
Trinta segundos é deliberadamente curto, e o uso único significa que um ticket capturado já está gasto. Peça um por ligação — incluindo cada reconexão — em vez de o guardar.
⚠️ Um ticket não é uma sessão. Autoriza a abertura de um único socket. Se o guardar em cache, a sua reconexão falhará no pior momento, que é exatamente quando se reconecta: depois de algo ter corrido mal.
Para um cliente do lado do servidor que não seja um navegador, este procedimento é desnecessário — envie o token da forma habitual.
As leituras exigem o token de leitura quando o hub tiver ambos os tokens definidos. → Settings
Iniciar e parar o fluxo
O socket não é uma torneira que apenas se liga. Aceita três mensagens:
| Mensagem | Faz |
|---|---|
get_telemetry |
uma trama, agora |
start_telemetry |
começa a enviar |
stop_telemetry |
pára de enviar, mantém o socket |
Pare quando a sua página estiver oculta e volte a iniciar quando estiver visível. Um separador do navegador deixado aberto a noite toda com um fluxo ativo custa trabalho real ao hub sem benefício para ninguém, e o hub também está a servir a aplicação, a ligação ao broker e o ciclo de medição.
Um socket por cliente. Vários sockets a partir de uma mesma página são um erro que parece um problema de desempenho: cada um é um fluxo que o hub tem de encher.
Quanto o hub envia
A telemetria tem dois perfis, lean e full, definidos no hub (/api/system/telemetry-config). Lean é a trama mais pequena; full inclui tudo o que o hub consegue reportar. A trama também tem um limite máximo de tamanho que o hub não ultrapassa.
Escolha lean, a menos que esteja a usar campos que só full inclui. Um painel que mostre a potência e o custo por ponto não precisa de full, e a diferença são bytes na sua rede a cada poucos segundos, durante todo o tempo em que o cliente estiver a correr.
Ler o que chega
Três coisas a fazer, e as duas primeiras são as que as integrações costumam saltar:
Mantenha a qualidade. As tramas em tempo real e os registos dizem o que o hub pensa dos seus próprios números: parcial, estimado, recalculado, de uma falha de medição. Um painel que descarta esses bits é um painel que não consegue explicar mais tarde um valor estranho, e a explicação está geralmente logo ali no bit. → History
Confie na hora do hub, não na sua. Os períodos, os dias e as zonas tarifárias são colocados pelo relógio e pelo fuso horário do próprio hub. Um cliente que volte a marcar a hora à chegada não concordará com o hub sobre a hora a que pertence uma leitura — e essa discordância fica invisível até uma mudança de dia. → Time
Trate um campo em falta como ausente, não como zero. Um ponto sem um módulo de tensão não reporta energia nenhuma, em vez de uma energia calculada a partir de uma tensão nominal; o hub recusa-se a inventá-la, e você também deve recusar.
Reconexão
O socket vai fechar: o hub reinicia para uma atualização, a Wi-Fi cai, um router reinicia. Planeie para isso em vez de se surpreender:
- Peça um ticket novo a cada tentativa. O anterior já está gasto ou expirou.
- Espere entre tentativas, e continue a esperar cada vez mais. Um cliente que tenta de novo em ciclo apertado contra um hub a meio de um reinício chega exatamente quando este está menos capaz de responder.
- Volte a enviar
start_telemetry. Um socket novo não está a enviar até que o peça. - Assuma que perdeu coisas. O fluxo são valores em tempo real, não uma fila; nada é reproduzido. Se o que perdeu importar, está no histórico, que é guardado, e no registo de preços, que é guardado durante 40 dias.
Quando usar outra coisa
| Pretende | Use |
|---|---|
| um valor em tempo real num ecrã | isto |
| Home Assistant, ou algo que já esteja num broker | MQTT — incluindo a descoberta |
| "a energia está barata neste momento?" | a notificação de preço retida por MQTT: um estado, não um fluxo → Knowing when energy is cheapest |
| períodos fechados, custos, um mês de dados | HTTP ou export.csv |
Para a notificação de preço em particular, não a construa sobre este socket. É um estado que o hub volta a publicar em cada limite de período de 15 minutos e sempre que algo muda, e por MQTT fica retido — por isso um cliente que se ligue tarde ainda recebe o estado atual. Um cliente WebSocket que esteve offline durante uma transição simplesmente perdeu-a.
Quando não funciona: o que verificar
O socket abre e fecha logo de seguida. O ticket já foi usado ou tem mais de 30 segundos. Peça um por ligação.
O socket fica aberto e nada chega.
Não foi enviado nenhum start_telemetry. Um socket novo fica em silêncio até ser pedido.
Funcionou e depois parou após uma atualização do hub. O hub reiniciou e o socket foi com ele. Reconecte com um ticket novo e volte a iniciar o fluxo.
Os valores chegam, mas o dinheiro não. Não está definida nenhuma tarifa, ou o hub ainda está no plano de exemplo de fábrica. → Tariffs
Um ponto envia corrente, mas nunca energia. Não tem tensão por trás. O hub mostra a potência em tempo real como uma estimativa a partir da tensão nominal e não regista energia, por design. → Remote nodes
Os totais horários não batem certo com os da aplicação por uma hora. Está a marcar as leituras com o seu próprio relógio. É o hub que decide em que hora cai uma leitura. → Time
Um cliente de navegador é recusado enquanto um script na mesma máquina funciona. O navegador está a aplicar regras de origem que o script não tem. Autorize a sua origem no hub. → Talking to the hub over HTTP
⚠️ Para qualquer trabalho dentro de um quadro elétrico, chame um eletricista qualificado.