01 · Panoramica
rbAmp è un modulo hardware compatto per la misura di precisione dei parametri della rete CA tramite interfaccia I²C. È costruito attorno a un microcontrollore con front-end analogico isolato integrato e calibrazione di fabbrica memorizzata in flash.
Cos'è rbAmp
Lo scopo principale della libreria — monitorare più carichi
components/rbamp è progettato per lavorare con un gruppo di moduli su un singolo bus I²C contemporaneamente, anziché per controllare un singolo dispositivo. Lo scenario canonico è un modulo principale all'ingresso di rete più N moduli su singoli carichi, tutti sullo stesso bus, guidati da un solo ESP32. La libreria offre un handle della flotta: un unico oggetto con cui scansionare il bus, interrogare ogni modulo in una sola chiamata, ottenere la potenza totale consumata e il bilancio "ingresso − Σ(carichi)", intercettare gli errori per modulo e — quando serve — sincronizzare gli snapshot di periodo con un comando broadcast.
I moduli multi-canale sono supportati anche — i soli corrente I2 / I3 (2 / 3 canali di corrente) e quelli dotati di tensione UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 canali di corrente, con potenza, PF e Wh per canale). Ogni canale ha il proprio modello di sensore CT. È tipico per un sotto-quadro in cui un unico punto di installazione monitora più linee: un modulo fornisce una ripartizione per canale senza un modulo separato su ciascuna.
Dettaglio architetturale importante. Potenza e Wh richiedono una variante UI; un bilancio «rete meno somma dei carichi» richiede un modulo UI su ogni carico. Le varianti I (I1/I2/I3) misurano solo corrente — non hanno tensione, 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» (energia totale) è svolto da una sola UI1 all'ingresso di rete, mentre 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).
Lavorare con un singolo modulo è il caso minimo di questa stessa libreria: rbamp_handle_t è il blocco su cui è costruita la flotta. Se ha un solo modulo sul bus, usa lo stesso handle direttamente — non serve l'API di flotta.
Lo scenario dell'80% — rete principale + N carichi secondari
- 1 modulo all'ingresso (rete) — consumo totale e qualità della rete.
- N moduli su singoli carichi — contabilità per canale.
- Anche i moduli multicanale si adattano a questo caso: un solo UI2 / UI3 / UI5 / UI7 (oppure I2 / I3) può misurare più carichi, ciascuno sul proprio canale — N moduli non devono necessariamente corrispondere a N carichi.
-
Una sola chiamata di flotta
rbamp_fleet_poll_all()interroga tutto; il bilanciomains − Σ(sub_loads)rivela il «resto» (consumo di fondo, carichi non contabilizzati, dispersioni). -
Un unico timestamp master condiviso → contabilità Wh corretta senza deriva tra moduli (vedi 02_tiers.md e la sezione sull'orologio master in 09_api_reference.md).
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 | float, V | 0…300 V |
| Tensione di picco U_peak | float, V | 0…450 V |
| Corrente efficace RMS I_rms | float, A | dipende dal sensore selezionato — vedi 03_sensor_selection.md |
| Corrente di picco I_peak | float, A | dipende dal sensore selezionato |
| Potenza attiva P (con segno in RT) | float, W | dipende dal sensore selezionato |
| Fattore di potenza PF | float | −1…+1 |
| Frequenza di rete | uint8, Hz | 50 / 60 Hz (rilevati) |
| P media su un periodo | float, W | come P |
Il valore RT della potenza attiva P è sempre con segno su qualsiasi linea di moduli (negativo = esportazione verso la rete). Il comportamento del valore mediato sul periodo (avg_p[ch] in rbamp_period_snapshot_t) dipende dalla linea del modulo — vedi la sezione "Linee di moduli" sotto e 02_tiers.md.
Cablaggio
Il modulo si collega al master con quattro fili sul lato LV. Il riferimento di rete singolo (l'ingresso di tensione L/N sulle varianti UI*) sta dietro un partitore isolato galvanicamente, e la pinza CT si accoppia magneticamente senza contatto elettrico; vedi 04 · Cablaggio, "Collegamento di rete e CT" (la tensione di rete può essere letale — legga prima l'avvertenza lì).
| Filo | Scopo |
|---|---|
VCC |
+5 V (4.5..5.5 V), ~15 mA, picco ~25 mA. Regolatore e filtraggio di 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 |
facoltativa, open-drain BASSA per ~10 µs ogni ~100 ms |
L'indirizzo predefinito è 0x50 (7 bit, intervallo impostabile 0x08..0x77), la velocità consigliata è 50 kHz su ESP32 (vedi la sezione sulla disciplina di ritentativo + plausibilità qui sotto). L'avvio a freddo fino alla prima misura valida è di ~250 ms.
Le regole complete (lunghezza del bus, raccomandazioni sui pull-up su un bus multimodulo, schemi di cablaggio per i vari target ESP32) sono nel capitolo 04 · Cablaggio.
Linee di moduli (riepilogo rapido)
I moduli BASIC e STANDARD (STD) sono in produzione. Il BASIC segue la logica di un contatore meccanico classico — contabilità a senso unico (solo consumo); lo STD conserva contatori di energia con segno:
| Livello | Potenza attiva RT P |
Accumulatore di periodo per canale avg_p[ch] |
Contatore Wh del componente |
|---|---|---|---|
| BASIC | con segno (negativo = esportazione verso la rete, visibile in tempo reale) | ciascuna finestra di 100 ms della potenza P media viene limitata a max(P, 0) prima di essere aggiunta all'accumulatore di periodo |
monotona — contabilizzazione solo del consumo |
| STANDARD (STD) | con segno; anche potenza reattiva e apparente | banchi di snapshot, oppure differenze di contatori — l'esportazione viene conservata (importazione ed esportazione contate separatamente) | Valore netto con segno (negativo = esportazione netta) |
Per i dettagli, vedi il capitolo 02 · Linee di moduli. A livello di componente lo stesso handle rbamp_handle_t viene usato indipendentemente dalla classe — rbamp_begin() rileva la linea del modulo (rbamp_line()); le differenze emergono nei valori che il modulo restituisce e nelle chiamate rbamp_std_* aggiuntive che offre un modulo STD.
Contabilità bidirezionale su BASIC: rbamp_energy_wh(dev, ch) sulla classe BASIC fornisce solo il consumo. Se deve contabilizzare separatamente l'immissione, campioni la potenza RT rbamp_read_power(dev, 0, &p) a circa 10 Hz e divida lei stessa i campioni positivi e negativi in due variabili accumulatrici. Vedi l'esempio in 06_examples.md (Scenario 9, «Misura bidirezionale sul lato master»).
Cosa fa questo componente
esp_timer_get_time().
Il componente si occupa anche della contabilizzazione del periodo: esegue uno snapshot, attende che il modulo si assesti, verifica che lo snapshot sia valido e integra i Wh rispetto al clock master (rbamp_read_period_snapshot() e rbamp_energy_wh(), vedi 05 · Avvio rapido Passo 5). Il confronto a livello di registri ("senza il componente"), lo schema dell'architettura, gli schemi di interazione e la tabella di mappatura sono in 09 · Riferimento API, appendice "Sotto il cofano".
Logging e Kconfig
A differenza della libreria Arduino, dove il flusso di log si configura a runtime (setLogStream(&Serial)), qui si usa il normale schema ESP-IDF: il componente registra con il tag "rbamp" tramite esp_log. Il livello di log è compilato tramite la scelta Kconfig CONFIG_RBAMP_LOG_LEVEL_* (NONE / ERROR / WARN / INFO / DEBUG, INFO per impostazione predefinita). Con NONE le stringhe di log vengono rimosse del tutto dal binario.
Anche il filtro a runtime funziona (tramite esp_log_level_set("rbamp", ...)), ma è limitato dall'alto dal livello di compilazione.
Sei simboli CONFIG_RBAMP_* sono disponibili in idf.py menuconfig → Configurazione componenti (Component config) → rbAmp client:
| Simbolo | Scopo | Predefinito |
|---|---|---|
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ |
Frequenza SCL per il bus condiviso | 50000 (50 kHz) |
CONFIG_RBAMP_I2C_TIMEOUT_MS |
timeout di trasmissione/ricezione | 100 ms |
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS |
tentativi di ritentativo per lettura a un byte | 3 |
CONFIG_RBAMP_NACK_RETRY_GAP_MS |
intervallo tra i tentativi di retry | 5 ms |
CONFIG_RBAMP_DISABLE_ENERGY |
rimuove l'accumulatore Wh dalla compilazione | n |
CONFIG_RBAMP_LOG_LEVEL_* |
livello di compilazione delle stringhe di log | INFO |
Per maggiori dettagli, vedi 09 · Riferimento API, sezione "Configurazione in fase di compilazione".
Cosa c'è dopo
- 02 · Linee di moduli — quale classe per quale attività
- 04 · Cablaggio — pull-up, lunghezza del bus, piedinatura della famiglia ESP32
- 05 · Guida rapida — il suo primo progetto funzionante
- 06 · Esempi — percorsi guidati dei progetti IDF pronti
- 09 · Riferimento API — ogni funzione pubblica
- 10 · Risoluzione dei problemi — quando qualcosa non funziona
Fonte e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repository: docs/01_overview.md (v1.7.3)