Dati live senza polling
⚠️ Questa pagina riguarda il firmware autonomo dell'hub. Un hub che esegue il pacchetto ESPHome non ha alcuna API REST, nessun WebSocket e nessun MQTT: è un dispositivo ESPHome, e Home Assistant comunica con esso attraverso il pannello RBgrid e l'azione
rbgrid_cmd. Tutto ciò che segue presuppone che l'hub serva la propria app web. → Esegui all'interno di Home Assistant
L'hub invia i dati da sé. Apri un unico WebSocket su /ws-telemetry e le letture arrivano man mano che l'hub le produce, invece di chiederle ripetutamente e ricevere una copia sempre leggermente datata.
È ciò che usa l'app stessa. Se stai costruendo una dashboard, un flusso Node-RED o qualsiasi cosa che voglia un valore in tempo reale su uno schermo, questo è il canale di trasporto; per ciò che vuole un record anziché un valore, usa la cronologia via HTTP.
L'elenco delle route e il riferimento dei campi live si trovano nel riferimento API generato, un file del repository, prodotto dallo schema dell'hub stesso a ogni release. Questa pagina non li ripete: un elenco di campi copiato a mano diventa obsoleto in silenzio, e un elenco obsoleto è peggio di nessuno, perché sembra credibile.
Entrare da un browser, senza mettere un token nell'URL
Un indirizzo WebSocket non trasporta intestazioni, quindi la mossa ovvia sarebbe mettere il token nella query string, ed è così che i token finiscono nella cronologia del browser, nei log del server e negli screenshot.
L'hub offre l'alternativa:
POST /api/v1/ws-ticketvia HTTP, con il tuo token.- Ottieni un ticket: monouso, valido per 30 secondi.
- Apri il socket con il ticket.
Trenta secondi è volutamente breve, e il monouso significa che un ticket catturato è già esaurito. Richiedine uno per ogni connessione, inclusa ogni riconnessione, anziché tenerne uno.
⚠️ Un ticket non è una sessione. Autorizza l'apertura di un solo socket. Se lo memorizzi nella cache, la tua riconnessione fallirà nel momento peggiore, cioè proprio quando ti riconnetti: dopo che qualcosa è andato storto.
Per un client lato server che non è un browser, questo passaggio non serve: invia il token nel modo ordinario.
Le letture richiedono il token di lettura quando l'hub ha impostati entrambi i token. → Settings
Avviare e fermare il flusso
Il socket non è un flusso continuo a cui ti limiti ad agganciarti. Richiede tre messaggi:
| Messaggio | Fa |
|---|---|
get_telemetry |
un frame, adesso |
start_telemetry |
inizia a inviare |
stop_telemetry |
smette di inviare, mantiene il socket |
Fermati quando la tua pagina è nascosta e riparti quando torna visibile. Una scheda del browser lasciata aperta tutta la notte con un flusso attivo costa lavoro reale all'hub senza alcun vantaggio per nessuno, e l'hub sta anche servendo l'app, la connessione al broker e il ciclo di misura.
Un socket per client. Più socket da una stessa pagina è un bug che sembra un problema di prestazioni: ognuno è un flusso che l'hub deve riempire.
Quanto invia l'hub
La telemetria ha due profili, lean e full, impostati sull'hub (/api/system/telemetry-config). Lean è il frame più piccolo; full contiene tutto ciò che l'hub può riportare. Il frame ha anche un limite di dimensione che l'hub non supera.
Scegli lean, a meno che tu non usi campi che esistono solo in full. Una dashboard che mostra potenza e costo per punto non ha bisogno di full, e la differenza sono byte sulla rete ogni pochi secondi, per tutto il tempo in cui il client resta attivo.
Leggere ciò che arriva
Tre cose da fare, e le prime due sono quelle che le integrazioni saltano:
Conserva la qualità. I frame live e i record dicono entrambi cosa pensa l'hub dei propri numeri: parziale, stimato, ricalcolato, da un'interruzione. Una dashboard che elimina questi dettagli non riesce a spiegare un valore strano in seguito, e la spiegazione è di solito proprio in quel dettaglio. → History
Affidati all'orario dell'hub, non al tuo. Periodi, giorni e fasce tariffarie sono determinati dall'orologio e dal fuso orario dell'hub. Un client che riapplica il timestamp all'arrivo non sarà d'accordo con l'hub su quale ora appartiene una lettura, e il disaccordo è invisibile fino al cambio di giorno. → Time
Tratta un campo mancante come mancante, non come zero. Un punto senza modulo di tensione non riporta alcuna energia, anziché un'energia calcolata da una tensione nominale; l'hub rifiuta di inventarla, e tu dovresti fare lo stesso.
Riconnessione
Il socket si chiuderà: l'hub si riavvia per un aggiornamento, il Wi-Fi cade, un router si riavvia. Pianificalo invece di restarne sorpreso:
- Richiedi un ticket nuovo per ogni tentativo. Quello vecchio è esaurito o scaduto.
- Attendi tra un tentativo e l'altro, e continua ad allungare l'attesa. Un client che riprova in un ciclo serrato contro un hub in riavvio arriva proprio quando è meno in grado di rispondere.
- Rinvia
start_telemetry. Un nuovo socket non trasmette finché non lo chiedi. - Dai per scontato di aver perso dei dati. Il flusso contiene valori in tempo reale, non una coda; nulla viene riprodotto. Se ciò che hai perso conta, è nella cronologia via HTTP, che è conservata, e nel registro dei prezzi, conservato per 40 giorni.
Quando usare altro
| Ti serve | Usa |
|---|---|
| un valore in tempo reale su uno schermo | questo |
| Home Assistant, o qualsiasi cosa già su un broker | MQTT — discovery incluso |
| "l'energia è conveniente adesso?" | la notifica di prezzo retained su MQTT: uno stato, non un flusso → Knowing when energy is cheapest |
| periodi chiusi, costi, un mese di dati | HTTP o export.csv |
Per la notifica di prezzo in particolare, non costruirla su questo socket. È uno stato che l'hub ripubblica a ogni limite di periodo di 15 minuti e ogni volta che cambia qualcosa, e via MQTT è retained: quindi un client che si connette in ritardo riceve comunque lo stato attuale. Un client WebSocket che era offline durante una transizione semplicemente l'ha persa.
Quando non funziona: cosa controllare
Il socket si apre e si chiude subito. Il ticket era già stato usato o è più vecchio di 30 secondi. Richiedine uno per connessione.
Il socket resta aperto e non arriva nulla.
Non è stato inviato alcun start_telemetry. Un socket nuovo resta silenzioso finché non lo chiedi.
Ha funzionato, poi si è fermato dopo un aggiornamento dell'hub. L'hub si è riavviato e il socket è andato con lui. Riconnettiti con un ticket nuovo e riavvia il flusso.
I valori arrivano, ma il denaro no. Nessuna tariffa è impostata, oppure l'hub è ancora sul piano di esempio di fabbrica. → Tariffs
Un punto invia corrente ma mai energia. Non ha una tensione dietro. L'hub mostra la potenza live come stima a partire dalla tensione nominale e non registra energia, per progetto. → Remote nodes
I miei totali orari differiscono di un'ora da quelli dell'app. Stai marcando le letture con il tuo orologio. È l'hub a decidere in quale ora si trova una lettura. → Time
Un client browser viene rifiutato mentre uno script sulla stessa macchina funziona. Il browser applica regole di origine che lo script non ha. Consenti la tua origine sull'hub. → Talking to the hub over HTTP
⚠️ Per qualsiasi lavoro all'interno di un quadro elettrico, chiama un elettricista qualificato.