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

01 · Panoramica

Catena del segnale rbAmp: sensore → modulo → I²C → master → cloud / Home Assistant

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 RbAmpStaleError e 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

Un modulo sull'alimentazione di rete e un modulo per ogni sotto-carico condividono un bus I²C con il master, che li interroga tutti con un'unica chiamata del fleet.

  • 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 (oppure I2 / 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 bilancio mains − Σ(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.

Sicurezza

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
Nota

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.

Nota

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)

Python
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

Python
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

Python
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

Python
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 valid prima della lettura; su un'istantanea non aggiornata solleva RbAmpStaleError.

  • 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 — float a 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

Dove si trova uno script Python: script, pacchetto rbamp, backend I²C e modulo rbAmp, con la velocità I²C per ciascun host.

Text
┌─────────────────────────────────────────────────────┐
│  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.

Gerarchia delle eccezioni del pacchetto rbamp: ogni errore deriva da RbAmpError, che deriva da OSError.

Lo schema Python standard:

Python
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()

Sequenza di transazioni sul bus che begin() esegue: legge la versione, rileva la linea del modulo, invia lo snapshot di priming, poi ritorna.

Text
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()

Sequenza di read_period_snapshot(): acquisisce l'istantanea del periodo, legge il blocco dell'istantanea, integra l'energia sul master per BASIC o legge i contatori interni del dispositivo per STD.

Text
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


Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repository: docs/01_overview.md (v1.6.1)