rbAmp
IT
Negozio
Docs
Aggiornato · Modifica su GitHub (Edit on GitHub)

09 · Riferimento API

Mappa dei registri del modulo: lo spazio di indirizzi della pagina 0 da 0x00 a 0xFF

Istantanea atomica del periodo: una scrittura chiude il periodo corrente e ne apre il successivo

L'API pubblica completa del pacchetto rbamp. Sorgente — __init__.py (riesportazioni), _rbamp_core.py (la classe principale RbAmp), _snapshot.py (strutture POD + gerarchia delle eccezioni), _energy.py (accumulatore dei Wh), _registers.py (costanti generate automaticamente).

Questo capitolo è un riferimento: firme, valori restituiti, effetti collaterali, casi limite. Per esempi funzionanti vada a 06 · Esempi; per un avvio rapido, vedere 05 · Avvio rapido.

Importazioni

Python
from rbamp import (
    RbAmp,                     # main class
    RbAmpEnergy,               # Wh accumulator (accessed via dev.energy)
    RbAmpSnapshot,             # RT-block dataclass-style
    RbAmpPeriodSnapshot,       # period snapshot dataclass-style
    RbAmpSensorClass,          # sensor-class enum
    TOPOLOGY_SINGLE, TOPOLOGY_SPLIT_PHASE, TOPOLOGY_THREE_PHASE,
    TOPOLOGY_FIVE_CH, TOPOLOGY_SEVEN_CH,
    topology_name,             # helper: int → topology name
    # STD module line (1.6.0)
    RbAmpStdEnergy, RbAmpStdVoltage, RbAmpStdChannel,
    RbAmpStdConfig, RbAmpStdHealth,   # value objects
    std_energy_delta,          # energy between two read_std_energy() snapshots
    phase_seq_name,            # helper: phase-sequence code → name
    PHASE_SEQ_NA, PHASE_SEQ_FORWARD, PHASE_SEQ_REVERSE, PHASE_SEQ_ABNORMAL,
    # Exception hierarchy
    RbAmpError,                # base class of all errors
    RbAmpIOError,
    RbAmpTimeoutError,
    RbAmpNotReadyError,
    RbAmpStaleError,
    RbAmpParamError,
    RbAmpModeError,
    RbAmpVersionError,
    RbAmpNotSupportedError,    # call not available on this module / firmware
    # Metadata
    __version__,               # "1.6.0"
    __protocol_version__,      # 0x04 (RBAMP_PROTOCOL_VERSION)
    REGISTERS, COMMANDS,       # raw protocol constants (advanced use)
)

Importazione minima per un'applicazione tipica:

Python
from rbamp import RbAmp, RbAmpSensorClass, RbAmpError

Idiomi generali

L'API segue gli schemi Python standard:

  • Una classe per ogni linea di moduli: la stessa classe RbAmp serve i moduli BASIC e STANDARD (STD). La linea viene rilevata automaticamente in begin() (vedere Linea di moduli STD); non la sceglie mai lei.

  • Basato su classi: la classe principale RbAmp gestisce tutto — letture RT, periodo, configurazione, diagnostica. L'handle contiene internamente il backend e l'accumulatore di energia.

  • Context manager: with RbAmp(bus, addr) as dev: — lo schema consigliato. __enter__ chiama automaticamente dev.begin().

  • Proprietà per le letture RT: dev.voltage, dev.frequency — una proprietà = una transazione I²C. Quelle indicizzate per canale passano da _ChannelProxy: dev.current[ch], dev.power[ch], dev.power_factor[ch].

  • Metodi per letture indicizzate per canale: dev.read_current(ch), dev.read_power(ch). Del tutto equivalenti alla forma a proprietà — usare quella più comoda.

  • Eccezioni per gli errori: ogni errore è una sottoclasse di RbAmpError. Il pattern standard Python try / except (non last_error() + un codice di ritorno).

  • Generatore asincrono per lo streaming periodico: async for snap in dev.stream_period(interval_s=...).

Tipi

RbAmp

Python
class RbAmp:
    def __init__(self, bus, addr: int = 0x50): ...

La classe principale. Un'istanza per ogni dispositivo slave. Il bus è un oggetto qualsiasi con una delle firme API "note": smbus2.SMBus, machine.I2C, oppure un backend personalizzato (vedere 04 · Hardware).

Il backend viene selezionato automaticamente al primo accesso al bus:

metodo del bus-object Backend
bus.readfrom_mem, bus.writeto_mem MachineI2CBackend (MicroPython)
bus.read_byte_data, bus.write_byte_data SMBusBackend (CPython + smbus2)
bus.read_byte, bus.register_acks, bus.now_ms già avvolto (mock di test, adattatori FTDI)

Se nessuna firma corrisponde, viene sollevata una RbAmpParamError con una descrizione.

Gerarchia delle eccezioni

Ogni errore del pacchetto è una sottoclasse di RbAmpError, che a sua volta eredita da OSError (non da Exception generico). Questo significa: il codice esistente con gestori except OSError: continua a intercettare gli errori rbAmp senza alcuna riscrittura — è la convenzione Python standard per i driver di I/O hardware.

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

Nota

: RbAmpParamError eredita da RbAmpError + ValueError su CPython (ereditarietà multipla). Su MicroPython, dove l'ereditarietà multipla non è supportata da tutte le porte, si ricade su una base singola. Dal punto di vista dell'utente, try / except RbAmpParamError funziona allo stesso modo. Ma try / except ValueError intercetta solo su CPython — su MicroPython questo gestore viene mancato. Il codice che si basa su un comportamento multipiattaforma deve intercettare esplicitamente RbAmpParamError.

Uso standard:

Python
try:
    snap = dev.read_period_snapshot()
except RbAmpStaleError:
    # period not ready yet — the master timestamp was committed by the package
    continue
except RbAmpIOError as e:
    log.warning("bus failure: %s", e)
except RbAmpError as e:
    log.error("unexpected: %s", e)

RbAmpSensorClass

Python
class RbAmpSensorClass(IntEnum):
    UNSET       = 0   # factory value after reset
    SCT_013     = 1   # SCT-013 series (shipping default)
    WIRED_CT    = 2   # factory-fitted wired CT (module ships paired)
    BUILTIN_CT  = 3   # factory-fitted built-in CT (module ships paired)
Nota

: su CPython si usa IntEnum dalla libreria standard enum. Sulle porte MicroPython senza un modulo enum, si usa una classe semplice di ripiego con gli stessi valori dei membri. Dal punto di vista dell'utente le due forme sono identiche: dev.set_sensor_class(RbAmpSensorClass.SCT_013) oppure dev.set_sensor_class(1) — funzionano entrambe.

SCT_013 è la classe da selezionare su un modulo con pinze SCT-013 montate dall'utente. WIRED_CT e BUILTIN_CT descrivono moduli consegnati preaccoppiati in fabbrica con il loro sensore: set_sensor_class() e set_ct_model*() si rifiutano di modificare un modulo del genere (RbAmpModeError, vedere guardia di lettura prima della scrittura). I valori fuori da 0..3 sollevano RbAmpParamError.

RbAmpSnapshot

Restituito da dev.read_all(). Una semplice classe Python (non un @dataclass, per compatibilità con MicroPython). Tutti i campi in unità SI.

Python
class RbAmpSnapshot:
    voltage:        float       # V — RMS voltage
    voltage_peak:   float       # V — peak voltage
    current:        list        # [ch0, ch1, ...] — RMS current per channel, A
    current_peak:   list        # [ch0, ch1, ...] — peak current, A
    power:          list        # [ch0, ch1, ...] — active power (signed), W
    power_factor:   list        # [ch0, ch1, ...] — dimensionless, −1..+1
    frequency:      float       # Hz
    topology:       int         # TOPOLOGY_* constant
    channels:       int         # number of valid channels (1..3, or 5 / 7 on UI5 / UI7)
    has_voltage_hw: bool        # True if a voltage sensor is present

I canali inutilizzati (oltre channels) vengono riempiti con zeri.

RbAmpPeriodSnapshot

Restituito da dev.read_period_snapshot(). La primitiva di contabilizzazione dell'energia.

Python
class RbAmpPeriodSnapshot:
    avg_p:        list   # [ch0, ch1, ...] — average P over the period, W (all channels)
    max_p:        float  # peak instantaneous power on channel 0
    latch_ms:     int    # period duration (device's view)
    master_dt_ms: int    # master wall-clock dt since the last snapshot
    valid:        bool   # True if the snapshot-ready flag was set
    avg_p_total:  float  # STD: total average P over the period, W (0.0 on BASIC)
    wh_net:       float  # STD: net energy over the period, Wh (0.0 on BASIC)
    module_restarted: bool  # STD counter source: the module restarted during the period
Nota

Per l'integrazione dell'energia usi master_dt_ms, non latch_ms — latch_ms è un timer diagnostico del modulo.

Costanti di topologia

Python
TOPOLOGY_SINGLE      = 1   # 1 current channel (UI1 / I1)
TOPOLOGY_SPLIT_PHASE = 2   # 2 current channels (UI2 / I2)
TOPOLOGY_THREE_PHASE = 3   # 3 current channels (UI3 / I3)
TOPOLOGY_FIVE_CH     = 5   # 5 current channels + voltage (UI5)
TOPOLOGY_SEVEN_CH    = 7   # 7 current channels + voltage (UI7)

topology_name(topology: int) -> str   # 1 → "SINGLE", 2 → "SPLIT_PHASE", ...

Ciclo di vita

RbAmp(bus, addr=0x50)

Costruttore. La risoluzione del backend avviene in __init__. Non viene generato traffico I²C fino a begin().

Parametro Descrizione
bus Oggetto bus I²C (smbus2.SMBus, machine.I2C, o un wrapper)
addr Indirizzo slave a 7 bit. Intervallo 0x08..0x77, predefinito 0x50

Solleva: RbAmpParamError se l'oggetto bus non è riconosciuto o addr è fuori intervallo.

dev.begin()

Sonda il dispositivo, rileva la linea del modulo, memorizza la topologia e predispone il comando di snapshot.

Rilevamento della linea del modulo (1.6.0). begin() verifica prima se il modulo è un modulo STD (mappa dei registri a 16 bit). Se lo è, l'handle passa alla modalità STD (dev.is_std diventa True, dev.channels e dev.has_voltage_hw provengono dal modulo) e begin() ritorna. Altrimenti esegue la sequenza BASIC qui sotto. Serve un backend di bus in grado di fare transazioni a 16 bit; in caso contrario il modulo viene trattato come BASIC.

Sequenza BASIC:

  1. Legge REG_VERSION — solleva RbAmpIOError su NACK, RbAmpVersionError se viene restituito 0x00 / 0xFF.

  2. Mette in cache la topologia (sul firmware attuale begin() non esegue alcun auto-probe; usa il suggerimento passato al costruttore).

  3. Legge U_rms per stabilire se è presente un sensore di tensione (soglia 1.0 V).

  4. Scrive CMD_LATCH_PERIOD (primer) + attende 50 ms. Il primo snapshot dopo l'accensione viene scartato.

  5. Memorizza time.monotonic() (o time.ticks_ms() su uPy) per la successiva integrazione dell'energia.

Su un modulo BASIC con pinze SCT-013, begin() valuta anche la correzione dello switch di rating SCT-013.

Idempotente: sicuro da chiamare più volte.

Context manager

Python
with RbAmp(bus, 0x50) as dev:
    # dev.begin() has already been called in __enter__
    ...
# __exit__ — no-op (bus closing is the caller's responsibility)

Lo schema consigliato. Il __exit__ del pacchetto NON chiude il bus — la gestione dell'oggetto bus resta compito del chiamante (lo schema tipico è with SMBus(1) as bus, RbAmp(bus, 0x50) as dev: annidati).

dev.probe() -> bool

Un controllo di vitalità leggero. Una singola lettura di REG_VERSION senza effetti collaterali.

Restituisce: True se lo slave ha risposto con ACK e ha riportato una versione supportata; False altrimenti. Non solleva eccezioni — per scenari di polling.

dev.wait_ready(timeout_ms=1000) -> None

Interroga il flag di pronto del modulo finché non è impostato. Utile dopo l'accensione — il modulo può richiedere fino a 100 ms per la sua prima finestra RT.

Solleva: RbAmpTimeoutError se il bit non viene visto prima che scada timeout_ms.

Proprietà — stato dell'handle

Python
dev.firmware_version: int      # REG_VERSION — opaque byte
dev.topology:         int      # TOPOLOGY_* constant
dev.topology_name:    str      # "SINGLE" / "SPLIT_PHASE" / "THREE_PHASE"
dev.channels:         int      # 1..3 (BASIC), 5 / 7 on UI5 / UI7, or the STD module's channel count
dev.is_std:           bool     # True if begin() detected an STD module
dev.has_voltage_hw:   bool     # True if begin() detected U_rms > 1.0
dev.address:          int      # 7-bit I²C address (updated after commit_address_change)

firmware_version è una proprietà in tempo reale: ogni lettura passa dal bus (una lettura a singolo byte di REG_VERSION). La metta in cache lato applicazione se la interroga in un ciclo intenso: fw = dev.firmware_version una volta dopo begin(). Se begin() non è ancora stato chiamato, firmware_version solleva RbAmpIOError (il modulo può non rispondere mentre l'handle è "a freddo").

Le proprietà rimanenti (topology, channels, has_voltage_hw, address) sono in cache nell'handle e restituiscono i valori memorizzati dopo begin() senza passare dal bus.

Letture in tempo reale (blocco RT, aggiornamento ogni 100 ms)

Tutti i metodi sollevano RbAmpIOError in caso di errore di comunicazione (NACK dopo i tentativi o scarto per controllo di sanità) oppure RbAmpParamError per un argomento non valido.

Finestre di misura da 100 ms si susseguono senza pause, DRDY impulsa una volta per finestra, e il master legge il blocco di risultato atomico.

Proprietà

Python
dev.voltage         -> float   # V — RMS voltage
dev.voltage_peak    -> float   # V — peak voltage
dev.frequency       -> float   # Hz — mains frequency

Indicizzato per canale tramite _ChannelProxy — supporta l'indicizzazione [ch] e l'iterazione:

Python
dev.current         # _ChannelProxy → dev.current[0], dev.current[1], ...
dev.current_peak    # _ChannelProxy
dev.power           # _ChannelProxy
dev.power_factor    # _ChannelProxy

Usage:

Python
i0 = dev.current[0]                       # a single channel
for i in dev.current:                      # iterate over all valid channels
    print(i)
total = sum(p for p in dev.power)          # sum of all channels

len(dev.current) è uguale a dev.channels.

Metodi (del tutto equivalenti alla forma a proprietà)

Python
dev.read_voltage(phase=0)         -> float
dev.read_voltage_peak(phase=0)    -> float
dev.read_current(ch=0)            -> float
dev.read_current_peak(ch=0)       -> float
dev.read_power(ch=0)              -> float       # signed
dev.read_power_factor(ch=0)       -> float
dev.read_frequency()              -> float

Lettura in un'unica soluzione dell'intero blocco RT

Python
dev.read_all()  -> RbAmpSnapshot

Equivalente a letture consecutive di read_voltage + read_voltage_peak + read_current(0..N) + read_current_peak(0..N) + read_power(0..N) + read_power_factor(0..N) + read_frequency. I canali non utilizzati (oltre channels) vengono riempiti con zeri.

Solleva: RbAmpIOError se fallisce una sotto-lettura.

I lettori comuni — voltage, voltage_peak, current, current_peak, power, power_factor, frequency e le loro forme read_* — funzionano su ogni linea di moduli. Su un modulo STD phase in read_voltage() / read_voltage_peak() seleziona l'ingresso di tensione (0..n_voltage-1); su un modulo BASIC è valido solo phase=0.

Linea di moduli STD (1.6.0)

Sicurezza

⚠️ Stato di validazione. Le funzioni on-device di energia, angolo di tensione e corrente di spunto sono validate su CPython (smbus2). Le stesse chiamate sono implementate per MicroPython (machine.I2C), ma il percorso a 16 bit di MicroPython non è ancora validato su hardware — per queste funzioni on-device preferisca CPython finché una nota di rilascio non dica diversamente. Le letture comuni (dev.voltage, dev.current[ch], dev.power[ch], istantanee di periodo) funzionano comunque su ogni host supportato.

Un'unica classe RbAmp serve entrambe le linee di moduli. begin() rileva la linea automaticamente; dev.is_std è True su un modulo STD. Si usano lo stesso cablaggio I²C e lo stesso indirizzo (vedere 04 · Hardware).

  • I lettori comuni (voltage, current, power, power_factor, frequency) funzionano su qualsiasi modulo.

  • Le chiamate di questa sezione sono riservate allo STD. Su un modulo BASIC sollevano RbAmpNotSupportedError.

  • Alcune chiamate STD richiedono anche un'immagine del modulo abbastanza recente (energia sul dispositivo, contatori in micro-unità, angoli di tensione, corrente di spunto). Se il modulo non le fornisce, la chiamata solleva RbAmpNotSupportedError ("non disponibile").

  • Le chiamate di periodo (latch_period, read_period_*, stream_period) e l'accumulatore dev.energy funzionano su un modulo STD — vedi «Contabilità di periodo» sotto. I totali di vita del modulo sono read_std_energy().

  • Le chiamate di configurazione del sensore (set_sensor_class, set_ct_model, set_ct_model_ch, set_ct_model_ch_force, read_ct_model_ch, read_sensor_class), reset, factory_reset, la coppia di cambio indirizzo, i registri di identità (firmware_version, read_variant, read_capability, read_product_id, read_uid, read_label, set_label, read_seq_digest), il canale di errori/eventi (read_last_error, read_event_flags, clear_event_flags, has_error, clear_error), gli helper di flotta (read_fleet_config, enable_gc, set_group_id, read_group_id, read_gc_tick), read_period_latch_ms e wait_ready sono solo BASIC: su un modulo STD sollevano RbAmpNotSupportedError prima che venga inviato alcunché sul bus.

Python
dev.is_std        -> bool   # True on an STD module (set by begin())
dev.std           -> object # internal STD client (advanced use) or None on BASIC

Lettori

Python
dev.read_std_voltage(phase=0)    -> RbAmpStdVoltage   # RMS, peak, THD, angle
dev.read_voltage_angle(phase=0)  -> (float, bool)     # (degrees, valid)
dev.read_phase_sequence()        -> int               # 0..3
dev.read_std_channel(ch=0)       -> RbAmpStdChannel   # I / P / Q / S / PF + harmonics
dev.read_std_totals(k=0)         -> RbAmpStdChannel   # totals block k (0 = grand total)
dev.read_reactive(ch=0)          -> float             # var
dev.read_apparent(ch=0)          -> float             # VA
dev.read_std_config()            -> RbAmpStdConfig
dev.read_std_health()            -> RbAmpStdHealth
  • read_voltage_angle(phase) — angolo di fase della tensione rispetto alla fase 0, restituito come (degrees, valid). valid è False su un modulo a tensione singola o su un'immagine del modulo che non riporta gli angoli.

  • read_phase_sequence() — codice della sequenza di fase: PHASE_SEQ_NA (0, non disponibile), PHASE_SEQ_FORWARD (1), PHASE_SEQ_REVERSE (2), PHASE_SEQ_ABNORMAL (3). phase_seq_name(code) restituisce il nome testuale. Solleva RbAmpNotSupportedError su un modulo BASIC o su un'immagine del modulo che non lo riporta.

  • read_reactive(ch) / read_apparent(ch) — potenza reattiva in var e potenza apparente in VA per un canale. Solo moduli STD; su un modulo BASIC sollevano RbAmpNotSupportedError (su BASIC la potenza reattiva non è esposta da questa libreria).

  • read_std_totals(k) — blocco di totali k; k=0 è il totale generale. I totali per fase dipendono dalla versione della mappa registri del modulo.

  • read_std_config() / read_std_health() — blocchi di configurazione e stato/salute.

Oggetti valore

Classi semplici (non @dataclass), tutte riesportate da rbamp.

Classe Campi
RbAmpStdVoltage u_rms, u_peak, thd_u, angle_deg, angle_valid
RbAmpStdChannel i_rms, i_peak, p, q, s, pf, thd_i, pf1, q1
RbAmpStdConfig sensor_class, ct_model, tier, i2c_addr, rate_ms, harmonics, start_ua, start_ua_supported
RbAmpStdHealth status, cal_ok, sensor_ok, mains_ok, time_valid, nvm_fault, maint, frame_count, crc_errors, lta_status, lta_src, cal_src, group_status, ring_drop, lost_frames, uptime_s, reset_cause, boot_count
RbAmpStdEnergy vedere sotto

dev.read_std_energy() -> RbAmpStdEnergy

Snapshot dell'energia di vita sul dispositivo. Richiede un modulo che fornisce l'energia sul dispositivo; altrimenti RbAmpNotSupportedError.

RbAmpStdEnergy contiene:

Gruppo Campi
Attiva, Wh act_import_wh, act_export_wh, act_net_wh
Attiva, mWh act_import_mwh, act_export_mwh, act_net_mwh
Attiva, µWh act_import_uwh, act_export_uwh, act_net_uwh
Reattiva rea_import_varh, rea_export_varh; µvarh: rea_import_uvarh, rea_export_uvarh
Per canale channels (numero di voci valide); ch_import_mwh[], ch_export_mwh[], ch_import_uwh[], ch_export_uwh[]
Contabilità generation, uptime_s, group_status
Flag di provenienza fine, fine_reactive

I campi µWh / µvarh sono sempre popolati. Quando l'immagine del modulo non fornisce i contatori più fini, vengono scalati da quelli più grossolani e fine (attiva) / fine_reactive valgono False — leggere il flag se serve sapere da dove viene il valore.

RbAmp.std_energy_delta(prev, now) -> (delta, module_restarted)

Energia consumata tra due letture di read_std_energy() (metodo statico; esportato anche come std_energy_delta). Sicuro in caso di interruzione di alimentazione.

  • module_restarted è True quando now.uptime_s < prev.uptime_s.
  • delta è un RbAmpStdEnergy che contiene l'incremento per campo, oppure None quando il contatore generation è cambiato (le due letture non sono confrontabili).

  • Un contatore che risulta leggermente inferiore alla lettura precedente (ripresa dopo un'interruzione di corrente) viene portato a 0; net è sempre import − export delle parti limitate.

  • Le voci per canale vengono compilate solo quando entrambe le istantanee hanno lo stesso numero di canali.

Python
prev = dev.read_std_energy()
time.sleep(60)
now = dev.read_std_energy()
delta, restarted = RbAmp.std_energy_delta(prev, now)
if delta is not None:
    print(delta.act_import_wh, "Wh imported in this interval")

Corrente di spunto e configurazione

Python
dev.get_start_current()     -> int    # µA, 0 = off
dev.set_start_current(ua)   -> None
dev.save_config()           -> None   # persist writable STD config to flash (blocking)
dev.set_time(unix_epoch)    -> None   # set the module's clock
  • get_start_current() — la corrente di spunto energetica in µA (0 = disattivata).

  • set_start_current(ua) — sotto questa corrente per canale il modulo non conteggia l'energia in import/export; le letture live (I, P, Q) non cambiano. Il valore si applica subito; chiamare save_config() per mantenerlo dopo un riavvio. Un valore non supportato solleva RbAmpParamError prima che venga scritto alcunché sul bus. Il valore deve essere 0 (disattivato) oppure un multiplo di 10 µA entro l'intervallo supportato.

  • save_config() — rende persistente la configurazione STD scrivibile. Bloccante.

  • set_time(unix_epoch) — imposta l'orologio del modulo da un epoch Unix; un epoch precedente al 2020 solleva RbAmpParamError. Reimpostare l'ora dopo ogni riavvio del modulo (read_std_health().time_valid è False finché l'orologio non è impostato).

  • get_start_current() / set_start_current() sollevano RbAmpNotSupportedError su un'immagine di modulo che non fornisce l'impostazione di corrente di avviamento; RbAmpStdConfig.start_ua_supported indica se la fornisce.

Banchi di latch

Un modulo STD che riporta i banchi latch mantiene 8 banchi indipendenti. Un banco accumula mentre il suo bit è impostato nella maschera di armamento; un latch lo legge e lo azzera al successivo confine della finestra di misura, quindi un periodo è l'intervallo tra due latch dello stesso banco, misurato con l'orologio del master. Queste chiamate richiedono un modulo che riporti i banchi e altrimenti sollevano RbAmpNotSupportedError; un numero di banco fuori da 0..7 solleva RbAmpParamError.

Python
dev.std_arm_banks(mask)                 -> None            # bit i = bank i accumulates
dev.std_latch(bank)                     -> None            # snapshot + reset; does not wait
dev.std_read_latch(bank)                -> RbAmpStdLatch
RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF) -> (wh_import, wh_export)
  • std_arm_banks(mask) — imposta la maschera di armamento. La maschera non viene conservata dopo un riavvio del modulo.

  • std_latch(bank) — esegue il latch di un banco. Lo legga non prima di 300 ms dopo.

  • std_read_latch(bank) — restituisce l'istantanea del banco. Il flag valid del modulo indica solo che il banco è stato sottoposto a latch almeno una volta; non è un flag di freschezza, quindi attenda almeno una finestra (300 ms è un limite sicuro) dopo std_latch(). Un banco mai sottoposto a latch solleva RbAmpStaleError. Un banco vuoto non più armato (il modulo si è riavviato) viene riarmato e sottoposto a latch una volta per iniziare un nuovo periodo, e la chiamata solleva RbAmpStaleError: scarti quel periodo e riavvii il proprio riferimento temporale.

  • RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF) — converte l'energia dello snapshot in Wh su dt_ms dell'orologio del master. ch è un indice di canale, oppure 0xFF (predefinito) per il totale del modulo. Restituisce (wh_import, wh_export); l'export è zero o negativo. Solleva RbAmpStaleError per uno snapshot senza campioni.

Python
class RbAmpStdLatch:
    bank:       int     # 0..7
    valid:      bool    # the bank has been latched at least once
    channels:   int
    p_avg, q_avg, s_avg: float     # average P (W), Q (var), S (VA) over the period
    max_p, max_i, max_u, min_u: float   # peak P (W), peak I (A), peak / minimum U (V)
    e_import_mws, e_export_mws: int     # energy, mW·samples (export <= 0)
    nsamp:      int     # samples in the period
    win_count:  int     # measurement windows in the period (0 = not armed / nothing elapsed)
    p_avg_ch:   list    # per-channel average P, W
    e_import_ch_mws, e_export_ch_mws: list   # per-channel energy, mW·samples

Contabilità di periodo

Vedi 01 · Panoramica per il quadro generale e il Passo 5 di 05 · Avvio rapido per un modello minimo.

Su un modulo STD le stesse chiamate funzionano. begin() sceglie la sorgente del periodo in base a quanto riporta il modulo:

Il modulo segnala Sorgente del periodo Comando latch
contatori di energia sul dispositivo differenza tra due letture del contatore, sulla pianificazione del master nessuno
solo banchi latch latch-a-latch sul banco 0 (almeno 300 ms di assestamento) CMD_LATCH_PERIOD sul banco 0
nessuno — le chiamate di periodo sollevano RbAmpNotSupportedError

Sulla sorgente a contatore il primo periodo inizia a begin(), latch_period() non fa nulla, is_period_valid() è True una volta ancorati i contatori, read_period_max_power() solleva RbAmpNotSupportedError (nessun picco) e read_period_avg_power(ch) esiste solo su un modulo a canale singolo, dopo la lettura di un periodo. Un cambio di generazione dei contatori riancora il periodo e solleva RbAmpStaleError; un riavvio del modulo all'interno di un periodo è segnalato in snap.module_restarted (l'energia non viene misurata mentre il modulo si riavvia). Sulla sorgente a latch un'istantanea vuota solleva RbAmpStaleError; se il banco aveva perso l'armamento (riavvio del modulo) viene prima riarmato. L'istantanea contiene avg_p_total, wh_net e module_restarted. read_period_latch_ms() è solo BASIC.

dev.latch_period() -> None

Scrive CMD_LATCH_PERIOD. Non attende — il chiamante deve rispettare l'assestamento di 50 ms e verificare dev.is_period_valid() prima di leggere.

Per la maggior parte delle attività usi read_period_snapshot() — racchiude l'intera sequenza.

dev.is_period_valid() -> bool

Legge il bit di istantanea pronta. Restituisce True se l'ultima istantanea è recente.

dev.read_period_avg_power(ch=0) -> float

Potenza attiva media su un canale nel periodo chiuso. Va chiamata dopo latch_period() + un assestamento di 50 ms + un controllo di validità.

Risolve ogni canale del modulo (ch = 0..channels-1), compresi i canali 3+ sui moduli a 5 e 7 canali (UI5 / UI7). Anche lo snapshot di periodo e l'accumulatore dei Wh coprono tutti i canali. dev.read_period_avg_p(ch) è un alias con lo stesso comportamento.

dev.read_period_max_power() -> float

Potenza istantanea di picco sul canale 0 sul periodo chiuso. ch=0 solo sul firmware v1.

dev.read_period_latch_ms() -> int

Durata del periodo dal punto di vista del dispositivo, in ms.

Valore diagnostico.

Il timer interno del modulo ha precisione limitata. Per l'integrazione dell'energia usare master_dt_ms da RbAmpPeriodSnapshot, non questo campo.

dev.read_period_snapshot(settle_ms=50, skip_latch=False) -> RbAmpPeriodSnapshot

Il punto di ingresso consigliato per la contabilità per periodo. La sequenza completa sotto il cofano:

  1. Se skip_latch=True — salta la scrittura del comando di snapshot (per lo schema multi-modulo dopo una serie manuale di comandi di snapshot).

  2. Altrimenti — scrivere CMD_LATCH_PERIOD.

  3. Acquisisca time.monotonic() per calcolare master_dt_ms.
  4. time.sleep(settle_ms / 1000) — 50 ms per default.
  5. Controllare il flag di snapshot pronto. Se 0 — sollevare RbAmpStaleError (il timestamp precedente viene mantenuto, così lo snapshot valido successivo copre l'intero intervallo e i Wh restano esatti).

  6. Legga avg_p[0..channels-1] + max_p + latch_ms.

  7. Aggiornare il timestamp e chiamare energy.tick(snap) per integrare i Wh (a meno che l'accumulatore sia disattivato con energy.disable()).
Parametro Descrizione
settle_ms Attesa dopo il comando di istantanea, in ms. Predefinito 50.
skip_latch Se True — non invia il comando di istantanea, legge soltanto.

Solleva: RbAmpStaleError (snapshot non aggiornato); RbAmpIOError (guasto del bus).

async dev.stream_period(interval_s=60.0, skip_stale=True)

Un generatore asincrono che produce RbAmpPeriodSnapshot con intervallo interval_s. Funziona su CPython asyncio e MicroPython uasyncio (MicroPython ≥ 1.20 — anche import asyncio funziona; per le versioni precedenti usare import uasyncio as asyncio).

Python
async for snap in dev.stream_period(interval_s=60.0):
    # snap is an RbAmpPeriodSnapshot, .valid guaranteed True (by default skip_stale=True)
    print(snap.avg_p[0])
Parametro Descrizione
interval_s Periodo tra due istantanee (consigliati ≥ 30 s)
skip_stale True (predefinito) — gli snapshot non aggiornati vengono saltati automaticamente. False — vengono prodotti con snap.valid=False, e il codice deve controllare da sé if not snap.valid: continue
Sicurezza

⚠ CPython: blocca il loop degli eventi. Sotto il cofano, stream_period() chiama la sincrona e bloccante read_period_snapshot() — che esegue un time.sleep(0.05) di assestamento più circa 50–100 ms di letture a singolo byte sul bus. Su CPython questo blocca l'intero loop asyncio per quei 100 ms — le altre coroutine (MQTT, HTTP, keepalive Wi-Fi) non ricevono CPU. Per server di produzione, incapsulare in run_in_executor:

Python
import asyncio

async def stream_period_nonblocking(dev, interval_s=60.0):
    loop = asyncio.get_event_loop()
    while True:
        await asyncio.sleep(interval_s)
        snap = await loop.run_in_executor(None, dev.read_period_snapshot)
        if snap.valid:
            yield snap

Su MicroPython il problema è minore — lo scheduler uasyncio cede il controllo ad altri task meno spesso, e l'I²C bloccante è considerato accettabile negli schemi async embedded. Se serve un comportamento non bloccante, usare un thread separato via _thread.start_new_thread (su ESP32 µPy).

Contabilizzazione dell'energia (accumulatore lato master)

dev.energy — istanza di RbAmpEnergy

Un accumulatore Wh per canale. Si accede tramite una proprietà — il pacchetto ne possiede l'istanza:

Python
dev.energy.wh(ch=0)         -> float    # current Wh total for the channel
dev.energy.reset(ch=0)      -> None     # zero a single channel
dev.energy.reset_all()      -> None     # zero all channels
dev.energy.is_enabled       -> bool     # True while auto-integration is active (default)
dev.energy.disable()        -> None     # turn off auto-integration
dev.energy.enable()         -> None     # turn it back on

L'accumulatore viene aggiornato automaticamente a ogni dev.read_period_snapshot() riuscito. È con segno — un valore negativo significa esportazione netta.

Formula di integrazione:

Text
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
         [W]             [milliseconds]              → [Wh]

dev.energy.disable() è utile per gli scenari di deep sleep in cui è il master stesso a gestire la persistenza dei Wh nella memoria RTC — vedere 06 · Esempi, Scenario 9.

Configurazione del sensore

Una sequenza in due passaggi. Per una guida dettagliata alla scelta del modello, vedere 03 · Selezione del sensore di corrente.

dev.set_sensor_class(cls) -> None

Imposta la classe del sensore di corrente e la salva in flash. Bloccante, ~705 ms.

Python
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
# or equivalently:
dev.set_sensor_class(1)
Parametro Descrizione
cls Un enum RbAmpSensorClass oppure un int 0..3

Raises:

  • RbAmpParamError — cls fuori da 0..3
  • RbAmpModeError — il modulo è preaccoppiato in fabbrica (classe attuale WIRED_CT / BUILTIN_CT) e cls è diverso; cambiarla cancellerebbe la calibrazione della pinza montata

  • RbAmpIOError — errore di comunicazione

Va chiamata prima di set_ct_model*(). Scrivere la stessa classe che il modulo già possiede è un no-op (nessuna scrittura sul bus), perché una scrittura di classe cancella lato dispositivo i modelli TA per canale. Vedi guardia di lettura-prima-della-scrittura.

dev.read_sensor_class() -> int

Legge la classe del sensore fissata: 0 UNSET, 1 SCT_013, 2 WIRED_CT, 3 BUILTIN_CT (i valori di RbAmpSensorClass). Restituisce 0 sul firmware in cui il registro non è presente.

dev.set_ct_model(code) -> None

La forma a parametro singolo (legacy) — imposta il modello della pinza TA solo sul canale 0.

code Modello
1 SCT-013-005
2 SCT-013-010
3 SCT-013-030
4 SCT-013-050
5 SCT-013-100
6 SCT-013-020
7 SCT-013-060
Nota

L'insieme accettato per la classe SCT_013 è {1, 2, 3, 4, 5, 6, 7}. La tabella completa degli insiemi accettati per classe è in 03 · Selezione del sensore di corrente.

Raises:

  • ValueError (e anche RbAmpParamError) — code non è nell'insieme di valori accettati per la classe corrente di REG_SENSOR_CLASS (per SCT_013 è {1, 2, 3, 4, 5, 6, 7})
  • RbAmpModeError — se set_sensor_class() non è stato chiamato, oppure il modulo è preaccoppiato in fabbrica (classe 2/3) e il codice differisce (usi set_ct_model_ch_force() in un contesto di assistenza)

  • RbAmpIOError — errore di comunicazione

Impostare il modello che il canale già possiede è un no-op (guardia di lettura-prima-della-scrittura).

Messaggio di RbAmpModeError (classe non impostata):

Text
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first

Equivalente a dev.set_ct_model_ch(0, code).

dev.set_ct_model_ch(channel, code) -> None

La forma per canale. Imposta il modello della pinza TA su un canale specifico.

Sotto il cofano: predisporre REG_CT_MODEL (0x05) → comando CMD_SET_CT_MODEL_CH0/1/2 (opcode 0x28/0x29/0x2A) → assestamento 5 ms → CMD_SAVE_USER_CONFIG (0x32) → 700 ms. Bloccante, ~705 ms.

Nota

✅ v1.3: l'ordine di collegamento ai canali non conta. Sulla v1.3, scrivere REG_CT_MODEL (0x05) predispone il valore ma non lo applica più automaticamente a ch0. L'applicazione avviene solo tramite CMD_SET_CT_MODEL_CHn. I canali si possono configurare in qualsiasi ordine.

Python
dev.set_ct_model_ch(0, 1)  # any order is OK on v1.3
dev.set_ct_model_ch(1, 3)
dev.set_ct_model_ch(2, 6)

Raises:

  • RbAmpParamError — channel fuori da 0..dev.channels-1 oppure code non nell'insieme accettato per la classe (per SCT_013 — {1, 2, 3, 4, 5, 6, 7})
  • RbAmpModeError — set_sensor_class() non chiamato, oppure il modulo è preaccoppiato in fabbrica e il codice differisce

dev.set_ct_model_ch_force(channel, code) -> None

Variante di servizio di set_ct_model_ch() che aggira la guardia di lettura prima della scrittura: scrive anche quando il modulo è preaccoppiato in fabbrica o ha già il codice. Pensata per i tecnici che rifanno la sensorizzazione di un'unità. Il modulo convalida comunque la coppia (classe, codice) e la chiamata solleva RbAmpParamError per una coppia non valida.

Guardia di lettura prima della scrittura

Scrivere un modello TA sostituisce la calibrazione di quel canale con il preset generico del modello, quindi dalla 1.6.0 i setter verificano prima:

Chiamata Il modulo possiede già il valore Modulo accoppiato in fabbrica (classe 2/3) Altrimenti
set_sensor_class(cls) nessuna operazione, nessuna scrittura sul bus RbAmpModeError se cls è diverso scritture + salvataggio
set_ct_model(code) / set_ct_model_ch(ch, code) nessuna operazione, nessuna scrittura sul bus RbAmpModeError se il codice è diverso scritture + salvataggio
set_ct_model_ch_force(ch, code) scritture scritture scritture

Mirror di verifica V2 — CT_MODEL_CH0/1/2 (0x51-0x53)

Registri di sola lettura che riflettono il preset TA effettivamente applicato su ciascun canale. Il protocollo di scrittura sul filo non cambia — le scritture usano il meccanismo sopra. 0x51-0x53 servono solo come rilettura per i controlli di stato e gli schemi lettura-confronto-scrittura:

Python
applied_ch0 = dev.read_ct_model_ch(0)   # what is actually applied
applied_ch1 = dev.read_ct_model_ch(1)
applied_ch2 = dev.read_ct_model_ch(2)

Correzione dello switch di rating SCT-013

I moduli SCT-013 vengono calibrati in fabbrica con un modello di pinza di riferimento. Quando un canale passa a un modello diverso, un'immagine del modulo che non si riscala da sola continua ad applicare il guadagno di riferimento, quindi corrente e potenza verrebbero lette con la scala sbagliata. Dalla 1.6.0 la libreria lo corregge automaticamente sui moduli BASIC con classe del sensore SCT_013:

  • Corrente, potenza e l'energia derivata dalla potenza (read_current, read_current_peak, read_power, read_period_avg_power, e quindi lo snapshot di periodo e dev.energy) sono corretti al modello scelto, rispetto al guadagno che il modulo applica effettivamente.

  • La tensione e il fattore di potenza non vengono mai modificati.

  • Sul firmware del modulo fino alla 1.4.19 un cambio di modello riavvia il modulo una volta (circa un secondo); dalla 1.4.20 il modulo si corregge da sé. La correzione di portata del TA scala corrente, potenza ed energia, mai tensione o fattore di potenza.
  • I moduli il cui firmware esegue questa operazione da sé vengono rilevati e lasciati invariati (scala 1).

  • I moduli accoppiati in fabbrica (classe 2/3) non vengono mai scalati.

  • La correzione viene valutata in begin() e di nuovo dopo un riavvio che la libreria pilota (reset()) o un riavvio rilevato. In una situazione (un modello scritto durante il ciclo di alimentazione in corso) la libreria può emettere un reset del modulo per leggere il guadagno memorizzato.
Python
dev.set_rating_correction(enabled: bool)  -> None   # default enabled
dev.rating_correction_enabled             -> bool
dev.ct_rating_scale(ch=0)                 -> float  # scale currently applied (1.0 = none)
dev.ct_rating_status(ch=0)                -> (action, detail) | None
dev.refresh_rating_correction()           -> None
  • set_rating_correction(enabled) — disattiva la correzione per leggere i valori grezzi, non corretti (oppure su un modulo il cui firmware corregge già). Ricalcola subito.

  • ct_rating_scale(ch) — la scala applicata a corrente/potenza/energia su un canale; 1.0 quando non è attiva alcuna correzione.

  • ct_rating_status(ch) — (action, detail) dell'ultima valutazione per un canale, oppure None se il canale non è mai stato valutato (per esempio non è un canale SCT). action è uno tra "unity", "ok", "needs_reset", "warn_uncal", "warn_gain"; detail è testo. Le azioni warn_* significano che la libreria non è riuscita a determinare un fattore di scala sicuro e ha lasciato la lettura non corretta.

  • refresh_rating_correction() — rivalutare dopo un riavvio che la libreria non ha pilotato (per esempio un modello salvato e il modulo resettato dall'esterno).

Questa è una caratteristica del percorso SCT-013 in tutte le librerie rbAmp, non specifica di Python.

dev.save_gains() -> None

Una scrittura "nuda" di CMD_SAVE_GAINS (0x26) — solo in fabbrica.

Nota

⛔ BLOCCATO nel firmware di produzione (la v1.3 restituisce DEV_ERR_PARAM; il dispositivo rifiuta la scrittura e un successivo reboot annulla qualsiasi modifica in RAM). CMD_SAVE_GAINS è riservato alla modalità di provisioning di fabbrica e salva solo guadagni / NF / coefficienti di fase. Per la persistenza lato utente di sensor_class / ct_model per canale / indirizzo / etichetta, usi dev.save_user_config() (oppure le chiamate per canale set_ct_model_ch() / set_sensor_class(), che emettono già internamente CMD_SAVE_USER_CONFIG (0x32)).

Solleva: RbAmpModeError se il modulo non è in modalità provisioning di fabbrica, RbAmpIOError in caso di errore di comunicazione.

dev.prepare_address_change(new_addr) -> None

Passo 1 di 2 per cambiare l'indirizzo I²C del modulo. Adatto alla produzione sul firmware attuale (commit in due fasi della v1.3).

Scenario: verifica dell'intervallo → scrittura del candidato in REG_I2C_ADDRESS (0x30) in RAM → scrittura del magic 0xA5 in REG_ADDR_COMMIT_MAGIC (0x31) — armato. Il chiamante deve chiamare commit_address_change() entro 5 secondi, altrimenti l'armamento scade.

Raises:

  • RbAmpParamError — new_addr fuori da 0x08..0x77 oppure uguale all'indirizzo attuale

  • RbAmpIOError — errore di comunicazione

dev.commit_address_change() -> None

Passo 2 di 2. Va chiamata entro 5 secondi da prepare_address_change().

Scenario: verifica della freschezza armata → CMD_COMMIT_ADDR (opcode 0x30) → salvataggio in flash → CMD_RESET → circa 300 ms dal boot alla risposta → aggiornamento del campo indirizzo interno. Dopo il riavvio, REG_I2C_ADDRESS (0x30) (v1.3) legge il nuovo indirizzo attivo — questa è la verifica canonica.

Sicurezza

⚠ Storico: prima delle correzioni della v1.3, il cambio di indirizzo era documentato in modo errato come riservato alla fabbrica. Sulla v1.3 è un'operazione di produzione tramite commit in due fasi.

Una sfumatura in più:

Sicurezza

⚠ Riavvio e nuova enumerazione dopo il commit. Dopo un commit riuscito, il dispositivo si riavvia e si rienumera sul NUOVO indirizzo. Le chiamate successive su questa istanza di handle indirizzano il nuovo indirizzo in modo trasparente — ma qualunque ALTRO master sul bus (un altro script Python, un componente ESP-IDF, una sonda di debug) continua a considerare il dispositivo all'indirizzo vecchio finché il suo stato interno non viene aggiornato manualmente.

Raises:

  • RbAmpTimeoutError — la finestra di armamento (5 s) è scaduta
  • RbAmpIOError — errore di comunicazione

dev.factory_reset() -> None

Il comando CMD_FACTORY_RESET + un'attesa di 1500 ms.

Sicurezza

⚠ Operazione distruttiva. Cancella TUTTI i parametri in flash (modello TA, classe del sensore, coefficienti di calibrazione, indirizzo I²C). Il modulo torna ai valori di fabbrica — RbAmpSensorClass diventa UNSET, REG_CT_MODEL diventa 0. Ogni configurazione applicata in precedenza tramite set_sensor_class() / set_ct_model*() viene persa. Il prossimo utente DEVE riapplicare sia set_sensor_class() sia set_ct_model*() prima che la contabilità funzioni di nuovo. Non è un "riavvio morbido" — per un riavvio morbido usi reset(). factory_reset() è riservata al recupero da uno stato noto come difettoso o al passaggio del modulo a un altro utente / altra installazione.

Solleva: RbAmpIOError in caso di errore di comunicazione.

dev.reset() -> None

Il comando CMD_RESET + un'attesa di 100 ms. Un riavvio morbido del dispositivo senza perdere i parametri in flash.

Solleva: RbAmpIOError in caso di errore di comunicazione.

Identificazione e provisioning (v1.3)

Questi metodi permettono al master di capire esattamente cosa è collegato al bus (variante, mappa dei bit di capacità, UID, etichetta) e di preparare un modulo nuovo o appena flashato al funzionamento (provisioning

  • salvando la configurazione in flash).

dev.read_variant() -> int

Legge il registro HW_VARIANT (0x55) del modulo (il byte SKU canonico della v1.3):

Codice SKU canali I Canale U
1 UI1 1 sì
4 I1 1 no
5 I2 2 no
6 I3 3 no

Questo è il percorso consigliato per l'autodetect — il percorso di sondaggio con NACK è stato rimosso (il firmware non risponde mai con NACK alle letture; le aree non mappate → 0x00).

dev.read_capability() -> int

Legge la mappa di funzionalità a 16 bit dai registri CAPABILITY (0x57/0x58), u16 little-endian. La mappa include un flag per il front-end di tensione. La usi per il rilevamento delle funzionalità (non euristiche sulla versione).

dev.has_voltage() -> bool

Una funzione di comodo sopra read_capability() — restituisce True se il modulo ha un canale U. Memorizzato nell'handle alla prima chiamata.

dev.read_product_id() -> int

Legge PRODUCT_ID (0x54) — il byte identificativo della famiglia (rbAmp = 0x01). Usato dallo scanner del fleet per confermare che il dispositivo a un indirizzo sia davvero un rbAmp.

dev.read_uid() -> bytes

Legge l'identificatore univoco del microcontrollore a 96 bit da UID (0x5C..0x67) in un'unica operazione a raffica (restituisce un oggetto bytes di lunghezza 12). L'UID è garantito univoco per ogni modulo e non cambia dopo un nuovo flashing.

dev.read_label() -> str

Legge l'etichetta utente di 8 byte da LABEL (0x68..0x6F). ASCII, riempito con zeri; restituisce una stringa (senza NUL). Stringa vuota se non è impostata alcuna etichetta.

dev.set_label(label: str) -> None

Scrive un'etichetta di 8 byte. La stringa viene troncata a 8 byte o riempita con zeri. La scrittura è byte per byte (rbAmp non auto-incrementa le scritture; il pacchetto fa il ciclo sui byte automaticamente). Dopo la scrittura serve dev.save_user_config() perché l'etichetta sopravviva a un reset.

Solleva: RbAmpIOError in caso di errore di comunicazione.

dev.is_provisioned() -> bool

Verifica se il modulo ha completato il provisioning iniziale. Controlla REG_ERROR != 0xFB (DEV_ERR_FLASH_PARAMS_BAD) — 0xFB è impostato dal firmware quando il blocco di configurazione utente è vuoto / corrotto. Un modulo appena uscito dalla fabbrica restituisce False — serve save_user_config() dopo la prima impostazione del modello TA e dell'indirizzo.

Nota

Sulla v1.3 questo codice è normale per un modulo vergine (non fatale). Non interrompere il provisioning alla prima comparsa di 0xFB.

dev.save_user_config() -> None

Esegue CMD_SAVE_USER_CONFIG (opcode 0x32) — salva in flash il blocco di configurazione utente: SENSOR_CLASS, CT_MODEL per canale, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Non salva i parametri di calibrazione di fabbrica.

Blocca il thread per ~700 ms (ciclo di cancellazione e scrittura della flash). Durante la chiamata, non tentare di accedere al modulo da altri task.

Solleva: RbAmpIOError / RbAmpTimeoutError.

Rilettura ≠ persistenza

: la conferma che un valore è stato scritto in flash richiede un riavvio + rilettura. Vedere la sezione "Modello degli errori v1.3" più sotto.

Modello degli errori v1.3 — due canali indipendenti

Gli errori hanno due canali indipendenti che funzionano in modi diversi. Capire la differenza è fondamentale per interpretare correttamente lo stato del modulo.

Canale A — lato client, sincrono Canale B — lato DUT, asincrono durevole
Dove risiede Validazione interna al pacchetto (_validate_ct_code ecc.) REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A)
Quando scatta Prima della transazione I²C (la libreria la intercetta) Dopo che il firmware accetta una scrittura e la rifiuta
Cosa vede il master Il setter solleva RbAmpParamError; REG_ERROR sul dispositivo resta 0x00 REG_ERROR = il codice di rifiuto subito; bit3 si attiva alcune centinaia di millisecondi dopo la transazione
Persistente no (solo un'eccezione) Ultima scrittura di REG_ERROR; bit3 sticky W1C
Percorso tipico Un argomento fuori dai limiti consentiti (channel ∉ {0,1,2}, code fuori dall'insieme caratterizzato, sensor_class fuori dall'enum) Una scrittura diretta di registro che il pacchetto non pre-valida (basso livello dev._io.write_reg() con un byte non valido)

Canale A — validazione lato client (setter del pacchetto)

Tutti i setter del pacchetto (set_sensor_class, set_ct_model, set_ct_model_ch, configure_channels, ecc.) verificano prima gli argomenti rispetto ai valori ammessi. Se un argomento è fuori intervallo, il setter solleva RbAmpParamError, senza alcuna transazione I²C. Di conseguenza, REG_ERROR sul dispositivo resta invariato:

Python
from rbamp import RbAmp, RbAmpParamError

try:
    dev.set_ct_model_ch(99, 3)        # invalid channel
except RbAmpParamError as e:
    print(f"client-side guard: {e}")
    reg_err = dev.read_last_error()
    print(f"REG_ERROR on the device: 0x{reg_err:02X}")
    # → 0x00 (the package stopped it before the wire, REG_ERROR untouched)

Ciò significa: se vuole sapere esattamente perché un setter è fallito, la fonte affidabile è l'eccezione stessa (RbAmpParamError.args / str(e)). REG_ERROR sul dispositivo non dice nulla in questo scenario.

Canale B — rifiuto lato DUT (asincrono durevole)

Se una scrittura è passata via I²C (la libreria non l'ha intercettata perché l'argomento sembrava valido) ma il firmware l'ha rifiutata, entra in gioco il secondo canale:

  • read_last_error() restituisce subito il codice della causa (per esempio 0xFE = DEV_ERR_PARAM). È l'esito dell'ultima scrittura: qualunque scrittura riuscita successiva lo sovrascrive. Va letto subito dopo la scrittura, prima di qualsiasi altra transazione.

  • has_error() — l'indicatore persistente W1C di EVENT_FLAGS.bit3. Non si attiva istantaneamente: al banco è stato misurato un ritardo di alcune centinaia di millisecondi tra la transazione rifiutata e l'impostazione del bit3.

Sicurezza

⚠ Non usare has_error() per validare una scrittura appena eseguita. Per l'esito di quella specifica scrittura, è affidabile solo read_last_error(), letto subito dopo la scrittura e prima di qualsiasi altra transazione (oltre all'eccezione del setter). has_error() è il canale asincrono per il monitoraggio a polling di «se qualcosa è andato in errore tra due controlli», non per la validazione sincrona.

Cancellare un errore durevole — cancellare entrambi (REG_ERROR e bit3)

bit3 viene ricalcolato dal firmware ogni poche centinaia di millisecondi a partire dallo stato attuale di REG_ERROR. Quindi un semplice clear_event_flags(1 << 3) non funzionerà — il bit3 viene subito reimpostato da REG_ERROR, non ancora azzerato. L'ordine corretto:

Python
dev.clear_error()                     # zero REG_ERROR
dev.clear_event_flags(1 << 3)         # reset sticky bit3

Se serve l'atomicità, non deve esserci alcuna scrittura rifiutata tra le due.

dev.read_last_error() -> int

Legge direttamente il registro REG_ERROR (0x02) del dispositivo (una sola lettura sul filo) — l'esito dell'ultima transazione accettata sul bus (una scrittura o un comando). Non persistente: qualsiasi scrittura riuscita successiva lo sovrascrive con il proprio esito. Usato nel Canale B (rifiuto lato DUT) per il codice di causa esteso.

dev.has_error() -> bool

Un helper di comodo su EVENT_FLAGS.bit3 (ERROR_OCCURRED). Restituisce True se il bit3 è impostato. W1C persistente; non si azzera finché non c'è un azzeramento esplicito (con una riserva — vedi la sezione «Azzerare un errore durevole» sopra).

dev.read_event_flags() -> int / dev.clear_event_flags(mask: int) -> None

EVENT_FLAGS (0x2A) è un byte di flag persistenti; i bit specifici sono descritti nella specifica (incluso ERROR_OCCURRED bit3). L'azzeramento è write-1-to-clear.

dev.clear_error() -> None

Emette CMD_CLEAR_ERROR (opcode 0x31) — azzera REG_ERROR. Necessario per azzerare un errore durevole insieme a clear_event_flags(1 << 3).

Configurazione multi-canale (v1.3)

Sui moduli multi-canale (I2, I3) ogni canale di corrente ha il proprio modello di sensore TA. L'utility atomica per la configurazione in blocco è configure_channels().

dev.configure_channels(cls: RbAmpSensorClass, models: Sequence[int], n: int = None) -> None

Parameters:

  • cls — la classe del sensore (RbAmpSensorClass.SCT_013 per le pinze SCT-013; WIRED_CT/BUILTIN_CT riservate).

  • models — una sequenza di codici modello TA (uno per canale).

  • n — la lunghezza (facoltativa; predefinito = len(models)).

Internamente la funzione esegue:

  1. set_sensor_class(cls) una volta.
  2. Per ogni canale: prepari REG_CT_MODEL = models[k] + CMD_SET_CT_MODEL_CHk.

  3. Uno CMD_SAVE_USER_CONFIG terminale alla fine — cioè un ciclo di cancellazione e scrittura della flash per l'intera configurazione.

Limitato alla variante: se len(models) è maggiore del numero di canali della variante, gli elementi in eccesso vengono ignorati.

Raises:

  • RbAmpParamError — cls non valida oppure models[k] (validazione lato client per classe; REG_ERROR sul dispositivo resta 0x00).

  • RbAmpIOError — errore di bus.

  • RbAmpTimeoutError — timeout di scrittura in flash.
Nota

Codici accettati per classe: SCT_013 → {1, 2, 3, 4, 5, 6, 7}; un codice fuori dall'insieme solleva RbAmpParamError prima del bus. Vedi 03 · Selezione del sensore.

dev.read_ct_model_ch(ch: int) -> int

Legge il modello di sensore TA applicato (mirror di verifica) su uno specifico canale dal registro 0x51 (ch0) / 0x52 (ch1) / 0x53 (ch2). È una rilettura dalla RAM, non una conferma della persistenza — per la conferma del salvataggio in flash, usare dev.reset() + una rilettura del mirror.

RbAmpFleet — gestione di più moduli

La classe RbAmpFleet è la principale superficie di alto livello del pacchetto v1.3. Gestisce una raccolta di moduli su un bus I²C condiviso: rilevamento, provisioning, aggregazione delle interrogazioni, aggregazione degli errori, istantanee sincrone tramite un broadcast General-Call.

Una flotta è legata a un solo bus (di solito SMBus(1) su CPython o I2C(0, ...) su MicroPython). Il limite morbido sul numero di moduli è RBAMP_FLEET_MAX_MODULES = 16.

Ciclo di vita

Python
RbAmpFleet(bus, max_modules: int = 16)

Dopo del fleet, tutti gli handle acquisiti vengono rilasciati.

Scoperta — scan()

Python
fleet.scan(match_product: bool = True) -> int

Interroga il bus sull'intervallo 0x08..0x77. Per ogni indirizzo che risponde con ACK:

  1. Verifica l'identità (PRODUCT_ID, HW_VARIANT, CAPABILITY). Se match_product = True, richiede una corrispondenza con il PRODUCT_ID di rbAmp.

  2. Esegue il rilevatore di conflitti. Gli indirizzi sospetti vanno nella lista excluded, non nel fleet.

Restituisce il numero di moduli aggiunti al fleet.

Solleva: RbAmpIOError se il bus è bloccato (wedge-canary di Tier-2).

Accesso al modulo

Python
fleet.count                              # property: number of modules in the fleet
len(fleet)                                # equivalent to fleet.count
fleet[index]                              # a module by index
fleet.find(address) -> RbAmp | None       # a module by address
fleet.add(dev: RbAmp) -> None             # adopt an existing handle
for dev in fleet:                         # iteration
    ...
fleet.excluded -> tuple[int]              # addresses that ended up in excluded

Polling — poll_all()

Python
fleet.poll_all() -> list[tuple[RbAmpSnapshot | None, RbAmpFleetPoll]]

Interroga tutti i moduli del fleet con una sola chiamata. Restituisce una lista di tuple; per ogni modulo:

  • un RbAmpSnapshot oppure None (in caso di errore)
  • un POD RbAmpFleetPoll con i campi addr, ok, channels

Resistente alle mancate risposte: un modulo silenzioso non annulla l'interrogazione degli altri.

Aggregazione

Python
fleet.total_power() -> float              # W; summed over all channels
fleet.total_energy_wh() -> float          # W·h; per-handle accumulators
fleet.poll_errors() -> dict[int, bool]    # per-addr bit3 status

total_power somma la potenza attiva su tutti i canali di tutti i moduli. Sulle varianti I non c'è potenza attiva → contribuiscono con 0. Nel canone, l'80% del risultato ≈ la potenza attiva del modulo di rete.

fleet.aligned_snapshot(group=0) -> list[dict]

Istantanea di periodo coerente dell'intero fleet su tutti i canali di ogni membro: manda in broadcast un'istantanea General-Call, poi legge la potenza media dell'istantanea di ciascun membro sincronizzato per ogni canale (read_period_avg_p). Restituisce un dict per membro, nell'ordine del fleet, con le chiavi addr, in_sync, period_valid, avg_p (lista, una voce per canale; None se il membro ha perso il tick o non ha risposto). L'istantanea allinea solo le medie di periodo — le letture in tempo reale (I, P, PF) non possono essere allineate tra canali.

Indirizzamento e controllo dei conflitti

Python
fleet.assign_address(dev: RbAmp, new_addr: int) -> None
fleet.check_conflict(addr: int) -> bool   # collision detected?

assign_address riassegna l'indirizzo a un modulo già nel fleet: internamente — commit in due fasi + reset; l'handle nel fleet viene aggiornato automaticamente.

check_conflict è un controllo in sola lettura, a titolo di massima, per un indirizzo specifico. Per passarli tutti in rassegna, iteri sul fleet.

Provisioning

Protocollo nativo

6.5 Provisioning — flash nuova + SAVE (riferimento API)

⚠ Nella build attuale di rbamp, il provisioning avviene tramite dev.prepare_address_change() + dev.commit_address_change() su un handle RbAmp(bus, 0x50) creato a mano, poi fleet.add(dev). Vedi il frammento in 06 · Esempi, Scenario 2.

OBBLIGATORIO: esattamente un modulo vergine sul bus al momento del provisioning. Due moduli a 0x50 contemporaneamente sono fisicamente indistinguibili su I²C — non si possono distinguere neanche con hardware speciale.

Sincronizzazione GC della flotta — snapshot sincroni su tutta la flotta

Python
fleet.enable_gc_all(group: int = 0) -> int
fleet.gc_latch(group: int = 0, tick: int | None = None,
               settle_ms: int = 50) -> int
fleet.check_sync(expected_tick: int) -> list[RbAmpFleetSync]

Per una sincronizzazione stretta degli snapshot (sfasamento < 1 ms su tutta la flotta) si usa lo snapshot di broadcast I²C General-Call.

  1. enable_gc_all(group) imposta il flag GC_ENABLE di FLEET_CONFIG + GROUP_ID su tutti i moduli del fleet ed emette CMD_SAVE_USER_CONFIG su ciascuno (in modo persistente). Un riavvio dei moduli è obbligatorio dopo l'attivazione — eseguito automaticamente. Restituisce il numero di moduli su cui l'attivazione è riuscita.

  2. gc_latch(group, tick, settle_ms) invia il frame GC A5 27 group tick_lo tick_hi all'indirizzo 0x00. Se tick=None, il tick viene incrementato automaticamente da un contatore interno. Restituisce il tick del broadcast.

  3. check_sync(expected_tick) legge GC_TICK (0x59) su ogni modulo. Restituisce una lista di POD RbAmpFleetSync con i campi:

Python
class RbAmpFleetSync:
    addr: int          # I²C address of the module
    gc_tick: int       # REG_GC_TICK; 0xFFFF = never received a GC
    in_sync: bool      # True if gc_tick == expected_tick
    reachable: bool    # False if the read NACKs / times out

Configurazione della flotta per dispositivo (v1.3)

Questi metodi lavorano direttamente con un singolo modulo (senza fleet).

dev.enable_gc(enable: bool = True) -> None

enable_gc(True) scrive 1 nel flag GC_ENABLE di FLEET_CONFIG (0x27), salva in flash ed esegue il reset — dopo l'avvio il modulo accetterà le istantanee GC. enable_gc(False) azzera il bit in modo simmetrico. Blocca per circa 1 secondo (attesa di SAVE_USER_CONFIG + attesa di stabilizzazione dopo il reset). Idempotente: non fa nulla se lo stato attuale corrisponde già a quello richiesto.

dev.read_fleet_config() -> int

Legge il byte FLEET_CONFIG (0x27). Utile per la conferma di rilettura.

dev.set_group_id(group: int) -> None / dev.read_group_id() -> int

GROUP_ID (0x28) è un filtro dei frame GC: il modulo reagisce solo ai frame GC con un group_id corrispondente. Predefinito = 0x00 (broadcast).

dev.read_gc_tick() -> int

Legge GC_TICK (0x59) — l'ultimo valore di tick ricevuto da un frame GC. 0xFFFF = il modulo non ha mai ricevuto un frame GC dall'avvio.

RbAmp.broadcast_latch_group(bus, group: int = 0, tick: int = 0) -> bool

Metodo statico. Un invio di basso livello del frame GC A5 27 group tick_lo tick_hi direttamente su bus (senza fleet). Utile se un fleet non è ancora stato creato, oppure se vuole il controllo manuale del contatore dei tick.

RbAmp.broadcast_latch(bus) -> bool

Un metodo statico. Un wrapper legacy — equivalente a broadcast_latch_group(bus, group=0, tick=0). Per lo sviluppo nuovo è preferita la forma esplicita broadcast_latch_group con il proprio tick per la verifica dei testimoni.

Precondizione

: la capacità di snapshot General-Call (CAP_GC_LATCH, riportata da REG_CAPABILITY) deve essere presente nel firmware e il GC deve essere abilitato su ogni modulo (dev.enable_gc(True) o fleet.enable_gc_all() imposta il flag GC_ENABLE di FLEET_CONFIG, predefinito OFF). Un modulo nuovo con i valori di fabbrica non accetta il GC — per progetto, come protezione da una trasmissione accidentale su un bus di avviamento. Se il GC è disabilitato su tutto il fleet, il bus rifiuta il frame GC a livello di NACK; questo è rilevabile, non un'interruzione silenziosa. Su un modulo legacy senza CAP_GC_LATCH, il wrapper ricade su un'istantanea sequenziale per dispositivo.

Diagnostica

dev.set_logger(log_callable) -> None

Un canale diagnostico facoltativo. log_callable accetta un solo argomento str. Se impostato, il pacchetto registra brevemente i risultati di probe(), le istantanee non aggiornate e i rifiuti di modalità.

Uso tipico:

Python
import logging
log = logging.getLogger("rbamp")
log.setLevel(logging.INFO)
log.addHandler(logging.StreamHandler())
dev.set_logger(log.info)

# Or, simplest of all — a plain print:
dev.set_logger(print)

dev.sanity_reject_count: int

Contatore dei valori float scartati dal filtro di sanità (!isfinite(x) or |x| > 10000). A regime — 0. Un valore diverso da zero dopo la mitigazione con i tentativi indica di solito un raro artefatto dello stack I²C sfuggito al livello di ripetizione.

Contatori diagnostici di MachineI2CBackend (solo MicroPython)

MachineI2CBackend (il backend interno su MicroPython) espone due contatori:

  • backend.retry_exhaustion_count — quante volte il ciclo di ripetizione si è esaurito senza successo (è stata sollevata un'RbAmpIOError)

  • backend.retry_count_total — quante volte il ciclo di retry ha recuperato con successo tramite un retry silenzioso

Questi contatori sono accessibili tramite l'API avanzata:

Python
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp

backend = MachineI2CBackend(i2c, retry_attempts=5)
dev = RbAmp(backend, 0x50)   # the address is a parameter of RbAmp, not the backend

# ...soak-test for an hour...
print("retries succeeded:", backend.retry_count_total)
print("retries exhausted:", backend.retry_exhaustion_count)
print("sanity rejects:",    dev.sanity_reject_count)

SMBusBackend (CPython) non ha livello di ripetizione — il driver I²C del kernel Linux non è soggetto allo schema di NACK.

dev.read_seq_digest() -> int

Legge il byte di sequenza del digest (0..255). Cambia ogni volta che il modulo esegue il commit di un nuovo insieme di letture, quindi due letture che restituiscono lo stesso valore provengono dallo stesso commit — utile come controllo di coerenza attorno a letture raggruppate. È solo un marcatore di cambiamento (nessun checksum).

dev.reset_counters() -> None

Azzera tutti i contatori (RbAmp + il backend se è un MachineI2CBackend). Lo usi all'inizio di un test di durata.

Metadati e costanti di protocollo

Python
rbamp.__version__              # "1.6.0" — PEP 440 version
rbamp.__protocol_version__     # 0x04  — RBAMP_PROTOCOL_VERSION (v1.3)
rbamp.RBAMP_REG_SCHEMA_CRC32   # CRC32 of the schema codegen contract

REGISTERS e COMMANDS sono dizionari a livello di protocollo generati automaticamente:

Python
from rbamp import REGISTERS, COMMANDS

REGISTERS["U_RMS"]           # 0x86
REGISTERS["PERIOD_VALID"]    # 0x07
COMMANDS["LATCH_PERIOD"]     # 0x27
COMMANDS["SAVE_USER_CONFIG"] # 0x32  — user-facing persistence path
COMMANDS["SAVE_GAINS"]       # 0x26  — factory-only; BLOCKED in production
COMMANDS["FACTORY_RESET"]    # 0xAA

Usato all'interno del pacchetto. Esposto per gli utenti avanzati che fanno passare dati grezzi attraverso il proprio backend; gli utenti ordinari non lo toccano.

Dettagli del protocollo sul filo

Per il porting / debug con un analizzatore logico.

Letture dei registri — auto-incremento

Una lettura a raffica + N bytes restituisce N byte consecutivi a partire da addr. Su CPython, tramite bus.read_i2c_block_data(addr, start_reg, N) — una singola transazione.

Scritture di registro — un byte alla volta (NON incremento automatico)

⚠ Le scritture NON si auto-incrementano. Una scrittura a raffica + N bytes scrive solo il primo byte.

Un registro multi-byte si scrive byte per byte:

Python
# WRONG — data loss
label = b"MyMeter1"
bus.write_i2c_block_data(0x50, 0x68, list(label))   # only 'M' lands

# CORRECT — byte-at-a-time loop
for i, byte in enumerate(label):
    bus.write_byte_data(0x50, 0x68 + i, byte)

Riguarda i multi-byte scrivibili: LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, protetti dalla fabbrica), NF (u16), THRESH (u16). Le letture — a raffica OK.

Eccezione: il frame di broadcast GC (5 byte all'indirizzo 0x00) è un percorso separato del protocollo sul filo (ricezione general-call), inviato come un'unica transazione I²C.

Rilevamento della variante

Il byte SKU autorevole è REG_HW_VARIANT (0x55) (dev.hw_variant):

valore SKU
0x01 UI1
0x02 UI2
0x03 UI3
0x04 I1
0x05 I2
0x06 I3

Snapshot di broadcast General-Call

Attivazione facoltativa per modulo tramite il flag GC_ENABLE di REG_FLEET_CONFIG. Predefinito OFF. Si attiva con CMD_SAVE_USER_CONFIG + CMD_RESET. Dopo il reset, il modulo resta in ascolto del frame di broadcast sull'indirizzo 0x00:

Text
addr=0x00 | A5 27   
  • A5 — magico; 27 — l'opcode CMD_LATCH_PERIOD.
  • — 0x00 = all-call, altrimenti deve corrispondere a REG_GROUP_ID (0x28).
  • — un contatore di periodo a 16 bit.

Rilevamento della modalità di guasto (a 2 livelli, C.10 confermato su hardware):

  1. NACK dell'indirizzo GC: se la GC è disattivata su tutta la flotta, bus.write_i2c_block_data(0x00, ...) solleva OSError (o l'equivalente del backend). È un errore grave, non uno scarto silenzioso.
  2. Testimone per modulo: se non si è verificato alcun NACK, legga REG_PERIOD_VALID (0x07) su ciascun modulo. 1 = istantanea riuscita; 0 = GC disabilitato su quel modulo oppure periodo vuoto.

Modello degli errori (v1.3)

  • REG_ERROR (0x02) — esito dell'ultima scrittura, NON persistente. Leggerlo SUBITO DOPO l'operazione.
  • EVENT_FLAGS (0x2A) bit3 — segnale durevole (W1C persistente). Rilevamento canonico degli errori tramite bit3.
Python
# Canonical durable monitoring
event_flags = dev.read_reg(0x2A)
if event_flags & (1 << 3):
    last_err = dev.read_reg(0x02)
    # handle it
    dev.write_reg(0x2A, (1 << 3))   # W1C clear

Riferimenti


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