rbAmp
IT
Negozio
Docs
Aggiornato il · Modifica su GitHub

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

Panoramica di come l'applicazione, la libreria, il bus I²C e i moduli rbAmp si incastrano.

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.

Sicurezza

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

Un master su un bus I²C condiviso con un modulo di rete all'alimentazione e moduli di sotto-carico sui singoli rami, una pinza per modulo.

  • 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 bilancio mains − Σ(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
Nota

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.

Nota

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

Cronologia di finestre di misura consecutive da 100 ms, dei eventuali impulsi di dati pronti e di uno snapshot di periodo attivato dal master.
Il suo compito principale è nascondere lo scambio di protocollo e sollevare l'applicazione dalla routine di gestione dei registri, dell'ordine dei byte e dei tempi di assestamento dopo i comandi. Inoltre, il componentecalcola l'energia (Wh)— il modulo restituisce solo la potenza media di periodo, e l'integrazione viene fatta dal master tramiteesp_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


Fonte e segnalazioni: rb-amp/rbamp-esp-idf · questa pagina nel repository: docs/01_overview.md (v1.7.3)