09 · Riferimento API
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
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:
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
RbAmpserve i moduli BASIC e STANDARD (STD). La linea viene rilevata automaticamente inbegin()(vedere Linea di moduli STD); non la sceglie mai lei. -
Basato su classi: la classe principale
RbAmpgestisce 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 automaticamentedev.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 Pythontry / except(nonlast_error()+ un codice di ritorno). -
Generatore asincrono per lo streaming periodico:
async for snap in dev.stream_period(interval_s=...).
Tipi
RbAmp
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.
: 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:
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
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)
: 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.
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.
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
Per l'integrazione dell'energia usi master_dt_ms, non latch_ms — latch_ms è un timer diagnostico del modulo.
Costanti di topologia
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()
02 · Inizializzazione e avvio (initialization) · BASIC o STD? (initialization) · Ciclo di polling continuo (consigliato) (period-metering)
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:
-
Legge
REG_VERSION— sollevaRbAmpIOErrorsu NACK,RbAmpVersionErrorse viene restituito0x00/0xFF. -
Mette in cache la topologia (sul firmware attuale
begin()non esegue alcun auto-probe; usa il suggerimento passato al costruttore). -
Legge
U_rmsper stabilire se è presente un sensore di tensione (soglia 1.0 V). -
Scrive
CMD_LATCH_PERIOD(primer) + attende 50 ms. Il primo snapshot dopo l'accensione viene scartato. -
Memorizza
time.monotonic()(otime.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
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
02 · Inizializzazione e avvio (inizializzazione) · 3. DATA_VALID (0xCE) non diventa mai 1 (risoluzione dei problemi) · 4 · Mappa dei registri (produzione v1.3) (riferimento API)
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
BASE o STD? (initialization) · Corrente multi-canale (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Blocco real-time V03 (0x86..0xBD) (api-reference)
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.
Proprietà
Corrente multi-canale (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Finestra di accesso ai canali (0x32 + 0x3C..0x3F) (api-reference)
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:
dev.current # _ChannelProxy → dev.current[0], dev.current[1], ...
dev.current_peak # _ChannelProxy
dev.power # _ChannelProxy
dev.power_factor # _ChannelProxy
Usage:
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à)
Riferimento dei registri RT (realtime-polling) · Contabilità bidirezionale (period-metering)
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
Riferimento dei registri RT (realtime-polling) · Polling — singolo modulo (realtime-polling) · 4.10 Blocco RT V03 (0x86..0xBD) (api-reference)
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)
⚠️ 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'accumulatoredev.energyfunzionano su un modulo STD — vedi «Contabilità di periodo» sotto. I totali di vita del modulo sonoread_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_msewait_readysono solo BASIC: su un modulo STD sollevanoRbAmpNotSupportedErrorprima che venga inviato alcunché sul bus.
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
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èFalsesu 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. SollevaRbAmpNotSupportedErrorsu 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 sollevanoRbAmpNotSupportedError(su BASIC la potenza reattiva non è esposta da questa libreria). -
read_std_totals(k)— blocco di totalik;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èTruequandonow.uptime_s < prev.uptime_s.-
deltaè unRbAmpStdEnergyche contiene l'incremento per campo, oppureNonequando il contatoregenerationè 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.
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
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; chiamaresave_config()per mantenerlo dopo un riavvio. Un valore non supportato sollevaRbAmpParamErrorprima che venga scritto alcunché sul bus. Il valore deve essere0(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 sollevaRbAmpParamError. Reimpostare l'ora dopo ogni riavvio del modulo (read_std_health().time_validèFalsefinché l'orologio non è impostato). -
get_start_current()/set_start_current()sollevanoRbAmpNotSupportedErrorsu un'immagine di modulo che non fornisce l'impostazione di corrente di avviamento;RbAmpStdConfig.start_ua_supportedindica 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.
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) dopostd_latch(). Un banco mai sottoposto a latch sollevaRbAmpStaleError. 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 sollevaRbAmpStaleError: 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 sudt_msdell'orologio del master.chè un indice di canale, oppure0xFF(predefinito) per il totale del modulo. Restituisce(wh_import, wh_export); l'export è zero o negativo. SollevaRbAmpStaleErrorper uno snapshot senza campioni.
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
04 · Misura per periodo e contabilizzazione tariffaria (period-metering)
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
04 · Misura per periodo e contabilità tariffaria (misura per periodo) · Calibrazione e accuratezza (risoluzione dei problemi)
Legge il bit di istantanea pronta. Restituisce True se l'ultima istantanea è recente.
dev.read_period_avg_power(ch=0) -> float
Registri dello snapshot del periodo (period-metering) · 4.11 Blocco periodo V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + periodo ch0 (0xD0..0xE3, build di produzione) (api-reference)
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
Registri dello snapshot del periodo (period-metering) · 4.12 V03 Q + periodo ch0 (0xD0..0xE3, build di produzione) (api-reference)
Potenza istantanea di picco sul canale 0 sul periodo chiuso. ch=0 solo sul firmware v1.
dev.read_period_latch_ms() -> int
13. Deriva dell'orologio multi-modulo nei test lunghi (troubleshooting) · 4.13 dt diagnostico lato chip (0xEC) (api-reference)
Durata del periodo dal punto di vista del dispositivo, in ms.
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
Ciclo di polling continuo (consigliato) (period-metering) · Taratura e precisione (troubleshooting) · 4.11 Blocco di periodo V03 (0xBE..0xCF) (api-reference)
Il punto di ingresso consigliato per la contabilità per periodo. La sequenza completa sotto il cofano:
-
Se
skip_latch=True— salta la scrittura del comando di snapshot (per lo schema multi-modulo dopo una serie manuale di comandi di snapshot). -
Altrimenti — scrivere
CMD_LATCH_PERIOD. - Acquisisca
time.monotonic()per calcolaremaster_dt_ms. time.sleep(settle_ms / 1000)— 50 ms per default.-
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). -
Legga
avg_p[0..channels-1]+max_p+latch_ms. - Aggiornare il timestamp e chiamare
energy.tick(snap)per integrare i Wh (a meno che l'accumulatore sia disattivato conenergy.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).
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 |
⚠ 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:
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
Algoritmo lato master (period-metering) · 7 · Semantica (riferimento API)
Un accumulatore Wh per canale. Si accede tramite una proprietà — il pacchetto ne possiede l'istanza:
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:
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
Impostazione della classe del sensore e del modello TA (inizializzazione) · 4.3 Sistema (0x20..0x25) (riferimento API) · 6.2 Associazione del modello TA — solo staging + CMD per canale (riferimento API)
Imposta la classe del sensore di corrente e la salva in flash. Bloccante, ~705 ms.
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—clsfuori da 0..3-
RbAmpModeError— il modulo è preaccoppiato in fabbrica (classe attualeWIRED_CT/BUILTIN_CT) eclsè 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 |
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 ancheRbAmpParamError) —codenon è nell'insieme di valori accettati per la classe corrente diREG_SENSOR_CLASS(perSCT_013è{1, 2, 3, 4, 5, 6, 7})-
RbAmpModeError— seset_sensor_class()non è stato chiamato, oppure il modulo è preaccoppiato in fabbrica (classe 2/3) e il codice differisce (usiset_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):
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
Impostazione della classe del sensore e del modello CT (initialization) · 6.2 Associazione del modello CT — pura predisposizione + CMD per canale (api-reference)
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.
✅ 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.
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—channelfuori da 0..dev.channels-1oppurecodenon nell'insieme accettato per la classe (perSCT_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:
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 edev.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.
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.0quando non è attiva alcuna correzione. -
ct_rating_status(ch)—(action, detail)dell'ultima valutazione per un canale, oppureNonese 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 azioniwarn_*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.
⛔ 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
Cambio di indirizzo (inizializzazione) · 4.5 Indirizzo (0x30..0x31) (riferimento API) · 6.1 Cambio di indirizzo — commit in due fasi (adatto alla produzione) (riferimento API)
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_addrfuori da 0x08..0x77 oppure uguale all'indirizzo attuale -
RbAmpIOError— errore di comunicazione
dev.commit_address_change() -> None
Cambio di indirizzo (inizializzazione) · 4.5 Indirizzo (0x30..0x31) (riferimento API) · 6.1 Cambio di indirizzo — commit in due fasi (adatto alla produzione) (riferimento API)
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.
⚠ 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ù:
⚠ 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) è scadutaRbAmpIOError— errore di comunicazione
dev.factory_reset() -> None
Il comando CMD_FACTORY_RESET + un'attesa di 1500 ms.
⚠ 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
Rilevamento automatico della variante del modulo (initialization) · Riferimento del protocollo di filo rbAmp (v1.3) (api-reference) · 3.6 Algoritmo di rilevamento canonico (api-reference)
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
Rilevamento automatico della variante del modulo (inizializzazione) · 3.2 CAPABILITY (registri 0x57/0x58, u16 LE, sola lettura) (riferimento API) · 8 · Esempi di tracce sul filo (riferimento API)
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
3.5 PRODUCT_ID (0x54, u8, sola lettura) (api-reference) · 4.8 Identità (0x54..0x6F) (api-reference)
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
8.3 Scrittura multi-byte — LABEL un byte alla volta (api-reference)
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
8.3 Scrittura multi-byte — LABEL un byte alla volta (api-reference)
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.
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
6.5 Provisioning — flash nuova + SAVE (riferimento API) · 8.6 Provisioning da flash nuova (riferimento API)
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.
: 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:
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 esempio0xFE = 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 diEVENT_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.
⚠ 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:
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
3. DATA_VALID (0xCE) non diventa mai 1 (troubleshooting) · Codici di errore (REG_ERROR = 0x02) (troubleshooting) · 4 · Mappa dei registri (produzione v1.3) (api-reference)
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
4.4 Configurazione della flotta (0x27..0x2F) (api-reference) · 8.8 Flusso degli eventi di soglia — scrittura della soglia → attivazione → azzeramento W1C (api-reference)
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
Codici di errore (REG_ERROR = 0x02) (troubleshooting) · 6.7 Recupero dallo stato di errore — albero decisionale (api-reference)
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_013per le pinze SCT-013;WIRED_CT/BUILTIN_CTriservate). -
models— una sequenza di codici modello TA (uno per canale). n— la lunghezza (facoltativa; predefinito =len(models)).
Internamente la funzione esegue:
set_sensor_class(cls)una volta.-
Per ogni canale: prepari
REG_CT_MODEL = models[k]+CMD_SET_CT_MODEL_CHk. -
Uno
CMD_SAVE_USER_CONFIGterminale 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—clsnon valida oppuremodels[k](validazione lato client per classe;REG_ERRORsul dispositivo resta0x00). -
RbAmpIOError— errore di bus. RbAmpTimeoutError— timeout di scrittura in flash.
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
4.7 Specchi di verifica del modello TA (0x51..0x53) (riferimento API) · 8.10 Rilettura dello specchio di verifica del modello TA (controllo di sanità dopo l'associazione) (riferimento API)
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
RbAmpFleet(bus, max_modules: int = 16)
Dopo del fleet, tutti gli handle acquisiti vengono rilasciati.
Scoperta — scan()
Configurazione multi-modulo (initialization) · Polling multi-modulo — tre strategie (realtime-polling) · Problemi multi-modulo (troubleshooting)
fleet.scan(match_product: bool = True) -> int
Interroga il bus sull'intervallo 0x08..0x77. Per ogni indirizzo che risponde con ACK:
-
Verifica l'identità (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Sematch_product = True, richiede una corrispondenza con il PRODUCT_ID di rbAmp. -
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
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()
Configurazione multi-modulo (initialization) · Polling multi-modulo — tre strategie (realtime-polling)
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
RbAmpSnapshotoppureNone(in caso di errore) - un POD
RbAmpFleetPollcon i campiaddr,ok,channels
Resistente alle mancate risposte: un modulo silenzioso non annulla l'interrogazione degli altri.
Aggregazione
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
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
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
General Call (broadcast all'indirizzo 0x00) (initialization) · Multi-modulo — snapshot simultaneo (period-metering) · 6.3 Snapshot broadcast GC — sincronizzazione della flotta su adesione (api-reference)
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.
-
enable_gc_all(group)imposta il flagGC_ENABLEdi FLEET_CONFIG +GROUP_IDsu tutti i moduli del fleet ed emetteCMD_SAVE_USER_CONFIGsu ciascuno (in modo persistente). Un riavvio dei moduli è obbligatorio dopo l'attivazione — eseguito automaticamente. Restituisce il numero di moduli su cui l'attivazione è riuscita. -
gc_latch(group, tick, settle_ms)invia il frame GCA5 27 group tick_lo tick_hiall'indirizzo0x00. Setick=None, il tick viene incrementato automaticamente da un contatore interno. Restituisce il tick del broadcast. -
check_sync(expected_tick)leggeGC_TICK (0x59)su ogni modulo. Restituisce una lista di PODRbAmpFleetSynccon i campi:
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
Chiamata generale (broadcast all'indirizzo 0x00) (inizializzazione) · 4.4 Configurazione della flotta (0x27..0x2F) (riferimento API)
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.
: 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:
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:
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
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:
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 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 scrive solo il primo byte.
Un registro multi-byte si scrive byte per byte:
# 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:
addr=0x00 | A5 27
A5— magico;27— l'opcodeCMD_LATCH_PERIOD.—0x00= all-call, altrimenti deve corrispondere aREG_GROUP_ID (0x28).— un contatore di periodo a 16 bit.
Rilevamento della modalità di guasto (a 2 livelli, C.10 confermato su hardware):
- NACK dell'indirizzo GC: se la GC è disattivata su tutta la flotta,
bus.write_i2c_block_data(0x00, ...)sollevaOSError(o l'equivalente del backend). È un errore grave, non uno scarto silenzioso. - 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.
# 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
- 05 · Avvio rapido — il suo primo script funzionante
- 06 · Esempi — scenari funzionanti
-
10 · Risoluzione dei problemi — decodifica degli errori e correzione dei problemi comuni
-
Sorgente:
__init__.py,_rbamp_core.py,_snapshot.py,_energy.py,_io_micropython.py,_io_smbus.py
Sorgente e segnalazioni: rb-amp/rbamp-python · questa pagina nel repository: docs/09_api_reference.md (v1.6.1)