09 · Riferimento API
L'API pubblica della libreria RbAmp per Arduino a partire dalla v1.6.1. Una sola classe serve entrambe le linee di prodotti — BASIC e STANDARD (STD): begin() rileva la linea e ogni chiamata viene instradata internamente. Le chiamate valide solo su una linea sono contrassegnate; una chiamata senza equivalente sulla linea rilevata fallisce con RB_ERR_NOT_IMPLEMENTED. Fonte di verità — i file di intestazione src/RbAmp.h, src/RbAmpSnapshot.h, src/RbAmpEnergy.h, src/RbAmpSensorModels.h, src/RbAmpRegisters.h (gli ultimi due sono generati automaticamente e non vanno modificati a mano).
Questo capitolo è un riferimento: firme, valori di ritorno, effetti collaterali, casi limite. Per esempi funzionanti vedi 06 · Esempi; per l'avvio rapido vedi 05 · Avvio rapido.
File di intestazione
| Includi | Cosa porta con sé |
|---|---|
|
Tutti i tipi pubblici (includono il resto) |
|
RbAmpSnapshot, RbAmpPeriodSnapshot, RbAmpTopology, RbAmpVariant, RbAmpLine, RbAmpSensorClass, RbAmpSctRating, RbAmpDrdyEvent e le strutture RbAmpStd* della linea STD |
|
RbAmpEnergy |
|
Registro generato dei modelli di sensore — i codici modello RBAMP_CT_* e rbamp_sensor_model_lookup() |
|
Costanti del protocollo generate automaticamente — RB_OK, RB_ERR_*, SETTLE_MS_* |
Uno sketch utente di solito richiede solo #include — il resto viene incluso in modo transitivo.
Su quale linea funziona una chiamata?
| Gruppo | BASIC | STD |
|---|---|---|
Ciclo di vita, letture in tempo reale (readVoltage … readAll), misura per periodo, energy() |
sì | sì |
readReactivePower(), readApparentPower() |
no (RB_ERR_NOT_IMPLEMENTED) |
sì |
Setter della classe del sensore / modello TA, saveUserConfig(), cambio di indirizzo, reset() |
sì | sì (il modello CT è un'etichetta su STD, vedi sotto) |
factoryReset(), helper General-Call, helper per le etichette, readCapability(), readCommitSeq(), readPeriodLatchMs() |
sì | no (RB_ERR_NOT_IMPLEMENTED) |
Linea di data-ready ed eventi (setDrdyPin(), waitDataReady(), setEventMask() …) |
sì | sì (dipende dall'immagine del modulo, vedi sotto) |
std* chiamate (API della linea STD) |
no (RB_ERR_NOT_IMPLEMENTED) |
sì |
Correzione della portata SCT-013 (sctRating*()) |
sì (classe SCT-013, firmware BASIC più vecchio) | mai applicato (scala 1) |
Alcune funzioni STD dipendono dalla versione dell'immagine del modulo: i contatori di micro-energia, la corrente di avvio per l'energia, gli angoli di fase della tensione e la sequenza di fase richiedono un'immagine di almeno 0x0001007B (stdReadImageVersion()). Su un'immagine più vecchia la libreria le segnala come "non disponibili" (un flag valid impostato a false, un valore derivato, oppure RB_ERR_NOT_IMPLEMENTED) — mai come un numero sbagliato.
Classe RbAmp
Il client principale. Un'istanza per dispositivo slave sul bus I²C. Più istanze possono condividere un unico bus TwoWire per interrogare più moduli.
Costruttore
explicit RbAmp(TwoWire& bus,
uint8_t addr = 0x50,
RbAmpTopology hint = RbAmpTopology::Single) noexcept;
| Parametro | Descrizione |
|---|---|
bus |
Riferimento al bus TwoWire (di solito Wire). Il chiamante deve invocare bus.begin() PRIMA di begin(). |
addr |
Indirizzo slave a 7 bit. Intervallo 0x08..0x77, predefinito 0x50. |
hint |
Suggerimento di topologia: il numero di canali di corrente (1/2/3). Sul firmware precedente alla v1.3 begin() non può determinare in modo affidabile la variante, quindi il suggerimento viene usato come ripiego per gli SKU multicanale. Il valore predefinito è Single — il default sicuro, che non provoca letture spurie di canali assenti. Per i moduli multicanale sul firmware precedente alla v1.3, passi esplicitamente il suggerimento corrispondente. |
Il costruttore non genera traffico I²C.
Metodi del ciclo di vita
bool begin() noexcept
02 · Inizializzazione e avvio (initialization) · BASIC o STD? (initialization) · Ciclo di polling continuo (consigliato) (period-metering)
Sondare il dispositivo, rilevare la linea di prodotto e la variante, innescare lo snapshot.
Sequence:
-
Prima la sonda di identità STD. Se il modulo risponde come modulo STD, i conteggi dei canali vengono dal modulo stesso, il banco di snapshot 0 viene armato e preparato, e
begin()restituisce — i passi BASIC qui sotto vengono saltati. -
Leggere
REG_VERSION(0x03). Se il dispositivo non ha risposto con ACK —falseconRB_ERR_NACK. Se ha restituito0x00/0xFF—falseconRB_ERR_VERSION. -
Memorizzi nella cache la topologia: il byte di variante del modulo sui firmware che lo espongono, altrimenti il
hintdel costruttore. Dopodichétopology()/channels()restituiscono valori validi senza toccare il bus. Il numero di canali non supera maiRBAMP_MAX_CHANNELS(7); i canali oltre quel limite non sono esposti e indirizzarli restituisceRB_ERR_PARAM. -
Legga
U_rmsper determinare se è presente un sensore di tensione (soglia 1.0 V). -
Scrivere
CMD_LATCH_PERIODcome innesco + attendere 50 ms. Il primo snapshot dopo l'accensione viene scartato (non viene consegnato al codice utente — mescola dati precedenti all'accensione). -
Memorizzare
millis()per la successiva integrazione dell'energia. - Su un modulo BASIC con la classe SCT-013, legga la correzione di portata per canale (vedere Correzione della portata SCT-013). Se il modulo si trova nello stato che richiede un riavvio per applicare il guadagno corretto,
begin()lo riavvia una volta.
Idempotente: sicuro da richiamare.
Restituisce: true in caso di successo; false altrimenti — vedi lastError() per i dettagli.
bool probe() noexcept
Un controllo leggero di attività. Una singola lettura di REG_VERSION senza effetti collaterali.
Restituisce: true se lo slave ha risposto con ACK e ha riportato una versione supportata (né 0 né 0xFF).
bool waitReady(uint32_t timeout_ms = 1000) noexcept
02 · Inizializzazione e avvio (inizializzazione) · 3. DATA_VALID (0xCE) non diventa mai 1 (risoluzione dei problemi) · 4 · Mappa dei registri (produzione v1.3) (riferimento API)
Interroga il flag di prontezza del modulo finché il bit 0 non è impostato. Utile dopo l'accensione — il modulo può richiedere fino a una finestra di misura (100 ms) per confermare i primi dati.
Restituisce: true se il bit è stato visto prima che scadesse timeout_ms; false con RB_ERR_TIMEOUT altrimenti.
uint8_t firmwareVersion() noexcept
Restituisce: il byte REG_VERSION (0x03). Valori BASIC noti: 0x01 = v1.0, 0x02 = v1.1, 0x03 = v1.2, 0x04 = v1.3. Il firmware BASIC più recente riporta valori più alti. 0 o 0xFF indicano un errore I²C (vedi lastError()).
RbAmpLine line() const noexcept
Restituisce: la linea di prodotto rilevata da begin() — RbAmpLine::Basic (il valore fino a quando begin() non è stato eseguito) oppure RbAmpLine::Std. Nessun accesso al bus.
RbAmpTopology topology() const noexcept
Restituisce: la topologia in cache. Nessun accesso al bus.
uint8_t channels() const noexcept
Corrente multicanale (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Blocco in tempo reale V03 (0x86..0xBD) (riferimento API) · 4.14 Finestra di accesso ai canali (0x32 + 0x3C..0x3F) (riferimento API)
Restituisce: il numero di canali di corrente, 1..RBAMP_MAX_CHANNELS (7). Sulla linea STD il conteggio è quello riportato dal modulo, limitato a RBAMP_MAX_CHANNELS.
bool hasVoltageHw() const noexcept
Restituisce: true se un sensore di tensione è stato rilevato a begin(). Dalla cache, nessun traffico.
uint8_t address() const noexcept
Restituisce: l'indirizzo I²C attuale a 7 bit. Aggiornato dopo un commitAddressChange() riuscito.
uint8_t rawTopology() noexcept
Lettura diretta di REG_TOPOLOGY (0x24). A differenza di topology(), questa esegue una transazione I²C.
Returns:
1/2/3—SINGLE/SPLIT_PHASE/THREE_PHASE.0xFF— errore I²C.
Per il rilevamento completo dello SKU usi readVariant() (legge REG_HW_VARIANT 0x55) — vedere Identificazione e provisioning.
Letture in tempo reale (blocco RT, aggiornamento ogni 100 ms)
Tutti i metodi restituiscono float. In caso di errore restituiscono NAN e impostano lastError(). Internamente si usa un filtro di ripetizione + sanità per la robustezza contro i rari disturbi del collegamento su ESP-IDF (vedere i contatori diagnostici qui sotto). Il modulo pubblica nuovi valori una volta per finestra di misura — 100 ms (firmware BASIC prima della v1.2 e immagini STD fino a 0x7B: 200 ms).
float readVoltage(uint8_t phase = 0) noexcept
Tensione RMS istantanea. phase è 0 sulla linea BASIC; sulla linea STD va da 0 .. n_voltage-1 (vedi stdInfo()). Una fase fuori intervallo restituisce NAN con RB_ERR_PARAM.
float readVoltagePeak(uint8_t phase = 0) noexcept
Picco di tensione nella finestra RT. Stessa regola di phase.
float readCurrent(uint8_t ch = 0) noexcept
Corrente multi-canale (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Finestra di accesso ai canali (0x32 + 0x3C..0x3F) (api-reference)
Corrente efficace RMS istantanea su un canale. ch deve essere < channels() — altrimenti NAN con RB_ERR_PARAM. Include qualsiasi canale pari o superiore a RBAMP_MAX_CHANNELS (7).
float readCurrentPeak(uint8_t ch = 0) noexcept
Corrente di picco su un canale nella finestra RT.
float readPower(uint8_t ch = 0) noexcept
Riferimento dei registri RT (realtime-polling) · Contabilità bidirezionale (period-metering)
Potenza attiva istantanea su un canale. Con segno — un valore negativo significa esportazione (il carico reimmette potenza nella rete, rilevante per installazioni fotovoltaiche / bidirezionali).
float readPowerFactor(uint8_t ch = 0) noexcept
Fattore di potenza su un canale. Adimensionale, intervallo −1..+1.
float readReactivePower(uint8_t ch = 0) noexcept — solo STD
Potenza reattiva su un canale, in var, con segno. Su BASIC la potenza reattiva non è esposta da questa libreria: la chiamata restituisce NAN con RB_ERR_NOT_IMPLEMENTED.
float readApparentPower(uint8_t ch = 0) noexcept — solo STD
Potenza apparente su un canale, in VA. Su un modulo BASIC restituisce NAN con RB_ERR_NOT_IMPLEMENTED.
float readFrequency() noexcept
Frequenza di rete, in Hz.
bool readAll(RbAmpSnapshot& out) noexcept
Riferimento dei registri RT (realtime-polling) · Polling — singolo modulo (realtime-polling) · 4.10 Blocco RT V03 (0x86..0xBD) (api-reference)
L'intero blocco RT in una sola chiamata, in una struct RbAmpSnapshot. Equivale a readVoltage() + readVoltagePeak() in sequenza
readCurrent(0..N)+readCurrentPeak(0..N)+readPower(0..N)+readPowerFactor(0..N)+readFrequency(). I canali non usati (oltrechannels()) sono riempiti con zeri.
Un singolo campo letto ma che non supera il filtro di plausibilità fisica viene impostato a NAN e segnalato in out.implausible (bit RBAMP_FIELD_*); il resto dello snapshot resta utilizzabile.
Restituisce: true a meno che una lettura di trasporto non sia fallita — in tal caso false e lastError() contiene il codice del primo errore.
Misura per periodo
Veda 01 · Panoramica per il quadro generale e 05 · Avvio rapido, passo 5, per un modello minimo.
bool latchPeriod() noexcept
04 · Misura per periodo e contabilizzazione tariffaria (period-metering)
Scrive CMD_LATCH_PERIOD (0x27) in REG_COMMAND. Non attende — il chiamante deve osservare lui stesso l'assestamento di 50 ms e controllare isPeriodValid() prima di leggere.
Per la maggior parte dei compiti usare readPeriodSnapshot() — incapsula l'intera sequenza.
Restituisce: true alla scrittura riuscita.
bool isPeriodValid() noexcept
04 · Misura per periodo e contabilizzazione tariffaria (period-metering) · Calibrazione e precisione (risoluzione dei problemi) · 7.5 Conservazione del periodo con snapshot fallito (riferimento API)
Legge il bit di prontezza dello snapshot. true se l'ultimo snapshot è recente e pronto per la lettura.
float readPeriodAvgPower(uint8_t ch = 0) noexcept
Registri dello snapshot del periodo (period-metering) · 4.11 Blocco periodo V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + periodo ch0 (0xD0..0xE3, build di produzione) (api-reference)
Potenza attiva media su un canale sul periodo chiuso. Va chiamata dopo latchPeriod() + 50 ms di assestamento + verifica di validità.
float readPeriodMaxPower() noexcept
Registri dello snapshot del periodo (period-metering) · 4.12 V03 Q + periodo ch0 (0xD0..0xE3, build di produzione) (api-reference)
Potenza istantanea di picco sul canale 0 nel periodo chiuso.
uint32_t readPeriodLatchMs() noexcept
13. Deriva dell'orologio multi-modulo nei test lunghi (troubleshooting) · 4.13 dt diagnostico lato chip (0xEC) (api-reference)
Durata del periodo dal punto di vista del dispositivo, in ms.
latch_ms è un timer diagnostico del modulo; non lo usi per l'energia — usi l'orologio del master (master_dt_ms da RbAmpPeriodSnapshot).
bool readPeriodSnapshot(RbAmpPeriodSnapshot& out, uint16_t settle_ms = 50, bool skip_latch = false) noexcept
Ciclo di interrogazione continuo (consigliato) (period-metering) · Multimodulo — snapshot simultaneo (period-metering) · Calibrazione e precisione (risoluzione dei problemi)
Il punto di ingresso consigliato per la misura per periodo. La sequenza completa in background:
-
Se
skip_latch == true— salta la scrittura del comando di snapshot (si applica dopobroadcastLatch()o dopo una serie manuale di comandi di snapshot). -
Altrimenti — scrivere
CMD_LATCH_PERIOD. - Acquisisca
millis()per calcolaremaster_dt_ms. -
delay(settle_ms)— 50 ms di default secondo la specifica del protocollo. -
Controlli il flag di prontezza dello snapshot. Se 0 — imposti
RB_ERR_STALEe registri il timestamp (così lo snapshot successivo non conta due volte perdt). -
Legga
avg_p[0..channels-1]+max_p+latch_ms. - Aggiornare il timestamp e chiamare
energy().tick(out, channels_)per l'integrazione automatica dei Wh.
| Parametro | Descrizione |
|---|---|
out |
Struttura di output. |
settle_ms |
Attesa dopo il comando di snapshot, 50 per impostazione predefinita. |
skip_latch |
Se true — non invii il comando di snapshot, legga soltanto (per una scena multi-scheda sincronizzata). |
Restituisce: true se out.valid == true; false se la lettura è fallita o lo snapshot non è aggiornato.
Sulla linea STD l'assestamento dopo uno snapshot viene portato ad almeno 300 ms (il modulo esegue lo snapshot al prossimo limite della finestra di misura), latch_ms è 0 e master_dt_ms è il periodo. Su un modulo STD che conserva contatori vita persistenti invece di banchi di snapshot, il periodo è la differenza di due letture del contatore sulla pianificazione del master; avg_p_total, wh_net e module_restarted dello snapshot vengono compilati lì.
Misura dell'energia (accumulatore lato master)
RbAmpEnergy& energy() noexcept
const RbAmpEnergy& energy() const noexcept
Accesso all'accumulatore Wh per canale di proprietà di questa istanza RbAmp. L'accumulatore viene aggiornato automaticamente a ogni readPeriodSnapshot() riuscito. Per i dettagli vedere la sezione "classe RbAmpEnergy" più sotto.
double energyWh(uint8_t ch = 0) const noexcept
Algoritmo lato master (period-metering) · 7 · Semantica (riferimento API)
Il totale di energia corrente di un canale, come energy().wh(ch) — tranne su un modulo STD che conserva contatori persistenti ma non pubblica la ripartizione per canale (più di un canale, mappa dei registri più vecchia): una richiesta per canale restituisce qui NaN invece di uno 0 che si leggerebbe come "nessun consumo". Usi RBAMP_ENERGY_CH_TOTAL come ch per il totale di tutti i canali.
Configurazione del sensore
Una sequenza in due passi: prima la classe del sensore, poi il modello. Entrambi i passi sono obbligatori sul firmware BASIC v1.2 e successivi.
Per una guida dettagliata alla scelta del modello vedere 03 · Scelta del sensore di corrente.
Modello CT — preset funzionale su BASIC, etichetta su STD. Su un modulo BASIC, scrivere il modello CT applica immediatamente il preset corrispondente — le letture di corrente cambiano. Cambiare la RbAmpSensorClass riporta a 0 i modelli CT dei canali sul modulo. Su un modulo STD il modello è solo un riferimento (etichetta del sensore): non imposta alcun guadagno, perché il modulo è calibrato per canale.
Lettura prima della scrittura. I setter leggono prima il modulo. Scrivere una classe o un modello che il modulo possiede già è un'operazione nulla (true, nessuna scrittura sul bus, nessun ciclo di flash), quindi una configurazione memorizzata può essere riapplicata a ogni avvio senza toccare la calibrazione del modulo. Un modulo di classe WiredCT o BuiltinCT (fornito e calibrato insieme al suo sensore) non viene riconfigurato: il setter restituisce false con RB_ERR_MODE e non scrive nulla. setCTModelChForce() è il percorso di assistenza.
Impostare un modello TA riavvia il modulo. Sul firmware BASIC fino alla 1.4.19 con la classe SCT-013, setCTModel() (entrambe le forme) e configureChannels() riavviano il modulo dopo il salvataggio perché il nuovo modello abbia effetto (circa un secondo in tutto, bloccante), poi rileggono la correzione della portata. Non le chiami in un ciclo e non si aspetti letture durante quel tempo.
bool setSensorClass(RbAmpSensorClass cls) noexcept
Impostazione della classe del sensore e del modello TA (inizializzazione) · 4.3 Sistema (0x20..0x25) (riferimento API) · 6.2 Associazione del modello TA — solo staging + CMD per canale (riferimento API)
Impostare la classe del sensore di corrente con un salvataggio in flash.
Sequenza: legga la classe attuale del modulo (lettura prima della scrittura) → scriva REG_SENSOR_CLASS (0x25) → CMD_SAVE_USER_CONFIG (0x32) → attenda 700 ms (cancellazione della flash). Bloccante. Adatto alla produzione — SAVE_USER_CONFIG non è soggetto a limitazioni.
Deve essere chiamato prima di setCTModel(). Altrimenti setCTModel() restituisce false con RB_ERR_PARAM. Azzera anche i modelli CT a 0 sul lato dispositivo, quindi impostare i modelli dopo. Sulla linea STD la classe è un metadato, persistito con il salvataggio della configurazione del modulo, e valgono le stesse regole lettura-prima-della-scrittura.
| Argomento | Significato |
|---|---|
RbAmpSensorClass::Sct013 |
Pinza SCT-013 della serie montata dall'utente; il modello seleziona il tipo di sensore |
RbAmpSensorClass::WiredCT |
TA cablato fornito con il modulo e calibrato insieme ad esso — non riscritto dai setter |
RbAmpSensorClass::BuiltinCT |
CT integrato, calibrato insieme al modulo — non riscritto dai setter |
Restituisce: true in caso di successo, oppure quando il modulo possiede già cls. false con RB_ERR_MODE quando il modulo è di classe WiredCT / BuiltinCT.
bool readSensorClass(uint8_t& out) noexcept
Legge la classe di sensore di corrente del modulo (un valore RbAmpSensorClass; 0 = non impostata). Funziona su entrambe le linee.
Restituisce: true in caso di successo.
bool setCTModel(uint8_t code) noexcept
La forma a singolo parametro — imposta il modello della pinza CT solo sul canale 0. Comoda per gli SKU a canale singolo (UI1/I1); sui multi-canale equivale a setCTModel(0, code).
Sequenza: scrive REG_CT_MODEL (0x05) → CMD_SET_CT_MODEL_CH0 (opcode 0x28) → assestamento di 5 ms → CMD_SAVE_USER_CONFIG (opcode 0x32) → 700 ms. Adatto alla produzione — usa il percorso di salvataggio della configurazione utente, senza limitazioni della modalità di fabbrica.
Indicare il modello con la define RBAMP_CT_* generata (da RbAmpSensorModels.h), ad esempio RBAMP_CT_SCT013_030:
| Definire | code |
Modello |
|---|---|---|
RBAMP_CT_SCT013_005 |
1 | SCT-013-005 |
RBAMP_CT_SCT013_010 |
2 | SCT-013-010 |
RBAMP_CT_SCT013_030 |
3 | SCT-013-030 |
RBAMP_CT_SCT013_050 |
4 | SCT-013-050 |
RBAMP_CT_SCT013_100 |
5 | SCT-013-100 |
RBAMP_CT_SCT013_020 |
6 | SCT-013-020 |
RBAMP_CT_SCT013_060 |
7 | SCT-013-060 |
Un code non presente nel registro per la classe del modulo → false con RB_ERR_PARAM e nessuna scrittura. Un codice presente nel registro ma non accettato dal modulo viene rifiutato dal modulo con RB_ERR_PARAM; il canale mantiene il modello precedente. Per l'insieme completo di codici accettati per classe vedi 03 · Selezione del sensore di corrente.
Per i moduli multicanale usi la forma per canale qui sotto.
bool setCTModel(RbAmpCTModel model) noexcept
Overload con enumerazione tipizzata per i sette codici SCT-013 (RbAmpCTModel::Sct013_030 …). Equivale a setCTModel(static_cast. Mantenuto per compatibilità con le versioni precedenti; il codice nuovo passa una define RBAMP_CT_* generata alla forma uint8_t, che è l'unico modo per nominare un modello TA cablato.
bool setCTModel(uint8_t channel, uint8_t code) noexcept
Impostazione della classe del sensore e del modello CT (initialization) · 6.2 Associazione del modello CT — pura predisposizione + CMD per canale (api-reference)
La forma per canale. Imposta il modello della pinza CT su uno specifico canale, 0 .. channels()-1 (i canali 3 e superiori sono i canali dello SKU di fascia alta; richiedono il firmware BASIC v1.4.18 o successivo).
In pratica: scrive REG_CT_MODEL (0x05) → comando CMD_SET_CT_MODEL_CH0/1/2 (opcode 0x28/0x29/0x2A) in base a channel → assestamento di 5 ms → CMD_SAVE_USER_CONFIG (opcode 0x32) → 700 ms. Adatto alla produzione — il percorso di salvataggio della configurazione utente è il canale di persistenza di produzione per ct_model / sensor_class / TA per canale. I canali 3 e superiori vengono associati tramite la finestra dei canali e riletti; un modello che il modulo rifiuta viene segnalato come RB_ERR_PARAM. Sul firmware precedente alla v1.2 la chiamata restituisce RB_ERR_VERSION.
L'ordine delle chiamate è arbitrario sulla v1.3. Scrivere REG_CT_MODEL (0x05) si limita a predisporre un valore — non viene applicato automaticamente al canale 0. L'applicazione avviene esclusivamente tramite l'opcode per canale CMD_SET_CT_MODEL_CHn (0x28 / 0x29 / 0x2A), che copia il valore predisposto nel proprio canale. I canali possono quindi essere configurati in qualsiasi ordine — crescente, decrescente o intercalato — senza sovrascritture:
dev.setCTModel(0, RBAMP_CT_SCT013_005); // channel 0
dev.setCTModel(1, RBAMP_CT_SCT013_030); // channel 1
dev.setCTModel(2, RBAMP_CT_SCT013_020); // channel 2
Dopo un'associazione multicanale, confermi il risultato con readCTModelCh(). Per una configurazione in batch con un solo salvataggio di tutti i canali, preferisca configureChannels().
Guardia RB_ERR_PARAM sulla precondizione di setSensorClass(), come nella forma a singolo parametro. Un canale pari o superiore a channels() (e quindi qualsiasi canale oltre RBAMP_MAX_CHANNELS) → RB_ERR_PARAM. Si applicano la lettura-prima-della-scrittura e il rifiuto RB_ERR_MODE come descritto sopra. Sulla linea STD il modello è un'etichetta scritta nella voce del canale, riletta e resa persistente con il salvataggio della configurazione del modulo; nessun effetto collaterale sul canale 0.
Restituisce: true in caso di successo, oppure quando il canale contiene già code.
bool setCTModel(uint8_t channel, RbAmpCTModel model) noexcept
Forma overload tipizzata con enum della forma per canale (solo codici SCT-013).
bool setCTModelChForce(uint8_t channel, uint8_t code) noexcept
Percorso di assistenza. Come setCTModel(channel, code), ma scrive indipendentemente dalla classe del modulo e dal modello che il canale possiede già. Sostituisce la calibrazione accoppiata di quel canale con il preset generico del modello — usarlo solo per riaccoppiare un modulo con un nuovo sensore in assistenza, e seguire con una calibrazione. Un codice assente dal registro viene comunque rifiutato (RB_ERR_PARAM, nessuna scrittura).
Restituisce: true in caso di successo.
bool readCTModelCh(uint8_t channel, uint8_t& out) noexcept
4.7 Specchi di verifica del modello TA (0x51..0x53) (riferimento API) · 8.10 Rilettura dello specchio di verifica del modello TA (controllo di sanità dopo l'associazione) (riferimento API)
Legge il modello CT effettivamente applicato a un canale (lo specchio di verifica del preset associato). Usarlo per confermare che un'associazione sia andata a buon fine. out = 0 significa non impostato.
Restituisce: true in caso di successo.
Registro dei sensori — sensorModel() / sensorModelRatedA()
Semplici ricerche nel registro generato (RbAmpSensorModels.h). Nessun traffico sul bus. Una corrispondenza nel registro non significa che il modulo collegato accetti il codice — la decisione spetta al modulo al momento della scrittura.
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(uint8_t cls, uint8_t code) noexcept;
static const rbamp_sensor_model_info_t* RbAmp::sensorModel(RbAmpSensorClass cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(uint8_t cls, uint8_t code) noexcept;
static float RbAmp::sensorModelRatedA(RbAmpSensorClass cls, uint8_t code) noexcept;
sensorModel() restituisce la voce del registro oppure nullptr se (class, code) non è nel registro. La voce (rbamp_sensor_model_info_t) contiene sensor_class, code, name, descriptor, status (caratterizzato / riservato / legacy) e i limiti attuali nominal_a (corrente efficace nominale), fs_a (corrente efficace all'inizio della saturazione per un sinusoide) e peak_a (soglia di saturazione istantanea). 0 in un limite = non noto per quel modello.
sensorModelRatedA() restituisce la corrente efficace nominale in ampere (0 = non nota). Copre la famiglia SCT-013 e i modelli di pinza che riportano una portata; i toroidi / codici di carico legacy restituiscono 0.
float rated = RbAmp::sensorModelRatedA(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
const rbamp_sensor_model_info_t* m = RbAmp::sensorModel(RbAmpSensorClass::Sct013, RBAMP_CT_SCT013_030);
if (m) Serial.println(m->descriptor);
Correzione della portata SCT-013
Sui firmware BASIC fino alla 1.4.19 un modulo di classe SCT-013 viene calibrato sull'SCT-013-030 e, dopo un riavvio, applica quel guadagno calibrato qualunque sia il modello indicato da un canale. La libreria compensa: begin() legge il modello e il guadagno applicato di ciascun canale e imposta una scala per canale. La scala viene applicata a readCurrent(), readCurrentPeak(), readPower(), readAll(), readPeriodAvgPower(), readPeriodMaxPower() e readPeriodSnapshot() — e quindi all'energia ricavata da essi. Fattore di potenza e tensione non vengono toccati. I limiti di plausibilità e setEventThresholds() sono espressi in ampere e watt reali.
Quindi cambiare la portata SCT-013 (ad esempio da 030 a 050) corregge automaticamente corrente, potenza ed energia; non cambia U né PF. Il firmware 1.4.20 e successivi si correggono da soli — la scala resta 1 e la scrittura del modello non richiede riavvio. I moduli STD e le classi CT cablate / integrate non vengono mai scalati.
bool sctRatingRefresh() noexcept
Rilegge lo stato di valutazione di ogni canale dal modulo. La libreria lo fa già dopo che readEventFlags() segnala EVENT_RESET_OCCURRED; chiamarla manualmente dopo un riavvio del modulo rilevato in altro modo.
Restituisce: true quando il modulo è stato letto.
bool sctRating(uint8_t channel, RbAmpSctRating& out) noexcept
Stato di un canale: model, applied_gain, noise_floor, scale e status.
Restituisce: true se channel è valido.
RbAmpSctRatingStatus |
Significato |
|---|---|
NotApplicable |
linea STD, una classe diversa da SCT-013, firmware che si corregge da solo, oppure nessun modello impostato — scala 1 |
Native |
il canale mostra il modello su cui il modulo è stato calibrato (030) — niente da correggere, scala 1 |
Corrected |
un altro modello SCT-013 su firmware BASIC più vecchio — le letture sono scalate |
Uncalibrated |
il modulo applica un preset generico senza una propria taratura — solo correzione nominale |
UnexpectedGain |
il guadagno applicato non è quello che si aspetta la correzione — non si presume nulla, scala 1 |
Unknown |
lo stato non ha potuto essere letto — scala 1 |
float sctRatingScale(uint8_t channel) const noexcept
Il fattore applicato alle letture di corrente / potenza di quel canale (1.0 quando non c'è correzione, e per un indice di canale oltre RBAMP_MAX_CHANNELS).
static float sctPresetGain(uint8_t model) noexcept
Il valore di guadagno predefinito della libreria per un codice modello SCT-013; 0 se sconosciuto. Utile soprattutto per la diagnostica.
bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept
Vedi Configurazione multi-canale.
bool saveGains() noexcept — solo modalità fabbrica su BASIC
Una scrittura "nuda" di CMD_SAVE_GAINS (0x26) — il percorso di persistenza di fabbrica per i coefficienti di calibrazione (guadagni / rumore di fondo / fase).
⚠ Solo fabbrica sul BASIC. BLOCCATO in produzione. Su un modulo BASIC di produzione CMD_SAVE_GAINS viene rifiutato dal firmware — la chiamata restituisce false, REG_ERROR viene impostato su DEV_ERR_PARAM (0xFE), e il riavvio successivo annulla le scritture solo in RAM. Per ogni persistenza rivolta all'utente (classe del sensore, modello TA per canale, indirizzo, configurazione della flotta, etichetta) usi saveUserConfig() (CMD_SAVE_USER_CONFIG, opcode 0x32) — questo è il percorso di persistenza adatto alla produzione. Il codice utente in un contesto di distribuzione non dovrebbe chiamare saveGains().
Linea STD: saveGains() emette il salvataggio di calibrazione del modulo, attende che il modulo segnali il comando terminato e verifica il suo verdetto. Il modulo scrive il suo archivio al massimo una volta ogni 5 s; un salvataggio entro quella finestra viene ritentato una volta dopo 5 s.
Restituisce: true per un comando riuscito (produzione BASIC: sempre false con RB_ERR_MODE).
bool prepareAddressChange(uint8_t new_addr) noexcept
Cambio di indirizzo (inizializzazione) · 4.5 Indirizzo (0x30..0x31) (riferimento API) · 6.1 Cambio di indirizzo — commit in due fasi (adatto alla produzione) (riferimento API)
Passo 1 di 2 per cambiare l'indirizzo I²C del modulo. OK per la produzione sul firmware attuale (commit in due fasi v1.3, nessun vincolo di modalità fabbrica per l'indirizzo).
Sequenza: valida l'intervallo di new_addr (0x08..0x77, ≠ attuale) → scrive il candidato in REG_I2C_ADDRESS (0x30) in RAM → scrive il magic 0xA5 in REG_ADDR_COMMIT_MAGIC (0x31) — armato. Il chiamante deve chiamare commitAddressChange() entro 5 secondi, altrimenti l'armamento scade.
Restituisce: true se armato con successo.
bool commitAddressChange() noexcept
Cambio di indirizzo (initialization) · 6.1 Cambio di indirizzo — commit in due fasi (OK per la produzione) (api-reference) · 8.5 Cambio di indirizzo in 5 passi (api-reference)
Passo 2 di 2. Deve essere chiamato entro 5 secondi da prepareAddressChange().
Sequenza: verificare la freschezza dello stato armato con magic → CMD_COMMIT_ADDR (opcode 0x30) → salvare in flash → CMD_RESET (0x01) → ~300 ms dall'avvio alla risposta → aggiornare il campo indirizzo interno. Da questo momento tutte le chiamate su questa istanza indirizzano il nuovo indirizzo.
⚠ Re-enumerazione dopo il commit. Dopo un commit riuscito il dispositivo si riavvia e si ri-enumera al NUOVO indirizzo. Le chiamate successive su questa istanza RbAmp indirizzano il nuovo indirizzo in modo trasparente — ma qualsiasi ALTRO master sul bus (uno script Python, un componente ESP-IDF su un altro MCU, una sonda di debug) continuerà a credere che il dispositivo sia all'indirizzo vecchio finché il suo stato interno non viene aggiornato a mano.
⚠ Percorso di verifica (v1.3): dopo il riavvio REG_I2C_ADDRESS (0x30) legge l'indirizzo attivo. Anche una scansione del bus al nuovo indirizzo conferma il commit.
Il cambio di indirizzo è un'operazione di produzione (non riservata alla fabbrica). Il percorso documentato per l'indirizzo I²C è la riconfigurazione tramite il banco di fabbrica (fuori dall'ambito della libreria).
Una nota aggiuntiva per commitAddressChange():
⚠ Riavvio e ri-enumerazione dopo il commit. Dopo un commit riuscito il dispositivo si riavvia e si ri-enumera al NUOVO indirizzo. Le chiamate successive su questa istanza RbAmp indirizzano il nuovo indirizzo in modo trasparente — ma qualsiasi ALTRO master sul bus (uno script Python, un componente ESP-IDF, una sonda di debug) continuerà a credere che il dispositivo sia all'indirizzo vecchio finché il suo stato interno non viene aggiornato a mano.
Se la finestra di armamento è scaduta, commitAddressChange() restituisce false con RB_ERR_TIMEOUT e azzera il flag di armamento — sarà necessaria una nuova chiamata a prepareAddressChange().
Restituisce: true in caso di successo.
Linea STD: il campo indirizzo viene scritto e salvato (la chiamata attende la fine del salvataggio; un indirizzo respinto restituisce RB_ERR_PARAM e il modulo mantiene il suo indirizzo), poi il modulo viene resettato. L'istanza passa al nuovo indirizzo solo quando il modulo risponde lì (fino a 3 s). Se torna invece sul VECCHIO indirizzo, l'istanza resta lì e viene restituito RB_ERR_NOT_READY.
bool factoryReset() noexcept
Il comando CMD_FACTORY_RESET (0xAA) + attesa di 1500 ms.
⚠ Operazione distruttiva. Cancella TUTTI i parametri in flash (modello TA, classe del sensore, coefficienti di calibrazione, indirizzo I²C). Il modulo torna ai valori di fabbrica — RbAmpSensorClass diventa Unset, REG_CT_MODEL diventa 0. Ogni impostazione applicata in precedenza tramite setSensorClass() / setCTModel() va persa. Il prossimo utente DEVE riapplicare sia setSensorClass() sia setCTModel() prima che la misura riprenda a funzionare. Non è un "riavvio morbido" — per un riavvio morbido usi reset(). factoryReset() è riservato al recupero da uno stato noto come errato o al passaggio del modulo a un altro utente / altra installazione.
Restituisce: true alla scrittura riuscita del comando.
Linea STD: non esiste un equivalente — la chiamata restituisce false con RB_ERR_NOT_IMPLEMENTED.
bool reset() noexcept
Il comando CMD_RESET (0x01) + attesa di 100 ms. Un riavvio a caldo del dispositivo senza perdere i parametri in flash.
Restituisce: true alla scrittura riuscita del comando.
Linea STD: attende prima qualsiasi comando in corso (un modulo non viene mai resettato a metà di un salvataggio), poi attende in silenzio (fino a 3 s) che il modulo risponda di nuovo e riarma il percorso di periodo.
Bus multi-modulo (statico)
static bool broadcastLatch(TwoWire& bus) noexcept
Invia uno snapshot broadcast I²C General-Call (A5 27 00 tick_lo tick_hi all'indirizzo 0x00) — tutti i moduli con GC abilitato eseguono contemporaneamente lo snapshot del periodo. Sul firmware v1.3 il GC è supportato come capacità opt-in: abilitazione per modulo tramite REG_FLEET_CONFIG.bit0 (azzerato per impostazione predefinita); la mappa delle capacità del modulo indica se supporta lo snapshot General-Call. Il General-Call è una funzione della linea BASIC (le funzioni General-Call e di etichetta restituiscono RB_ERR_NOT_IMPLEMENTED su un'istanza STD).
Semantica del ritorno:
-
Firmware v1.3, GC attivo su almeno un modulo — restituisce
true, la flotta prende lo snapshot in sincronia (scarto < 1 ms tra i moduli). -
Firmware v1.3, GC disattivato su tutti i moduli —
Wire.endTransmission()verso0x00riceve NACK a livello di bus → restituiscefalse. Correzione: abiliti il GC su ciascun modulo conenableGc(true)(scriveFLEET_CONFIG.bit0+SAVE_USER_CONFIG+ reset), oppure usiRbAmpFleet::enableGcAll(). -
Firmware legacy senza supporto General-Call — restituisce
falsesenza toccare il bus. Ripiegare su una serie sequenziale dilatchPeriod()su ogni dispositivo — vedi 06 · Esempi, la sezione sul bus multi-modulo.
Diagnostica
int8_t lastError() const noexcept
Restituisce: il codice dell'ultimo errore — RB_OK (0) oppure uno dei valori RB_ERR_* (negativi). La tabella completa è nella sezione "Codici di errore" qui sotto + 10 · Risoluzione dei problemi.
static const char* errorString(int8_t code) noexcept
Restituisce: una stringa costante con una descrizione leggibile del codice di errore. Non restituisce mai NULL.
void setLogStream(Stream* stream) noexcept
Un canale di diagnostica opzionale. Se impostato, la libreria registra brevemente i risultati di probe(), gli snapshot non aggiornati e i rifiuti di modalità. Passare nullptr per disattivarlo. Disattivato per impostazione predefinita.
Uso tipico:
dev.setLogStream(&Serial);
uint32_t retryExhaustionCount() const noexcept
Quante volte dall'accensione (o dall'ultimo resetCounters()) il ciclo di ripetizione si è esaurito durante una singola lettura di un byte. Il valore in regime stazionario è 0. Un valore diverso da zero indica problemi di collegamento (vedere 10 · Risoluzione dei problemi).
uint32_t sanityRejectCount() const noexcept
Quanti valori float grezzi sono stati scartati dal filtro di sanità (!isfinite(x) || |x| > 10000). In regime stazionario — 0. Un valore diverso da zero dopo la mitigazione con ripetizioni di solito indica un raro artefatto dello stack I²C di ESP-IDF sopravvissuto al livello di ripetizione.
void resetCounters() noexcept
Azzera entrambi i contatori. Lo usi all'inizio di un test di durata o di una finestra di regressione per misurare solo gli eventi nella finestra.
const char* errorString() const noexcept
Scorciatoia d'istanza per errorString(lastError()). Non restituisce mai NULL.
bool readCommitSeq(uint8_t& out) noexcept — solo BASIC
Legge il byte di sequenza di commit del modulo. Il modulo lo incrementa una volta per ogni finestra di misura pubblicata (100 ms sul firmware v1.2+, 200 ms prima), con ritorno 255→0. Lo campioni prima e dopo una lettura di più registri per rilevare se i valori pubblicati sono avanzati a metà lettura. È solo un flag di variazione — non c'è CRC. Su un'istanza STD la chiamata fallisce con RB_ERR_NOT_IMPLEMENTED (usi readDataSeq()).
Restituisce: true in caso di successo.
Identificazione e provisioning (v1.3)
Questi metodi permettono al master di capire esattamente che cosa è collegato al bus (variante, mappa dei bit di capacità, UID, etichetta) e di preparare un modulo nuovo o appena flashato al funzionamento (provisioning + salvataggio della configurazione in flash).
RbAmpVariant readVariant() noexcept
Rilevamento automatico della variante del modulo (initialization) · Riferimento del protocollo di filo rbAmp (v1.3) (api-reference) · 3.6 Algoritmo di rilevamento canonico (api-reference)
Legge il registro HW_VARIANT (0x55) del modulo e restituisce un RbAmpVariant:
| Valore | SKU | canali I | Canale U |
|---|---|---|---|
UI1 (1) |
UI1 | 1 | sì |
UI2 (2) |
UI2 | 2 | sì |
UI3 (3) |
UI3 | 3 | sì |
I1 (4) |
I1 | 1 | no |
I2 (5) |
I2 | 2 | no |
I3 (6) |
I3 | 3 | no |
UI5 (7) |
UI5 (SKU di fascia alta) | 5 | sì |
UI7 (8) |
UI7 (SKU senior) | 7 | sì |
Unknown (0) |
non identificato (firmware v1.0/v1.1, un guasto I²C, o non un rbAmp) | — | — |
Il rilevamento automatico della variante tramite readVariant() è il percorso raccomandato. Il suggerimento di topologia del costruttore resta come ripiego per il firmware precedente alla v1.2 (dove HW_VARIANT non è disponibile). Suggerimento predefinito = RbAmpTopology::Single — sicuro, non provoca letture spurie di canali assenti su UI1/I1.
bool readCapability(uint16_t& out) noexcept — solo BASIC
Rilevamento automatico della variante del modulo (inizializzazione) · 3.2 CAPABILITY (registri 0x57/0x58, u16 LE, sola lettura) (riferimento API) · 8 · Esempi di tracce sul filo (riferimento API)
Legge la mappa delle funzioni a 16 bit del modulo. Ramificare sulle costanti di capacità con nome di RbAmpRegistersV2.h (namespace rbamp::v2), mai su euristiche di versione del firmware. Tra l'altro la mappa indica se il modulo ha un front-end di tensione — se non ce l'ha, non calcola P / PF / energia e quei valori leggono 0 — e se supporta lo snapshot broadcast General-Call (vedi broadcastLatch()). Su un'istanza STD la chiamata restituisce false con RB_ERR_NOT_IMPLEMENTED; usare stdInfo() in quel caso.
uint8_t readProductId() noexcept
3.5 PRODUCT_ID (0x54, u8, sola lettura) (api-reference) · 4.8 Identità (0x54..0x6F) (api-reference)
Legge PRODUCT_ID (0x54) — l'identificatore byte della famiglia (sensore rbAmp = 0x01, rbDimmer = 0x02; 0 in caso di errore). Usato dallo scanner della flotta per confermare che il dispositivo a un indirizzo sia davvero un rbAmp e non un altro slave I²C che ha risposto allo stesso indirizzo. Un'istanza STD riporta la famiglia del sensore.
bool readUid(uint8_t uid[12]) noexcept
Legge l'identificatore unico a 96 bit del microcontrollore da UID (0x5C..0x67) in un'unica operazione a raffica. L'UID è garantito unico per ogni modulo e non cambia al re-flash — comodo per i log seriali, i controlli anti-clone lato master e l'identificazione quando un modulo viene sostituito in una flotta installata. Funziona su entrambe le linee.
bool readLabel(char out[9]) noexcept — solo BASIC
8.3 Scrittura multi-byte — LABEL un byte alla volta (api-reference)
Legge l'etichetta utente di 8 byte da LABEL (0x68..0x6F). ASCII, con riempimento di zeri; il risultato termina sempre con null (un array di 9 byte = 8 byte di dati + il terminatore \0). Etichetta vuota = non impostata.
bool writeLabel(const char* label) noexcept — solo BASIC
8.3 Scrittura multi-byte — LABEL un byte alla volta (api-reference)
Scrive l'etichetta di 8 byte. Accetta una stringa terminata da null — i byte in eccesso vengono troncati, quelli mancanti vengono riempiti con zeri. La scrittura avviene byte per byte per le scritture multibyte (il protocollo a filo di rbAmp incrementa automaticamente le letture dei registri in modalità raffica, ma non le scritture — vedere Dettagli del protocollo sul filo più sotto; il ciclo di byte lo fa la libreria). Dopo la scrittura serve dev.saveUserConfig() perché l'etichetta sopravviva a un reset.
Un modulo appena uscito dalla fabbrica può segnalare l'errore 0xFB (DEV_ERR_FLASH_PARAMS_BAD) al primo avvio: il blocco di configurazione utente è ancora vuoto. È normale (non fatale); saveUserConfig() lo cancella. Non interrompere il provisioning alla prima comparsa di 0xFB.
bool saveUserConfig() noexcept
6.5 Provisioning — flash nuova + SAVE (riferimento API) · 8.6 Provisioning da flash nuova (riferimento API)
Emette CMD_SAVE_USER_CONFIG (opcode 0x32) — salva il blocco di configurazione utente nella flash: SENSOR_CLASS, CT_MODEL per canale, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Non salva i parametri di calibrazione di fabbrica — quelli stanno sotto un CMD_SAVE_GAINS separato, bloccato in modalità produzione.
Blocca il thread per ~700 ms (ciclo di cancellazione e scrittura della flash). Durante la chiamata non tentare di accedere al modulo da altri task.
Linea STD: emette il salvataggio della configurazione del modulo (classe, riferimento TA, livello, indirizzo I²C; la calibrazione viene conservata), attende che il modulo segnali il comando terminato (senza pausa fissa) e verifica il verdetto — un campo non valido (ad esempio un indirizzo fuori intervallo) restituisce RB_ERR_PARAM. Un salvataggio entro il limite di frequenza di 5 s del modulo viene ritentato una volta dopo 5 s.
: confermare che un valore è stato scritto in flash richiede un riavvio + una rilettura. Vedi la sezione "modello di errore v1.3" più sotto.
Modello di errore v1.3 — due canali indipendenti
Gli errori hanno due canali indipendenti che funzionano in modo diverso. Capire la differenza è essenziale per interpretare correttamente lo stato del modulo.
| Canale A — lato client, sincrono | Canale B — lato DUT, asincrono durevole | |
|---|---|---|
| Dove risiede | Validazione all'interno della libreria (libreria Arduino) | REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A) |
| Quando scatta | Prima della transazione I²C (la libreria la interrompe) | Dopo che il FW ha accettato la scrittura e l'ha rifiutata |
| Cosa vede il master | il setter restituisce false + lastError() == RB_ERR_PARAM; REG_ERROR sul dispositivo resta 0x00 |
REG_ERROR = il codice di guasto immediatamente; bit3 si blocca alcune centinaia di millisecondi dopo la transazione |
| Persistente | no (solo un valore booleano di ritorno) | Ultima scrittura di REG_ERROR; bit3 sticky W1C |
| Percorso tipico | Un argomento fuori dai limiti consentiti (canale ∉ {0,1,2}, codice ∉ l'insieme caratterizzato, sensor_class fuori dall'enum) | Una scrittura grezza di registro che la libreria non pre-valida (uso a basso livello di writeReg() con una maschera non valida) |
Canale A — validazione lato client (setter della libreria)
Tutti i setter della libreria (setSensorClass, setCTModel, setCTModel(ch, code), configureChannels, ecc.) verificano prima gli argomenti rispetto ai valori ammessi. Se un argomento è fuori intervallo, il setter restituisce false e imposta lastError() == RB_ERR_PARAM, senza eseguire alcuna transazione I²C. Di conseguenza REG_ERROR sul dispositivo non viene toccato:
if (!dev.setCTModel(/*ch=*/99, /*code=*/3)) { // client-side guard
Serial.print(F("rejected: "));
Serial.println(dev.lastError()); // RB_ERR_PARAM (lib cached)
uint8_t reg_err = dev.readLastError(); // device REG_ERROR byte
Serial.println(reg_err, HEX); // 0x00 — REG_ERROR untouched
}
lastError() vs readLastError() — due canali diversi, non sinonimi. lastError() restituisce il codice RB_ERR_* memorizzato nella libreria dalla chiamata precedente — senza alcuna operazione I²C. readLastError() esegue una singola lettura sul filo del registro REG_ERROR (0x02) del dispositivo — l'esito dell'ultima scrittura lato firmware. Nel Canale A (sopra), lastError() = RB_ERR_PARAM mentre readLastError() = 0x00 (la libreria non ha mai raggiunto il filo — REG_ERROR non toccato). Nel Canale B (sotto) entrambi mostreranno un codice, ma in modo diverso: lastError() — l'ultima semantica della libreria in cache; readLastError() — il valore esatto del byte REG_ERROR in questo momento.
Quindi: se si vuole sapere esattamente perché un setter ha rifiutato, la fonte affidabile è il codice di ritorno della funzione + lastError(). REG_ERROR sul dispositivo non dirà nulla in questo scenario.
Canale B — rifiuto lato DUT (asincrono durevole)
Se la scrittura è passata via I²C (la libreria non l'ha bloccata perché l'argomento sembrava valido) ma il firmware l'ha rifiutata, entra in gioco il secondo canale:
-
readLastError()contiene immediatamente il codice di motivo (ad esempio0xFE = DEV_ERR_PARAM). È l'esito dell'ultima scrittura: qualsiasi successiva scrittura riuscita lo sovrascriverà. Va letto immediatamente dopo la scrittura, prima di qualsiasi altra transazione. -
hasError(out)— l'indicatore W1C persistenteEVENT_FLAGS.bit3. Non si attiva istantaneamente: al banco è stato misurato un ritardo di alcune centinaia di millisecondi tra la transazione fallita e l'impostazione di bit3. Subito dopo la scrittura bit3 è ancorafalse; dopo 300 ms ètrue. Da quel momentobit3resta stabile su qualsiasi numero di letture.
⚠ Non usi hasError() per validare una scrittura appena effettuata. Per l'esito di questa specifica scrittura è affidabile solo readLastError(), letto subito dopo la scrittura prima di qualsiasi altra transazione (più il codice di ritorno del setter, se ne ha uno). hasError() è un canale asincrono per un monitoraggio a interrogazione del tipo "qualcosa è andato in errore tra due controlli", non per una validazione sincrona.
Cancellare un errore durevole — cancellare entrambi (REG_ERROR e bit3)
bit3 viene ripreso dal firmware ogni poche centinaia di millisecondi dallo stato attuale di REG_ERROR. Quindi un semplice clearEventFlags(1 << 3) non funzionerà — bit3 verrà immediatamente reimpostato dal REG_ERROR non ancora cancellato. L'ordine corretto: prima clearError() (cancella REG_ERROR), poi clearEventFlags(1 << 3) (cancella il latch persistente). Se vuole l'atomicità — non ci deve essere alcuna scrittura respinta tra i due.
uint8_t readLastError() noexcept
3. DATA_VALID (0xCE) non diventa mai 1 (troubleshooting) · Codici di errore (REG_ERROR = 0x02) (troubleshooting) · 4 · Mappa dei registri (produzione v1.3) (api-reference)
Legge direttamente il registro REG_ERROR (0x02) del dispositivo (una singola lettura sul filo; restituisce 0x00 per OK, 0xFA..0xFF per una classe di errore, e 0xFF se la lettura I²C stessa è fallita) — l'esito dell'ultima transazione accettata con successo dal bus (una scrittura o un comando). Non persistente: ogni successiva scrittura riuscita lo sovrascrive con il proprio esito. Usato nel Canale B (rifiuto lato DUT) per il codice di motivo esteso. Sulla linea STD il verdetto del comando è già mappato su lastError() (vedi API della linea STD).
Da non confondere con lastError(): è un metodo diverso, che restituisce il RB_ERR_* memorizzato in cache dalla chiamata precedente della libreria senza alcuna operazione I²C. Vedi il riquadro nel Canale A sopra.
bool hasError(bool& out) noexcept
Un helper di comodo sopra EVENT_FLAGS.bit3. Restituisce true in out se bit3 è impostato. W1C persistente; non viene azzerato finché non c'è un azzeramento esplicito (con un'avvertenza — vedi la sezione "Cancellare un errore durevole" sopra).
bool readEventFlags(uint8_t& out) noexcept / bool clearEventFlags(uint8_t mask) noexcept
EVENT_FLAGS (0x2A) — un byte di flag persistenti; i bit specifici sono descritti nella specifica (incluso ERROR_OCCURRED bit3). L'azzeramento è write-1-to-clear: scrivere una maschera con uno nei bit da reimpostare.
bool clearError() noexcept
Codici di errore (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recupero dallo stato di errore — albero decisionale (api-reference)
Emette CMD_CLEAR_ERROR (opcode 0x31) — azzera REG_ERROR. Necessario per cancellare un errore durevole, insieme a clearEventFlags(1 << 3) (vedi sopra). Senza clearError(), un semplice clearEventFlags(1 << 3) lascerà bit3 a true dopo alcune centinaia di millisecondi a causa del nuovo latch.
Configurazione multi-canale (v1.3)
Su moduli multi-canale ogni canale di corrente ha il proprio modello di sensore CT. L'utility atomica per la configurazione in blocco è configureChannels().
bool configureChannels(RbAmpSensorClass cls, const uint8_t* models, uint8_t n) noexcept
Parameters:
-
cls— la classe del sensore, applicata per prima. ConRbAmpSensorClass::Sct013i modelli vengono associati; una richiesta di associare modelli sottoWiredCT/BuiltinCTviene respinta subito (false,RB_ERR_MODE, nulla scritto). -
models— un array dincodici di modello TA (defineRBAMP_CT_*generate), uno per canale.0lascia invariato il modello esistente di quel canale. -
n— la lunghezza dell'array. Limitato achannels(): gli elementi extra dell'array vengono ignorati. Senè minore, i canali mancanti non vengono modificati (mantengono il modello precedente).
Internamente la funzione esegue:
setSensorClass(cls)una volta.- Per ogni canale
k < min(n, channels): predisporreREG_CT_MODEL = models[k]+CMD_SET_CT_MODEL_CHk. - Un salvataggio finale del terminale — un solo ciclo di cancellazione e scrittura della flash per l'intera configurazione invece di uno per canale (circa 3 volte meno cicli di usura su tre canali).
Vale la regola lettura-prima-della-scrittura: una classe o un modello già presenti nel modulo non vengono riscritti, quindi riapplicare la stessa configurazione costa solo letture e nessun ciclo di flash. Su firmware BASIC fino a 1.4.19 con classe SCT-013, il modulo viene riavviato dopo il salvataggio (vedi Configurazione del sensore).
Return:
true— la configurazione è stata applicata e salvata (o era già presente).-
false+lastError() == RB_ERR_PARAM— unclsnon valido o unmodels[k]non presente nel registro (validazione lato client, vedere "Modello di errore" sopra); il batch viene interrotto. -
false+RB_ERR_MODE— il modulo è di una classe accoppiata in fabbrica. false+ altri codici — errore del bus, timeout, ecc.
Codici accettati per SCT_013: {1, 2, 3, 4, 5, 6, 7} (SCT-013-005, -010, -030, -050, -100, -020, -060). Dettagli — 03 · Selezione del sensore di corrente.
bool readCTModelCh(uint8_t ch, uint8_t& out) noexcept
Legge il modello di sensore TA applicato (specchio di verifica) su un canale specifico. È una rilettura dalla RAM, non una conferma della persistenza — per confermare un salvataggio in flash usi dev.reset() + una rilettura dello specchio.
Linea di data-ready ed eventi
Entrambe le linee. L'uscita DRDY del modulo è a drain aperto, HIGH a riposo (pull-up dell'host), e genera un impulso LOW ogni volta che viene pubblicato un nuovo snapshot completo — una volta per finestra di misura (100 ms). Più moduli possono condividere una linea (wired-OR). Un modulo la cui condizione mascherata è in attesa tiene la linea fissa a LOW (livello di allarme) finché i flag non vengono cancellati. Sulla linea STD il blocco eventi esiste sui moduli la cui immagine lo prevede; su BASIC dal firmware v1.3. Dettagli hardware — 04 · Cablaggio.
bool setDrdyPin(int pin) noexcept
01 · Connessione hardware (hardware-connection) · 03 · Polling in tempo reale (realtime-polling)
Colleghi la linea DRDY di questo modulo (oppure la stacchi con pin < 0). Configura il pin come ingresso con la pull-up interna e un interrupt sul fronte di discesa; l'ISR si limita a contare e a marcare temporalmente il fronte — nessun traffico sul bus lì. Fino a 4 linee distinte e 8 moduli per linea. Un modulo STD la cui immagine non supporta il contratto data-ready rifiuta con RB_ERR_NOT_IMPLEMENTED; waitDataReady() interroga allora la sequenza. Senza una linea, anche waitDataReady() interroga.
bool waitDataReady(uint32_t timeout_ms, RbAmpDrdyEvent* ev = nullptr) noexcept
01 · Connessione hardware (hardware-connection) · 03 · Polling in tempo reale (realtime-polling)
Si blocca finché questo modulo non pubblica un nuovo snapshot (o un allarme), al massimo per timeout_ms (0 = un unico controllo non bloccante).
Con una linea: attende il fronte, poi conferma che è di questo modulo tramite il numero di sequenza del suo snapshot (un impulso proveniente da un altro modulo su una linea condivisa viene ignorato). Se la linea è ancora BASSA poco dopo il fronte, qualche modulo su di essa ha un allarme attivo: vengono letti e azzerati i flag di ogni modulo in grado di generare allarmi sulla linea; i flag di questo modulo tornano in ev, quelli degli altri sono memorizzati sulle loro istanze e riportati alla successiva attesa. Senza linea interroga il sequence ogni RBAMP_DRDY_POLL_MS (predefinito 20 ms; definirlo prima di includere la libreria per sovrascriverlo).
Restituisce: true con ev compilato; false con RB_ERR_TIMEOUT quando non è arrivato nulla, RB_ERR_NOT_IMPLEMENTED su un modulo STD la cui immagine non ha un contatore di pubblicazione.
bool readAllReady(uint32_t timeout_ms, RbAmpSnapshot& out, RbAmpDrdyEvent* ev = nullptr) noexcept
waitDataReady() seguito da readAll(), così l'intera lettura cade in una sola finestra di pubblicazione: lo snapshot non viene mai letto due volte e non attraversa una pubblicazione.
bool readDataSeq(uint16_t& out) noexcept
La sequenza di snapshot del modulo — il contatore di pubblicazione su STD, il byte di sequenza di commit su BASIC. Serve solo per rilevare le variazioni.
uint8_t beginEventFlags() const noexcept
I flag di evento così come begin() li ha trovati, prima che la libreria scrivesse qualcosa. EVENT_RESET_OCCURRED qui significa che il modulo si è riavviato prima che questa istanza lo incontrasse. Nessun accesso al bus.
bool readEventMask(uint8_t& out) noexcept / bool setEventMask(uint8_t mask) noexcept
Legge / imposta quali bit di evento tengono DRDY a LOW (bit rbamp::v2::EVENT_*). setEventMask() verifica con una rilettura. La maschera vive nella RAM del modulo: la riapplichi dopo un reset del modulo (EVENT_RESET_OCCURRED lo segnala).
bool setEventThresholds(float i_amps, float p_watts) noexcept
4.4 Configurazione della flotta (0x27..0x2F) (api-reference) · 8.8 Flusso degli eventi di soglia — scrittura della soglia → attivazione → azzeramento W1C (api-reference)
Impostare le soglie di corrente / potenza che governano EVENT_THRESH_I / EVENT_THRESH_P; un valore <= 0 disattiva quella soglia. RAM sul modulo.
-
BASIC confronta la corrente massima di canale e la somma con segno delle potenze di canale — l'esportazione non lo fa mai scattare.
-
STD confronta la corrente di qualsiasi canale e la grandezza della potenza totale — indipendente dalla direzione.
Gli eventi di soglia sono bloccati a livello (ripristinati ad ogni finestra finché la condizione è vera): abbassare la soglia prima di aspettarsi una linea silenziosa.
readEventFlags() / clearEventFlags() / hasError() sono descritte sotto Modello di errore.
RbAmpDrdyEvent
struct RbAmpDrdyEvent {
bool fresh; // a new snapshot of THIS module is available
bool by_edge; // woken by the DRDY edge (false = found by polling)
uint16_t seq; // snapshot sequence now
uint16_t missed; // snapshots published since the previous call that were not read
bool alarm; // the line was held LOW (masked event pending on this module)
uint8_t event_flags; // event flags consumed from this module on an alarm, else 0
uint32_t latency_us; // edge to return, µs (0 when polling)
};
RbAmp dev(Wire, 0x50);
...
dev.setDrdyPin(15); // optional: omit to poll
dev.setEventThresholds(0, 3000); // power threshold, W
dev.setEventMask(rbamp::v2::EVENT_THRESH_P);
RbAmpSnapshot snap;
RbAmpDrdyEvent ev;
if (dev.readAllReady(500, snap, &ev)) {
if (ev.alarm) { /* ev.event_flags holds the cleared flags */ }
// use snap
}
Panoramica delle funzionalità
Le sintesi delle funzionalità qui sotto sono state spostate dal README.
- Configurazione del sensore di corrente —
setSensorClass(class)sceglie la famiglia (SCT-013 montato dall'utente; i moduli con CT cablato / integrato sono forniti calibrati insieme al loro sensore e non vengono riconfigurati), poisetCTModel(code)— oppureconfigureChannels(class, models[], n)per un modulo multi-canale in un'unica chiamata. I setter leggono prima di scrivere: una classe o un modello già presenti nel modulo non costano alcuna scrittura sul bus né cicli di flash, quindi riapplicare una configurazione memorizzata a ogni avvio è sicuro. L'insieme dei codici SCT-013 accettati è{1=005A, 2=010A, 3=030A, 4=050A, 5=100A, 6=020A, 7=060A}. I coefficienti di calibrazione si caricano automaticamente dalla tabella di preset di fabbrica. I moduli BASIC fino al firmware 1.4.19 sono calibrati su SCT-013-030: quando si seleziona un altro modello SCT-013 la libreria riavvia il modulo dopo il salvataggio e da quel momento scala le letture di corrente e potenza rispetto al guadagno applicato dal modulo (vedisctRating()); il fattore di potenza e la tensione non sono influenzati, e un modulo che riporta il bit di capacità di autocorrezione (firmware 1.4.20+) non necessita di nulla. - Gestore
RbAmpFleet— per più moduli su un bus:scan()scopre e acquisisce i moduli (con rilevamento delle collisioni),pollAll()li legge in un unico passaggio,totalPower()/totalEnergyWh()aggregano, e il percorso General-Call (enableGcAll()→gcLatch(tick)→checkSync()) acquisisce lo snapshot del periodo di ogni modulo simultaneamente con rilevamento dei frame persi per singolo modulo.provision()/assignAddress()portano sul bus moduli appena usciti dalla fabbrica con indirizzi distinti. - Entrambe le linee di prodotto, una sola API —
begin()rileva se un modulo parla il modello di registri BASIC (8 bit) o STD (16 bit, a virgola fissa) e instrada internamente ogni chiamata;line()le dice quale. Su un modulo STD funzionano le stesse chiamatereadVoltage(phase)/readCurrent(ch)/readPower(ch)/readPeriodSnapshot(), il numero di canali viene dal modulo (i moduli trifase sono semplicemente N > 1), e le funzioni esclusive STD sono esposte comereadReactivePower(ch)/readApparentPower(ch),stdReadChannel(ch)(una raffica: I / P / Q / S / PF / picco / energia con segno / armoniche),stdReadVoltage(v),stdReadHealth()e otto banchi di snapshot temporizzati dal master (stdArmBanks()→stdLatch(bank)→stdReadLatch(bank)→stdLatchWh()). I moduli che conservano contatori vita persistenti invece di banchi di snapshot sono serviti dalle stesse chiamatereadPeriodSnapshot()/energy()(un periodo è la differenza di due letture del contatore;stdReadEnergy()fornisce i contatori grezzi), più l'orologio del modulo (stdSetTime()), la cronologia e il registro eventi (stdHistRead(),stdEventRead()), l'identità (stdIdentify(),RbAmp::stdProbe()), la messa in servizio tramite UID (RbAmp::stdSetAddressByUid()) e l'aggiornamento del firmware via I2C (stdOtaWritePreparedImage(), immagini preparate sull'host di build del produttore). Ogni comando attende che il modulo segnali la fine prima di leggere il verdetto, e i blocchi multibyte vengono letti in una transazione così che i contatori non si spezzino. I moduli che pubblicano contatori a micro-risoluzione riempiono i campi*_uwh/*_uvarhdiRbAmpStdEnergy(fine == true; altrove derivati dai contatori grossolani, quindi i campi sono sempre utilizzabili), accettano una corrente di avvio sotto la quale un canale non conta energia (stdSetEnergyStartCurrent()) e riportano gli angoli di fase della tensione (angle_deginstdReadVoltage()) e la sequenza di fase (stdReadPhaseSequence()). Se il suo sketch salvaRbAmpStdEnergy(NVS, EEPROM, file), memorizzi i singoli campi che servono nel proprio formato fisso, non la struct come blob grezzo — la struttura acquisisce campi tra le versioni della libreria e un blob vecchio non corrisponderà alla nuova dimensione. - Linea data-ready ed eventi —
setDrdyPin(pin)ascolta l'uscita DRDY del modulo;waitDataReady()/readAllReady()ritornano subito dopo che il modulo pubblica un nuovo snapshot (più moduli possono condividere una linea), e un modulo che tiene la linea segnala un evento mascherato (setEventMask(),setEventThresholds()) che l'attesa legge e cancella per conto dell'utente. Senza linea le stesse chiamate fanno polling.
API della linea STD
La linea STANDARD (STD) è rilevata da begin() (dev.line() == RbAmpLine::Std). L'API scalare sopra (readVoltage(), readCurrent(), readPower(), readReactivePower(), readApparentPower(), readAll(), readPeriodSnapshot(), energy(), i setter di configurazione, reset(), il cambio di indirizzo) funziona su entrambe le linee. Le chiamate std* qui sotto aggiungono letture di interi blocchi e le funzioni che ha solo la linea STD.
- Ogni chiamata
std*fallisce conRB_ERR_NOT_IMPLEMENTEDsu un'istanza BASIC. -
La disponibilità delle funzioni segue l'immagine del modulo: verifichi
stdReadImageVersion()e i flagvalid/finedelle strutture restituite. Una funzione che il modulo non possiede viene segnalata come "non disponibile" — non restituisce mai un valore inventato. -
begin()esegue il rilevamento della linea e la scoperta dei canali. I corrispondenti helper interni non fanno parte dell'API pubblica; chiamibegin(),readAll()ereadPeriodSnapshot(). -
Ogni comando attende che il modulo segnali di averlo completato e poi verifica il suo verdetto. Un valore rifiutato restituisce
RB_ERR_PARAMe lascia il modulo invariato. -
Le primitive a 8 bit rifiutano su un'istanza STD, quindi un percorso solo-BASIC non può mai eseguire una transazione su registro sbagliato su un modulo STD.
if (dev.begin() && dev.line() == RbAmpLine::Std) {
RbAmpStdChannel c;
if (dev.stdReadChannel(0, c)) {
Serial.printf("P=%.1f W Q=%.1f var S=%.1f VA PF=%.2f\n", c.p, c.q, c.s, c.pf);
}
}
Fonte dell'energia e versione minima della libreria
readPeriodSnapshot() e energy() prendono il periodo da una delle due fonti, scelta una volta da begin() in base ai bit di capacità del modulo e riportata in stdInfo().period_source:
| Il modulo segnala | period_source |
Periodo / energia proviene da |
|---|---|---|
| contatori di energia persistenti (bit 13), con o senza banchi | Counters |
i contatori del modulo (un periodo è la differenza di due letture) |
| solo banchi di snapshot (bit 8) | Latch |
banco 0 |
| nessuno | None |
le chiamate rifiutano con RB_ERR_NOT_IMPLEMENTED |
L'immagine STD seriale 0x7E riporta entrambi i bit. Richiede la libreria 1.6.2 o successiva per prendere la sua energia dai contatori del modulo. La libreria 1.6.1 e precedenti leggono il periodo dal banco 0 su quell'immagine, cioè un'energia integrata sull'host invece che sui contatori propri del modulo; aggiorni la libreria per ottenere i valori basati sui contatori. I banchi restano disponibili su 0x7E tramite le chiamate in Banchi di snapshot di periodo.
Identità
bool stdInfo(RbAmpStdInfo& out) noexcept
Identità in cache da begin() — nessun traffico sul bus. Fallisce con RB_ERR_NOT_IMPLEMENTED su un'istanza BASIC o prima di begin().
struct RbAmpStdInfo {
uint8_t map_version; // register-map version
uint16_t capabilities; // feature bitmap of the module
uint8_t status; // status bits at begin() time (live: stdReadHealth())
uint8_t n_voltage; // populated voltage channels
uint8_t n_current; // populated current channels (the library exposes up to RBAMP_MAX_CHANNELS)
uint8_t variant; // raw variant byte (also mapped into readVariant())
uint32_t active_bank; // running firmware bank (firmware update), 0 if none
uint32_t ota_bank_size; // firmware bank size the module reports, 0 if none
RbAmpStdPeriodSource period_source; // which period / energy mechanism this module offers
};
RbAmpStdPeriodSource: Latch (il modulo ha banchi di snapshot; il banco 0 serve readPeriodSnapshot()), Counters (nessun banco di snapshot, ma contatori di energia vita persistenti — un periodo è la differenza di due letture del contatore; le chiamate ai banchi vengono rifiutate senza traffico sul bus) oppure None (le chiamate di periodo / energia falliscono con RB_ERR_NOT_IMPLEMENTED).
bool stdIdentify(RbAmpStdIdentity& out) noexcept
Identità di questo modulo: i dati in cache di begin() più l'UID, la versione dell'immagine in esecuzione e l'id della scheda (gli ultimi due dove il modulo li riporta; altrimenti 0).
struct RbAmpStdIdentity {
uint8_t i2c_addr; // 7-bit address the module answered on
uint8_t map_version;
uint16_t capabilities;
uint8_t variant;
uint8_t n_voltage, n_current;
uint8_t uid[12]; // chip UID — the module's identity in a database
uint32_t fw_version; // running image version (0 if unknown)
uint32_t board_id; // board id (0 if unknown)
};
static int8_t stdProbe(TwoWire& bus, uint8_t addr, RbAmpStdIdentity& out) noexcept
Identifica chi risponde all'indirizzo addr senza un'istanza (scansione del bus). Un tentativo per lettura, senza livello di ripetizione — un NACK è la risposta.
Restituisce: RB_OK; RB_ERR_NACK nessuno risponde a quell'indirizzo; RB_ERR_VERSION qualcosa che non è un modulo STD; RB_ERR_PARAM indirizzo fuori da 0x08..0x77; RB_ERR_IO una lettura successiva è fallita.
bool stdReadImageVersion(uint32_t& out) noexcept
La versione dell'immagine in esecuzione (non la versione della mappa dei registri); 0 se il modulo non ne riporta una. Serve a verificare se una funzione che richiede un'immagine recente è presente (micro-energia, corrente di avvio, angoli di tensione e sequenza di fase richiedono un'immagine di almeno 0x0001007B).
bool stdReadBoardId(uint32_t& out) noexcept
Id scheda dell'immagine in esecuzione.
Letture a blocchi
bool stdReadChannel(uint8_t ch, RbAmpStdChannel& out) noexcept
Un canale di corrente (0 .. channels()-1) in una sola raffica: I, P, Q, S, PF, picco, accumulatori di energia grezzi con segno e campi delle armoniche.
bool stdReadTotals(uint8_t k, RbAmpStdChannel& out) noexcept
Un blocco aggregato: k = 0 totale generale (tutti i canali di corrente), k = 1..3 totali per fase A / B / C (su un modulo monofase k = 1 equivale al canale 0 e k = 2, 3 leggono 0). Solo I / P / Q / S / PF / picco — sui moduli con contatori di vita utile i campi energia leggono 0 qui; l'energia proviene da stdReadEnergy().
struct RbAmpStdChannel {
float i_rms, i_peak; // A
float p; // W, signed
float q; // var, signed
float s; // VA
float pf; // power factor, −1..+1
float thd_i; // current THD, % — 0 unless harmonics are enabled
float pf1; // displacement power factor — 0 unless harmonics are enabled
float q1; // fundamental reactive power, var — 0 unless harmonics are enabled
int64_t e_import_mws; // raw import energy accumulator (>= 0), see stdLatchWh()
int64_t e_export_mws; // raw export energy accumulator (<= 0)
uint8_t implausible; // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};
Per il monitoraggio, integri p da sé oppure usi stdReadEnergy(); gli accumulatori grezzi esistono per il percorso dei banchi di snapshot.
bool stdReadVoltage(uint8_t v, RbAmpStdVoltage& out) noexcept
Un canale di tensione (0 .. n_voltage-1).
struct RbAmpStdVoltage {
float u_rms, u_peak; // V
float thd_u; // voltage THD, % — 0 unless harmonics are enabled
float angle_deg; // phase angle vs voltage 0, degrees; 0 when angle_valid is false
bool angle_valid; // false on older images, when the input is too low to measure, and on single-voltage modules for v > 0
uint8_t implausible;
};
bool stdReadPhaseSequence(RbAmpStdPhaseSeq& out) noexcept
Sequenza di fase di un modulo a tre tensioni, derivata dal modulo dagli angoli di tensione. Restituisce true con NotAvailable — e nessun traffico sul bus — su un'immagine che non la pubblica; il modulo stesso riporta NotAvailable con meno di tre ingressi di tensione o quando un ingresso è troppo basso per essere misurato.
RbAmpStdPhaseSeq: NotAvailable, Forward (L1-L2-L3), Reverse (L1-L3-L2), Abnormal (nessuno schema trifase, ad esempio due ingressi sulla stessa fase).
bool stdReadHealth(RbAmpStdHealth& out) noexcept
Stato di salute del modulo in tempo reale. Consideri valide le letture quando status ha il bit di sensore OK e frame_count cresce tra due interrogazioni.
struct RbAmpStdHealth {
uint8_t status; // status bits: cal_ok / sensor_ok / mains_ok / time_valid / nvm_fault / maint
uint32_t frame_count; // sensor frame counter — must grow between polls (liveness)
uint32_t crc_errors; // sensor frame error counter
bool time_valid; // the module clock was set since its last restart — see stdSetTime()
bool nvm_fault; // energy store unusable
bool maint; // maintenance mode
uint8_t lta_status; // life-time energy store: 0 ok · 1 new · 2 fault · 3 corrupt (service)
uint8_t lta_src; // where the life-time counters were restored from
uint8_t cal_src; // 0 built-in defaults · 1 flash · 2 EEPROM · 3 stored calibration is for another firmware
uint8_t group_status; // per-channel energy store: 0 ok · 1 new · 2 fault · 3 restarted at 0
uint16_t legal_noen, ring_drop; // module diagnostics (ring_drop should stay 0)
uint32_t lost_frames; // should stay flat
uint32_t uptime_s; // seconds since the module's last restart
uint8_t reset_cause; // cause of this boot (image-dependent; 0 below)
uint16_t boot_count; // persisted boot counter, low 16 bits — a master that missed a restart sees it step
};
I campi contrassegnati "dipendenti dall'immagine" o documentati per mappe di registri più recenti leggono 0 / false sui moduli che non li forniscono. cal_ok può leggere 0 su un'unità calibrata con un'immagine più vecchia finché saveGains() non è stato eseguito una volta; le letture in sé non sono influenzate.
Banchi di snapshot del periodo
Un modulo STD che riporta banchi di snapshot (bit di capacità 8) mantiene otto periodi indipendenti, temporizzati dal master. Uso tipico: armare una volta i banchi necessari; poi, per ciascun banco, secondo la propria pianificazione: stdLatch(bank) → attendere almeno 300 ms → stdReadLatch(bank, snap) → stdLatchWh(snap, dt, ...) con il dt misurato dal master dall'ultimo snapshot di quel banco. I banchi sono uno strumento a sé: sono disponibili qualunque sia la fonte di energia del modulo (vedi Fonte dell'energia e versione minima della libreria). Su un modulo senza banchi, stdArmBanks(), stdLatch() e stdReadLatch() rifiutano con RB_ERR_NOT_IMPLEMENTED senza scrivere nulla. Il banco 0 serve readPeriodSnapshot() e energy() solo su un modulo che ha banchi e nessun contatore persistente.
bool stdArmBanks(uint8_t mask) noexcept
Imposta la maschera di accumulo: bit b = il banco b accumula (i banchi appena armati partono puliti; i banchi disarmati si congelano e mantengono l'ultimo snapshot). Tenere il bit 0 impostato se si usa readPeriodSnapshot(). La maschera risiede nella RAM del modulo ed è persa a un reset del modulo; la libreria riarma un banco quando una lettura trova uno snapshot vuoto su un banco disarmato (vedi stdReadLatch()).
bool stdLatch(uint8_t bank) noexcept
Richiede uno snapshot + reset di bank al prossimo limite di finestra del modulo. Non attende; la legga almeno 300 ms dopo.
bool stdReadLatch(uint8_t bank, RbAmpStdLatch& out) noexcept
Legge l'ultimo snapshot di bank in una sola raffica (totali + energia per canale di ogni canale popolato).
Restituisce: false con RB_ERR_STALE se il modulo non ha mai eseguito uno snapshot di questo banco (out.valid == false), oppure se lo snapshot è vuoto (win_count == 0) perché il banco ha perso l'armamento dopo un reset del modulo. In quest'ultimo caso la libreria riarma e acquisisce uno snapshot di innesco del banco: scartare questo periodo e riavviare la propria ancora dt (l'intervallo di interruzione non contiene dati).
struct RbAmpStdLatch {
float p_avg, q_avg, s_avg; // average W / var / VA over the period
float max_p, max_i; // peak power (W) and peak RMS current (A)
float max_u, min_u; // peak / minimum RMS voltage (V)
int64_t e_import_mws, e_export_mws; // raw energy accumulators over the period
uint32_t nsamp; // conversion divisor used by stdLatchWh()
uint32_t win_count; // measurement windows in the period (0 = not armed / nothing elapsed)
uint8_t channels, bank;
bool valid; // the bank has EVER been snapshotted (not a freshness signal)
float p_avg_ch[RBAMP_MAX_CHANNELS];
int64_t e_import_ch_mws[RBAMP_MAX_CHANNELS], e_export_ch_mws[RBAMP_MAX_CHANNELS];
};
static bool stdLatchWh(const RbAmpStdLatch& snap, uint32_t dt_ms, uint8_t ch, double& wh_import, double& wh_export) noexcept
Converte gli accumulatori grezzi di energia di uno snapshot in Wh sul periodo misurato dal master dt_ms (tempo di parete tra lo snapshot precedente e questo del banco). ch è un indice di canale, oppure RBAMP_STD_TOTAL per i totali del banco. wh_import è >= 0, wh_export è <= 0.
Restituisce: false se ch è fuori intervallo o non è stato accumulato nulla.
Contatori di energia vita
I moduli che mantengono i contatori di energia persistenti conservano i dati anche in caso di perdita di alimentazione; sono monotoni con una separazione firmata import / export.
bool stdReadEnergy(RbAmpStdEnergy& out) noexcept
Legga i contatori vita del modulo. Ogni blocco viene letto in una transazione, quindi un contatore a 64 bit non può spezzarsi tra due pubblicazioni.
Restituisce: false con RB_ERR_NOT_IMPLEMENTED quando il modulo non conserva energia a bordo; RB_ERR_NOT_READY se il blocco non è programmato.
struct RbAmpStdEnergy {
int64_t act_import_wh, act_export_wh, act_net_wh; // active energy, Wh (export is a magnitude)
int64_t rea_import_varh, rea_export_varh; // reactive energy, varh
uint32_t generation; // steps when the counters were reset or adopted — never take a delta across a change
uint32_t uptime_s; // module uptime at the reading (a drop = the module restarted)
int64_t act_import_mwh, act_export_mwh, act_net_mwh; // mWh (0 on modules without them)
uint8_t channels; // valid entries in the per-channel arrays (0 on modules without them)
uint8_t group_status; // per-channel store: 0 ok · 1 new · 2 fault · 3 restarted at 0
int64_t ch_import_mwh[RBAMP_MAX_CHANNELS], ch_export_mwh[RBAMP_MAX_CHANNELS];
bool fine; // true: the µWh / µvarh fields are the module's own micro-resolution counters
int64_t act_import_uwh, act_export_uwh, act_net_uwh; // µWh
int64_t rea_import_uvarh, rea_export_uvarh; // µvarh
int64_t ch_import_uwh[RBAMP_MAX_CHANNELS], ch_export_uwh[RBAMP_MAX_CHANNELS];
};
I campi *_uwh / *_uvarh sono sempre compilati, quindi può usarli su qualsiasi modulo: quando fine == true sono i contatori a micro-risoluzione del modulo stesso (immagine 0x0001007B o successiva); altrimenti sono derivati dai contatori più grossolani e procedono in quelle unità. Se il suo sketch salva RbAmpStdEnergy, memorizzi i singoli campi che servono nel proprio formato fisso invece della struct come blob grezzo — la struttura acquisisce campi tra le versioni della libreria.
static bool stdEnergyDelta(const RbAmpStdEnergy& prev, const RbAmpStdEnergy& now, RbAmpStdEnergy* delta, bool* module_restarted) noexcept
Energia tra due letture: now − prev, ciascun contatore limitato a 0 (un contatore può riprendere leggermente sotto l'ultima lettura dopo un riavvio del modulo); il netto viene ricalcolato come importazione − esportazione dei delta limitati. delta e module_restarted possono essere nullptr; delta->fine è true solo quando entrambe le letture erano buone; *module_restarted è true quando l'uptime di now è inferiore a quello di prev.
Restituisce: false quando generation è cambiato tra le letture (reset o adozione dei contatori di vita utile) — non contabilizzare quell'intervallo.
bool stdSetEnergyStartCurrent(uint16_t ua) noexcept
Impostare la corrente di avvio per il conteggio dell'energia, in µA: sotto questa corrente di canale il modulo non conta energia per il canale (importazione o esportazione, totale e per canale). A carico nullo la potenza misurata è rumore di segno qualsiasi e altrimenti entrerebbe in entrambi i contatori. Le letture (I / P / Q) non sono influenzate. Si applica subito, con verifica di lettura; da rendere persistente con saveUserConfig(). 0 lo disattiva; altrimenti il valore deve essere un multiplo di 10 µA entro l'intervallo accettato dal modulo — qualsiasi altro valore restituisce RB_ERR_PARAM senza scrittura sul bus.
Restituisce: false con RB_ERR_NOT_IMPLEMENTED quando il modulo non ha una corrente di avvio (nessuna energia a micro-risoluzione o immagine più vecchia).
bool stdReadEnergyStartCurrent(uint16_t& ua) noexcept
La corrente di avvio attuale per il conteggio dell'energia, in µA (0 = disattivata).
Configurazione
bool stdReadConfig(RbAmpStdConfig& out) noexcept
Il blocco di configurazione in una sola raffica.
struct RbAmpStdConfig {
uint8_t sensor_class; // RbAmpSensorClass value, 0 = unset. Persisted.
uint8_t ct_model; // CT model reference for channel 0 (label only, sets no gain). Persisted.
uint8_t tier; // module tier code. Persisted.
uint8_t i2c_addr; // persisted 7-bit address (applies on reset)
uint16_t rate_ms; // report-rate hint, ms (RAM only)
bool harmonics; // base-harmonics extraction enabled (RAM only)
};
bool stdSetHarmonics(bool enable) noexcept
Abilita / disabilita l'estrazione delle armoniche di base (THD, PF di spostamento, potenza reattiva fondamentale). Solo in RAM (non persistente), con verifica di rilettura. Richiede la capacità THD del modulo — altrimenti RB_ERR_NOT_IMPLEMENTED.
bool stdCalThdFloor() noexcept
Acquisire il THD grezzo a vuoto come pavimento del sensore e memorizzarlo (circa 700 ms). Eseguire con rete pulita e nessun carico; in seguito le letture THD vengono corrette per il pavimento del sensore. Richiede la capacità THD.
Orologio
L'orologio del modulo si perde a ogni riavvio. Lo imposti dopo begin() e ogni volta che RbAmpStdHealth::time_valid è false; senza di esso il modulo non registra cronologia.
bool stdSetTime(uint32_t unix_epoch) noexcept
Imposta l'orologio del modulo (epoch Unix, UTC). Restituisce false con RB_ERR_PARAM se il modulo rifiuta l'epoch (prima del 2020), RB_ERR_NOT_READY se ha accettato il valore ma non ha segnalato l'orologio come valido entro 300 ms.
bool stdReadTime(uint32_t& unix_epoch, bool& valid) noexcept
L'orologio del modulo e se è stato impostato dall'ultimo riavvio del modulo.
Comandi e messa in servizio
bool stdCommand(uint8_t opcode, uint32_t settle_ms, uint32_t timeout_ms = 0) noexcept
Emette un comando qualsiasi del modulo e attende il suo verdetto: attende che il modulo sia inattivo (un comando scritto mentre è occupato viene perso), scrive il codice operativo, interroga lo stato del comando finché il modulo segnala la fine, poi legge il verdetto. settle_ms limita soltanto il primo polling. timeout_ms = 0 significa 1000 ms; mai meno di 1000.
Restituisce: false con il verdetto mappato su un codice di errore — PARAM, NOT_IMPLEMENTED (comando sconosciuto), CHECKSUM (controllo del valore), MODE (chiave / gate), NOT_READY (limite di frequenza / ripetizione), TIMEOUT, IO (errore di archiviazione del modulo).
bool stdWaitIdle(uint32_t timeout_ms = 0) noexcept
Attendere che il modulo segnali che non è in corso alcun comando (0 = 1000 ms).
bool stdLocate() noexcept
Fa lampeggiare i LED del modulo per circa 10 s — per trovarlo in un quadro.
static int8_t stdSetAddressByUid(TwoWire& bus, uint8_t shared_addr, const uint8_t uid[12], uint8_t new_addr, uint32_t restart_ms = 0) noexcept
Assegna a un modulo tra più su un indirizzo condiviso il proprio indirizzo, selezionato per UID (messa in servizio). È solo in scrittura sull'indirizzo condiviso (più moduli potrebbero rispondere, quindi lì non si legge nulla). Il modulo indirizzato salva il nuovo indirizzo e si riavvia; la chiamata poi sonda il nuovo indirizzo e verifica l'UID. Ripeta begin() su un'istanza legata al nuovo indirizzo. restart_ms = 0 significa 1500 ms.
Restituisce: RB_OK; RB_ERR_PARAM indirizzo fuori intervallo; RB_ERR_NACK nessun modulo ha risposto sull'indirizzo condiviso; RB_ERR_NOT_READY nulla risponde successivamente al nuovo indirizzo; RB_ERR_VERSION il modulo presente non è quello indirizzato (l'UID è diverso).
Cronologia e registro eventi
I record esistono solo per i periodi durante i quali l'orologio del modulo era valido (vedere stdSetTime()).
enum class RbAmpStdHistPeriod : uint8_t {
Min15 = 0, // 15-minute energy records — RAM only (the last record survives no restart)
Hour = 1, // hourly energy records — persistent ring (the one to backfill from)
Events = 2, // event log (read with stdEventRead())
};
bool stdHistInfo(RbAmpStdHistPeriod period, RbAmpStdHistInfo& out) noexcept
Riepilogo dell'anello: count, capacity, record_size, oldest_ts, newest_ts (tempo Unix). I record vengono letti dal più recente tramite un indice back.
bool stdHistRead(RbAmpStdHistPeriod period, uint16_t back, RbAmpStdHistRecord& out) noexcept
Recupera e decodifica un record del periodo di energia (Min15 o Hour; back = 0 è il più recente). Restituisce false con RB_ERR_NOT_READY quando non esiste tale record (anello vuoto o back oltre il limite); RB_ERR_PARAM per l'anello degli eventi (usare stdEventRead()).
struct RbAmpStdHistRecord {
uint32_t ts; // Unix time at the end of the period
uint16_t flags; // partial / power-up / clock / life-time-jump bits
uint16_t n; // measurement windows in the period
bool from_ram; // served from RAM (not yet persisted)
float v_rms, i_total, p_avg, q_avg, s_avg, pf;
float p_min, p_max, i_min, i_max;
uint64_t e_import_wh, e_export_wh; // life-time ABSOLUTE counters at the end of the period
uint8_t phases; // valid entries in the per-phase arrays (0..3)
double ph_import_wh[3], ph_export_wh[3]; // THIS period's energy per phase
};
Ricavare l'energia di un periodo da due record orari consecutivi solo quando i loro timestamp differiscono esattamente di un periodo e nessuno dei due porta il flag di salto del contatore di vita.
bool stdHistReadRaw(RbAmpStdHistPeriod period, uint16_t back, uint8_t rec[rbamp_std::REG_HIST_REC_SIZE], uint8_t* flags) noexcept
Recupera un record non decodificato di un qualsiasi anello in rec; flags (opzionale) riceve i flag del record del modulo.
bool stdEventRead(uint16_t back, RbAmpStdEvent& out) noexcept
Recupera e decodifica un record del registro eventi (back = 0 è il più recente); RB_ERR_NOT_READY = nessun record di questo tipo.
struct RbAmpStdEvent {
uint32_t ts; // Unix time (0 if the clock was not set)
uint32_t uptime_s; // module uptime at the event
uint8_t type; // record type
uint8_t flags;
uint16_t boot; // boot counter at the event
uint32_t a_before, a_after; // event-specific values
uint64_t e_before_wh, e_after_wh; // life-time energy before / after, Wh
};
bool stdHistFlush() noexcept
Chieda al modulo di scrivere ora i suoi accumulatori di energia nella propria memoria.
Aggiornamento del firmware via I²C
Un aggiornamento in due fasi: stdOtaBegin() → stdOtaWritePage() per ogni pagina → stdOtaCommit() (verifica l'immagine e arma lo scambio; nessun riavvio) → stdOtaActivate() (riavvia nella nuova immagine quando si è pronti). In pratica usare stdOtaWritePreparedImage(), che esegue begin + pagine + commit in una sola chiamata, e poi stdOtaActivate(). I moduli accettano solo immagini preparate dal produttore; un'immagine difettosa viene ripristinata dal modulo stesso e la calibrazione sopravvive. Ogni passo attende che il modulo segnali il comando completato (nessuna pausa fissa). Tutte le chiamate falliscono con RB_ERR_NOT_IMPLEMENTED se il modulo non segnala la capacità di aggiornamento.
typedef void (*RbAmpOtaProgress)(uint32_t done, uint32_t total, void* ctx);
| Chiamata | Descrizione |
|---|---|
bool stdOtaStatus(uint8_t& out) |
Lo stato di aggiornamento del modulo (rbamp_std::OTA_IDLE / READY / OK / ERR / DOWNGRADE). |
bool stdOtaBegin(uint32_t timeout_ms = 0) |
Cancellare il banco inattivo e attendere che il modulo segnali di essere pronto. 0 = predefinito (5 s). false con RB_ERR_TIMEOUT se non viene raggiunto. |
bool stdOtaWritePage(uint32_t page_idx, const uint8_t* page) |
Scrive una pagina di 256 byte all'indice page_idx. false con RB_ERR_CHECKSUM se il payload è arrivato corrotto (rinvii la stessa pagina), RB_ERR_IO se il modulo ha rifiutato la pagina, RB_ERR_NOT_READY se la sessione non è più aperta — negli ultimi due casi ripartire da stdOtaBegin() (vedere stdOtaDiag()). |
bool stdOtaCommit(uint32_t timeout_ms = 0) |
Verifica l'immagine scritta e arma lo scambio del banco. 0 = predefinito (3 s). RB_ERR_CHECKSUM immagine non valida, RB_ERR_VERSION immagine più vecchia di quella in esecuzione (rifiutata), RB_ERR_TIMEOUT. |
bool stdOtaActivate() |
Riavvia nell'immagine armata, attende che il modulo torni, lo riscopre, conferma che il banco in esecuzione è cambiato e attende che la nuova immagine si confermi. Blocca per l'intera sequenza (circa 12 s). L'istanza resta legata e stdInfo() riflette il nuovo firmware. false con RB_ERR_NOT_READY se non c'era nulla di armato, il modulo è tornato sul banco precedente o non ha confermato la nuova immagine; RB_ERR_VERSION se l'immagine che gira dopo non è quella in staging (ripristinata). |
static uint32_t stdCrc32(const uint8_t* data, size_t len) |
CRC-32 (compatibile con zlib) — il checksum per pagina che il modulo verifica. |
bool stdOtaWritePreparedImage(const uint8_t* image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) |
Trasmette un'immagine preparata per il banco (begin + pagine + commit; senza activate). len deve coincidere con la dimensione del banco del modulo, altrimenti RB_ERR_PARAM. Le pagine vanno in ordine crescente, le pagine vuote vengono saltate, una pagina che il modulo segnala come corrotta viene reinviata una volta. |
bool stdOtaWritePreparedImage(Stream& image, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) |
Forma a flusso — una pagina tenuta in RAM. |
bool stdOtaWritePreparedImage(const uint8_t* bank_a, const uint8_t* bank_b, size_t len, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) |
Fornisca entrambe le immagini per banco; la libreria sceglie quella del banco non in esecuzione. RB_ERR_NOT_IMPLEMENTED se il modulo non riporta il banco in esecuzione. |
bool stdOtaActiveBank(uint8_t& out) |
ID del banco in esecuzione: 0 = A, 1 = B. |
bool stdOtaStagedVersion(uint32_t& out) |
Versione dell'immagine armata (committata, non ancora attivata); 0 quando non c'è nulla di armato. |
bool stdOtaDiag(uint8_t& reason, uint8_t& hal_status) |
Il motivo dell'ultimo errore di aggiornamento del modulo più un byte di stato di basso livello. Leggerlo dopo che un commit o una scrittura di pagina è fallito. |
bool stdOtaAbort() |
Chiuda la sessione di aggiornamento / disarmi un'immagine armata senza riavviare. |
bool stdOtaBoardOk(uint32_t image_board_word) |
Rifiuta un'immagine costruita per un'altra scheda prima di inviarla: confronta l'id scheda del modulo con la parola di scheda dell'immagine (dal manifest dell'immagine). Una mancata corrispondenza restituisce RB_ERR_PARAM; RB_ERR_NOT_IMPLEMENTED sui moduli che non riportano un id scheda. |
bool stdOtaWriteImage(const uint8_t* image, size_t len, uint32_t version, RbAmpOtaProgress cb = nullptr, void* ctx = nullptr) e la forma Stream& |
Mantenuta solo per compatibilità del sorgente: restituisce false con RB_ERR_NOT_IMPLEMENTED senza toccare il modulo. Usare stdOtaWritePreparedImage(). |
RbAmpFleet — gestione di più moduli
La classe RbAmpFleet è la principale superficie di alto livello della libreria v1.3. Gestisce una raccolta di moduli su un bus I²C condiviso: scoperta, provisioning, aggregazione delle interrogazioni, aggregazione degli errori e snapshot sincroni tramite broadcast General-Call.
Una flotta è legata a un unico bus TwoWire (di solito Wire); ogni modulo acquisito è un handle RbAmp di sua proprietà. Il limite morbido sul numero di moduli è RBAMP_FLEET_MAX_MODULES = 16.
Ciclo di vita
RbAmpFleet(TwoWire& bus);
~RbAmpFleet(); // releases all adopted handles
Dopo ~RbAmpFleet(), tutti i puntatori di handle ottenuti tramite get(idx) sono non validi.
Scoperta — scan()
Configurazione multi-modulo (initialization) · Polling multi-modulo — tre strategie (realtime-polling) · Problemi multi-modulo (troubleshooting)
bool scan(bool match_product, size_t& added);
Sonda il bus nell'intervallo 0x08..0x77, e per ogni indirizzo che dà ACK:
-
Verifica l'identità (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Sematch_product = true, richiede una corrispondenza con il PRODUCT_ID di rbAmp. -
Esegue un rilevatore di conflitti su due segnali indipendenti (coerenza dell'identità + valore in tempo reale). Gli indirizzi sospetti finiscono nell'elenco
excluded, non nella flotta. -
Esegue un canarino di blocco di Livello 2: sonda un indirizzo dove non dovrebbe esserci nessuno. Se il canarino riceve un ACK, restituisce
false— il bus è bloccato e la flotta resta vuota (vedere la diagnostica nel cap. 10).
Al successo, added contiene il numero di moduli aggiunti alla flotta. excludedCount() (vedere sotto) è disponibile tramite un getter separato.
Accesso al modulo
size_t count() const noexcept;
RbAmp* get(size_t index) noexcept;
RbAmp* find(uint8_t address) noexcept;
bool add(RbAmp* dev) noexcept;
size_t excludedCount() const noexcept;
int excludedAddr(size_t i) const noexcept;
get restituisce nullptr fuori intervallo; find restituisce nullptr se l'indirizzo non è nella flotta (per esempio perché è stato escluso). add permette di aggiungere manualmente un handle creato separatamente (per esempio dopo un provisioning manuale).
Polling — pollAll()
Configurazione multi-modulo (initialization) · Polling multi-modulo — tre strategie (realtime-polling)
bool pollAll(RbAmpSnapshot* snaps,
RbAmpFleetPoll* status,
size_t capacity,
size_t& n_ok);
Interroga tutti i moduli della flotta in una sola chiamata. Per ogni modulo esegue una lettura RT completa (readAll()), allegando il risultato all'elemento snaps[i] corrispondente. In parallelo, status[i] riceve il risultato per modulo (ok=true/false + addr + channels).
Al termine, n_ok è il numero di moduli per i quali è stato ottenuto uno snapshot valido.
Resiliente ai MISS: un modulo silenzioso non annulla l'interrogazione degli altri. Questo conta per una flotta in produzione — la perdita di un modulo (un filo rotto, una bruciatura) non deve far cadere l'intero monitoraggio.
Aggregazione
bool totalPower(float& out_w) noexcept;
bool totalEnergyWh(double& out_wh) noexcept;
bool pollErrors(uint32_t& error_mask, size_t& n_errors) noexcept;
totalPower somma la potenza attiva di tutti i canali di tutti i moduli. Sulle varianti I non c'è potenza attiva → contribuiscono con 0. Nella distribuzione canonica (UI1 di rete + sotto-contatori I2/I3) il risultato è la potenza attiva del modulo di rete.
totalEnergyWh somma allo stesso modo i accumulatori Wh degli handle. Anche questo funziona correttamente: le varianti I danno 0, UI1 dà l'energia per carico.
pollErrors scorre la flotta chiamando hasError() su ogni modulo; error_mask è una maschera di bit dei moduli segnalati con EVENT bit3 per posizione (significativa per i primi 32 moduli); n_errors è il numero totale di moduli con il flag di errore al momento della lettura.
Indirizzamento e controllo dei conflitti
bool assignAddress(RbAmp* dev, uint8_t new_addr);
bool checkConflict(uint8_t addr, bool& collision) noexcept;
assignAddress riassegna un modulo già presente nella flotta a un nuovo indirizzo: internamente — un commit in due fasi + reset; l'handle nella flotta viene aggiornato automaticamente (le chiamate successive continuano a funzionare).
checkConflict — un controllo di sola lettura, best-effort, per un indirizzo specifico: legge l'identità (PRODUCT_ID / HW_VARIANT / CAPABILITY) e la confronta con lo stato in cache della flotta. Se viene rilevata un'incoerenza — collision = true. Per scorrere tutti gli indirizzi noti, iterare sulla flotta: for (size_t i = 0; i < fleet.count(); ++i) + checkConflict(fleet.get(i)->address(), col). Non garantisce di individuare moduli identici — vedi la disciplina di provisioning.
Provisioning — provision() (statico)
static bool provision(TwoWire& bus,
uint8_t desired_addr,
bool save_config,
RbAmp*& out_dev);
Accetta un TwoWire& (di solito Wire) e out_dev come parametro di uscita. In caso di successo out_dev appartiene al chiamante — tipicamente lo passa direttamente a fleet.add(out_dev):
Esegue il provisioning di esattamente un modulo vergine (di fabbrica 0x50) all'indirizzo indicato. Internamente:
- Verifica che ci sia una risposta a
0x50. - Verifica che nessuno sia ancora presente su
desired_addr. - Esegue il commit in due fasi dell'indirizzo.
-
Reimposta il modulo e attende che compaia a
desired_addrentro la finestra di avvio. -
Crea l'handle; se
save_config = true— chiamasaveUserConfig()(persiste in flash). -
Restituisce l'handle pronto tramite
out.
⚠ DEVE: esattamente un modulo vergine sul bus nel momento della chiamata. Due moduli a 0x50 contemporaneamente sono fisicamente indistinguibili su I²C — non possono essere distinti nemmeno con hardware speciale. La garanzia si basa sull'operatore, non sulla libreria. Per il recupero vedere 10 · Risoluzione dei problemi, sezione "Flotta: provisioning fallito".
Sincronizzazione GC della flotta — snapshot sincroni su tutta la flotta
General Call (broadcast all'indirizzo 0x00) (initialization) · Multi-modulo — snapshot simultaneo (period-metering) · 6.3 Snapshot broadcast GC — sincronizzazione della flotta su adesione (api-reference)
bool enableGcAll(uint8_t group, size_t& ok_count);
bool gcLatch(uint8_t group, uint16_t tick, uint16_t settle_ms);
bool checkSync(uint16_t expected_tick,
RbAmpFleetSync* status,
size_t status_cap,
size_t& n_missed);
Per una sincronizzazione stretta degli snapshot sull'intera flotta si usa uno snapshot broadcast General-Call I²C.
-
enableGcAllimpostaFLEET_CONFIG.bit0+GROUP_IDsu tutti i moduli della flotta ed emetteCMD_SAVE_USER_CONFIGsu ciascuno (persistente). Un riavvio dei moduli è obbligatorio dopo l'abilitazione — viene eseguito automaticamente.ok_countè il numero di moduli per i quali l'abilitazione è riuscita. -
gcLatchinvia il frame GCA5 27 group tick_lo tick_hiall'indirizzo0x00— tutti i moduli con GC abilitato e ungroupcorrispondente eseguono immediatamente il comando di snapshot (LATCH_PERIOD).settle_msè la pausa dopo il frame (tipicamente 50 ms) prima della verifica. -
checkSyncleggeGC_TICK (0x59)su ogni modulo inRbAmpFleetSync status[status_cap]. Il risultato per modulo:
struct RbAmpFleetSync {
uint8_t addr; // I²C address of the module
uint16_t gc_tick; // REG_GC_TICK; 0xFFFF = never received a GC
bool in_sync; // true if gc_tick == expected_tick
bool reachable; // false if the read NACKed / timed out
};
n_missed è il numero di moduli con in_sync = false (o semplicemente che non rispondono). Se tutti sono in_sync, n_missed == 0.
Configurazione della flotta per dispositivo (v1.3)
Questi metodi lavorano con un singolo modulo direttamente (senza flotta) — per i casi in cui si configura un singolo modulo prima di aggiungerlo a una flotta, oppure si vuole un controllo di dettaglio.
bool enableGc(bool enable) noexcept / bool readFleetConfig(uint8_t& out) noexcept
Chiamata generale (broadcast all'indirizzo 0x00) (inizializzazione) · 4.4 Configurazione della flotta (0x27..0x2F) (riferimento API)
enableGc(true) scrive 1 su FLEET_CONFIG.bit0 (0x27), salva in flash e fa un reset — il modulo inizierà ad accettare snapshot GC dopo l'avvio. enableGc(false) azzera il bit in modo simmetrico. Si blocca per ~1 secondo (assestamento di SAVE_USER_CONFIG + assestamento del reset). readFleetConfig restituisce il byte di configurazione corrente — utile per la conferma in lettura.
bool setGroupId(uint8_t group) noexcept / bool readGroupId(uint8_t& out) noexcept
GROUP_ID (0x28) — il filtro dei frame GC: il modulo reagisce solo ai frame GC con un group_id corrispondente. Valore predefinito = 0x00 (broadcast, reagisce a qualsiasi). Usato per bus multi-utente — per esempio un gruppo "fase A" e un gruppo "fase B" su un unico bus condiviso.
bool readGcTick(uint16_t& out) noexcept
Legge GC_TICK (0x59) — l'ultimo valore di tick ricevuto da un frame GC. Serve per rilevare i frame persi (se due moduli hanno tick diversi, qualcuno ha perso un frame). 0xFFFF = il modulo non ha mai ricevuto un frame GC dall'avvio.
static bool broadcastLatchGroup(TwoWire& bus, uint8_t group, uint16_t tick) noexcept
Invio di basso livello del frame GC A5 27 group tick_lo tick_hi direttamente tramite bus (senza una flotta). Utile se la flotta non è ancora creata, oppure se vuole il controllo manuale del contatore di tick.
bool readActiveAddress(uint8_t& out) noexcept
Legge REG_I2C_ADDRESS (0x30) — l'indirizzo attivo (in esecuzione) del modulo. Sulla v1.3, all'avvio legge l'indirizzo attivo, non un candidato in staging. Sulla linea STD restituisce il campo indirizzo persistito (che si applica al reset). Utile per la conferma di rilettura dopo commitAddressChange().
Classe RbAmpEnergy
Un accumulatore Wh per canale. Di proprietà di RbAmp, accessibile tramite dev.energy(). L'utente di norma non lo crea direttamente.
Metodi pubblici
double wh(uint8_t ch = 0) const noexcept;
Il totale corrente in Wh su un canale, oppure per tutti i canali con RBAMP_ENERGY_CH_TOTAL. Con segno — un valore negativo significa esportazione netta. Se ch è fuori intervallo, restituisce 0.0. (Su un modulo STD senza contatori per canale usi RbAmp::energyWh() per ottenere NaN invece di uno 0 fuorviante.)
void addWh(uint8_t ch, double wh) noexcept;
Aggiunge un'energia con segno a un canale o al totale di tutti i canali. Usato dalla libreria sul percorso del contatore STD; disponibile anche al codice utente che integra l'energia da sé.
void reset(uint8_t ch = 0) noexcept;
void resetAll() noexcept;
Azzerare un canale (o il totale con RBAMP_ENERGY_CH_TOTAL) oppure tutti i canali.
void disable() noexcept;
void enable() noexcept;
bool isEnabled() const noexcept;
Abilita/disabilita l'integrazione automatica. Con l'integrazione disabilitata, readPeriodSnapshot() continua a funzionare ma non fa avanzare l'accumulatore — utile se il master tiene una propria memoria Wh persistente.
uint32_t droppedDtCount() const noexcept;
void resetDroppedDtCount() noexcept;
Diagnostica: quanti tick di integrazione sono stati persi perché il periodo del master era più lungo del limite di sanità di un'ora.
Il tick() interno
void tick(const RbAmpPeriodSnapshot& snap, uint8_t channels) noexcept;
Chiamato automaticamente da RbAmp::readPeriodSnapshot() in caso di successo. Il codice utente non lo chiama direttamente. Idempotente: gli snapshot con valid == false vengono ignorati.
La formula di integrazione:
wh[ch] += snap.avg_p[ch] × snap.master_dt_ms / 1000 / 3600
[W] [milliseconds] → [Wh]
Precisione
Dipende dalla piattaforma — per i dettagli vedere 04 · Hardware:
-
ESP32 / ESP8266 / STM32duino / SAMD / RP2040: un accumulatore
doublea 64 bit. -
Arduino AVR classico (Uno, Mega, Nano): la toolchain definisce
doublecomefloata 32 bit. Per le installazioni di lunga durata, azzerare periodicamente l'accumulatore (ad esempio una volta al giorno).
Struct POD ed enumerazioni
Le strutture della linea STD (RbAmpStd*) sono descritte insieme alle chiamate che le restituiscono nella API della linea STD.
RbAmpSnapshot
Restituito da readAll(). Tutti i campi in unità SI. I canali non usati (oltre channels) sono riempiti con zeri.
#define RBAMP_MAX_CHANNELS 7 // override before including to shrink the arrays
struct RbAmpSnapshot {
float voltage; // V — RMS voltage
float voltage_peak; // V — peak voltage
float current[RBAMP_MAX_CHANNELS]; // A — RMS current per channel
float current_peak[RBAMP_MAX_CHANNELS]; // A — peak current per channel
float power[RBAMP_MAX_CHANNELS]; // W — active power per channel (signed)
float power_factor[RBAMP_MAX_CHANNELS]; // dimensionless, −1..+1
float frequency; // Hz — grid frequency
RbAmpTopology topology; // Single / SplitPhase / ThreePhase / Five / Seven
uint8_t channels; // 1..RBAMP_MAX_CHANNELS — number of valid channels
bool has_voltage_hw; // true if a voltage sensor is present
uint8_t implausible; // RBAMP_FIELD_* bits of fields set to NaN by the sanity filter
};
Bit implausible: RBAMP_FIELD_VOLTAGE, RBAMP_FIELD_CURRENT, RBAMP_FIELD_POWER, RBAMP_FIELD_PF, RBAMP_FIELD_FREQUENCY.
RbAmpPeriodSnapshot
Restituito da readPeriodSnapshot(). La primitiva di misura dell'energia.
struct RbAmpPeriodSnapshot {
float avg_p[RBAMP_MAX_CHANNELS]; // W — average active power over the period
float max_p; // W — peak instantaneous power on channel 0
uint32_t latch_ms; // ms — period duration (device's view, diagnostic; 0 on STD)
uint32_t master_dt_ms; // ms — master wall-clock dt since the last snapshot
bool valid; // true if the snapshot ready flag was set
float avg_p_total; // W — average active power over the period, all channels
double wh_net; // Wh — net energy of this period (import − export)
bool module_restarted; // the module restarted inside this period (STD counter path only)
};
latch_ms è un timer diagnostico del modulo; non lo usi per l'energia — usi l'orologio del master (master_dt_ms).
RbAmpTopology
enum class RbAmpTopology : uint8_t {
Single = 1, // 1 current channel (UI1 / I1)
SplitPhase = 2, // 2 current channels (UI2 / I2)
ThreePhase = 3, // 3 current channels (UI3 / I3)
Five = 5, // 5 current channels (UI5) — senior SKU
Seven = 7, // 7 current channels (UI7) — senior SKU
};
RbAmpLine
enum class RbAmpLine : uint8_t {
Basic = 0, // 8-bit register map (the default until begin() runs)
Std = 1, // STANDARD (STD) line: 16-bit register map
};
RbAmpVariant
Unknown, UI1, UI2, UI3, I1, I2, I3, UI5, UI7 — vedere readVariant().
RbAmpSensorClass
enum class RbAmpSensorClass : uint8_t {
Unset = 0, // Factory default; setCTModel() will refuse
Sct013 = 1, // SCT-013 series clamp fitted by the user
WiredCT = 2, // Wired CT shipped with the module and calibrated together with it
BuiltinCT = 3, // Built-in CT, calibrated together with the module
};
WiredCT e BuiltinCT descrivono moduli forniti e calibrati insieme al loro sensore. I setter non riscrivono mai tali moduli (restituiscono false con RB_ERR_MODE); setCTModelChForce() è il percorso di assistenza.
RbAmpCTModel
Un enum congelato per la compatibilità all'indietro dei sette codici SCT-013 (Sct013_005 … Sct013_060). Il nuovo codice passa una define RBAMP_CT_* generata agli overload uint8_t.
RbAmpSctRating e RbAmpSctRatingStatus
Vedi Correzione della portata SCT-013.
RbAmpDrdyEvent
Vedi Linea data-ready ed eventi.
Codici di errore (namespace rbamp)
Definito in RbAmpRegisters.h, restituito da lastError().
namespace rbamp {
constexpr int8_t RB_OK = 0;
constexpr int8_t RB_ERR_IO = -1; // I²C transport error
constexpr int8_t RB_ERR_NACK = -2; // retry exhausted, slave not responding
constexpr int8_t RB_ERR_TIMEOUT = -3; // timeout (waitReady / waitDataReady / commit-addr window expired)
constexpr int8_t RB_ERR_NOT_READY = -4; // module not ready / no such record / nothing armed
constexpr int8_t RB_ERR_STALE = -5; // period snapshot not ready
constexpr int8_t RB_ERR_PARAM = -6; // invalid channel / address / precondition; the module rejected a value
constexpr int8_t RB_ERR_MODE = -7; // not allowed in the module's current mode (factory-paired class, factory-only command)
constexpr int8_t RB_ERR_CHECKSUM = -8; // value check failed — checksum / signature / range
constexpr int8_t RB_ERR_VERSION = -9; // unsupported firmware / image version
constexpr int8_t RB_ERR_NOT_IMPLEMENTED = -10; // no counterpart on this line or on this module image
constexpr int8_t RB_ERR_NON_PHYSICAL = -11; // float rejected by the sanity filter
}
Ricette diagnostiche per ogni codice — 10 · Risoluzione dei problemi.
Ricette diagnostiche per ogni codice — 10 · Risoluzione dei problemi.
Configurazione in fase di compilazione
Definire PRIMA di #include per sovrascrivere i valori predefiniti:
#define RBAMP_NACK_RETRY_ATTEMPTS 5 // number of retry attempts per byte
#define RBAMP_NACK_RETRY_GAP_MS 5 // pause between attempts, ms
#include
Valori predefiniti della piattaforma:
#if defined(ARDUINO_ARCH_ESP32) || defined(ESP_PLATFORM)
# define RBAMP_NACK_RETRY_ATTEMPTS 3
#else
# define RBAMP_NACK_RETRY_ATTEMPTS 1
#endif
#define RBAMP_NACK_RETRY_GAP_MS 5
Per approfondire il sottosistema di resilienza — 10 · Risoluzione dei problemi.
Costanti di tempo di assestamento
Definiti in RbAmpRegisters.h. La libreria li usa internamente; sono esportati per chi vuole rispettare gli stessi tempi durante l'accesso diretto al bus:
constexpr uint16_t SETTLE_MS_LATCH_PERIOD = 50; // after CMD_LATCH_PERIOD
constexpr uint16_t SETTLE_MS_SAVE_GAINS = 700; // after CMD_SAVE_GAINS (flash write)
constexpr uint16_t SETTLE_MS_RESET = 300; // after CMD_RESET
constexpr uint16_t SETTLE_MS_FACTORY_RESET = 1500; // after CMD_FACTORY_RESET
Dettagli del protocollo sul filo
Questa sezione descrive il protocollo a registri a 8 bit della linea BASIC. La linea STD usa un puntatore di registro a 16 bit con letture a raffica ad auto-incremento; la libreria lo gestisce internamente (begin() rileva la linea) e il cablaggio fisico è lo stesso bus I²C. Il codice applicativo non ha mai bisogno dei dettagli del filo STD — usare le chiamate della API della linea STD.
Letture dei registri — auto-incremento
Una lettura a raffica restituisce N byte consecutivi a partire da addr. I metodi della libreria usano le raffiche dove possibile (una transazione I²C = 4 byte di float).
Scritture di registro — un byte alla volta (NON incremento automatico)
⚠ Le scritture NON incrementano automaticamente. Una scrittura a raffica scrive solo il primo byte — i byte 1..N vengono scartati.
Un registro multibyte viene scritto un byte alla volta — una transazione I²C separata di un solo byte per ogni indirizzo:
// WRONG — data loss
uint8_t label[8] = "MyMeter1";
Wire.beginTransmission(addr);
Wire.write(0x68); // start of LABEL
Wire.write(label, 8); // burst — only 'M' lands
Wire.endTransmission();
// CORRECT — byte-at-a-time loop
for (int i = 0; i < 8; i++) {
Wire.beginTransmission(addr);
Wire.write(0x68 + i);
Wire.write(label[i]);
Wire.endTransmission();
}
Riguarda i registri scrivibili multibyte: LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, riservati alla fabbrica), NF (u16), THRESH (u16). Letture — raffica ammessa.
Eccezione: il frame broadcast GC (5 byte A5 27 g tl th verso l'indirizzo 0x00) è un percorso separato del protocollo sul filo (ricezione general-call, non una scrittura di registro), inviato come singola transazione. Vedere lo scenario 12 in 06 · Esempi.
Lettura di registri non mappati
Qualsiasi lettura da un indirizzo non mappato restituisce 0x00. Il firmware non invia mai NACK sulle letture dei registri. Il rilevamento dell'assenza del dispositivo avviene tramite l'ACK del frame di indirizzo I²C, non sondando i registri.
Rilevamento della variante
Il byte SKU autorevole è REG_HW_VARIANT (0x55) (il metodo readVariant()):
| valore | SKU |
|---|---|
0x01 |
UI1 (1× I + U) |
0x02 |
UI2 (2× I + U) |
0x03 |
UI3 (3× I + U) |
0x04 |
I1 (1× I, senza U) |
0x05 |
I2 (2× I, senza U) |
0x06 |
I3 (3× I, senza U) |
0x07 |
UI5 (5× I + U, SKU di fascia alta) |
0x08 |
UI7 (7× I + U, SKU di fascia alta) |
REG_TOPOLOGY (0x24) è ausiliario (indica solo il numero di canali, non distingue la presenza di U). Sulla linea STD la libreria legge l'identità dalla mappa a 16 bit del modulo durante begin() e associa la variante a readVariant().
Snapshot broadcast General-Call (sincronizzazione multimodulo)
Abilitazione per modulo tramite REG_FLEET_CONFIG.bit0 — GC_ENABLE. Predefinito OFF. Si abilita tramite CMD_SAVE_USER_CONFIG + CMD_RESET (morbido o hard). Dopo il reset il modulo resta in ascolto di un frame broadcast all'indirizzo 0x00:
addr=0x00 | A5 27
A5— magic;27— opcodeCMD_LATCH_PERIOD.—0x00= all-call, altrimenti deve corrispondere aREG_GROUP_ID (0x28).— il contatore di periodo di sincronizzazione master a 16 bit.
Il frame esegue solo lo snapshot; gli opcode distruttivi non vengono trasmessi tramite GC.
Rilevamento della modalità di guasto (due livelli):
- NACK dell'indirizzo GC (subito a livello di bus): se il GC è disattivato sull'intera flotta —
Wire.endTransmission()verso0x00restituisce un codice diverso da zero (NACK). Si tratta di un errore fatale, non di uno scarto silenzioso. La libreria lo tratta come "GC non abilitato" (richiede le precondizioni di abilitazione + reset). - Testimone per modulo (dopo l'assestamento): se non si è verificato alcun NACK — legga
REG_V03_PERIOD_VALID (0x07)su ciascun modulo atteso.1= snapshot riuscito;0= GC disattivato su questo modulo oppure periodo vuoto;!=1→ ripiego su un latch per dispositivo.
Riferimenti
- 05 · Avvio rapido — il primo sketch funzionante
- 06 · Esempi — scenari di lavoro
-
10 · Risoluzione dei problemi — decodifica degli errori e soluzione dei problemi comuni
-
File sorgente con commenti Doxygen:
src/RbAmp.h
Sorgente e segnalazioni: rb-amp/rbamp-arduino · questa pagina nel repository: docs/09_api_reference.md (v1.6.2)