Parlare con l'hub via HTTP

⚠️ 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 gli parla attraverso il pannello RBgrid e l'azione rbgrid_cmd. Tutto ciò che segue presuppone che l'hub serva la propria app web. → Run it inside Home Assistant

Tutto ciò che fa l'app, lo fa via HTTP sull'hub nella tua rete. Nel percorso non c'è alcun cloud e nessun account: se raggiungi l'hub, puoi leggerlo, e con il suo token puoi anche modificarlo.

Questa pagina copre la parte che una tabella delle route non può dirti — quale token, con quale frequenza chiedere, e i pochi errori che sembrano guasti dell'hub e non lo sono. Le route stesse sono nel riferimento API generato, un file del repository che l'hub produce dal proprio schema e che viene rigenerato a ogni release. Qui non si ripete quell'elenco di proposito: una tabella delle route copiata a mano è sbagliata una release dopo, e lo è in silenzio.

I due token

Token	A cosa serve
admin	modificare l'hub. Una volta impostato, ogni scrittura lo richiede — e l'hub risponde `Admin token required.` quando manca
read	leggere l'hub, quando ne hai impostato uno

Impostali nell'app, Settings → Security. Finché non è impostato un token admin, chiunque possa raggiungere l'hub può modificarlo — per questo l'app mantiene a schermo un avviso finché non sono completati sia questo sia la password del punto di accesso. → Settings

Invia un token come bearer token nella richiesta. Il riferimento generato contrassegna ogni route che richiede il token admin per le scritture.

⚠️ Ciò che il riferimento generato non ti dice è quali letture richiedono il token di lettura — lo dice da sé, nella propria intestazione. La regola seguita dall'app è: quando l'hub ha impostati entrambi i token, anche le letture richiedono il token di lettura. Se stai costruendo qualcosa che legge soltanto, imposta un token di lettura e invialo; un 401 su una route che ti aspettavi aperta di solito significa proprio questo.

Per le cinque route dei prezzi la suddivisione è dichiarata: GET richiede il token di lettura, POST richiede il token admin. Quindi una dashboard che legge soltanto i prezzi e il registro dei prezzi applicati non ha mai bisogno di quello admin — e non va dato a lei.

Un client browser non dovrebbe portare un token nell'URL

Per una pagina che apre un WebSocket, mettere un token nell'indirizzo è il modo in cui i token finiscono nei log, nella cronologia e negli screenshot. L'hub offre una via d'uscita: POST /api/v1/ws-ticket restituisce un ticket monouso, valido per 30 secondi, che il socket presenta al suo posto. → Live data over WebSocket

Consentire a un browser di un'altra origine di chiamare l'hub

Una pagina servita da un altro posto viene bloccata dal browser, non dall'hub. /api/system/security è dove consenti un'origine — fino a otto. È una porta deliberata, quindi aprila solo per le origini che usi e per nessun'altra.

Cosa interrogare, e cosa no

Non interrogare per i valori in tempo reale. Li invia l'hub: tramite WebSocket e tramite MQTT, con il ritmo proprio dell'hub. Interrogare /api/v1/summary in un ciclo ti dà gli stessi numeri più tardi, costa all'hub lavoro che potrebbe spendere in misurazione, e ti dà un intervallo di campionamento che si sposta rispetto a quello dell'hub.

Interroga per le cose che cambiano lentamente, e adatta la frequenza a quanto cambiano davvero:

Cosa	Cambia	Chiedi
record della cronologia	quando si chiude un periodo	al massimo una volta per periodo; per `from`/`to`, non rileggendo l'intera giornata
economia	con i record su cui si basa	lo stesso
stato dei prezzi	quando arrivano i prezzi o cambia uno stato	la notifica dei prezzi è uno stato a cui puoi iscriverti; vedi sotto
configurazione	quando la modifichi	dopo che l'hai modificata

⚠️ Un ciclo senza backoff è l'unico schema che ti costerà un fine settimana. Se una route fallisce, la risposta corretta è aspettare più a lungo prima del tentativo successivo, non insistere di più. L'hub è un microcontrollore che serve un'app web, una connessione al broker, il ciclo di misurazione e te allo stesso tempo; un client che lo bombarda con tentativi stretti è, dal lato dell'hub, indistinguibile da un client che lo fa di proposito.

Leggere ciò che l'hub ha misurato

History è per punto e per periodo, ed è lo stesso dato che mostra la pagina History dell'app — inclusa la qualità di ogni record, che è la parte che gli integratori più spesso scartano e poi non riescono a spiegare un valore. Un record porta dei bit che indicano se è parziale, ricalcolato, stimato o se copre un'interruzione. Portali con te in qualsiasi cosa costruisci; un numero di cui hai scartato la qualità è un numero che non puoi difendere. → History

Economics è il costo e il valore dell'esportazione, calcolati dall'hub con il prezzo in vigore per ogni periodo — non ricalcolati da una tariffa attuale. → How cost is calculated

export.csv ti dà la stessa cosa sotto forma di file, per punto, periodo e tipo. Per tutto ciò che richiede un foglio di calcolo o un archivio lungo, questa è la via più economica: una sola richiesta invece di un ciclo.

⚠️ La cronologia oraria è conservata per 60 giorni, poi diventa giornaliera, mensile e annuale. Se ti servono le ore di un intero periodo di fatturazione a posteriori, scaricale prima che passino — un export.csv pianificato è il modo abituale.

Le route dei prezzi (firmware 1.2.0 e successivi)

Tre route, che rispondono a tre domande diverse:

Route	Risponde a
`/api/v1/dynprice`	come è configurata la tariffazione, quali fornitori esistono, e lo stato attuale
`/api/v1/price`	il prezzo risolto per ogni periodo di 15 minuti — e con `log=1`, a quale prezzo è stato effettivamente registrato ogni periodo concluso, per 40 giorni
`/api/v1/signal`	la notifica di prezzo attuale: il prezzo adesso, la sua fonte, la posizione del periodo nella giornata, quali finestre convenienti sono aperte, e i due flag

/api/v1/price è anche una scrittura. Un client che conosce i tuoi prezzi — un'integrazione di Home Assistant, il tuo script — può inviare fino a 200 periodi all'hub, e l'hub prezza l'energia con quelli. È la via per un fornitore per il quale l'hub non ha una fonte. Dichiari se ciò che invii è un prezzo spot o all-in; sbagliare questo è l'errore più costoso disponibile qui, perché moltiplica in silenzio ogni valore di costo. → Where your price comes from

Per la notifica, preferisci il topic MQTT retained invece di interrogare /api/v1/signal. È uno stato: l'hub lo ripubblica a ogni confine di 15 minuti e nel momento in cui cambia qualcosa, e un messaggio retained consegna lo stato attuale a un client che si connette più tardi. Chi interroga ottiene la stessa cosa, in ritardo, e non perde nulla solo chiedendo di continuo. → Knowing when energy is cheapest

Modificare le cose

Le scritture richiedono il token admin e, per alcune route, un riavvio prima di avere effetto — il riferimento generato ha una colonna che lo indica. Alcune regole che non compaiono in nessuna tabella:

Una scrittura rifiutata indica il campo. L'hub risponde 400 con il campo che non ha accettato, cosa molto più utile di un codice di stato. Leggilo: di solito ti sta dicendo qualcosa di vero sulla tua configurazione, come una zona di prezzo che opera in una valuta diversa da quella del tuo piano.
I nomi sono limitati in byte, non in caratteri — 24 byte per un nome breve, 31 per un nome. Una lettera cirillica o accentata ne occupa due, quindi un nome che sembra corto può essere comunque rifiutato.
Su alcune route la configurazione è un documento intero. Dove una route accetta una sezione di configurazione, inviarne una parziale sostituisce la sezione. Leggila, cambia ciò che intendi cambiare, e rimandala indietro.

Ciò che l'API non fa

Nessun cloud, nessun account, nessun accesso remoto. L'hub serve la tua rete. Tutto ciò che va oltre è il tuo tunnel, la tua VPN, la tua responsabilità.
Non controlla nulla. Non esiste una route che commuti un carico. L'hub misura, prezza e pubblica; agire su questa base è compito di ciò che costruisci. → Knowing when energy is cheapest
Nessun limite di frequenza per route su cui fare affidamento. La sua assenza non è un permesso; vedi l'avviso sul backoff sopra.

Quando una chiamata non fa ciò che ti aspetti: cosa controllare

401 su qualcosa che ieri funzionava. Da allora è stato impostato un token sull'hub. Le letture richiedono il token di lettura una volta che esistono entrambi i token; le scritture richiedono quello admin.

Admin token required. su una scrittura che sei sicuro di poter fare. Il token è impostato ma non arriva all'hub — controlla che sia un bearer token nella richiesta stessa, e non un parametro nella query string.

Un browser riceve un errore CORS, curl funziona bene. È il browser che rifiuta, non l'hub. Aggiungi la tua origine in /api/system/security; c'è spazio per otto.

Una scrittura restituisce 400 e indica un campo che non hai inviato. Alcune route accettano un'intera sezione di configurazione. Il campo è nella sezione che hai sostituito, e non era valido nello stato in cui si trova l'hub — il caso più comune è una zona la cui valuta non corrisponde a quella del piano.

Un'impostazione è stata salvata ma non è cambiato nulla. Alcune route richiedono un riavvio per applicarsi; il riferimento generato indica quali nella propria colonna.

La cronologia ha dei buchi. I buchi sono record che l'hub non ha, non record che ha perso: era in riavvio, in aggiornamento o senza alimentazione. I bit di qualità dei record vicini dicono cosa è successo. → History

Il registro dei prezzi ha meno di 96 righe per un giorno. Stessa causa, stesso significato: il registro contiene i periodi in cui l'hub era in funzione. Un periodo mancante non è un prezzo mancante.

I valori in tempo reale arrivano lentamente, o non allineati con l'app. Stai interrogando dove dovresti iscriverti. → Live data over WebSocket

⚠️ Per qualsiasi intervento all'interno di un quadro elettrico, rivolgiti a un elettricista qualificato.