01 · Panoramica
Cos'è rbAmp
rbAmp è un modulo hardware compatto per la misura di precisione dei parametri della rete in corrente alternata. Dal punto di vista di chi integra, è un normale slave I²C: dai alimentazione, leggi un registro e ottieni un valore pronto all'uso in unità fisiche. Dal lato master non serve alcuna elaborazione del segnale. La calibrazione di fabbrica viene eseguita una sola volta in produzione e memorizzata nella flash del modulo; all'utente resta solo da scegliere il modello di pinza TA (vedi 03_sensor_selection.md) e cablare il bus.
Flusso dei dati (in una riga)
Il punto di forza: le grandezze fisiche arrivano dal modulo già pronte all'uso. Dal lato ESP32 non c'è elaborazione del segnale, né tabelle di calibrazione, né calcoli RMS/potenza. Il componente ESPHome è un client I²C leggero + un accumulatore di energia + uno strato di pubblicazione verso HA. Per il funzionamento di base non serve alcun calcolo lambda:.
rbAmp nell'ecosistema ESPHome
Se hai già usato i contatori di energia integrati (pzemac via UART, atm90e32 via SPI, cse7766 via UART), questo segue esattamente la stessa struttura. Il componente rbamp è un «cittadino ben educato» di ESPHome: usa il trasporto standard i2c:, la sintassi standard sensor.platform: rbamp, gli slot sensore standard con device_class / state_class / unit_of_measurement, e supporta l'intero insieme standard di filtri e proprietà dei sensori.
Confronta l'anatomia (il modello mentale è identico):
# ATM90E32 (SPI meter) — shown for comparison only, not part of an rbAmp config:
spi:
clk_pin: GPIO18
miso_pin: GPIO19
mosi_pin: GPIO23
sensor:
- platform: atm90e32
cs_pin: GPIO5
voltage_a:
name: "Mains Voltage"
power_a:
name: "Mains Power"
# rbAmp (I²C meter) — a separate file, do not paste both:
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
rbamp:
id: meter1
address: 0x50
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current: # power needs voltage AND current declared
name: "Mains Current"
power:
name: "Mains Power"
Le uniche differenze sono il trasporto (i2c: invece di spi:) e il fatto che rbamp: è dichiarato come blocco separato (richiede un id: + address: per un bus multi-modulo). Il resto è ESPHome standard: i nomi degli slot (voltage, current, power, energy, frequency, power_factor) sono riconoscibili, e la personalizzazione (name, update_interval, accuracy_decimals, filters:) funziona come al solito. Per un esempio di personalizzazione dettagliato, vedere 06_examples.md §1.1 "UI1 con personalizzazione — tutte le manopole standard di ESPHome".
Installazione canonica — una flotta multi-modulo
Il caso d'uso principale di rbAmp in ESPHome è monitorare più carichi da un unico master ESP32. Una casa, un laboratorio o un quadro hanno di solito un'unica alimentazione di rete e più derivazioni: uno scaldabagno, un condizionatore, un'auto elettrica, singole stanze. Un rbAmp UI1 viene posto sull'alimentazione e conta potenza ed energia totali; più moduli rbAmp I2/I3 vengono posti sulle derivazioni e contano solo le correnti di ciascun canale.
Tutti i moduli vivono su un singolo bus I²C dell'ESP32 — ciascuno con il proprio indirizzo nell'intervallo 0x50..0x77. Il componente supporta MULTI_CONF = True, quindi un singolo file YAML può dichiarare più blocchi rbamp: e pubblicarli tutti come insiemi di entità indipendenti in Home Assistant.
In questo scenario l'ESP32 è l'unico master: emette un snapshot General-Call condiviso in broadcast quando fleet_gc_enable: true, e tutti i moduli avviano atomicamente un nuovo periodo di accumulo in un unico momento sul filo. Ciò dà una sincronizzazione stretta tra i sotto-contatori — le somme dei canali coincidono con le somme dell'alimentazione entro la durata di un singolo periodo.
Una configurazione con modulo singolo (UI1 sulla rete, senza sotto-contatori) è il caso minimo, non il canone. Con la v1.3 entrambe sono valide; la configurazione multi-modulo è consigliata già nel primo capitolo della documentazione, perché l'80% delle installazioni sul campo è esattamente questo.
Che cosa misuri
| Grandezza | Slot YAML | Intervallo | Accuratezza tipica |
|---|---|---|---|
| Tensione RMS | voltage |
0..300 V | ±0.5% |
| Corrente RMS (per canale) | current / current_1 / current_2 |
da 0 a 100 A (dipende dallo SKU) | ±0.5..1% (modulo) |
| Potenza attiva (con segno) | power / power_1 / power_2 |
±23 kW | ±1% (modulo) |
| Fattore di potenza (con segno) | power_factor / power_factor_1 / power_factor_2 |
−1..+1 | ±0.01 con PF ≈ 1 (carico resistivo) con sensori SCT-013 da 10 A in su; lo sfasamento proprio del sensore da 5 A aggiunge fino a ~0.015 di errore di lettura — un carico puramente resistivo legge ~0.985–0.993 |
| Potenza reattiva (senza segno, √(S² − P²), include la distorsione; nessuna accuratezza dichiarata) | reactive_power / reactive_power_1 / reactive_power_2 |
come P | — |
| Potenza apparente | apparent_power (solo CH0; per CH1/CH2 usa un sensore template di HA, vedi Integrazioni fai-da-te §6) |
come P | ±2% |
| Frequenza di rete | frequency |
50 / 60 Hz (rilevato su BASIC) | — |
| Energia accumulata (Wh) | energy / energy_1 / ... (per canale); energy_total / energy_exported_total / energy_net (STANDARD (STD), tutti i canali) |
64-bit | dipende dall'accuratezza di P |
| Energia reattiva (varh) | reactive_energy / reactive_energy_exported (STANDARD) |
64-bit | — |
Sono le cifre proprie del modulo. Ciò che si legge è il modulo più il sensore che si monta, quindi il totale dipende dal sensore e dal suo valore nominale: i minimi rilevabili, i minimi leggibili e le classi di accuratezza per ciascun valore nominale della famiglia SCT-013 sono pubblicati nella tabella di accuratezza BASIC. I moduli con sensore TA accoppiato in fabbrica e i moduli STD sono specificati separatamente lì.
Ci sono slot per fino a sette canali di corrente (current_3 ... current_6 e i corrispondenti power_N, energy_N, power_factor_N sulle varianti con più canali).
Tutte le grandezze istantanee vengono aggiornate in autonomia dal modulo con un passo di ~100 ms. Sui moduli BASIC l'accumulo dei Wh viene fatto dall'ESP32 in base alla potenza media restituita dal modulo nell'intervallo tra due chiamate update(); sui moduli STANDARD il componente accumula i contatori di energia del modulo. Il componente ESPHome nasconde questi protocolli — l'utente vede solo entità sensore pronte all'uso in Home Assistant.
Che cosa aggiunge il componente ESPHome
- Sensori HA pronti all'uso — ogni slot ha già impostati
device_class,state_classe unità. Il sensoreenergycompare subito nella dashboard Energia, senza configurazione manuale. - Un solo YAML per entrambe le linee di moduli — all'avvio il componente rileva se è collegato un modulo BASIC o STANDARD e ricava dal modulo stesso numero di canali, variante e funzioni.
topology:non serve. Le chiavi che valgono solo per una generazione vengono ignorate con una riga di log sull'altra. - Energia on-device (STANDARD) — il modulo mantiene propri contatori cumulativi; il componente li accumula, quindi i totali sopravvivono ai riavvii sia dell'ESP32 sia del modulo e restano monotoni. Sensori di totale generale:
energy_total,energy_exported_total,energy_net,reactive_energy,reactive_energy_exported.start_current_ua:imposta la corrente al di sotto della quale un canale non conteggia energia. - Persistenza NVS dei Wh — il totale di energia viene scritto nella flash dell'ESP32 ogni 5 minuti (e allo spegnimento pulito, così un riavvio o un OTA non perde l'ultimo intervallo) e ripristinato prima del primo
publish_state. Home Assistant non vede mai uno zero momentaneo dopo un riavvio e non lo interpreta come un azzeramento del contatore. - Configurazione dichiarativa dei sensori — due righe YAML (
sensor_class:+ct_models:per UI3, oppurect_model:per UI1) fissano la famiglia e il modello TA di ciascun canale. I coefficienti di fabbrica vengono caricati automaticamente dal modulo — nessun passaggio di calibrazione nella sequenza di avvio. - Pianificazione delle interrogazioni tramite
PollingComponent::update()con unupdate_intervalconfigurabile (60 s di default). - Cadenze di lettura RT e snapshot disaccoppiate (v1.4+) — la chiave facoltativa
latch_interval:permette al ciclo snapshot → integrazione Wh di girare alla propria cadenza, mentreupdate_interval:continua a controllare con quale frequenza il componente ESPHome legge il blocco in tempo reale V/I/P/PF/Q. Uso tipico:update_interval: 3s+latch_interval: 60s— valori freschi nella dashboard ogni 3 s, carico di snapshot sul bus una volta al minuto. L'integrazione dell'energia non aggiunge errore proprio oltre all'accuratezza della potenza attiva del modulo (l'integrazione lato master usa il dt reale tra gli eventi di snapshot). - Resilienza ai NACK — è implementata una disciplina a tre livelli: 50 kHz per impostazione predefinita, ritentativo per byte e un filtro di integrità per NaN/Inf. Dettagli sotto.
- Assegnazione dell'indirizzo in un'unica fase — la chiave
new_address:cambia l'indirizzo I²C del modulo in un solo ciclo di avvio. Con firmware v1.3 funziona in modalità di produzione senza il blocco del provisioning di fabbrica (commit dell'indirizzo in due fasi, rilevato automaticamente). Comodo per la configurazione in serie di un lotto di dispositivi dopo averli installati in un quadro. - Bus multi-modulo —
MULTI_CONF = Truepermette di dichiarare più blocchirbamp:su un ESP32 e interrogarli tutti a turno. - Sincronizzazione Fleet General-Call (v1.3) — la chiave
fleet_gc_enable: trueabilita la ricezione del broadcast dello snapshot GC dall'ESP32. Tutti i moduli con questo flag e ungroup_id:corrispondente avviano un nuovo periodo simultaneamente. Condizionato dalla capacità; sul firmware legacy registra un avviso e salta senza applicare. Solo moduli BASIC. - Superficie di identità (v1.3) — i metodi pubblici
get_variant_str()/get_capability_hex()/get_uid_hex()/get_firmware_version()/get_last_error_str()sono accessibili dalambda:e tramite untext_sensor.platform: template. Permettono di mostrare in HA la variante corrente del modulo (UI1/UI3/I2…), la bitmap delle capacità, l'UID e la versione del firmware. - Avvio con lettura-confronto-scrittura (v1.3) —
sensor_class:/ct_model:/ct_models:vengono scritti in flash solo se il valore richiesto è diverso da quello memorizzato. La riscrittura della configurazione all'avvio scende da ~2.8 s (installazione a freddo di UI3) a ~0 ms con una configurazione stabile. Il vecchio consiglio di «rimuoverect_model:dal YAML dopo la verifica» è obsoleto — la configurazione è idempotente. - Protezione della calibrazione di fabbrica (v1.8.1+) — su un modulo calibrato in coppia con il proprio sensore montato (
WIRED_CT/BUILTIN_CT) un cambio di classe o di modello dal YAML viene rifiutato con una riga di log. L'opzione di servizioct_model_force: truela scavalca deliberatamente. - Il cambio di portata SCT mantiene la precisione (v1.9) — selezionare un'altra portata SCT-013 tramite
ct_model:mantiene la calibrazione individuale di fabbrica: sul firmware fino alla 1.4.19 il componente completa il cambio con il riavvio richiesto del modulo e scala le letture; i firmware più recenti lo fanno sul modulo.
Architettura
Il motore di misura risiede nel modulo; l'ESP32 funge da ponte verso HA. Sui moduli BASIC le Wh vengono integrate sull'ESP32 rispetto al proprio clock, il che mantiene coerente l'accumulo tra più moduli. I moduli STANDARD mantengono da sé i contatori di energia cumulativa e l'ESP32 li accumula.
Flusso dei dati all'interno di un singolo update()
La descrizione qui sotto è il flusso BASIC. Su un modulo STANDARD il ramo istantaneo è lo stesso; il ramo per periodo viene sostituito da un'unica lettura coerente dei contatori di energia del modulo, la cui differenza rispetto allo snapshot precedente viene sommata ai totali correnti (nessun passaggio di snapshot).
Ogni chiamata update() su un modulo BASIC esegue due rami in parallelo:
Ramo 1 — valori istantanei (blocco RT)
- Controllare il registro di stato. Se il modulo è occupato (avvio, finestra di scrittura flash), saltare senza scrivere.
- Per ogni sensore RT dichiarato, leggere un float32 dal registro corrispondente.
- Filtro di integrità
std::isfinite()— scarta NaN/Inf, che possono derivare da tearing nella lettura di registri non atomici. sensor->publish_state(val).
Sul firmware v1.3 il blocco dei valori istantanei (U / I / P / PF / Q per tutti i canali dichiarati) viene letto in un'unica lettura a raffica con auto-incremento in lettura — una fase di indirizzo seguita dai byte del blocco. Se la raffica fallisce o il firmware non supporta la capacità, il componente ricade sulle letture per registro (4 transazioni per float, ciascuna con la propria fase di indirizzo). La scrittura con auto-incremento non è supportata; le scritture per registro avvengono sempre byte per byte.
Ramo 2 — misura per periodo (accumulo di energia)
- Registra
t_latch = millis(). - Invia il comando di snapshot — chiude il periodo di accumulo corrente e apre subito il successivo. Una singola transazione chiude e apre insieme; nessun campione viene perso al confine.
- Dopo 50 ms (un timeout non bloccante), leggi il flag di validità. Se il modulo non ha ancora finito di integrare (interrogazione più veloce del periodo di integrazione, oppure snapshot obsoleto), salta — il ciclo successivo recupererà l'intervallo mancato.
- Leggi la potenza attiva media sul periodo per ciascun canale.
E_Wh[ch] += avg_p_W[ch] × (t_latch − last_latch_ms_) / 3_600_000.- Aggiorna
last_latch_ms_solo dopo il successo su tutti i canali. - Salva in NVS se sono passati più di 5 minuti dall'ultimo salvataggio.
Il primo snapshot dopo l'avvio azzera l'accumulatore del modulo e calibra il clock master; il suo risultato viene scartato tramite il flag primed_.
Persistenza dell'energia in NVS
I valori accumulati sono memorizzati nella struttura RbAmpPrefData (totale per canale fino a sette canali + esportazione per canale per i canali 0..2):
struct RbAmpPrefData {
double energy_total_wh[7];
double energy_export_wh[3];
} __attribute__((packed));
Sui moduli STANDARD i totali complessivi e gli accumulatori reattivi (energy_total, energy_exported_total, reactive_energy*) risiedono in un secondo slot NVS separato, così i valori per canale non vengono toccati da un aggiornamento. Entrambi gli slot vengono scritti ogni 5 minuti e allo spegnimento pulito (riavvio / OTA).
La chiave NVS deriva dall'ID del componente in XOR con RBAMP_PREF_VERSION (0x52424D31 = «RBM1»). Se la struttura cambia, incrementare la costante di versione scarta in silenzio i dati obsoleti invece di interpretarli male.
All'avvio setup() ripristina i totali prima del primo update(). Se il componente pubblicasse prima 0 Wh e poi saltasse al valore salvato, Home Assistant interpreterebbe il salto come un azzeramento del contatore e inizierebbe un nuovo segmento di storico. Ripristinare prima della prima pubblicazione lo evita.
La frequenza di salvataggio è governata da due condizioni:
- Per tempo — ogni 5 minuti (
SAVE_INTERVAL_MS = 300000). - Per evento — dopo ogni ciclo completo di integrazione riuscito (tutti i canali letti senza NACK) e allo spegnimento pulito.
La perdita di dati nel caso peggiore in caso di improvvisa interruzione di alimentazione dell'ESP32 è di 5 minuti di energia accumulata. Con un carico medio di 60 W sono 5 Wh — sotto la risoluzione della barra giornaliera della dashboard Energia.
Usura della NVS — la flash può "consumarsi"?
Ogni salvataggio scrive ~16 byte nella sezione NVS dell'ESP32. Il livello NVS di ESP-IDF raggruppa le piccole scritture in un unico blocco e cancella una pagina (4 KB) solo quando il blocco è pieno. Con un ciclo di 5 minuti:
| Metrica | Valore |
|---|---|
| Risparmio al giorno | 288 |
| Salvataggi all'anno | ~105120 |
| Dimensione di scrittura | ~16 byte |
| Dimensione della pagina NVS | 4096 byte |
| Cancellazioni di pagina all'anno | ~411 (≈ 105120 × 16 ÷ 4096) |
| Limite di cicli di cancellazione (datasheet della flash NOR dell'ESP32) | 100000 cicli |
| Tempo di guasto (TTF) | ~240 anni per pagina NVS |
La NVS di ESP-IDF esegue inoltre il wear-leveling sulle pagine NVS disponibili (la partizione predefinita ha 4 pagine), il che moltiplica il TTF per ~4×. In pratica: l'usura della NVS con un ciclo di salvataggio di 5 minuti non è un fattore limitante — l'hardware diventerà obsoleto prima.
Quando conviene ridurre la frequenza: se un utente forza SAVE_INTERVAL_MS sotto il valore predefinito (per esempio 30 s) con codice personalizzato, ricalcola il TTF con la stessa formula. Un limite inferiore sicuro per 10 anni di esercizio è ~30 s.
Disciplina dei NACK
Le schede ESP32 che usano il driver ESP-IDF v5 i2c_master (che ESPHome, arduino-esp32 v3.x e MicroPython su ESP32 usano tutti) inviano periodicamente NACK alle letture dal modulo a 100 kHz — in circa il 20% delle transazioni. Lo stesso modulo, ma con un master diverso (ad esempio un altro MCU a 32 bit o un Raspberry Pi), dà 0% di NACK. Il problema sta quindi dal lato master, non dal modulo. I dettagli sono nel riferimento API sotto "I²C electrical discipline" [disciplina elettrica I²C].
C'è una seconda complicazione: quando i2c_master_transmit_receive() restituisce ESP_FAIL a causa di un NACK, il driver IDF v5 non azzera il buffer utente. I dati della transazione precedente restano. Alcuni di questi schemi residui sembrano float plausibili (ad esempio 0x3C 0x2F 0xFB 0x3F → 1.962 V) e superano un controllo ingenuo isfinite().
Il componente implementa tre livelli di mitigazione:
| Livello | Implementazione | Effetto |
|---|---|---|
| Bus a 50 kHz per impostazione predefinita | frequency: 50kHz nel blocco YAML i2c: |
Riduce il tasso di NACK di circa 5× in modo empirico |
| Ritentativo per byte | 3 tentativi, pausa di 5 ms, su ogni byte di ogni float32 | Elimina un NACK transitorio prima che i dati vengano usati |
| Filtro di sanità permissivo | std::isfinite() senza limiti fisici rigidi |
Intercetta NaN/Inf/denormali dal buffer obsoleto; lascia passare i valori validi di caso limite (brownout, disconnessione) |
Con tutti e tre i livelli attivi il componente raggiunge oltre il 99% di letture valide sul banco alla frequenza consigliata di 50 kHz. Il firmware v1.1 e v1.3 hanno rafforzato la finestra di ripristino I²C del modulo, ma 50 kHz resta l'impostazione consigliata sui master basati su ESP-IDF perché l'interazione di temporizzazione del driver persiste a 100 kHz.
La famiglia di librerie rbAmp
Questo componente è un membro della famiglia multipiattaforma di librerie client rbAmp. Implementano tutte lo stesso protocollo di filo (riferimento API).
| Piattaforma | Repository |
|---|---|
| ESPHome (questo componente) | rb-amp/rbamp-esphome |
| Arduino / arduino-esp32 | rb-amp/rbamp-arduino |
| ESP-IDF | rb-amp/rbamp-esp-idf |
| Python (CPython + MicroPython) | rb-amp/rbamp-python |
Tutte le librerie usano le stesse convenzioni di filo — scritture byte per byte con lettura a raffica opzionale, la stessa macchina a stati di snapshot per la misura per periodo, lo stesso rilevamento della variante SKU all'avvio e gli stessi codici REG_ERROR. Il codice di una qualsiasi di queste piattaforme si porta su un'altra con una traduzione sintattica meccanica — la logica del protocollo è identica. Vedere 09 · API reference per la mappa dei registri canonica.
SKU supportati
| Variante | Canale di tensione | Canali di corrente | Potenza | Slot ESPHome disponibili |
|---|---|---|---|---|
| UI1 | sì | 1 | sì | voltage, current, power, energy, frequency, power_factor, reactive_power, apparent_power |
| UI2 | sì | 2 | sì | + current_1, power_1, energy_1, power_factor_1, reactive_power_1 |
| UI3 | sì | 3 | sì | + current_2, power_2, energy_2, power_factor_2, reactive_power_2 |
| I1 | no | 1 | no | current, frequency |
| I2 | no | 2 | no | + current_1 |
| I3 | no | 3 | no | + current_2 |
I moduli con più di un ingresso di tensione usano gli slot per fase (voltage_a/b/c, current_a/b/c, ...) — vedi 09 §2.2; i due gruppi non possono essere mescolati in un unico blocco sensor:.
Sulle varianti solo-I, gli slot power, energy e power_factor richiedono uno slot voltage dichiarato (verificato dal validatore dello schema) — dichiarali solo sugli SKU UI*.
Cosa c'è dopo
- 02_tiers.md — le linee di moduli BASIC / STANDARD (STD) e quali chiavi YAML sono disponibili su ciascuna
- 03_sensor_selection.md — scelta della pinza TA e comportamento delle chiavi
ct_model:/ct_models: - 04_hardware.md — pinout GPIO, pull-up, bus multi-modulo
Fonte e segnalazioni: rb-amp/rbamp-esphome · questa pagina nel repository: docs/01_overview.md (v1.9.1)