Sensori e unità

RBgrid misura attraverso due livelli:

• Sensori — i canali fisici che l'hub può vedere. In un hub v1.1.x sono i canali dei moduli I²C rbAmp: un ingresso di tensione e uno o più canali di corrente per modulo. Non c'è un ADC integrato; i moduli misurano e l'hub li legge via I²C.
• Unità — i punti di misura che crei associando un canale. Un'unità ha una propria identità, un nome, un ruolo, statistiche e una cronologia. Spostare un'unità su un altro canale (rebind) ne mantiene id, nome, cronologia e slot di cronologia.

Non scrivi alcun codice per aggiungere un sensore o un'unità. I canali compaiono da soli quando un modulo viene collegato; trasformi un canale in un'unità dall'app web o dall'API REST a runtime.

Sensori — i canali fisici

Ogni canale di un modulo collegato è elencato, che sia in uso oppure no. Un canale non associato a un'unità è semplicemente free: non produce dati, non viene sommato e non genera allarmi. Un modulo può essere usato con qualsiasi sottoinsieme dei suoi canali, in qualsiasi ordine.

Ogni canale riporta:

• ch_label — il canale come stampato sul corpo del modulo: I0, I1, … per i canali di corrente (numerati da 0), V per l'ingresso di tensione del modulo, e L1–L3 su un modulo consapevole delle fasi.
• Modello TA — per un canale di corrente, il modello del trasformatore di corrente in uso (ct_code / ct_name leggibile, per esempio SCT-013-050, 50 A; ct_name viene omesso quando il modello è sconosciuto) e i limiti del modulo per esso. Nell'app è il Current sensor del punto. Su un modulo che accetta una TA a pinza di tua scelta imposti tu il modello (vedi Scegliere il modello TA più sotto); su un modulo la cui TA è abbinata in fabbrica al canale, il modello è fisso.
• Stato della correzione — se il modulo ha applicato la sua correzione per il modello TA scelto. Se non l'ha fatto (readings not corrected), l'interfaccia mostra un avviso e il motivo (il canale non è calibrato · il suo guadagno non corrisponde al modello TA · il modulo non conosce questo modello TA). Finché la correzione non è applicata, le letture possono differire da quelle reali.

I moduli stessi provengono dalla configurazione moduli dell'hub; un modulo all'indirizzo predefinito (0x50) viene trovato senza alcuna configurazione (vedi Get started). Le famiglie di moduli rbAmp, la composizione dei loro canali e la gamma di TA sono documentate insieme ai moduli: vedi la documentazione dei moduli rbAmp.

Unità — i punti di misura

Un'unità si crea associando un canale a un punto. Contiene:

Nell'app i ruoli si chiamano Appliance, Load, Breaker, Generation, Storage, Charging station, Heating/cooling, Smart appliance, e per i ruoli di alimentazione Grid input e Backup input.

Due unità sono speciali di alimentazione: l'alimentazione principale (il collegamento alla rete) e un'alimentazione alternativa facoltativa (generazione interna). L'app non offre mai i ruoli di alimentazione durante l'associazione e non permette di cambiarli, e l'hub blocca entrambe: una patch che tocca uno dei due ruoli viene rifiutata (HTTP 409). Esse portano il monitoraggio economico del sito. Il bus di tensione (l'ingresso V del modulo) e l'ingresso principale non possono essere eliminati.

Configurazione a runtime — app web o REST

Tutto si configura sull'hub in funzione. Nulla viene impostato nel codice C.

App web — Points → Free sensors → Bind trasforma un canale libero in un'unità; i campi dell'unità si modificano nelle sue impostazioni.

REST — le stesse operazioni sono disponibili via HTTP:

Le operazioni di scrittura richiedono il token di amministrazione dell'hub, quando è impostato: impostalo con POST /api/system/token e invialo nelle scritture; è consigliato. Finché non imposti un token, le scritture sono aperte sulla rete locale.

Associare un canale, per esempio:

POST /api/v1/units
{
  "sensor": { "iface": "i2c", "bus": 0, "module": 0, "ch": 1 },
  "name": "Kitchen", "point": "kitchen",
  "role": "ZONE_LOAD", "stat_class": "1HOUR", "location": "ground floor"
}

La risposta restituisce il nuovo unit_id. Gli id nuovi vengono assegnati a partire da 0100 in su. Rinominare un punto ritira il vecchio slug, così un sistema esterno non riprende silenziosamente un punto diverso con la stessa chiave.

Eliminare (o dissociare) un'unità cancella in modo definitivo la sua cronologia memorizzata; il suo canale torna libero. L'ID di un punto rimosso può essere riutilizzato di proposito: l'app lo offre durante l'associazione (Bind with the previous ID). L'hub poi riparte da zero con la cronologia, ma Home Assistant e MQTT continuano la vecchia serie come un unico punto.

Parametri come name, role, phase, rated_power_w, max_current_a e il modello TA si modificano in tempo reale con l'endpoint di patch e vengono salvati anche dopo un riavvio. Il riferimento completo dei campi è nella API di unità e sensori.

Scegliere il modello TA

Su un canale il cui modulo accetta una TA a pinza di tua scelta (serie SCT), imposta il modello TA sulla pinza effettivamente montata: il Current sensor del punto nelle sue impostazioni, oppure ct_code tramite l'endpoint di patch. Il modello viene scritto nel modulo insieme alla sua calibrazione di tipo, e resta legato all'identità di quel modulo, così un modulo diverso nello stesso slot mantiene il proprio modello memorizzato.

Cambialo solo se è davvero montata una pinza diversa. Scrivere il modello sostituisce la calibrazione di fabbrica del canale, e quella calibrazione non può essere ripristinata. Su un canale abbinato in fabbrica (serie CT) il modello è fisso: l'hub rifiuta la modifica. Su un modulo non calibrato il modello non può essere scelto.

Fase

phase indica a quale linea di alimentazione appartiene un canale. Su un'alimentazione monofase tutti i canali usano il valore predefinito (1P / L1). Sono supportate alimentazioni monofase e trifase. Potenza ed energia monofase sono validate sull'hardware. Anche potenza ed energia trifase sono verificate sull'hardware, con i tre ingressi di tensione su una sola fase di banco; una vera rete trifase a 120° non è mai stata sul banco. Un ingresso trifase è un unico STD-U3I3, e la scheda del suo modulo è dove scegli se l'ingresso viene misurato come un punto con le fasi compensate oppure come un punto per fase, ciascuna con la propria importazione ed esportazione. I sistemi di alimentazione validati sul tuo hub sono elencati in GET /api/v1/schema → enums.grid_system_validated.

phase è solo un'etichetta. L'hub non moltiplica né divide mai i valori di un'unità per il numero di fasi: un'unità con un solo trasformatore di corrente riporta ciò che quel singolo conduttore trasporta, qualunque sia il suo phase. Un'unità impostata su 3 phases su un carico trifase è l'energia misurata di un solo ramo: non dividerla né moltiplicarla per tre.

Statistiche

Ogni unità conserva i dati a 3 secondi e a 15 minuti solo in RAM; non hanno cronologia memorizzata. La cronologia memorizzata inizia a livello orario: l'hub conserva le registrazioni orarie sulla propria flash, che sopravvivono a un riavvio, e da esse costruisce giorni, settimane, mesi e anni. È uguale per ogni unità, qualunque sia il suo stat_class. La cronologia viene conservata per un massimo di 12 unità; le unità oltre la dodicesima mostrano solo valori in tempo reale. Un'unità aggiunta mentre l'hub è in funzione inizia la sua cronologia dopo il riavvio successivo. I totali di energia dall'origine sono conservati separatamente dalla cronologia.

Quando un canale è vicino al limite

Un punto segnala il proprio stato sulla sua tessera nella Overview, in Load lines, nella tabella dei punti e in Needs attention; la pagina del punto mostra un avviso:

• clipping — la corrente ha raggiunto il punto di saturazione del sensore (la sua corrente a fondo scala, che è superiore alla sua portata nominale). Oltre quel valore la lettura è sottostimata, e il modulo da solo non può accorgersene. Anche le impostazioni del punto avvisano in anticipo quando l'interruttore di linea supera il limite del sensore, e le righe della Cronologia annotano il clipping.
• sensor limit — la corrente è vicina alla corrente di saturazione del sensore: l'hub segnala a circa il 90 % di quella corrente. Per le pinze SCT-013 la corrente di saturazione è circa il 116 % della portata (58 A su un SCT-013-050), quindi l'avviso scatta a circa il 104 % della portata (52 A). Fino alla corrente di saturazione le letture sono corrette. I sensori propri dei moduli STD non hanno tali segnalazioni; leggono correttamente fino a circa il 130 % della loro portata.
• Una TA invertita su un modulo BASIC: il punto mostra sensor reversed — not metered. Un modulo BASIC misura solo il flusso in avanti, quindi il carico non viene misurato finché non ruoti la pinza.

Il registro eventi aggiunge una riga quando lo stato cambia: "near its limit", "clipping" o "back within range". Solo clipping marca il record dell'ora (un flag di qualità per sovraportata); "near its limit" compare solo nel registro. Vedi The Overview e Points per dove compaiono questi stati.