02 · Livelli dei moduli
Che cosa è una linea di moduli
Controlli l'etichetta del suo modulo; dev.line() stampa la linea dopo begin().
rbAmp è disponibile in linee di moduli: BASIC e STANDARD (STD). Una linea di moduli è un accoppiamento completo di revisione hardware e firmware, non un flag software. Passare da una linea all'altra richiede un cambio fisico di SKU, non un aggiornamento del firmware.
Dal punto di vista della libreria e del suo codice: una sola classe RbAmp serve entrambe le linee di produzione. begin() rileva se un modulo è BASIC o STANDARD (STD) e instrada internamente ogni chiamata; i metodi comuni (readVoltage(), readCurrent(), readPower(), readPeriodSnapshot(), energy() …) funzionano su entrambi. La linea STD aggiunge chiamate proprie — potenza reattiva e apparente, letture di blocco per canale, contatori di energia vita cumulativa con segno — vedere 09 · Riferimento API.
Stato attuale
Il livello BASIC e la linea STANDARD (STD) sono linee di moduli in commercio; questa libreria supporta entrambe (STANDARD (STD) dalla libreria 1.6.0, vedere il README).
| Livello | Spedizione |
|---|---|
| BASIC | ✅ sì |
| STANDARD (STD) | ✅ sì (libreria 1.6.0+) |
BASIC — livello di ingresso per la misura domestica
Hardware
Un percorso analogico a basso costo adatto ai carichi domestici tipici. Il modulo include un front-end analogico isolato, un regolatore di alimentazione a bordo e una calibrazione di fabbrica memorizzata in flash.
Comportamento del firmware
La logica di un classico contatore meccanico a disco — il conteggio va solo in avanti; l'esportazione verso la rete non viene sottratta.
I tre "livelli" dei valori di potenza attiva si comportano in modo diverso:
| Segnale | Significato | Comportamento su BASIC |
|---|---|---|
dev.readPower(ch) |
potenza RT istantanea, aggiornata ogni ~100 ms | con segno — un valore negativo è visibile in tempo reale (esportazione) |
PERIOD_AVG_P_W (dentro readPeriodSnapshot) |
potenza media sul periodo | la media P di ogni finestra da 100 ms è limitata a max(P, 0) prima di essere sommata all'accumulatore del periodo |
dev.energy().wh(ch) |
Wh accumulati dalla libreria | monotono — solo consumo; l'esportazione non viene conteggiata |
In altre parole: l'utente vede l'esportazione nella lettura RT, ma essa manca dal contatore Wh della libreria sul BASIC.
Casi d'uso tipici
-
Abitazioni senza generazione in loco (senza pannelli solari, turbine eoliche o sistemi a batteria)
-
Contatori secondari per carichi puramente consumatori (scaldabagni, motori, elettrodomestici)
-
Monitoraggio dei consumi di un edificio dove la misura bidirezionale non è richiesta
Misura bidirezionale sul BASIC (lato master)
Se deve tenere traccia separatamente dell'esportazione verso la rete su un modulo BASIC, lo faccia lato master. La potenza RT dev.readPower(0) è con segno, quindi:
double consume_wh = 0.0;
double export_wh = 0.0;
uint32_t t_prev_ms = millis();
void loop() {
// Sample RT power at 10 Hz — matches the firmware-commit cadence
// (100 ms per channel). Faster gives empty repeat reads; slower
// loses resolution on abrupt load transitions.
//
// delay() blocks the loop — incompatible with concurrent work
// (LCD refresh, MQTT, networking). For sketches with other tasks,
// replace it with a non-blocking millis() / scheduler pattern.
delay(100);
uint32_t t_now_ms = millis();
float dt_s = (t_now_ms - t_prev_ms) / 1000.0f;
t_prev_ms = t_now_ms;
float p = dev.readPower(0);
if (isnan(p)) return;
double dwh = (double)p * dt_s / 3600.0;
if (p >= 0) consume_wh += dwh;
else export_wh += -dwh;
}
Un esempio completo funzionante è in 06_examples.md (lo scenario BidirectionalEnergy) e in examples/06_BidirectionalEnergy/.
STANDARD (STD) — linea bidirezionale
I moduli STANDARD (STD) sono una linea di moduli in commercio. La libreria li rileva in begin() (dev.line() == RbAmpLine::Std) e usa lo stesso cablaggio e la stessa API comune del BASIC (vedere 04 · Cablaggio).
Cosa aggiunge la linea STD
Su un modulo STD con contatori di energia persistenti, l'API per periodo/snapshot e l'energia provengono dai contatori del modulo stesso (le immagini STD più vecchie usano i banchi di snapshot del modulo); il modello CT su STD è solo un'etichetta e non imposta alcun guadagno.
-
Energia con segno: importazione ed esportazione sono contabilizzate separatamente. Sui moduli che conservano contatori vita persistenti,
dev.energy()ereadPeriodSnapshot()prendono i valori del modulo stesso (wh_net= importazione − esportazione), estdReadEnergy()fornisce i contatori grezzi (Wh, mWh e, sulle immagini che li prevedono, µWh / µvarh). -
Altre grandezze (su BASIC la potenza reattiva non è esposta da questa libreria):
readReactivePower(ch),readApparentPower(ch),stdReadChannel(ch)(I / P / Q / S / PF / picco in una sola raffica) e, quando abilitati, valori basati sulle armoniche (THD, fattore di potenza di spostamento). -
Moduli multi-canale / multi-tensione: il numero di canali proviene dal modulo;
stdReadVoltage(v), totali per fase constdReadTotals(k). -
Diagnostica e assistenza:
stdReadHealth(), orologio del modulo, cronologia e registro eventi, identificazione tramite UID, aggiornamento del firmware via I²C.
Tutto questo è elencato chiamata per chiamata in 09 · Riferimento API § API della linea STD.
Alcune funzioni STD dipendono dalla versione dell'immagine del modulo: contatori di energia a micro-risoluzione, corrente di avvio per l'energia, angoli di fase di tensione e sequenza di fase richiedono una versione dell'immagine di almeno 0x0001007B (dev.stdReadImageVersion()); su un'immagine più vecchia sono segnalate come "non disponibili". Le chiamate solo-STD su un modulo BASIC restituiscono RB_ERR_NOT_IMPLEMENTED.
Casi d'uso tipici
- Abitazioni con generazione solare sul tetto
- Abitazioni con turbine eoliche
- Sistemi di accumulo a batteria
- Carichi rigenerativi
- Ricarica EV vehicle-to-grid (V2G)
Come rilevare la linea a runtime
if (!dev.begin()) { /* see dev.errorString() */ }
// Product line, detected by begin(): BASIC or STANDARD (STD)
RbAmpLine line = dev.line(); // RbAmpLine::Basic / RbAmpLine::Std
// Firmware version — opaque byte
uint8_t fw = dev.firmwareVersion();
// Presence of a voltage sensor (UI* variants vs I*-only)
bool voltage_hw = dev.hasVoltageHw();
// Number of current channels
uint8_t channels = dev.channels();
// Full SKU — variant byte (REG_HW_VARIANT)
RbAmpVariant variant = dev.readVariant(); // UI1, UI2, UI3, I1, I2, I3, UI5, UI7 …
: line() indica BASIC o STANDARD (STD). Gli altri indicatori (versione del firmware, numero di canali, sensore di tensione, SKU) descrivono l'hardware. L'etichetta SKU sull'involucro del modulo resta la fonte autorevole per il prodotto.
Dove nella documentazione sono segnalate le voci che dipendono dal livello
In tutto il testo della libreria e nella documentazione canonica, le funzioni dipendenti dal livello sono segnalate esplicitamente, ad esempio:
— non disponibile su un modulo BASIC.
Oppure, al contrario, comportamento specifico del BASIC:
: il contatore dev.energy().wh(ch) è monotono — l'esportazione verso la rete non viene conteggiata. Per la misura bidirezionale, vedere l'esempio BidirectionalEnergy o usi un modulo STANDARD (STD).
Cosa c'è dopo
-
03 · Selezione del sensore di corrente — quale SCT-013 per quale lavoro
-
04 · Cablaggio — dettagli hardware
-
06 · Esempi — scenari per il BASIC, compresa la misura bidirezionale lato master
-
09 · Riferimento API — l'API pubblica completa
Sorgente e segnalazioni: rb-amp/rbamp-arduino · questa pagina nel repository: docs/02_tiers.md (v1.6.2)