01 · Panoramica
Cos'è rbAmp
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.
Dal punto di vista di chi integra, il modulo si comporta come uno slave I²C standard: crea RbAmp(bus, 0x50), chiama dev.begin() e ottiene valori pronti all'uso tramite proprietà e metodi. Lo stesso sorgente gira su MicroPython (con machine.I2C) e su CPython (con smbus2) — il backend viene scelto automaticamente in base al tipo dell'oggetto bus.
Termini usati in questa documentazione
- Linea del modulo — BASIC o STANDARD (STD): la linea di prodotto del modulo (vedi 02).
- Variante — UI1, UI2, UI3, I1, I2, I3 (e UI5/UI7): quanti canali di corrente e se il modulo ha un ingresso di tensione.
- Versione del firmware / versione dell'immagine del modulo — il software dentro il modulo; alcune chiamate STD richiedono un'immagine abbastanza recente.
- Lettura RT — una lettura istantanea (tensione, corrente, potenza), aggiornata dal modulo ogni 100 ms.
- Periodo / snapshot — uno snapshot congela i totali del periodo finora e avvia il successivo; uno snapshot di periodo è il risultato congelato (potenza media per canale).
- Istantanea non aggiornata — il modulo non aveva un'istantanea nuova pronta; la libreria solleva
RbAmpStaleErrore la successiva istantanea valida copre l'intero intervallo. - Primer — la prima istantanea presa da
begin(); scarta ciò che si è accumulato dall'accensione. - GC (General Call) — un unico frame I²C di broadcast che fa prendere lo snapshot a più moduli nello stesso istante.
- DRDY — pin opzionale che impulsa circa ogni 100 ms quando nuovi dati RT sono pronti.
Un modulo o molti
Un modulo o molti: inizi con un RbAmp; usi RbAmpFleet per più moduli. Il pacchetto Python rbamp funziona con un solo modulo e anche con un gruppo di moduli su un unico bus I²C. Lo scenario canonico multi-modulo è un modulo master sull'alimentazione di rete più N moduli sui singoli carichi, tutti su un bus, guidati da un unico ESP32 / RPi / SBC. La libreria fornisce la classe RbAmpFleet — un unico oggetto attraverso il quale si scansiona il bus, si interrogano tutti i moduli con una chiamata, si ottengono la potenza totale e il bilancio "rete − Σ(consumatori)", si intercettano gli errori di ciascun modulo e, quando serve, si sincronizzano le istantanee di periodo con un comando in 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 della stessa libreria: la classe RbAmp è il blocco su cui si appoggia RbAmpFleet. Se ha un solo modulo sul bus, usa direttamente quello stesso handle — l'API del fleet non serve.
Lo scenario dell'80% — rete principale + N carichi secondari
- 1 modulo sulla linea di alimentazione (rete) — consumo totale 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.poll_all()interroga tutto; il bilanciomains − Σ(sub_loads)mostra "il resto" (consumo di fondo, carichi non misurati, dispersioni). -
Un unico riferimento temporale del master → contabilità corretta dei Wh senza deriva tra moduli.
Dettaglio architetturale importante. 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 configurazione canonica, il ruolo di «contatore di rete» (misura dell'energia) è svolto da un unico UI1 sull'alimentazione di rete; 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, veda il capitolo 06 · Esempi, scenario 1 ("Rete + N sotto-carichi — il canone dell'80%"). Per l'API, veda il capitolo 09 · Riferimento API, sezione "Gestore del fleet".
Cosa misura rbAmp
| Grandezza | Tipo Python | 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 scelto — 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 | int, Hz |
50 / 60 Hz (rilevati) |
| P media sul periodo | float, W |
come P |
Il valore RT della potenza attiva P è sempre con segno su qualsiasi linea di moduli (negativo significa export verso la rete). Il comportamento del valore mediato sul periodo (snap.avg_p[ch] in RbAmpPeriodSnapshot) dipende dalla linea del modulo — vedere la sezione "Linee di moduli" più sotto e 02_tiers.md.
Cablaggio
Il modulo si collega all'host con quattro fili sul lato a bassa tensione; tutto ciò che tocca la rete resta dentro il contenitore.
| Filo | Scopo |
|---|---|
VCC |
+5 V (4.5..5.5 V), corrente ~15 mA, picco ~25 mA |
GND |
in comune con l'host (obbligatorio) |
SDA, SCL |
I²C, logica 3.3 V, tolleranza a 5 V. Pull-up integrati da 4.7 kΩ |
DRDY |
facoltativa, open-drain BASSA per ~10 µs ogni ~100 ms |
L'indirizzo predefinito è 0x50 (7 bit, intervallo di modifica 0x08..0x77). La velocità consigliata per MicroPython su ESP32 è 50 kHz; per CPython tramite l'I²C del kernel è di solito 100 kHz (lo schema di NACK non si presenta tramite l'API del kernel Linux).
Le regole complete (lunghezza del bus, raccomandazioni di pull-up su un bus multi-modulo, schemi di cablaggio per RPi / ESP32 / RP2040 / STM32) sono nel capitolo 04 · Cablaggio.
Linee di moduli (riepilogo rapido)
I moduli BASIC e STANDARD (STD) sono in produzione; STANDARD è supportato da questa libreria dalla 1.6.0.
BASIC è una misura del solo consumo (unidirezionale), secondo la logica di un classico contatore meccanico:
| Linea di moduli | Potenza RT dev.power[ch] |
Accumulatore di periodo snap.avg_p[ch] |
Contatore Wh del pacchetto |
|---|---|---|---|
| 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 — misura solo del consumo |
| STANDARD (STD) | con segno | stesse chiamate di BASIC; la sorgente sono i contatori di energia del modulo o il banco latch 0, scelti a begin(); l'energia è netta (l'esportazione sottrae) |
dev.energy integra il periodo; i totali del modulo: read_std_energy() (vedi capitolo 02) |
Per i dettagli, veda il capitolo 02 · Linee di moduli. A livello di pacchetto si usa la stessa classe RbAmp indipendentemente dalla linea del modulo; le differenze emergono nei valori restituiti dal modulo.
Misura bidirezionale su BASIC: dev.energy.wh(ch) sulla linea di moduli BASIC dà solo il consumo. Se serve contabilizzare l'esportazione separatamente, campionare la potenza RT dev.power[0] (oppure dev.read_power(0)) a ~10 Hz e dividere i campioni positivi e negativi in due variabili accumulatrici proprie. Per un esempio, vedi 06_examples.md, scenario «Misura bidirezionale lato master».
Che cosa fa questo pacchetto
Il compito principale è nascondere lo scambio di protocollo e sollevare il codice utente dalla routine di lavorare con i registri, l'ordine dei byte e i tempi di assestamento dopo i comandi. Inoltre il pacchetto calcola l'energia (Wh) — il modulo restituisce solo la potenza media per periodo, e il master esegue l'integrazione usando time.monotonic() / time.ticks_us().
Senza il pacchetto (accesso diretto ai registri tramite smbus2)
import struct
from smbus2 import SMBus, i2c_msg
# Read U_RMS — burst-read 4 bytes (auto-increment is supported on reads).
with SMBus(1) as bus:
buf = bytes(bus.read_i2c_block_data(0x50, 0x86, 4))
u_rms = struct.unpack("
Con il pacchetto
from smbus2 import SMBus
from rbamp import RbAmp
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
dev.begin()
u_rms = dev.voltage # property (one call = one transaction)
# or: u_rms = dev.read_voltage()
Lettura di un periodo — senza il pacchetto
import time, struct
with SMBus(1) as bus:
# Snapshot + 50 ms settle + ready-flag check + assemble 4 bytes of avg_p
bus.write_byte_data(0x50, 0x01, 0x27) # REG_COMMAND, CMD_LATCH_PERIOD
t_latch = time.monotonic()
time.sleep(0.050) # settle
bus.write_byte(0x50, 0x07)
if bus.read_byte(0x50) & 0x01 == 0:
# snapshot is stale — keep the previous t_prev_latch, so the next
# good snapshot covers the full interval
raise SystemExit("stale snapshot")
# ...read 4 bytes of avg_p, struct.unpack, integrate Wh:
# dt_s = time.monotonic() - t_prev_latch
# E_Wh += avg_p * dt_s / 3600
Lettura di un periodo — con il pacchetto
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
dev.begin()
snap = dev.read_period_snapshot() # snapshot + settle + valid + read + Wh tick
print(snap.avg_p[0], "W")
print(dev.energy.wh(0), "Wh")
Internamente il pacchetto garantisce:
- Un'attesa di stabilizzazione di 50 ms dopo
CMD_LATCH_PERIOD, e una lettura corretta dell'istantanea. -
Un controllo del flag
validprima della lettura; su un'istantanea non aggiornata sollevaRbAmpStaleError. -
Mantenere il timestamp precedente su uno snapshot non aggiornato, così lo snapshot buono successivo copre l'intero intervallo e i Wh restano esatti.
-
Accumulo dei Wh per canale in doppia precisione (CPython —
floata 64 bit; MicroPython — dipende dalla build, vedi 04 · Cablaggio). -
Caricamento automatico dei coefficienti di taratura quando il sensore di corrente viene selezionato tramite
dev.set_sensor_class(cls)+dev.set_ct_model(code)— l'utente non deve conoscere i registri di taratura interni.
Quando usare il pacchetto e quando l'accesso diretto al bus
| Attività | Pacchetto | Accesso diretto tramite smbus2 / machine.I2C |
|---|---|---|
| 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 dal pacchetto (ad esempio in un DB lato master) |
| Più moduli su un bus | ✅ (tramite snapshot sequenziali + assestamento condiviso) | — |
| Misura bidirezionale sul BASIC | ✅ (tramite letture RT — vedere 06_examples.md) | alternativa — un proprio ciclo di lettura RT |
| Streaming asincrono tramite asyncio / uasyncio | ✅ (async for snap in dev.stream_period()) |
difficile — nessun wrapper asincrono integrato |
| Porting su un'altra piattaforma | n/a | ✅ — vedere rbamp-docs (mappa dei registri e protocollo) |
Per tutte le attività tipiche delle prime righe, il pacchetto è la strada giusta.
Architettura
┌─────────────────────────────────────────────────────┐
│ User code (.py) │
│ from smbus2 import SMBus │
│ from rbamp import RbAmp, RbAmpSensorClass │
│ with SMBus(1) as bus, RbAmp(bus, 0x50) as dev: │
│ # __enter__ calls dev.begin() itself; │
│ # explicit begin() shown for transparency │
│ dev.set_sensor_class(RbAmpSensorClass.SCT_013)│
│ dev.set_ct_model(3) │
│ snap = dev.read_period_snapshot() │
│ dev.energy.wh(0) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Public API of the RbAmp class (rbamp/__init__.py) │
│ ┌─────────────────────────────────────────────┐ │
│ │ Lifecycle: begin / probe / wait_ready │ │
│ │ RT properties: .voltage / .power[ch] / │ │
│ │ .current[ch] / .frequency │ │
│ │ RT methods: read_voltage / read_power / │ │
│ │ read_all │ │
│ │ Period: latch_period / │ │
│ │ read_period_snapshot │ │
│ │ Async: stream_period │ │
│ │ Configuration: set_sensor_class / │ │
│ │ set_ct_model │ │
│ │ Diagnostics: retry_exhaustion_count / │ │
│ │ sanity_reject_count │ │
│ │ Exceptions: RbAmpError → IOError / │ │
│ │ TimeoutError / StaleError / │ │
│ │ ParamError / ModeError / │ │
│ │ VersionError │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Backend selection (inside __init__): │ │
│ │ bus.readfrom_mem → MachineI2CBackend │ │
│ │ bus.read_byte_data → SMBusBackend │ │
│ │ duck-typed → custom (FTDI / mocks) │ │
│ └─────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────┐ │
│ │ Instance state: │ │
│ │ • RbAmpEnergy — Wh accumulator │ │
│ │ • RbAmpSnapshot / RbAmpPeriodSnapshot │ │
│ │ • Time of last snapshot (monotonic) │ │
│ └─────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Backend — native I²C on the host platform: │
│ smbus2 (CPython) / machine.I2C (MicroPython) │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ rbAmp module at address 0x50 │
│ • U / I / P / PF measurement pipeline (~100 ms) │
│ • Period accumulator (atomic CMD_LATCH_PERIOD) │
└─────────────────────────────────────────────────────┘
Gerarchia delle eccezioni
Diversamente dalla libreria Arduino (dove gli errori sono riportati tramite lastError() + un codice di ritorno) e dal componente ESP-IDF (dove sono riportati tramite esp_err_t), il pacchetto Python usa il classico pattern Python — una gerarchia di eccezioni.
Lo schema Python standard:
from rbamp import RbAmp, RbAmpStaleError, RbAmpError
try:
snap = dev.read_period_snapshot()
except RbAmpStaleError:
# Snapshot is stale — the package keeps the previous timestamp, the next good snapshot covers the full interval
continue
except RbAmpError as e:
log.warning("rbAmp failure: %s", e)
Diagrammi di interazione
Il flusso di dev.begin()
code RbAmp Backend rbAmp module
│ │ │ │
├─dev.begin()► │ │
│ ├─read_u8(REG_VERSION)► │
│ │ ├──[0x50, 0x03]────────►│
│ │ │◄────────────────ACK───┤
│ │ ├──[read 1 byte]───────►│
│ │ │◄──────────────[0x04]──┤
│ │◄─────── version_byte ─────┤ │
│ │ │ │
│ ├─read_float_le(U_RMS)►(4 single-byte reads) │
│ │ → 226.3 V │ │
│ │ → has_voltage_hw = True │
│ │ │ │
│ ├─write_cmd(LATCH)──►│ │
│ │ ├──[0x50, 0x01, 0x27]──►│
│ │ sleep(50ms) │ │
│ │ │ │
│◄────self────┤ (or raises RbAmpIOError on failure) │
Il primo snapshot è un primer (il modulo restituisce quanto ha accumulato dall'accensione, inadatto alla misura tariffaria). Il pacchetto registra da sé che questo snapshot va scartato — il codice utente non lo vede mai.
Il flusso di dev.read_period_snapshot()
code RbAmp Backend rbAmp module
│ │ │ │
├─read_period_snapshot()► │ │
│ ├─write_cmd(LATCH)──►│ t_now = time.monotonic()
│ │ │ │
│ │ sleep(50ms) │ │
│ │ │ │
│ ├─is_period_valid()─►│ │
│ │ → True │ │
│ │ │ │
│ ├─read_float_le(AVG_P0)►(4 reads) │
│ ├─read_float_le(MAX_P0)►(4 reads) │
│ ├─read_u32_le(LATCH_MS)►(4 reads) │
│ │ │ │
│ │ dt = t_now − last_latch │
│ │ energy.wh[ch] += avg_p[ch] × dt / 3600 │
│ │ last_latch = t_now │
│ │ │ │
│◄─snap──────┤ │ │
Lo snapshot atomico lato modulo garantisce che ogni misura di un periodo finisca in esattamente uno snapshot — nessuna duplicazione, nessuna perdita al confine di periodo.
Corrispondenza con l'API a registri diretti
Una tabella per chi migra dal proprio lavoro di accesso diretto:
API diretta (smbus2 / machine.I2C) |
Equivalente del pacchetto |
|---|---|
Lettura manuale di 4 byte + struct.unpack |
dev.voltage (proprietà) oppure dev.read_voltage() |
read_byte per canale × 4 |
dev.power[ch] (_ChannelProxy) oppure dev.read_power(ch) |
write_byte_data(0x50, 0x01, 0x27); time.sleep(0.05) |
dev.latch_period(); time.sleep(0.05) (oppure direttamente dev.read_period_snapshot()) |
Verifica di read_byte(0x07) & 1 |
dev.is_period_valid() oppure il campo snap.valid |
Formula manuale E_Wh += avg_p × dt / 3600 |
dev.energy.wh(0) — aggiornato automaticamente |
| Configurazione manuale del sensore di corrente tramite l'API a registri diretti | dev.set_sensor_class(cls) + dev.set_ct_model(code) — i preset di fabbrica vengono caricati automaticamente |
Cosa c'è dopo
- 02 · Linee di moduli — quale linea di moduli per quale attività
-
04 · Cablaggio — pull-up, lunghezza del bus, cablaggio per host (RPi / ESP32 / RP2040 / STM32)
-
05 · Avvio rapido — il primo script funzionante per entrambi i backend
-
06 · Esempi — una guida agli scenari pronti
-
09 · Riferimento API — ogni classe pubblica + metodo + proprietà + eccezione
-
10 · Risoluzione dei problemi — quando qualcosa non funziona
Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repository: docs/01_overview.md (v1.6.1)