01 · Panoramica
Cos'è rbAmp
rbAmp è un modulo hardware compatto per la misura di precisione dei parametri della rete in corrente alternata tramite l'interfaccia I²C. Dispone di un front-end analogico isolato integrato e di una calibrazione di fabbrica memorizzata in flash.
Dal punto di vista di chi integra, il modulo si comporta come uno slave I²C standard: colleghi l'alimentazione, legga i registri e otterrà valori pronti in unità fisiche. Non serve alcuna elaborazione del segnale lato master.
Lo scopo principale della libreria — monitorare più carichi
La libreria RbAmp Arduino è costruita per lavorare con un gruppo di moduli contemporaneamente su un unico bus I²C, non per pilotare un singolo dispositivo. Lo scenario canonico è un modulo principale sull'alimentazione di rete più N moduli su singoli carichi, tutti su un bus, pilotati da un unico Arduino/ESP32. La libreria fornisce la classe RbAmpFleet — un unico oggetto con cui si esegue la scansione del bus, si interroga ogni modulo con una sola chiamata, si ottengono la potenza totale consumata e il bilancio "alimentazione − Σ(carichi)", si intercettano gli errori su ogni modulo e, quando serve, si sincronizzano gli snapshot di periodo con un comando broadcast.
Sono supportati anche i moduli multicanale — i soli corrente I2 / I3 (due o tre TA) e quelli con tensione UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 canali di corrente, con potenza, PF e Wh per canale). Ogni canale ha un proprio modello di sensore. È tipico di un sottoquadro, dove un unico punto di installazione monitora più linee di alimentazione.
Lavorare con un singolo modulo è il caso minimo di questa stessa libreria: la classe RbAmp è il mattone su cui è costruito RbAmpFleet. Se c'è un solo modulo sul bus, si usa direttamente quello stesso handle — l'API della flotta non serve.
Lo scenario dell'80% — rete principale + N carichi secondari
- 1 modulo sulla linea di alimentazione di rete — consumo complessivo e qualità della rete.
- N moduli su singoli carichi — misura per canale.
- Anche i moduli multicanale si adattano a questo caso: un
UI2/UI3/UI5/UI7(oppureI2/I3) può misurare più carichi, ciascuno sul proprio canale — N moduli non devono significare N carichi. -
Una sola chiamata
fleet.pollAll()interroga tutto; il bilanciomains − Σ(sub_loads)rivela "il resto" (consumo di fondo, carichi non misurati, dispersioni). -
Un unico timestamp master condiviso → misura Wh corretta senza deriva tra moduli (vedi 02_tiers.md e la sezione sull'orologio di parete del master in 09_api_reference.md).
Dettaglio architetturale importante. Le varianti I (I1/I2/I3) misurano solo corrente — non hanno tensione, né potenza attiva, né PF. L'energia attiva (Wh) e la potenza sono calcolate solo sulle varianti UI (che hanno un front-end di tensione). Nella distribuzione canonica il ruolo di "contatore di rete" (misura per tariffa/periodo) è svolto da un unico UI1 sulla linea di alimentazione; il ruolo di sotto-contatore (dettaglio di corrente per carico) è svolto dai moduli I2/I3 (oppure da UI2 / UI3 / UI5 / UI7 quando servono potenza e Wh per carico).
Per i dettagli, vedi il capitolo 06 · Esempi, scenario 1 ("Rete + N carichi secondari — il canone 80%"). Per l'API, vedi il capitolo 09 · Riferimento API, sezione "Fleet manager" (gestore della flotta).
Cosa misura rbAmp
| Grandezza | Tipo | Intervallo |
|---|---|---|
| Tensione efficace RMS U_rms | float32, V | 0…300 V |
| Tensione di picco U_peak | float32, V | 0…450 V |
| Corrente efficace RMS I_rms | float32, A | dipende dal sensore scelto — vedi 03_sensor_selection.md |
| Corrente di picco I_peak | float32, A | dipende dal sensore selezionato |
| Potenza attiva P (con segno in RT) | float32, W | dipende dal sensore selezionato |
| Fattore di potenza PF | float32 | −1…+1 |
| Frequenza di rete | uint8, Hz | 50 / 60 Hz (rilevati) |
| P media sul periodo | float32, W | come per P |
Il valore RT della potenza attiva P è sempre con segno su qualsiasi livello di modulo (negativo significa esportazione verso la rete). Il comportamento del valore mediato sul periodo (PERIOD_AVG_P_W) dipende dal livello del modulo — vedere la sezione "Livelli dei moduli" più sotto e 02_tiers.md.
Connessione
Il modulo si collega al master con quattro fili sul lato a bassa tensione; tutto ciò che tocca la rete resta all'interno dell'involucro.
| Filo | Scopo |
|---|---|
VCC |
+5 V (4.5..5.5 V), corrente ~15 mA, picco ~25 mA. Regolatore e filtraggio a bordo |
GND |
in comune con il master (obbligatorio) |
SDA, SCL |
I²C, logica a 3.3 V, tollerante a 5 V. Pull-up integrate da 4.7 kΩ verso 3.3 V |
DRDY |
opzionale, drain aperto BASSO per ~10 µs ogni ~100 ms |
L'indirizzo predefinito è 0x50 (7 bit, intervallo di modifica 0x08..0x77), a 100 kHz (UNO / Mega / STM32 / RP2040) o 50 kHz (ESP32 / ESP8266); non usi 400 kHz. L'avvio a freddo fino alla prima misura valida è ~250 ms.
Le regole complete (lunghezza del bus, raccomandazioni sui pull-up su un bus multi-modulo, schemi di cablaggio con host diversi) sono nel capitolo 04 · Connessione.
Livelli dei moduli (scheda rapida)
Il livello BASIC implementa una misura unidirezionale (solo consumo) seguendo la logica di un contatore meccanico classico; la linea STANDARD (STD) è una seconda linea di moduli in commercio con energia con segno (importazione / esportazione):
| Livello | Potenza attiva RT P |
Accumulatore di periodo PERIOD_AVG_P_W |
Contatore Wh della libreria |
|---|---|---|---|
| BASIC | con segno (negativo = esportazione verso la rete, visibile in tempo reale) | ogni finestra di 100 ms della media di P viene limitata a max(P, 0) prima di essere aggiunta all'accumulatore di periodo |
monotono — conta solo il consumo |
| STANDARD (STD) | con segno | import ed export contabilizzati separatamente (banchi di snapshot, oppure i contatori di vita utile persistenti del modulo) | energia netta = importazione − esportazione (wh_net, stdReadEnergy()) |
I dettagli sono nel capitolo 02 · Livelli dei moduli. A livello di libreria si usa la stessa classe RbAmp indipendentemente dal livello; le differenze emergono nei valori che il modulo restituisce.
Misura bidirezionale sul BASIC: dev.energy().wh(ch) della libreria sul livello BASIC fornisce solo il consumo. Se deve contabilizzare separatamente l'esportazione, campioni la potenza RT dev.readPower(0) a ~10 Hz e divida i campioni positivi e negativi in due variabili accumulatore da sé. Un esempio è in 06_examples.md (lo scenario BidirectionalEnergy).
Cosa fa questa libreria
Il compito principale è nascondere lo scambio di protocollo e alleggerire lo sketch dalla routine di lavoro con i registri, l'ordine dei byte e i tempi di assestamento dopo i comandi. Inoltre, la libreria calcola l'energia (Wh): il modulo restituisce solo la potenza media del periodo, e l'integrazione è eseguita dal master sul proprio orologio.
Stai sviluppando per ESPHome? Usa il componente esterno invece di questa libreria direttamente — integra il protocollo rbAmp in modo nativo nella pipeline YAML di ESPHome.
Senza la libreria (accesso diretto ai registri)
// Reading U_RMS — in four transactions.
Wire.beginTransmission(0x50);
Wire.write(0x86);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
uint8_t b0 = Wire.read();
// ...repeat for b1, b2, b3...
float u_rms;
uint8_t buf[4] = {b0, b1, b2, b3};
memcpy(&u_rms, buf, 4);
Con la libreria
float u_rms = dev.readVoltage();
Lettura del periodo — senza la libreria
Wire.beginTransmission(0x50);
Wire.write(0x01); Wire.write(0x27); // CMD_LATCH_PERIOD
Wire.endTransmission();
uint32_t t_latch_ms = millis();
delay(50); // settling time after the command
Wire.beginTransmission(0x50);
Wire.write(0x07);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
if ((Wire.read() & 0x01) == 0) {
// snapshot is stale — t_latch_ms must STILL be recorded,
// otherwise the next snapshot will count Wh over two periods
t_prev_latch_ms = t_latch_ms; // <-- this line is easy to forget
return;
}
// ...read 4 bytes of avg_p, assemble the float, integrate Wh:
// float dt_s = (millis() - t_prev_latch_ms) / 1000.0f;
// E_Wh += avg_p × dt_s / 3600.0f;
Lettura del periodo — con la libreria
RbAmpPeriodSnapshot snap;
if (dev.readPeriodSnapshot(snap)) {
// snap.avg_p[0] is filled,
// dev.energy().wh(0) was incremented by avg_p × master_dt_s / 3600,
// master_dt_ms is accounted for and saved for the next cycle.
}
Internamente la libreria garantisce:
-
Un tempo di assestamento di 50 ms dopo
CMD_LATCH_PERIOD, e una lettura corretta dello snapshot (snapshot atomico lato modulo). -
Un controllo del flag
PERIOD_VALIDprima della lettura. -
Registrare l'orario sull'orologio del master anche su uno snapshot non aggiornato (protegge dal doppio conteggio dei Wh al periodo successivo).
-
Accumulo di energia Wh per canale a doppia precisione.
- Caricamento automatico dei coefficienti di calibrazione quando si seleziona un sensore di corrente tramite
setSensorClass(class)+setCTModel(code)— l'utente non deve conoscere i registri NF/GAIN.
Quando usare la libreria, quando usare l'accesso diretto ai registri
| Attività | Libreria | Accesso diretto ai registri |
|---|---|---|
| Lettura di U / I / P / PF / frequenza | ✅ | solo per il debug con un analizzatore logico |
| Misura dell'energia per periodo | ✅ | solo se i Wh sono memorizzati fuori dalla libreria (ad esempio in un database lato master) |
| Più moduli su un bus | ✅ | — |
| Misura bidirezionale sul BASIC | ✅ (tramite letture RT — vedere 06_examples.md) | alternativa — un suo ciclo di letture RT e integrazione manuale |
| Adattamento a una piattaforma non Arduino | n/a | ✅ — vedi 09 · Riferimento API, la sezione "Dettagli del protocollo sul filo" |
| Limite RAM rigido (AVR Uno) | ~42 B per istanza RbAmp + 63 B per snapshot; fattibile, ma stretto su più moduli (3 moduli × ~42 B + 3 × 63 B ≈ 315 B occupano già una quota notevole del budget di RAM dell'applicazione) |
✅ se l'istanza della libreria non ci sta |
Per tutti i compiti tipici nelle prime righe la libreria è la scelta giusta.
Architettura
Diagrammi di interazione
Il flusso di begin()
Il primo snapshot è un innesco (il modulo restituisce quanto accumulato dall'accensione, il che non è adatto alla misura tariffaria). La libreria registra da sola che questo snapshot va scartato — il codice utente non lo vede mai.
Il flusso di readPeriodSnapshot(snap)
Lo snapshot atomico sul lato modulo garantisce che ogni misura all'interno del periodo cada in esattamente uno snapshot — nessuna duplicazione, nessuna perdita al confine del periodo.
Corrispondenza con l'API a registri diretti
Una tabella per chi migra dal proprio lavoro basato sull'accesso diretto:
| API diretta | Equivalente tramite la libreria |
|---|---|
Lettura manuale di 4 byte + memcpy |
dev.readVoltage() / dev.readPower(ch) |
Wire.write(0x01); Wire.write(0x27); delay(50) |
dev.latchPeriod(); delay(50) (oppure semplicemente dev.readPeriodSnapshot()) |
Verifica di Wire.read(0x07) & 1 |
dev.isPeriodValid() |
La formula manuale E_Wh += avg_p × dt_s / 3600 |
dev.energy().wh(0) — aggiornato automaticamente |
| Configurazione manuale del sensore di corrente tramite l'API a registri diretti | dev.setSensorClass(class) + dev.setCTModel(code) — i preset di fabbrica vengono caricati automaticamente |
Cosa c'è dopo
- 02 · Livelli dei moduli — quale livello per quale compito
- 04 · Collegamento — pull-up, lunghezza del bus, configurazione multimodulo
- 05 · Avvio rapido — il primo sketch funzionante
- 06 · Esempi — rassegna degli sketch pronti all'uso
- 09 · Riferimento API — ogni metodo pubblico
- 10 · Risoluzione dei problemi — quando qualcosa non funziona
Sorgente e problemi: rb-amp/rbamp-arduino · questa pagina nel repo: docs/01_overview.md (v1.6.2)