Nodi remoti (ESP-NOW)

Panoramica

Un nodo remoto è una piccola scheda ESP32 con i propri moduli rbAmp. Misura dove un cavo I2C dall'hub non arriva: un garage, una pompa della piscina, uno scaldabagno in cantina, un sottoquadro in un edificio esterno. Invia le sue letture all'hub via radio, tramite ESP-NOW. Il nodo non è collegato alla tua rete Wi-Fi e non ha un indirizzo proprio: comunica solo con il suo hub. I suoi canali diventano normali punti sull'hub, con valori in tempo reale, cronologia e costo come qualsiasi altro punto.

Questa pagina è la documentazione completa dei nodi: scheda e moduli, cablaggio, flashing, associazione, come un nodo mantiene l'ora e l'energia, che cosa mostra l'app, le API dell'hub e i topic MQTT, e che cosa fare quando qualcosa non va. I nodi remoti richiedono il firmware dell'hub v1.1.7 o successivo e l'app web 1.1.7 o successiva. Su un hub con firmware più vecchio, l'app non mostra alcuna sezione Nodes; "Remote nodes are not available in this hub firmware." compare solo per un hub la cui immagine firmware non può eseguire nodi.

Un nodo è un trasmettitore. Non ha display, né pagina web, né cronologia leggibile, e non ha aggiornamenti over the air: lo si aggiorna via USB. Dal firmware 1.5 conserva i periodi di 15 minuti completati nella propria memoria flash finché l'hub non li ha ricevuti — è una coda, non un registro che puoi aprire. Il resto lo fa l'hub.

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

Che cosa ti serve

Requisito
Scheda del nodo Un modulo ESP32 originale con 4 MB di flash. La PSRAM non è necessaria. Sulla v1.1.7 il firmware del nodo è compilato e testato solo per l'ESP32 originale: le schede ESP32-S2, S3 e C3 non sono previste né testate.
Moduli rbAmp sul nodo Fino a tre moduli sul bus I2C del nodo, agli indirizzi 0x50, 0x51 e 0x52 (impostazione del modulo stesso); SDA è GPIO 25 e SCL è GPIO 26. L'hub usa fino a quattro canali di corrente per nodo.
Un ingresso di tensione sul nodo Sulla v1.1.7 un nodo registra l'energia solo quando uno dei suoi moduli misura la tensione. Un modulo solo-corrente su un nodo fornisce la corrente in tempo reale, ma nessun periodo di 15 minuti, quindi nessuna cronologia e nessun costo. Installa un set rbAmp monofase con ingresso di tensione.
Fasi Sulla v1.1.7 un nodo misura solo punti monofase. Su un nodo non esiste raggruppamento di fasi né l'opzione "use as the three-phase input": quella è per un modulo sull'hub. Uno STD-U3I3 su un nodo non è testato.
L'hub Firmware v1.1.7 o successivo, collegato alla tua Wi-Fi. La radio dell'hub per i nodi funziona sullo stesso canale del tuo router; un hub senza Wi-Fi non può gestire nodi. Un hub gestisce fino a sei nodi.
Slot di cronologia I punti dei nodi condividono i 12 slot di cronologia esistenti dell'hub con i punti dell'hub stesso; non ne aggiungono altri. La sezione Nodes mostra "History: used of 12 points in use" prima dell'associazione.
Un computer con USB Per il flashing del nodo e per ogni successivo aggiornamento del firmware del nodo.
Pinze amperometriche Come per un modulo sull'hub; il modello di pinza è impostato per canale dall'hub (vedi Node settings).

Cablaggio del nodo

Un nodo si cabla come un piccolo hub: i suoi moduli rbAmp si collegano al bus I2C del nodo, e le pinze amperometriche vanno sui moduli.

  • I2C: quattro fili tra la scheda ESP32 e i moduli, SDA a GPIO 25, SCL a GPIO 26, GND e 3.3 V. Gli indirizzi dei moduli 0x50, 0x51, 0x52 si impostano sui moduli stessi; il nodo legge quelli presenti all'avvio, fino a tre. Il bus è tirato su dalle resistenze di pull-up a bordo dei moduli; con fino a tre moduli su cavi corti, lasciale come sono. La lunghezza dei cavi e i pull-up negli altri casi sono descritti nella guida al cablaggio rbAmp, la stessa usata per i moduli sull'hub.
  • Ingresso di tensione: sulla v1.1.7 un modulo del nodo deve avere il suo ingresso di tensione collegato alla rete che misura; senza di esso il nodo ha la corrente in tempo reale ma non registra energia (vedi What you need). L'ingresso di tensione fornisce anche al nodo la direzione di ciascuna corrente, importazione o esportazione.
  • Pinze: una per canale di corrente, sul conduttore che vuoi misurare, con la freccia orientata come indicato nella documentazione dei moduli rbAmp. Il modello di pinza si imposta per canale dall'hub (vedi Node settings); un modello sbagliato scala le letture in modo errato.
  • Alimentazione: l'alimentazione abituale della scheda ESP32, ad esempio la sua porta USB o un alimentatore da 5 V sull'ingresso della scheda. Il nodo non ha batteria né autonomia: un'interruzione di corrente lo ferma, e l'energia del periodo che era in corso va persa.
  • Posizione: dove resterà installato. Un nodo non deve trovarsi vicino all'hub per essere associato; il collegamento viene verificato nel punto in cui si trova (vedi Checking the link). Evita, dove possibile, involucri metallici tra il nodo e l'hub.

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

Flashing del firmware del nodo

Il firmware del nodo viene pubblicato con ogni release dell'hub nella pagina Releases di RBgrid su GitHub: rbgrid-node_vX.Y.Z.bin (la sola applicazione) e rbgrid-node_vX.Y.Z_full.zip (bootloader, tabella delle partizioni e applicazione). Usa la versione che corrisponde al tuo hub, oppure una più recente.

Con la scheda in modalità download e esptool installato (pip install esptool), scrivi l'intero set:

python -m esptool --chip esp32 -p <PORT> -b 460800 write_flash 0x1000 bootloader.bin 0x8000 partition-table.bin 0x10000 rbgrid-node_vX.Y.Z.bin

⚠️ Aggiornando un nodo al firmware 1.5 si scrivono tutti e tre i file, non solo l'applicazione. La 1.5 aggiunge la partizione flash in cui vivono i periodi conservati. Un nodo a cui viene data solo la nuova applicazione esegue la 1.5 senza un posto dove conservarli e ricade su otto periodi in memoria, e la scheda non lo dice. Scrivere tutti e tre i file è anche ciò che serve per ogni aggiornamento successivo: non costa nulla, e un nodo associato con la 1.4 non deve essere riassociato.

Come compilare il firmware da soli, e quali pin cambiare se la tua scheda collega l'I2C in modo diverso, sono descritti in node/README.md nel repository di RBgrid.

Il nodo non richiede alcun file di chiave né alcuna impostazione di canale. Ottiene la chiave dall'hub quando lo associ, e trova da solo il canale dell'hub.

Compilare da soli il firmware del nodo

Il sorgente è la cartella node/ del repository di RBgrid, con la stessa licenza del firmware dell'hub. Si compila con ESP-IDF 5.5.1 (anche 5.4.1 compila):

cd node
idf.py set-target esp32
idf.py build
idf.py -p <PORT> flash

La libreria rbAmp viene scaricata al momento della compilazione (dependencies.lock ne fissa la versione). Se la tua scheda collega l'I2C ad altri pin, compila con -DRBN_I2C_SDA=<n> -DRBN_I2C_SCL=<n>. Non serve alcun file di chiave. Le varianti di sviluppo presenti nel sorgente (RBN_ROLE_MASTER, RBN_FREERUN, RBN_OUTPUT_NODE) non fanno parte della release e non sono supportate.

Associare un nodo

I nodi si gestiscono in Management → Points, nella sezione Remote nodes (ESP-NOW). L'intestazione mostra "n of 6 nodes" e lo stato della radio per i nodi, "radio on" o "radio off". Su un hub che può gestire nodi la sezione si trova in cima alla pagina, sopra rbAmp modules, e la procedura guidata di configurazione include un passo facoltativo ESP-NOW nodes ("Step 5 of 8", dopo Sensors e prima di Tariff).

  1. Posiziona il nodo dove resterà, con i moduli e le pinze installati, ma lascialo senza alimentazione.
  2. Nell'app, scegli il Pairing time (in minuti) e premi Pair a node. La sezione dice: "Power the node up now. It shows up below in a few seconds." e conta alla rovescia: "Waiting for a node… time left". Stop pairing chiude la finestra in anticipo.
  3. Alimenta il nodo (o resettalo). Cerca l'hub sui canali Wi-Fi, scambia le chiavi con esso e compare nell'elenco, contrassegnato new. I suoi punti vengono aggiunti subito: "Paired in this window: n. Their points are already added; no restart needed."

La sezione Remote nodes con una finestra di associazione aperta: «Waiting for a node… 1:56 left» e «Stop pairing», sopra le due schede dei nodi

⚠️ Mentre la finestra di associazione è aperta, qualsiasi nodo RBgrid nel raggio che lo chiede viene associato. Non c'è alcun PIN. Questo include un nodo di proprietà di qualcun altro il cui hub è rimasto silenzioso: un nodo associato che non riceve risposta per circa 150 secondi comincia a chiedere di associarsi da solo. Apri la finestra solo quando stai per alimentare un nodo, tienila breve, e chiudila con Stop pairing quando il tuo nodo è nell'elenco; poi verifica che l'elenco contenga solo i nodi che ti aspetti.

Le chiavi sono conservate sul nodo e sull'hub. Dopo un riavvio, o dopo che la radio è stata spenta, il nodo si ricollega da solo; lo associ una volta sola.

Prima di associare, controlla le due righe di capacità nella sezione: "n of 6 nodes" (quando l'hub è pieno il pulsante viene sostituito da "The hub takes up to 6 nodes. Remove one to pair another.") e "History: used of 12 points in use. Points beyond 12 show live values only." (oppure "History: all 12 points are in use. A new node's points will show live values only."). Se la radio è spenta, la sezione dice "Turn the radio for nodes on to pair one."

Ogni nodo porta fino a quattro punti. Vengono denominati in base al nodo e ai suoi canali; rinominali e assegna loro i ruoli nelle rispettive pagine, come per qualsiasi altro punto (vedi Points). I punti dei nodi non possono essere collegati o scollegati a mano: un canale disattivato nelle impostazioni del nodo smette di misurare, e rimuovere il nodo rimuove i suoi punti.

La scheda del nodo

La sezione Remote nodes: la radio sul canale 6, il controllo di associazione e due schede di nodo — una online con il suo segnale, la sincronizzazione dell'orologio e due canali in ricezione, una offline da 90 minuti

Ogni nodo associato ha una scheda nella sezione.

Sulla scheda Che cosa significa
online / offline L'hub ha sentito il nodo negli ultimi 15 secondi, oppure no. Un nodo spento (vedi sotto) mostra off.
new Associato nella finestra di associazione corrente.
Last heard "now", "n s ago", "n min ago", "n h ago", oppure "not heard since the hub started".
Signal L'intensità dell'ultimo frame del nodo, in dBm, come l'ha registrata la radio dell'hub.
Lost packets, last minute La quota dei beacon orari dell'hub che il nodo ha mancato nell'ultimo minuto, in percentuale. Mostra "measuring (1 min)" finché non è passato un minuto intero.
Clock sync Quanto da vicino l'orologio del nodo segue quello dell'hub: "±n µs · n ppm".
Firmware La versione del firmware del nodo, una volta che il nodo l'ha riportata.
Period "15 min". Il periodo è fisso; la finestra Settings lo dice: "Energy records: every 15 min, fixed."
Waiting to send Dove l'hub lo riporta: il numero di periodi di 15 minuti completati che il nodo trattiene perché l'hub era fuori portata (vedi How a node keeps time and energy). Il firmware dell'hub v1.1.7 non lo riporta, quindi la riga lì non compare.
Channel n Ogni canale di corrente del nodo: il punto che alimenta (il suo nome, un link alla pagina del punto; "Point key" finché il punto non ha un nome) e il suo stato, "receiving", "no data" o "off (Settings)".
settings not applied yet / settings not applied Le impostazioni sono state inviate al nodo e lui non le ha ancora confermate, oppure le ha rifiutate.
Signal, lost packets and clock sync missing Un nodo non sentito dall'avvio dell'hub non ha nessuna di queste: la scheda omette le tre righe e Last heard mostra "not heard since the hub started". Compaiono con il primo frame del nodo.

La scheda ha tre pulsanti: Settings, Turn off / Turn on, e Delete.

La scheda di un nodo al completo: il MAC e il suo badge online, Last heard, Lost packets nell'ultimo minuto, Clock sync, Signal, Firmware 1.5 e il periodo di 15 minuti, con i due canali del nodo collegati a punti con nome

Impostazioni del nodo

Settings apre "Node mac: settings". Per ogni canale mostra Channel n measures (on o off) e Current clamp, il modello di pinza montato su quel canale. "Pick the clamp actually fitted to each channel: a wrong one scales its readings wrongly. A channel turned off stops measuring." Almeno un canale deve restare attivo.

Send to the node invia le impostazioni tramite l'hub: "Sent. The node applies the settings on its next contact; the card shows «settings not applied yet» until it confirms." Se il nodo è offline, l'hub conserva le impostazioni e le consegna quando il nodo torna ("The node is offline. It takes the settings when it's back.").

Il periodo di energia di un nodo è fisso a 15 minuti ("Energy records: every 15 min, fixed."); non può essere modificato.

Spegnere e riaccendere un nodo

Turn off mantiene il nodo associato ma fa scartare all'hub i suoi dati. L'app chiede prima conferma: "The hub discards the node's data while it's off: that energy won't be in History or the totals, and turning it back on doesn't bring it back. To pause a node and keep its energy, leave it on." Mentre è spento, la scheda mostra off e i suoi punti non mostrano valori in tempo reale. Turn on riprende.

Usalo quando un nodo misura qualcosa che per un po' non vuoi conteggiare. Per fermare un nodo in modo definitivo, rimuovilo.

La radio per i nodi

La riga Radio for nodes nell'intestazione della sezione mostra uno di tre stati:

  • "On, channel n: the same as your Wi-Fi router's." La radio dell'hub per i nodi è attiva. Funziona sul canale Wi-Fi dell'hub, che sceglie il tuo router; se il router passa a un altro canale, l'hub e i suoi nodi lo seguono.
  • "Starts by itself when a node is paired (factory setting)." Non è ancora in funzione nulla; la radio parte con la prima associazione o quando un nodo è già associato.
  • "Off. Nodes can't send data." L'hai spenta tu.

Spegnerla chiede prima conferma: "The nodes stop sending live values. They keep their 15-minute energy records and send them when the radio is on again (up to 2 hours on node firmware 1.4, about 5 days on 1.5). The hub remembers this after a restart." Ogni nodo passa subito offline. I valori in tempo reale di quel periodo non vengono conservati; i registri sì, per tutto il tempo che il firmware del nodo riesce a tenerli.

Rimuovere un nodo

Delete chiede "Remove node mac?": "The node and its points (channels: n) are removed, with their stored history, for good. Download the history first in History (CSV) if you need it. To use the node again, pair it again."

⚠️ Rimuovere un nodo elimina i suoi punti e tutta la cronologia memorizzata. Se potresti avere bisogno dei registri, scaricali prima in History.

L'hub smette subito di accettare i dati del nodo e conferma: "Node removed, with its points: n." Per usare di nuovo il nodo, riassocialo: apri una finestra di associazione e resetta il nodo (oppure attendi circa 2 minuti e mezzo: un nodo che non riceve risposta dal suo hub per 150 secondi comincia a chiedere di associarsi da solo).

Spostare un nodo su un altro hub

Un nodo associato continua a chiedere al suo hub; quando non riceve risposta per 150 secondi si segna come non associato e chiede di riassociarsi, e dopo un reset lo chiede subito. Quindi spostare un nodo su un altro hub, o rimettere in servizio un nodo usato, è un'associazione:

  1. Delete sul vecchio hub (se ce l'hai ancora).
  2. Apri una finestra di associazione sul nuovo hub e resetta il nodo (oppure attendi circa 2 minuti e mezzo). Il nodo prende la chiave del nuovo hub.

Cancellare prima la flash del nodo (python -m esptool --chip esp32 -p <PORT> erase_flash, poi flash the firmware again) è facoltativo: un avvio pulito, non un requisito.

Come un nodo mantiene l'ora e l'energia

  • Orologio. L'orologio è quello dell'hub. Il nodo chiede l'ora ogni 5 secondi finché non l'ha, poi ogni minuto, e nel frattempo usa il proprio timer. Clock sync sulla scheda mostra quanto da vicino lo segue.
  • I valori in tempo reale vengono inviati circa una volta al secondo e mostrati sui punti del nodo. Non vengono memorizzati.
  • L'energia viene registrata in periodi di 15 minuti, che il nodo chiude secondo il proprio orologio sui limiti di 15 minuti dell'hub, con l'energia dai contatori interni dei suoi moduli. Quando cambia la zona tariffaria, l'hub chiede a ogni nodo di chiudere anche il proprio periodo in quel momento, così il costo per zona è esatto.
  • Un periodo raggiunge l'hub, oppure viene conservato. Il nodo invia un periodo completato finché l'hub non conferma di averlo registrato, quindi i registri reggono un collegamento debole meglio della vista in tempo reale. L'hub riconosce un periodo che ha già e non lo conteggia mai due volte.
  • Fuori portata. Il nodo continua a chiudere i periodi in orario e trattiene quelli completati finché l'hub non li conferma. Quando il collegamento torna, arrivano tutti insieme e vengono registrati e prezzati in base all'ora in cui sono stati misurati, non all'ora di arrivo. Quanto può trattenere dipende dal firmware del nodo, non dall'hub:
    • Firmware del nodo 1.5 li scrive nella propria flash: circa cinque giorni di periodi, e sopravvivono a un'interruzione di corrente sul nodo.
  • Firmware del nodo 1.4 ne conserva otto (circa due ore) in RAM; un nono spinge fuori il più vecchio, e un'interruzione di corrente sul nodo fa perdere i periodi trattenuti e quello in corso.

In entrambi i casi, quando la scorta è piena il periodo più vecchio viene eliminato, e il nodo lo segnala nel proprio log.

  • Un nodo che si avvia senza il suo hub non chiude alcun periodo finché non ha sentito l'hub almeno una volta. L'energia non va persa: sulla v1.1.7 il primo registro dopo un avvio copre tutto da quando il nodo si è avviato fino alla fine del suo primo periodo completo di 15 minuti, quindi quel periodo può risultare più alto di quanto fosse realmente il carico.

Il firmware non prevede una soglia di superamento per il segnale o per i pacchetti persi, e questa pagina non ne fornisce una; il nodo è affidabile nel punto in cui si trova oppure non lo è. Il test corretto è quello del comportamento:

  1. Associa il nodo nel punto in cui resterà, con il carico effettivamente in funzione.
  2. Osserva la scheda per circa dieci minuti: il nodo dovrebbe restare online, Lost packets, last minute dovrebbe restare a 0 e Last heard dovrebbe restare su "now" o pochi secondi.
  3. Se i pacchetti persi salgono sopra zero, oppure il nodo oscilla tra online e offline, il collegamento è marginale. Sposta un po' il nodo, o l'hub, e osserva di nuovo.

Nel firmware esistono due soglie, e sono le uniche: un nodo è offline dopo 15 secondi senza un frame (l'hub pubblica node_offline e node_online su MQTT), e un nodo che non sente alcun beacon per 8 secondi ricomincia a cercare il canale dell'hub (è così che segue un router che cambia canale; non serve alcun riavvio).

Un collegamento debole si manifesta con pacchetti persi sopra 0 e vuoti nei valori in tempo reale mentre i registri continuano ad arrivare; uno peggiore fa oscillare il nodo. Un nodo fuori portata e un nodo senza alimentazione appaiono uguali all'app e all'API. Solo la cronologia della scheda prima del calo le distingue: un collegamento debole peggiora per primo (perdite in aumento, segnale in calo, oscillazioni), un'interruzione di corrente è netta.

Sapere in seguito che un nodo è diventato silenzioso

La conservazione di cinque giorni serve solo se te ne accorgi entro cinque giorni.

Dal firmware v1.2.0 l'hub lo registra. Un nodo che smette di trasmettere e uno che torna sono righe nel Hub log — espnow: node <MAC> offline e … online — quindi un nodo che è diventato silenzioso mentre eri assente lascia una traccia che puoi ritrovare in seguito, con il suo orario. → Events

Sul firmware v1.1.8 nulla nell'app viene a cercarti: un nodo che smette di riportare è mostrato sulla sua scheda e nell'elenco Nodes, e in nessun altro posto. Non c'è alcuna voce nel Journal dell'app e nessun elemento in Needs attention — su quel firmware l'hub scrive la riga solo nel proprio log seriale.

Su nessuno dei due firmware l'app fa scattare un allarme: il log è un registro da consultare, non una notifica che ti raggiunge. Per quello, usa Home Assistant.

Con Home Assistant hai un vero allarme, e costa un'automazione. L'hub pubblica per ogni nodo un'entità di connettività Online tramite MQTT discovery, come sotto-dispositivo dell'hub, e segue lo stato trattenuto del nodo. Se fai un'automazione sullo spegnimento di quell'entità, ti viene segnalato entro un minuto. La stessa transizione viene pubblicata come evento node_offline sul topic degli eventi dell'hub, se preferisci osservare gli eventi.

Senza MQTT, la scheda è tutto ciò che hai. Apri ogni tanto la sezione Nodes — oppure dai un'occhiata ai punti del nodo in History, dove un nodo silenzioso lascia un vuoto che cresce.

Che cos'è davvero la transizione, così puoi regolare la pazienza dell'automazione:

  • l'evento scatta dopo 15 secondi senza un frame in tempo reale — la stessa soglia usata dalla scheda, e un nodo invia circa un frame al secondo;
  • non c'è debounce: ogni vuoto più lungo di 15 s produce una coppia offline/online, e i vuoti più brevi non producono nulla. Un collegamento marginale ti dà qualche coppia, non centinaia;
  • il topic di stato viene aggiornato una volta al minuto con segnale e perdite, come stato e non come evento — quindi una dashboard che lo legge non è mai più vecchia di un minuto.

Totali e il resto "unmetered"

Il totale della casa non può essere contato due volte: i totali di sistema vengono calcolati al confine della rete, solo dal punto di ingresso. I punti di carico, sull'hub o su un nodo, non si sommano mai a essi.

Il resto unmetered nella Overview invece può. È l'ingresso meno la somma di tutti i punti di linea, e i punti dei nodi sono punti di linea. Se misuri un sottoquadro su un nodo e un carico dentro quel sottoquadro su un altro canale, quel carico viene sottratto due volte, e il resto può diventare negativo.

Dal firmware v1.1.8 puoi segnalarlo all'hub: contrassegna il punto interno come misurato dentro quello esterno, e smette di essere sottratto una seconda volta. È la risposta giusta per un'alimentazione secondaria di officina o garage misurata su un nodo con i carichi misurati dietro di essa — conservi entrambi i valori e il resto continua ad avere senso. Non cambia nulla nella misura né nel totale della casa.

L'impostazione è Management → Points → il punto → Point setup → Point settings → Measured inside, dove None: a line of its own è il valore predefinito. L'elenco esclude l'ingresso, il bus di tensione, il punto stesso e tutto ciò che è già dentro di esso; una scelta che l'hub rifiuta mostra "The hub refused that choice: the point is gone, is an input, or is already inside this one. Pick another." → Points

⚠️ Vale per un livello. B dentro A viene conteggiato una volta. Dove una catena va più in profondità — C dentro B dentro A — e il punto intermedio non è mostrato, alcune viste possono ancora contare due volte il punto più interno.

Sulla v1.1.7 non esisteva un'impostazione del genere, e il consiglio era di misurare o il sottoquadro o i carichi al suo interno, non entrambi. Il totale della casa non cambia in nessuno dei due casi: i totali di sistema sono calcolati all'ingresso.

Dove i nodi compaiono altrove

  • Points: i canali di un nodo sono punti come gli altri, con le proprie pagine, ruoli e nomi (vedi Points).
  • History e Economics: per punto, come per qualsiasi punto; i punti dei nodi condividono i 12 slot di cronologia (vedi History).
  • Events: il Hub log registra l'associazione di un nodo, le impostazioni che conferma, e le righe FAIL per frame o registri che l'hub non è riuscito a contare. Un nodo che va offline o torna non è nel log — viene pubblicato su MQTT e mostrato sulla scheda del nodo (vedi Events).
  • MQTT: l'hub pubblica uno stato trattenuto per nodo su rbgrid/<mac>/node/<NODEMAC>/status (online, segnale, pacchetti persi, ultimo contatto), aggiornato ogni minuto, e gli eventi del nodo su rbgrid/<mac>/event; le stesse azioni sul nodo sono disponibili tramite il canale di comando (vedi MQTT broker).
  • Home Assistant: un dispositivo per nodo, con un sensore Online e un sensore Signal, tramite discovery. I punti del nodo compaiono come quelli locali.
  • L'API dell'hub: GET /api/v1/espnow elenca lo stato della radio e ogni nodo con il suo stato di salute; POST /api/v1/espnow esegue le stesse azioni dell'app (vedi sotto).

L'API dell'hub

Tutto ciò che l'app fa con i nodi passa per un unico endpoint dell'hub, che puoi usare anche tu.

GET /api/v1/espnow (il token di lettura, come per le altre letture) restituisce la radio e il registro:

Campo Significato
running, enabled la radio è attiva; enabled è auto (parte da sola quando un nodo è associato), on oppure off
keys, key_source true su ogni immagine dell'hub dalla v1.1.7, e da dove proviene la chiave dell'hub (generated: creata da questo hub la prima volta che la radio è partita). Un hub senza keys non può gestire nodi
max_nodes, max_channels_per_node 6 e 4
channel il canale radio, quello del router Wi-Fi
pairing_open, pairing_left_s, paired_count la finestra di associazione, i secondi che restano, il numero di nodi associati
beacons_sent, rt_recv, stats_recv, periods_recv, periods_injected, periods_dropped, periods_dup contatori dall'avvio dell'hub: beacon orari inviati, frame in tempo reale e di periodo ricevuti, periodi registrati, scartati, e riconosciuti come ripetizioni
nodes[] per nodo: mac, online, disabled, last_seen_s, rssi_dbm, sync{ resid_sd_us, skew_ppm, fits, loss_pct }, channels[{ ch, ct_code, unit_id, present }], config_state (none, pending, applied, failed), config[], period_s, fw. Un nodo non sentito dall'avvio dell'hub non ha last_seen_s né sync{}

POST /api/v1/espnow (il token di amministratore) con { "action": … }:

action Campi Che cosa fa
hub_on / hub_off — accende o spegne la radio per i nodi (mantenuto tra i riavvii); spegnerla porta subito ogni nodo offline
pair seconds 10–600 apre la finestra di associazione; 409 ESPNOW_DISABLED mentre la radio è spenta
pair_cancel — la chiude in anticipo
configure mac, config: { channels: [ { ch, enabled, ct_code } ] } impostazioni del nodo; l'hub reinvia finché il nodo non conferma. 400 PERIOD_UNSUPPORTED per qualsiasi period_s diverso da 900; 400 BAD_REQUEST per un canale sconosciuto, un ct_code fuori da 1–7 o tutti i canali spenti
disable / enable mac spegne o accende un nodo
remove mac rimuove il nodo e i suoi punti, con la loro cronologia
latch — chiede a ogni nodo di chiudere ora il suo periodo corrente
add mac, channels: [ { ch, ct_code } ] registra un nodo a mano, senza associazione

Gli errori tornano come { "ok": false, "error": "BAD_REQUEST" | "ESPNOW_DISABLED" | "ESPNOW_OFF" | "ESPNOW_START_FAILED" | "REGISTRY", "message": "…" }. I punti dei nodi sono punti normali in ogni altro endpoint (src: "espnow" nel frame in tempo reale), e GET /api/system/provisioning riporta nodes_paired.

Tramite MQTT lo stesso funziona sul canale di comando: {"cmd":"get","section":"espnow"} restituisce la GET sopra, e {"cmd":"set","section":"espnow","token":"<admin>","data":{"action":"pair","seconds":60}} esegue un'azione e risponde con la risposta dell'hub. L'hub pubblica uno stato trattenuto per nodo su rbgrid/<mac>/node/<NODEMAC>/status ({ "online", "rssi_dbm", "loss_pct", "last_seen_s" }, aggiornato ogni minuto) e gli eventi del nodo su rbgrid/<mac>/event (paired, removed, node_online, node_offline). In Home Assistant ogni nodo è un dispositivo con un sensore Online e uno Signal (dBm); un nodo non sentito dall'avvio dell'hub mostra "no data".

Messaggi

Messaggio Che cosa significa
Remote nodes are not available in this hub firmware. L'immagine firmware di questo hub non può eseguire nodi. (Un hub precedente alla v1.1.7 non mostra affatto la sezione Nodes.)
Turn the radio for nodes on to pair one. La radio è spenta; accendila prima.
The hub takes up to 6 nodes. Remove one to pair another. Tutti e sei gli slot per nodi sono occupati.
The radio for nodes is off. Turn it on first. Un'azione richiede la radio, ed è spenta.
The hub couldn't start the radio for nodes. Try again; if it keeps failing, restart the hub. La radio non è riuscita a partire.
The hub couldn't change its node list (full, or the node isn't known). Il registro dei nodi ha rifiutato la modifica.
The hub didn't accept the request. L'hub ha risposto che la richiesta era malformata. Ricarica la pagina e riprova.
The hub refused: message Il motivo dell'hub stesso.
The hub didn't answer. Check the connection and try again. Nessuna risposta dall'hub.
The hub doesn't know this node any more. Reload the page. Il nodo è stato rimosso, forse da un altro browser.
The hub takes only the 15-minute period. Per un nodo viene accettato solo il periodo di 15 minuti.

Risoluzione dei problemi

Ho premuto Pair a node, ma non compare nulla

  • Alimenta il nodo, o resettalo, mentre la finestra è aperta.
  • Verifica che la radio per i nodi non sia spenta, e che l'hub sia collegato alla tua Wi-Fi.
  • Un nodo associato a un altro hub chiede di nuovo quando quell'hub non gli risponde da 150 secondi, oppure subito dopo un reset (vedi Moving a node to another hub).
  • Controlla l'alimentazione del nodo, e che il suo flashing sia terminato senza errori.

Il nodo è offline, oppure va continuamente online e offline

  • Non si sente nulla da lui da 15 secondi. Controlla prima la sua alimentazione; poi la sua posizione. Vedi Checking the link.
  • La radio dell'hub per i nodi potrebbe essere spenta: in tal caso ogni nodo è offline.

Signal, lost packets e clock sync mancano dalla scheda

  • Il nodo non è stato sentito dall'avvio dell'hub ("Last heard: not heard since the hub started"). Le righe compaiono con il suo primo frame.

I punti del nodo mostrano valori in tempo reale ma nessuna cronologia

  • I 12 slot di cronologia dell'hub erano già occupati al momento dell'associazione del nodo: "Points beyond 12 show live values only." Rimuovi un punto che non ti serve, poi riassocia il nodo, oppure accetta punti solo in tempo reale.
  • Un nodo registra energia solo con un modulo che misura la tensione. Un modulo solo-corrente fornisce la corrente in tempo reale e una potenza in tempo reale stimata (la tensione nominale × corrente, 230 V se non è impostata nessuna) — ma nessun periodo, nessuna cronologia e nessun costo. Dalla v1.1.8 l'hub non registra affatto energia per un ingresso del genere, invece di inventarla dalla tensione nominale.

Ogni nodo risulta offline anche se è alimentato e associato

  • GET /api/v1/espnow → inject_age_ms pari a -1 significa che il task dell'hub che registra i dati dei nodi non è in esecuzione. Fino alla v1.1.7 l'hub poteva non avviarlo in silenzio quando la RAM interna era insufficiente all'avvio, e nessuno lo segnalava; la v1.1.8 riserva quella memoria in fase di compilazione. Aggiorna l'hub.

Dalla v1.2.0 non devi cercarlo: la sezione Remote nodes mostra un avviso quando il task si è fermato, con accanto un pulsante Restart now.

La sezione Remote nodes con un avviso che l'hub non registra i dati dei nodi, e un pulsante «Restart now»

Il riavvio risolve la condizione su un hub che ha la memoria; se si ripresenta dopo il riavvio, l'hub è su un firmware precedente alla v1.1.8 e la soluzione è aggiornare, non riavviare di nuovo.

La sincronizzazione dell'orologio continua a perdersi

  • Un altro hub RBgrid è sullo stesso canale Wi-Fi, e un nodo con firmware 1.4 ha accettato i beacon orari di entrambi gli hub. Aggiorna il nodo alla 1.5: da allora segue solo l'hub a cui è associato, e non richiede una nuova associazione.

Manca energia per un po' di tempo

  • Il nodo era fuori portata per più tempo di quanto possa trattenere periodi, oppure ha perso alimentazione. Con il firmware del nodo 1.5 sono circa cinque giorni, e un'interruzione di corrente non fa perdere ciò che trattiene; con la 1.4 sono otto periodi, circa due ore, e un'interruzione di corrente fa perdere sia quelli sia il periodo in corso.
  • Il nodo era spento (Turn off) in quel periodo: l'hub scarta i dati di un nodo mentre è spento.
  • Il nodo si è avviato mentre l'hub non era raggiungibile: sulla v1.1.7 l'energia dal suo avvio finisce nel suo primo periodo completo di 15 minuti, quindi un periodo precedente appare vuoto e quello appare alto. Non si perde nulla.

Il mio router ha cambiato canale Wi-Fi

  • Non c'è nulla da fare. La radio dell'hub per i nodi segue il router, e un nodo che non sente nulla per 8 secondi torna a cercare l'hub.