02 · Linee di moduli
Cos'è una linea di moduli
I moduli rbAmp sono disponibili in due linee: BASIC e STANDARD (STD). Una linea di moduli è un pacchetto completo di revisione hardware e firmware, non un flag software. Passare da una linea all'altra richiede un cambio fisico di SKU, non un aggiornamento firmware.
Dal punto di vista del pacchetto e del codice utente: una sola classe RbAmp serve ogni linea di moduli, e i lettori comuni (voltage, current, power, power_factor, frequency) funzionano su tutti. La linea del modulo viene rilevata automaticamente a begin(). I moduli STANDARD (STD) espongono inoltre le chiamate solo-STD (energia sul dispositivo e così via, vedi sotto); chiamarne una su un modulo BASIC solleva RbAmpNotSupportedError.
Stato attuale
I moduli BASIC e STANDARD sono supportati da questa libreria (STANDARD dalla 1.6.0).
| Linea di moduli | Spedizione |
|---|---|
| BASIC | ✅ sì |
| STANDARD (STD) | ✅ sì (supportato da questa libreria dalla 1.6.0) |
BASIC — Linea di moduli di misura del consumo, livello base
Hardware
Un percorso analogico economico adatto ai carichi domestici tipici. Il modulo include un front-end analogico isolato, un regolatore di alimentazione di bordo e la calibrazione di fabbrica memorizzata in flash.
Comportamento del firmware
La logica di un classico contatore a disco meccanico — il conteggio va solo in avanti; l'export verso la rete non viene sottratto.
I tre "livelli" dei valori di potenza attiva si comportano in modo diverso:
| Segnale | Significato | Comportamento su BASIC |
|---|---|---|
dev.power[ch] / dev.read_power(ch) |
potenza attiva RT istantanea, aggiornamento ogni ~100 ms | con segno — un valore negativo è visibile in tempo reale (esportazione) |
snap.avg_p[ch] (da dev.read_period_snapshot()) |
potenza media sul periodo | ciascuna finestra media-P di 100 ms viene limitata a max(P, 0) prima di essere aggiunta all'accumulatore di periodo |
dev.energy.wh(ch) |
Wh accumulati dal pacchetto | monotono — solo consumo; l'esportazione non viene conteggiata |
In altre parole: l'utente vede l'export nella lettura RT, ma non è presente nel contatore dei Wh del pacchetto su BASIC.
Applicazioni tipiche
-
Famiglie senza produzione propria (senza pannelli solari, turbine eoliche, sistemi a batteria)
-
Sottocontabilizzazione di carichi puramente consumatori (scaldabagni, motori, elettrodomestici)
-
Monitoraggio dei consumi di un edificio dove la misura bidirezionale non è richiesta
Misura bidirezionale su BASIC (lato master)
Se deve tracciare separatamente l'export verso la rete su un modulo BASIC, lo faccia lato master. La potenza RT dev.power[0] ha il segno (oppure il metodo equivalente dev.read_power(0)), quindi:
import time
from rbamp import RbAmp, RbAmpIOError
def bidirectional_loop(dev):
consume_wh = 0.0
export_wh = 0.0
t_prev = time.monotonic()
while True:
# Sample RT power at 10 Hz — matches the firmware-commit
# cadence (100 ms per channel). Faster yields empty repeated
# reads; slower loses resolution on sharp load transitions.
time.sleep(0.1)
t_now = time.monotonic()
dt_s = t_now - t_prev
t_prev = t_now
try:
p = dev.read_power(0)
except RbAmpIOError:
continue
dwh = p * dt_s / 3600.0
if p >= 0.0:
consume_wh += dwh
else:
export_wh += -dwh
Su MicroPython sostituisca time.monotonic() con time.ticks_ms() / time.ticks_diff() (più precisi e poco onerosi in RAM sulle piattaforme embedded) e time.sleep(0.1) con time.sleep_ms(100). Su CPython non serve alcuna modifica.
Un esempio completo funzionante dello schema è in 06_examples.md, nello scenario «Misura bidirezionale lato master», nonché nei file sorgente examples_upy/07_bidirectional_energy.py e examples_cpython/05_bidirectional_energy.py.
STANDARD (STD) — linea di moduli in produzione
I moduli STANDARD sono una linea di moduli in commercio che questa libreria supporta dalla versione 1.6.0. Usano una mappa dei registri diversa (a 16 bit) rispetto a BASIC; la libreria nasconde la differenza — stessa classe RbAmp, stesso cablaggio I²C e stesso indirizzo, e gli stessi lettori comuni.
Cosa aggiunge la libreria su un modulo STD:
-
Energia sul dispositivo:
dev.read_std_energy()restituisce i contatori a vita del modulo stesso — energia attiva di import / export / netta e reattiva, in risoluzione Wh, mWh e µWh, con valori per canale.RbAmp.std_energy_delta(prev, now)dà l'energia usata tra due letture ed è sicura in caso di interruzione di alimentazione. Per questi contatori non integra la potenza sul master. -
Misura per periodo:
read_period_snapshot()e le altre chiamate di periodo funzionano come su BASIC.begin()sceglie la sorgente — i contatori di energia del modulo (il periodo è la differenza di due letture; non viene inviato alcun comando di latch) oppure, su un modulo con soli banchi di latch, il banco di latch 0. L'energia è netta (l'export sottrae). -
Banchi latch (moduli che li riportano):
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank),RbAmp.std_latch_wh(snap, dt_ms). -
Funzioni multifase:
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch)(solo STD; su BASIC la potenza reattiva non è esposta da questa libreria),dev.read_apparent(ch). -
Corrente di avviamento:
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). -
Blocchi completi:
dev.read_std_voltage(),read_std_channel(),read_std_totals(),read_std_config(),read_std_health(),dev.set_time().
Notes:
-
Alcune chiamate STD richiedono un'immagine del modulo abbastanza recente (contatori di energia in micro-unità, angoli di tensione, corrente di avviamento). Se il modulo non ne fornisce una, la chiamata solleva
RbAmpNotSupportedError(«non disponibile»). -
Usare
dev.is_stdper ramificare nel codice applicativo. -
La configurazione della classe del sensore e del modello TA, reset e cambio di indirizzo, i registri di identità, il canale di errori/eventi, le funzioni di supporto del fleet e
wait_ready()sono riservati ai BASIC; su un modulo STD sollevanoRbAmpNotSupportedError. -
Le funzioni di energia sul dispositivo, angolo e corrente di avviamento sono validate su CPython (
smbus2). Il percorso MicroPython a 16 bit è implementato ma non ancora validato su hardware — preferire CPython per queste funzioni finché una nota di rilascio non dica diversamente.
Firme complete: 09 · Riferimento API.
Come rilevare la linea del modulo a runtime
Nel firmware attuale non c'è un registro esplicito della «linea del modulo». Indicatori indiretti sono disponibili tramite le proprietà dell'handle:
# Firmware version — opaque byte
fw = dev.firmware_version
# Presence of a voltage sensor (UI* variants vs I*-only)
voltage_hw = dev.has_voltage_hw
# Number of current channels (1 / 2 / 3 on BASIC; 5 / 7 on UI5 / UI7)
channels = dev.channels
# BASIC variant byte (1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3, 7=UI5, 8=UI7)
variant = dev.read_variant()
# Module line: True on an STD module (detected in begin())
is_std = dev.is_std
: dev.is_std indica la linea del modulo (STD o BASIC). Gli altri indicatori (versione del firmware, numero di canali, presenza di un sensore di tensione, variante) descrivono il modulo ma non identificano la linea. dev.read_variant() è il byte di variante BASIC; usi l'etichetta SKU sull'involucro del modulo come fonte di riferimento per il prodotto.
Come sono contrassegnati nella documentazione i punti che dipendono dalla linea del modulo
Nel testo del pacchetto e nella documentazione canonica le funzioni che dipendono dalla linea del modulo sono contrassegnate esplicitamente, per esempio:
— questa chiamata non è disponibile su un modulo BASIC.
Oppure, al contrario, comportamento specifico del BASIC:
: il contatore dev.energy.wh(ch) è monotono — l'export verso la rete non viene conteggiato. Per la misura bidirezionale, vedere lo scenario "Misura bidirezionale lato master" in 06_examples.md, oppure usi un modulo STANDARD, dove l'energia per periodo è netta e dev.read_std_energy() ha contatori separati di import ed export.
Cosa segue
-
03 · Selezione del sensore di corrente — quale SCT-013 per quale compito
-
04 · Cablaggio — specifiche hardware per ciascun host (RPi / ESP32 / RP2040 / STM32 / Pyboard)
-
06 · Esempi — scenari per BASIC, incluse le misure bidirezionali lato master
-
09 · Riferimento API — l'API pubblica completa
Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repo: docs/02_tiers.md (v1.6.1)