rbAmp
IT
Negozio
Docs
Aggiornato · Modifica su GitHub [Edit on GitHub]

01 · Panoramica

Catena del segnale dalla pinza di corrente attraverso il modulo rbAmp e I²C fino al master e poi al cloud o a Home Assistant.

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

Un modulo sull'alimentazione di rete e un modulo per ogni carico secondario, tutti su un bus I²C condiviso letto da un unico master.

  • 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 (oppure I2 / I3) può misurare più carichi, ciascuno sul proprio canale — N moduli non devono significare N carichi.
  • Una sola chiamata fleet.pollAll() interroga tutto; il bilancio mains − Σ(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).

Sicurezza

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
Nota

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.

Nota

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.

Nota

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)

C++
// 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

C++
float u_rms = dev.readVoltage();

Lettura del periodo — senza la libreria

C++
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

C++
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_VALID prima 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

Dove si trova lo sketch: sketch, libreria RbAmp, Wire (I²C) e il modulo rbAmp all'indirizzo predefinito 0x50.

Diagrammi di interazione

Il flusso di begin()

Sequenza di begin(): lettura della versione, rilevamento della linea, snapshot di innesco (scartato), poi pronto.

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)

Sequenza di readPeriodSnapshot(): la libreria chiude il periodo sul modulo, legge lo snapshot, integra l'energia sull'orologio del master e restituisce il risultato allo sketch.

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


Sorgente e problemi: rb-amp/rbamp-arduino · questa pagina nel repo: docs/01_overview.md (v1.6.2)