09 · Référence de l'API
L'API publique complète du paquet rbamp. Source — __init__.py (réexportations), _rbamp_core.py (la classe principale RbAmp), _snapshot.py (structures POD + hiérarchie des exceptions), _energy.py (accumulateur de Wh), _registers.py (constantes générées automatiquement).
Ce chapitre est une référence : signatures, valeurs renvoyées, effets de bord, cas limites. Pour des exemples fonctionnels, voir 06 · Exemples ; pour démarrer vite, voir 05 · Démarrage rapide.
Imports
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)
)
Import minimal pour une application typique :
from rbamp import RbAmp, RbAmpSensorClass, RbAmpError
Idiomes généraux
L'API suit les schémas Python standard :
-
Une classe pour chaque gamme de modules : la même classe
RbAmpcouvre les modules BASIC et STANDARD (STD). La gamme est détectée automatiquement dansbegin()(voir gamme de modules STD) ; vous ne la choisissez jamais. -
Orientée classe : la classe principale
RbAmpgère tout — lectures temps réel, période, configuration, diagnostics. Le handle détient en interne le backend et l'accumulateur d'énergie. -
Gestionnaire de contexte :
with RbAmp(bus, addr) as dev:— l'idiome recommandé.__enter__appelle automatiquementdev.begin(). -
Propriétés pour les lectures temps réel :
dev.voltage,dev.frequency— une propriété = une transaction I²C. Les propriétés indexées par canal passent par_ChannelProxy:dev.current[ch],dev.power[ch],dev.power_factor[ch]. -
Méthodes de lecture indexées par canal :
dev.read_current(ch),dev.read_power(ch). Totalement équivalentes à la forme propriété — utilisez celle qui vous convient. -
Des exceptions pour les erreurs : chaque erreur est une sous-classe de
RbAmpError. Le schéma Python standardtry / except(et nonlast_error()+ un code de retour). -
Générateur asynchrone pour le streaming périodique :
async for snap in dev.stream_period(interval_s=...).
Types
RbAmp
class RbAmp:
def __init__(self, bus, addr: int = 0x50): ...
La classe principale. Une instance par appareil esclave. Le bus est n'importe quel objet respectant une des signatures d'API « connues » : smbus2.SMBus, machine.I2C, ou un backend personnalisé (voir 04 · Matériel).
Le backend est sélectionné automatiquement au premier accès au bus :
| méthode de l'objet bus | 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 |
déjà enveloppé (simulacres de test, adaptateurs FTDI) |
Si aucune signature ne correspond, une RbAmpParamError est levée avec une description.
Hiérarchie des exceptions
Chaque erreur du paquet est une sous-classe de RbAmpError, qui hérite elle-même de OSError (et non de Exception nue). Cela signifie que le code existant avec des gestionnaires except OSError: continue d'attraper les erreurs rbAmp sans aucune réécriture — la convention Python standard pour les pilotes d'E/S matérielles.
: RbAmpParamError hérite de RbAmpError + ValueError sous CPython (héritage multiple). Sous MicroPython, dont tous les ports ne prennent pas en charge l'héritage multiple, il se replie sur une base unique. Du point de vue de l'utilisateur, try / except RbAmpParamError fonctionne de la même façon. Mais try / except ValueError n'intercepte que sous CPython — sous MicroPython, ce gestionnaire passe à côté. Le code qui doit se comporter de la même façon sur toutes les plateformes doit intercepter explicitement RbAmpParamError.
Usage 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)
: sous CPython, IntEnum de la bibliothèque standard enum est utilisé. Sur les ports MicroPython sans module enum, un repli en classe simple avec les mêmes valeurs de membres est utilisé. Du point de vue de l'utilisateur, les deux formes sont identiques : dev.set_sensor_class(RbAmpSensorClass.SCT_013) ou dev.set_sensor_class(1) — les deux fonctionnent.
SCT_013 est la classe à sélectionner sur un module équipé de pinces SCT-013 installées par l'utilisateur. WIRED_CT et BUILTIN_CT décrivent des modules livrés appairés en usine avec leur capteur : set_sensor_class() et set_ct_model*() refusent de modifier un tel module (RbAmpModeError, voir garde de lecture avant écriture). Les valeurs hors de 0..3 lèvent RbAmpParamError.
RbAmpSnapshot
Renvoyé par dev.read_all(). Une classe Python simple (pas un @dataclass, pour la compatibilité MicroPython). Tous les champs sont en unités 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
Les voies inutilisées (au-delà de channels) sont remplies de zéros.
RbAmpPeriodSnapshot
Renvoyé par dev.read_period_snapshot(). La primitive de comptabilité de l'énergie.
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
Pour l'intégration d'énergie, utilisez master_dt_ms, et non latch_ms — latch_ms est un minuteur de diagnostic du module.
Constantes de topologie
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", ...
Cycle de vie
RbAmp(bus, addr=0x50)
Constructeur. La résolution du backend a lieu dans __init__. Aucun trafic I²C n'est généré avant begin().
| Paramètre | Description |
|---|---|
bus |
Objet bus I²C (smbus2.SMBus, machine.I2C, ou un wrapper) |
addr |
Adresse esclave 7 bits. Plage 0x08..0x77, par défaut 0x50 |
Lève : RbAmpParamError si l'objet bus n'est pas reconnu ou si addr est hors plage.
dev.begin()
02 · Initialisation et démarrage (initialization) · BASIC ou STD ? (initialization) · Cycle d'interrogation continu (recommandé) (period-metering)
Sonde le périphérique, détecte la gamme du module, met en cache la topologie et amorce la commande d'instantané.
Détection de la gamme (1.6.0). begin() vérifie d'abord si le module est un module STD (carte de registres 16 bits). Si oui, le descripteur passe en mode STD (dev.is_std devient True, dev.channels et dev.has_voltage_hw viennent du module) et begin() retourne. Sinon, la séquence BASIC ci-dessous s'exécute. Cela nécessite un backend de bus capable de transactions 16 bits ; sinon le module est traité comme BASIC.
Séquence BASIC :
-
Lit
REG_VERSION— lèveRbAmpIOErrorsur NACK,RbAmpVersionErrorsi0x00/0xFFest renvoyé. -
Met en cache la topologie (sur le firmware actuel,
begin()ne fait pas de sondage automatique ; il utilise l'indication passée au constructeur). -
Lit
U_rmspour déterminer si un capteur de tension est présent (seuil 1.0 V). -
Écrit
CMD_LATCH_PERIOD(amorce) + attend 50 ms. Le premier instantané après la mise sous tension est écarté. -
Mémorise
time.monotonic()(outime.ticks_ms()sur uPy) pour l'intégration d'énergie ultérieure.
Sur un module BASIC avec pinces SCT-013, begin() évalue aussi la correction de changement de calibre SCT-013.
Idempotent : sans risque à appeler plusieurs fois.
Gestionnaire de contexte
with RbAmp(bus, 0x50) as dev:
# dev.begin() has already been called in __enter__
...
# __exit__ — no-op (bus closing is the caller's responsibility)
L'idiome recommandé. Le __exit__ du paquet NE ferme PAS le bus — la gestion de l'objet bus reste à la charge de l'appelant (le schéma typique est un with SMBus(1) as bus, RbAmp(bus, 0x50) as dev: imbriqué).
dev.probe() -> bool
Une vérification de vivacité légère. Une seule lecture REG_VERSION sans effet de bord.
Renvoie : True si l'esclave a acquitté (ACK) et annoncé une version prise en charge ; False sinon. Ne lève pas d'exception — pour les scénarios de scrutation.
dev.wait_ready(timeout_ms=1000) -> None
02 · Initialisation et démarrage (initialization) · 3. DATA_VALID (0xCE) ne passe jamais à 1 (troubleshooting) · 4 · Carte des registres (production v1.3) (api-reference)
Interroge le drapeau « prêt » du module jusqu'à ce qu'il soit levé. Utile après la mise sous tension — le module peut avoir besoin de jusqu'à 100 ms pour sa première fenêtre temps réel.
Lève : RbAmpTimeoutError si le bit n'est pas vu avant que timeout_ms ne soit écoulé.
Propriétés — état du handle
BASIC ou STD ? (initialization) · Courant multicanal (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.10 Bloc temps réel 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 est une propriété vivante : chaque lecture passe par le bus (une lecture d'un octet de REG_VERSION). Mettez-la en cache côté application si vous l'interrogez dans une boucle serrée : fw = dev.firmware_version une fois après begin(). Si begin() n'a pas encore été appelé, firmware_version lève RbAmpIOError (le module peut répondre NACK tant que le descripteur est « froid »).
Les autres propriétés (topology, channels, has_voltage_hw, address) sont mises en cache dans le descripteur et renvoient les valeurs enregistrées après begin() sans toucher au bus.
Lectures temps réel (bloc RT, mise à jour toutes les 100 ms)
Toutes les méthodes lèvent RbAmpIOError en cas d'échec de communication (NACK après nouvelles tentatives ou rejet de cohérence) ou RbAmpParamError pour un argument invalide.
Propriétés
Courant multi-canaux (UI2 / UI3 / UI5 / UI7) (realtime-polling) · 4.14 Fenêtre d'accès aux canaux (0x32 + 0x3C..0x3F) (api-reference)
dev.voltage -> float # V — RMS voltage
dev.voltage_peak -> float # V — peak voltage
dev.frequency -> float # Hz — mains frequency
Indexé par canal via _ChannelProxy — prend en charge l'indexation [ch] et l'itération :
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) est égal à dev.channels.
Méthodes (strictement équivalentes à la forme sous forme de propriété)
Référence des registres RT (realtime-polling) · Comptabilité bidirectionnelle (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
Lecture unique de l'ensemble du bloc RT
Référence des registres RT (realtime-polling) · Interrogation — module unique (realtime-polling) · 4.10 Bloc temps réel V03 (0x86..0xBD) (api-reference)
dev.read_all() -> RbAmpSnapshot
Équivalent à des 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 consécutifs. Les canaux inutilisés (au-delà de channels) sont remplis de zéros.
Lève : RbAmpIOError si une lecture élémentaire échoue.
Les lecteurs communs — voltage, voltage_peak, current, current_peak, power, power_factor, frequency et leurs formes read_* — fonctionnent sur toutes les gammes de modules. Sur un module STD, phase dans read_voltage() / read_voltage_peak() sélectionne l'entrée de tension (0..n_voltage-1) ; sur un module BASIC, seul phase=0 est valide.
Gamme de modules STD (1.6.0)
⚠️ Statut de validation. Les fonctions embarquées d'énergie, d'angle de tension et de courant de démarrage sont validées sous CPython (smbus2). Les mêmes appels sont implémentés pour MicroPython (machine.I2C), mais le chemin 16 bits de MicroPython n'est pas encore validé sur matériel — privilégiez CPython pour ces fonctions embarquées tant qu'une note de version n'indique pas le contraire. Les mesures courantes (dev.voltage, dev.current[ch], dev.power[ch], instantanés de période) fonctionnent quoi qu'il en soit sur tout hôte pris en charge.
Une seule classe RbAmp couvre les deux gammes de modules. begin() détecte la gamme automatiquement ; dev.is_std vaut True sur un module STD. Le même câblage I²C et la même adresse s'appliquent (voir 04 · Matériel).
-
Les lectures communes (
voltage,current,power,power_factor,frequency) fonctionnent sur tout module. -
Les appels de cette section sont réservés au STD. Sur un module BASIC, ils lèvent
RbAmpNotSupportedError. -
Certains appels STD nécessitent aussi une image de module assez récente (énergie embarquée, compteurs en micro-unités, angles de tension, courant de démarrage). Si le module ne les fournit pas, l'appel lève
RbAmpNotSupportedError(« non disponible »). -
Les appels de période (
latch_period,read_period_*,stream_period) et l'accumulateurdev.energyfonctionnent sur un module STD — voir « Comptabilité de période » ci-dessous. Les totaux à vie propres au module sont fournis parread_std_energy(). -
Les appels de configuration des capteurs (
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 paire de changement d'adresse, les registres d'identité (firmware_version,read_variant,read_capability,read_product_id,read_uid,read_label,set_label,read_seq_digest), le canal erreur / événement (read_last_error,read_event_flags,clear_event_flags,has_error,clear_error), les aides de flotte (read_fleet_config,enable_gc,set_group_id,read_group_id,read_gc_tick),read_period_latch_msetwait_readysont réservés à BASIC : sur un module STD, ils lèventRbAmpNotSupportedErroravant tout envoi sur le 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
Lectures
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)— angle de phase de la tension par rapport à la phase 0, renvoyé sous la forme(degrees, valid).validvautFalsesur un module à tension unique ou sur une image de module qui ne signale pas les angles. -
read_phase_sequence()— code de séquence de phase :PHASE_SEQ_NA(0, non disponible),PHASE_SEQ_FORWARD(1),PHASE_SEQ_REVERSE(2),PHASE_SEQ_ABNORMAL(3).phase_seq_name(code)renvoie le nom textuel. LèveRbAmpNotSupportedErrorsur un module BASIC ou une image de module qui ne le signale pas. -
read_reactive(ch)/read_apparent(ch)— puissance réactive en var et puissance apparente en VA pour un canal. Modules STD uniquement ; sur un module BASIC, elles lèventRbAmpNotSupportedError(sur BASIC, la puissance réactive n'est pas exposée par cette bibliothèque). -
read_std_totals(k)— bloc de totauxk;k=0est le total général. Les totaux par phase dépendent de la version de la carte de registres du module. -
read_std_config()/read_std_health()— blocs de configuration et d'état/santé.
Objets de valeur
Classes simples (pas @dataclass), toutes réexportées depuis rbamp.
| Classe | Champs |
|---|---|
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 |
voir ci-dessous |
dev.read_std_energy() -> RbAmpStdEnergy
Instantané de l'énergie à vie embarquée. Nécessite un module qui fournit l'énergie embarquée ; sinon RbAmpNotSupportedError.
RbAmpStdEnergy contient :
| Groupe | Champs |
|---|---|
| Active, Wh | act_import_wh, act_export_wh, act_net_wh |
| Actif, mWh | act_import_mwh, act_export_mwh, act_net_mwh |
| Actif, µWh | act_import_uwh, act_export_uwh, act_net_uwh |
| Réactive | rea_import_varh, rea_export_varh ; µvarh : rea_import_uvarh, rea_export_uvarh |
| Par voie | channels (nombre d'entrées valides) ; ch_import_mwh[], ch_export_mwh[], ch_import_uwh[], ch_export_uwh[] |
| Comptabilité | generation, uptime_s, group_status |
| Indicateurs de provenance | fine, fine_reactive |
Les champs µWh / µvarh sont toujours renseignés. Lorsque l'image du module ne fournit pas les compteurs plus fins, ils sont mis à l'échelle à partir des plus grossiers, et fine (actif) / fine_reactive valent False — lisez ce drapeau si vous devez savoir d'où vient la valeur.
RbAmp.std_energy_delta(prev, now) -> (delta, module_restarted)
Énergie consommée entre deux instantanés read_std_energy() (méthode statique ; également exportée sous std_energy_delta). Sûre en cas de coupure de courant.
module_restartedvautTruelorsquenow.uptime_s < prev.uptime_s.-
deltaest unRbAmpStdEnergycontenant l'augmentation par champ, ouNonelorsque le compteurgenerationa changé (les deux lectures ne sont pas comparables). -
Un compteur qui revient légèrement en dessous de la lecture précédente (reprise après une coupure) est ramené à 0 ;
netvaut toujours import − export des parties écrêtées. -
Les entrées par voie ne sont remplies que lorsque les deux instantanés ont le même nombre de voies.
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")
Courant de démarrage et configuration
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()— le courant de démarrage de l'énergie en µA (0= désactivé). -
set_start_current(ua)— en dessous de ce courant par canal, le module ne comptabilise pas l'énergie en import/export ; les lectures en direct (I, P, Q) ne sont pas affectées. La valeur s'applique immédiatement ; appelezsave_config()pour la conserver après un redémarrage. Une valeur non prise en charge lèveRbAmpParamErroravant toute écriture sur le bus. La valeur doit être0(désactivé) ou un multiple de 10 µA dans la plage prise en charge. -
save_config()— persiste la configuration STD inscriptible. Bloquant. -
set_time(unix_epoch)— règle l'horloge du module à partir d'une époque Unix ; une époque antérieure à 2020 lèveRbAmpParamError. Réglez à nouveau l'heure après chaque redémarrage du module (read_std_health().time_validvautFalsetant que l'horloge n'est pas réglée). -
get_start_current()/set_start_current()lèventRbAmpNotSupportedErrorsur une image de module qui ne fournit pas le réglage du courant de démarrage ;RbAmpStdConfig.start_ua_supportedindique si c'est le cas.
Banques de latch
Un module STD qui expose des latch banks en conserve 8 indépendantes. Un banc s'accumule tant que son bit est levé dans le masque d'armement ; un latch le lit et le remet à zéro à la prochaine frontière de fenêtre de mesure, de sorte qu'une période est l'intervalle entre deux latches du même banc, mesuré à l'horloge du maître. Ces appels exigent un module qui expose des bancs et lèvent RbAmpNotSupportedError sinon ; un numéro de banc hors de 0..7 lève 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)— définit le masque d'armement. Le masque n'est pas conservé lors d'un redémarrage du module. -
std_latch(bank)— effectue le latch d'une banque. Ne la lisez pas avant 300 ms. -
std_read_latch(bank)— renvoie l'instantané de la banque. L'indicateur valid du module signale seulement que la banque a été verrouillée au moins une fois ; ce n'est pas un indicateur de fraîcheur, donc attendez au moins une fenêtre (300 ms est une borne sûre) aprèsstd_latch(). Une banque jamais verrouillée lèveRbAmpStaleError. Une banque vide qui n'est plus armée (le module a redémarré) est réarmée et verrouillée une fois pour démarrer une nouvelle période, et l'appel lèveRbAmpStaleError: abandonnez cette période et redémarrez votre propre référence temporelle. -
RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF)— convertit l'énergie de l'instantané en Wh surdt_msde l'horloge du maître.chest un indice de canal, ou0xFF(défaut) pour le total du module. Renvoie(wh_import, wh_export); l'export est nul ou négatif. LèveRbAmpStaleErrorpour un instantané sans échantillons.
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
Comptabilité de période
Voir 01 · Vue d'ensemble pour la vue générale, et 05 · Démarrage rapide, étape 5, pour un gabarit minimal.
Sur un module STD, les mêmes appels fonctionnent. begin() choisit la source de période selon ce que le module annonce :
| Le module signale | Source de période | Commande latch |
|---|---|---|
| compteurs d'énergie embarqués | différence entre deux lectures de compteur, sur le calendrier du maître | aucun |
| latch banks uniquement | latch-à-latch sur le banc 0 (au moins 300 ms de stabilisation) | CMD_LATCH_PERIOD sur le banc 0 |
| aucun | — | les appels de période lèvent RbAmpNotSupportedError |
Sur la source compteur, la première période démarre à begin(), latch_period() ne fait rien, is_period_valid() vaut True une fois les compteurs ancrés, read_period_max_power() lève RbAmpNotSupportedError (pas de crête), et read_period_avg_power(ch) n'existe que sur un module mono-voie, après la lecture d'une période. Un changement de génération de compteur réancre la période et lève RbAmpStaleError ; un redémarrage du module au sein d'une période est signalé dans snap.module_restarted (l'énergie n'est pas mesurée pendant le redémarrage). Sur la source latch, un instantané vide lève RbAmpStaleError ; si la banque avait perdu son armement (redémarrage du module), elle est d'abord réarmée. L'instantané porte avg_p_total, wh_net et module_restarted. read_period_latch_ms() est réservée au BASIC.
dev.latch_period() -> None
Écrit CMD_LATCH_PERIOD. N'attend pas — l'appelant doit respecter la stabilisation de 50 ms et vérifier dev.is_period_valid() avant de lire.
Pour la plupart des tâches, utilisez read_period_snapshot() — il encapsule toute la séquence.
dev.is_period_valid() -> bool
04 · Mesure par période et comptabilité tarifaire (mesure par période) · Étalonnage et précision (dépannage)
Lit le bit « instantané prêt ». Renvoie True si le dernier instantané est frais.
dev.read_period_avg_power(ch=0) -> float
Registres d'instantané de période (period-metering) · 4.11 Bloc de période V03 (0xBE..0xCF) (api-reference) · 4.12 V03 Q + période ch0 (0xD0..0xE3, build de production) (api-reference)
Puissance active moyenne sur un canal, sur la période clôturée. Doit être appelée après latch_period() + une stabilisation de 50 ms + une vérification de validité.
Résout chaque canal du module (ch = 0..channels-1), y compris les canaux 3 et plus sur les modules à 5 et 7 canaux (UI5 / UI7). L'instantané de période et l'accumulateur de Wh couvrent aussi tous les canaux. dev.read_period_avg_p(ch) est un alias au comportement identique.
dev.read_period_max_power() -> float
Registres d'instantané de période (period-metering) · 4.12 V03 Q + période ch0 (0xD0..0xE3, build de production) (api-reference)
Puissance instantanée crête sur la voie 0 sur la période fermée. ch=0 seulement sur le firmware v1.
dev.read_period_latch_ms() -> int
13. Dérive d'horloge multi-modules dans les longs tests (troubleshooting) · 4.13 dt côté puce de diagnostic (0xEC) (api-reference)
Durée de la période du point de vue de l'appareil, en ms.
Le minuteur interne du module a une précision limitée. Pour l'intégration de l'énergie, utilisez master_dt_ms de RbAmpPeriodSnapshot, et non ce champ.
dev.read_period_snapshot(settle_ms=50, skip_latch=False) -> RbAmpPeriodSnapshot
Cycle de scrutation continu (recommandé) (period-metering) · Calibration et précision (troubleshooting) · 4.11 Bloc de période V03 (0xBE..0xCF) (api-reference)
Le point d'entrée recommandé pour la comptabilité par période. La séquence complète sous le capot :
-
Si
skip_latch=True— ignore l'écriture de la commande d'instantané (pour le schéma multi-modules après une série manuelle de commandes d'instantané). -
Sinon — écrivez
CMD_LATCH_PERIOD. - Capturez
time.monotonic()pour calculermaster_dt_ms. time.sleep(settle_ms / 1000)— 50 ms par défaut.-
Vérifiez le drapeau « instantané prêt ». S'il vaut 0, levez
RbAmpStaleError(l'horodatage précédent est conservé, de sorte que l'instantané valide suivant couvre tout l'intervalle et que les Wh restent exacts). -
Lisez
avg_p[0..channels-1]+max_p+latch_ms. - Mettez à jour l'horodatage et appelez
energy.tick(snap)pour intégrer les Wh (sauf si l'accumulateur est désactivé viaenergy.disable()).
| Paramètre | Description |
|---|---|
settle_ms |
Attente après la commande d'instantané, en ms. Par défaut 50. |
skip_latch |
Si True — n'envoyez pas la commande d'instantané, lisez seulement. |
Lève : RbAmpStaleError (instantané obsolète) ; RbAmpIOError (panne de bus).
async dev.stream_period(interval_s=60.0, skip_stale=True)
Un générateur asynchrone qui produit des RbAmpPeriodSnapshot à l'intervalle interval_s. Fonctionne sur CPython asyncio et MicroPython uasyncio (MicroPython ≥ 1.20 — import asyncio fonctionne aussi ; pour les versions antérieures, utilisez 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])
| Paramètre | Description |
|---|---|
interval_s |
Période entre les instantanés (≥ 30 s recommandé) |
skip_stale |
True (défaut) — les instantanés obsolètes sont ignorés automatiquement. False — ils sont produits avec snap.valid=False, et votre code doit tester lui-même if not snap.valid: continue |
⚠ CPython : bloque la boucle d'événements. En coulisses, stream_period() appelle la fonction synchrone et bloquante read_period_snapshot() — qui fait un time.sleep(0.05) de stabilisation plus ~50–100 ms de lectures d'octets uniques sur le bus. Sur CPython, cela bloque toute la boucle asyncio pendant ces 100 ms — les autres coroutines (MQTT, HTTP, keepalive Wi-Fi) n'obtiennent aucun temps CPU. Pour les serveurs de production, enveloppez-le dans 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
Sur MicroPython le problème est moindre — l'ordonnanceur uasyncio cède la main aux autres tâches moins souvent, et l'I²C bloquant est jugé acceptable dans les schémas asynchrones embarqués. Si vous avez besoin d'un comportement non bloquant, utilisez un thread séparé via _thread.start_new_thread (sur ESP32 µPy).
Comptabilisation de l'énergie (accumulateur côté maître)
dev.energy — instance RbAmpEnergy
Algorithme côté maître (period-metering) · 7 · Sémantique (api-reference)
Un accumulateur de Wh par canal. Accessible par une propriété — le paquet en est propriétaire :
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'accumulateur est mis à jour automatiquement à chaque dev.read_period_snapshot() réussi. Il est signé — une valeur négative signifie un export net.
Formule d'intégration :
wh[ch] += snap.avg_p[ch] × master_dt_ms / 1000 / 3600
[W] [milliseconds] → [Wh]
dev.energy.disable() est utile pour les scénarios de veille profonde où le maître gère lui-même la persistance des Wh dans la mémoire RTC — voir 06 · Exemples, scénario 9.
Configuration du capteur
Une séquence en deux temps. Pour un guide détaillé du choix du modèle, voir 03 · Sélection du capteur de courant.
dev.set_sensor_class(cls) -> None
Définir la classe de capteur et le modèle de TC (initialization) · 4.3 Système (0x20..0x25) (api-reference) · 6.2 Liaison du modèle de TC — simple préparation + CMD par canal (api-reference)
Règle la classe du capteur de courant et l'enregistre en flash. Bloquant, ~705 ms.
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
# or equivalently:
dev.set_sensor_class(1)
| Paramètre | Description |
|---|---|
cls |
Une énumération RbAmpSensorClass ou un int 0..3 |
Raises:
RbAmpParamError—clshors de 0..3-
RbAmpModeError— le module est appairé en usine (classe couranteWIRED_CT/BUILTIN_CT) etclsdiffère ; la modifier effacerait l'étalonnage du capteur installé -
RbAmpIOError— échec de communication
À appeler avant set_ct_model*(). Réécrire la classe déjà détenue par le module est un no-op (aucune écriture sur le bus), car une écriture de classe efface côté périphérique les modèles de CT par canal. Voir garde de lecture avant écriture.
dev.read_sensor_class() -> int
Lit la classe de capteur figée : 0 UNSET, 1 SCT_013, 2 WIRED_CT, 3 BUILTIN_CT (valeurs de RbAmpSensorClass). Renvoie 0 sur un firmware où le registre n'est pas présent.
dev.set_ct_model(code) -> None
La forme à paramètre unique (héritée) — définit le modèle de pince de courant sur la voie 0 uniquement.
code |
Modèle |
|---|---|
| 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'ensemble accepté pour la classe SCT_013 est {1, 2, 3, 4, 5, 6, 7}. Le tableau complet des ensembles acceptés par classe est dans 03 · Sélection du capteur de courant.
Raises:
ValueError(et aussiRbAmpParamError) —codeabsent de l'ensemble d'acceptation de la classe pour leREG_SENSOR_CLASScourant (pourSCT_013, il s'agit de{1, 2, 3, 4, 5, 6, 7})-
RbAmpModeError— siset_sensor_class()n'a pas été appelé, ou si le module est appairé en usine (classe 2/3) et que le code diffère (utilisezset_ct_model_ch_force()en contexte de maintenance) -
RbAmpIOError— échec de communication
Régler le modèle déjà détenu par le canal est un no-op (garde de lecture avant écriture).
Message RbAmpModeError (classe non définie) :
REG_SENSOR_CLASS is UNSET;
call dev.set_sensor_class(RbAmpSensorClass.SCT_013) first
Équivalent à dev.set_ct_model_ch(0, code).
dev.set_ct_model_ch(channel, code) -> None
Réglage de la classe de capteur et du modèle de CT (initialization) · 6.2 Liaison du modèle de CT — préparation pure + CMD par canal (api-reference)
La forme par voie. Définit le modèle de pince de courant sur une voie donnée.
En coulisses : préparer REG_CT_MODEL (0x05) → commande CMD_SET_CT_MODEL_CH0/1/2 (opcode 0x28/0x29/0x2A) → stabilisation de 5 ms → CMD_SAVE_USER_CONFIG (0x32) → 700 ms. Bloquant, ~705 ms.
✅ v1.3 : l'ordre de liaison des canaux n'a pas d'importance. Sur v1.3, écrire REG_CT_MODEL (0x05) met la valeur en attente mais ne l'applique plus automatiquement à ch0. L'application se fait uniquement via CMD_SET_CT_MODEL_CHn. Vous pouvez configurer les canaux dans n'importe quel ordre.
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—channelhors de 0..dev.channels-1oucodeabsent de l'ensemble accepté pour la classe (pourSCT_013—{1, 2, 3, 4, 5, 6, 7})RbAmpModeError—set_sensor_class()non appelé, ou module appairé en usine et code différent
dev.set_ct_model_ch_force(channel, code) -> None
Variante de service de set_ct_model_ch() qui contourne la garde de lecture avant écriture : elle écrit même lorsque le module est appairé en usine ou détient déjà le code. Destinée aux techniciens qui rééquipent un appareil en capteurs. Le module valide toujours la paire (classe, code) et l'appel lève RbAmpParamError pour une paire incorrecte.
Garde de lecture avant écriture
Écrire un modèle de CT remplace l'étalonnage de la voie par le préréglage générique du modèle ; depuis la 1.6.0, les setters vérifient donc d'abord :
| Appel | Le module détient déjà cette valeur | Module appairé en usine (classe 2/3) | Sinon |
|---|---|---|---|
set_sensor_class(cls) |
sans effet, aucune écriture sur le bus | RbAmpModeError si cls diffère |
écritures + sauvegarde |
set_ct_model(code) / set_ct_model_ch(ch, code) |
sans effet, aucune écriture sur le bus | RbAmpModeError si le code diffère |
écritures + sauvegarde |
set_ct_model_ch_force(ch, code) |
écritures | écritures | écritures |
Miroirs de vérification V2 — CT_MODEL_CH0/1/2 (0x51-0x53)
Registres en lecture seule reflétant le préréglage de pince réellement appliqué sur chaque voie. Le protocole d'écriture sur le fil ne change pas — les écritures utilisent le mécanisme ci-dessus. 0x51-0x53 ne sont qu'une relecture pour les vérifications d'état et les schémas lecture-comparaison-écriture :
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)
Correction du changement de calibre SCT-013
Les modules SCT-013 sont étalonnés en usine avec un modèle de pince de référence. Lorsqu'une voie passe à un autre modèle, une image de module qui ne se remet pas à l'échelle d'elle-même continue d'appliquer le gain de référence ; le courant et la puissance seraient donc lus à la mauvaise échelle. Depuis la 1.6.0, la bibliothèque corrige cela automatiquement sur les modules BASIC avec la classe de capteur SCT_013 :
-
Le courant, la puissance et l'énergie dérivée de la puissance (
read_current,read_current_peak,read_power,read_period_avg_power, donc aussi l'instantané de période etdev.energy) sont corrigés selon le modèle choisi, par rapport au gain que le module applique réellement. -
La tension et le facteur de puissance ne sont jamais modifiés.
- Sur le firmware du module jusqu'à 1.4.19, un changement de modèle redémarre le module une fois (environ une seconde) ; à partir de 1.4.20, le module se corrige lui-même. La correction du calibre SCT met à l'échelle le courant, la puissance et l'énergie, jamais la tension ni le facteur de puissance.
-
Les modules dont le firmware réalise lui-même cette opération sont détectés et laissés tels quels (échelle 1).
-
Les modules appairés en usine (classe 2/3) ne sont jamais mis à l'échelle.
- La correction est évaluée dans
begin(), puis après un redémarrage que la bibliothèque déclenche (reset()) ou un redémarrage détecté. Dans un cas particulier (un modèle écrit pendant le cycle d'alimentation courant), la bibliothèque peut émettre une réinitialisation du module pour lire le gain enregistré.
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)— désactive la correction pour lire les valeurs brutes, non corrigées (ou sur un module dont le firmware corrige déjà). Recalcule immédiatement. -
ct_rating_scale(ch)— l'échelle appliquée au courant, à la puissance et à l'énergie sur une voie ;1.0lorsqu'aucune correction n'est active. -
ct_rating_status(ch)—(action, detail)de la dernière évaluation d'un canal, ouNonesi le canal n'a jamais été évalué (par exemple, pas un canal SCT).actionvaut l'une de :"unity","ok","needs_reset","warn_uncal","warn_gain";detailest un texte. Les actionswarn_*signifient que la bibliothèque n'a pas pu déterminer une mise à l'échelle sûre et a laissé la lecture non corrigée. -
refresh_rating_correction()— réévaluer après un redémarrage que la bibliothèque n'a pas piloté (par exemple un modèle enregistré et le module réinitialisé de l'extérieur).
C'est une fonction du chemin SCT-013 de toutes les bibliothèques rbAmp, et non propre à Python.
dev.save_gains() -> None
Une écriture CMD_SAVE_GAINS (0x26) « nue » — réservée à l'usine.
⛔ BLOQUÉ dans le firmware de production (v1.3 renvoie DEV_ERR_PARAM ; l'appareil rejette l'écriture et un redémarrage ultérieur annule toute modification côté RAM). CMD_SAVE_GAINS est réservée au mode de provisionnement en usine et ne persiste que les gains / NF / coefficients de phase. Pour une persistance destinée à l'utilisateur de sensor_class / ct_model par voie / adresse / étiquette, utilisez dev.save_user_config() (ou les appels par voie set_ct_model_ch() / set_sensor_class(), qui émettent déjà CMD_SAVE_USER_CONFIG (0x32) en interne).
Lève : RbAmpModeError si le module n'est pas en mode provisionnement usine, RbAmpIOError en cas d'échec de communication.
dev.prepare_address_change(new_addr) -> None
Changement d'adresse (initialization) · 4.5 Adresse (0x30..0x31) (api-reference) · 6.1 Changement d'adresse — commit en deux phases (compatible production) (api-reference)
Étape 1 sur 2 pour changer l'adresse I²C du module. Compatible production sur le firmware actuel (commit en deux phases v1.3).
Scénario : contrôle de la plage → écrire le candidat dans REG_I2C_ADDRESS (0x30) en RAM → écrire le magic 0xA5 dans REG_ADDR_COMMIT_MAGIC (0x31) — armé. L'appelant doit appeler commit_address_change() dans les 5 secondes, faute de quoi l'armement expire.
Raises:
-
RbAmpParamError—new_addrhors de 0x08..0x77 ou égal à l'adresse actuelle -
RbAmpIOError— échec de communication
dev.commit_address_change() -> None
Changement d'adresse (initialization) · 4.5 Adresse (0x30..0x31) (api-reference) · 6.1 Changement d'adresse — commit en deux phases (compatible production) (api-reference)
Étape 2 sur 2. Doit être appelée dans les 5 secondes qui suivent prepare_address_change().
Scénario : vérifier la fraîcheur de l'armement magique → CMD_COMMIT_ADDR (opcode 0x30) → persister en flash → CMD_RESET → environ 300 ms jusqu'à la réponse au démarrage → mettre à jour le champ d'adresse interne. Après le redémarrage, REG_I2C_ADDRESS (0x30) (v1.3) lit la nouvelle adresse active — c'est la vérification canonique.
⚠ Historique : avant les correctifs v1.3, le changement d'adresse était à tort documenté comme réservé à l'usine. En v1.3, c'est une opération de production via validation en deux phases.
Une nuance supplémentaire :
⚠ Redémarrage et réénumération après validation. Après une validation réussie, l'appareil se réinitialise et se réénumère sur la NOUVELLE adresse. Les appels suivants sur cette instance de descripteur ciblent la nouvelle adresse de façon transparente — mais tout AUTRE maître sur le bus (un autre script Python, un composant ESP-IDF, une sonde de débogage) continue de considérer l'appareil à l'ancienne adresse tant que son état interne n'est pas mis à jour manuellement.
Raises:
RbAmpTimeoutError— la fenêtre d'armement (5 s) a expiréRbAmpIOError— échec de communication
dev.factory_reset() -> None
La commande CMD_FACTORY_RESET + une attente de 1500 ms.
⚠ Opération destructive. Efface TOUS les paramètres flash (modèle de CT, classe de capteur, coefficients d'étalonnage, adresse I²C). Le module revient aux réglages d'usine : RbAmpSensorClass devient UNSET, REG_CT_MODEL devient 0. Toute configuration appliquée via set_sensor_class() / set_ct_model*() disparaît. Le prochain utilisateur DOIT réappliquer set_sensor_class() et set_ct_model*() avant que la comptabilité ne refonctionne. Ce n'est pas un « redémarrage doux » — pour un redémarrage doux, utilisez reset(). factory_reset() est réservé à la récupération d'un état connu comme défectueux ou à la remise du module à un autre utilisateur ou à une autre installation.
Lève : RbAmpIOError en cas d'échec de communication.
dev.reset() -> None
La commande CMD_RESET + une attente de 100 ms. Un redémarrage doux de l'appareil sans perdre les paramètres flash.
Lève : RbAmpIOError en cas d'échec de communication.
Identification et provisionnement (v1.3)
Ces méthodes permettent au maître de comprendre exactement ce qui est connecté au bus (variante, carte de bits de capacités, UID, étiquette) et de préparer un module neuf ou fraîchement flashé à l'exploitation (provisionnement
- enregistrer la configuration en flash).
dev.read_variant() -> int
Détection automatique de la variante du module (initialization) · Référence du protocole filaire rbAmp (v1.3) (api-reference) · 3.6 Algorithme canonique de détection (api-reference)
Lit le registre HW_VARIANT (0x55) du module (l'octet SKU canonique de la v1.3) :
| Code | SKU | Canaux I | Canal U |
|---|---|---|---|
1 |
UI1 | 1 | oui |
4 |
I1 | 1 | non |
5 |
I2 | 2 | non |
6 |
I3 | 3 | non |
C'est le chemin recommandé pour la détection automatique — le chemin de sondage par NACK a été supprimé (le firmware ne renvoie jamais de NACK en lecture ; adresse non mappée → 0x00).
dev.read_capability() -> int
Détection automatique de la variante du module (initialization) · 3.2 CAPABILITY (registres 0x57/0x58, u16 LE, lecture seule) (api-reference) · 8 · Exemples de traces filaires (api-reference)
Lit la carte de fonctionnalités 16 bits depuis les registres CAPABILITY (0x57/0x58), en u16 little-endian. La carte inclut un indicateur de front-end de tension. Utilisez-la pour la détection de fonctionnalités (et non des heuristiques de version).
dev.has_voltage() -> bool
Une aide pratique au-dessus de read_capability() — renvoie True si le module dispose d'une voie U. Mise en cache dans le descripteur au premier appel.
dev.read_product_id() -> int
3.5 PRODUCT_ID (0x54, u8, lecture seule) (api-reference) · 4.8 Identité (0x54..0x6F) (api-reference)
Lit PRODUCT_ID (0x54) — l'octet d'identification de la famille (rbAmp = 0x01). Utilisé par le scanner de flotte pour confirmer que l'appareil à une adresse est bien un rbAmp.
dev.read_uid() -> bytes
Lit l'identifiant MCU unique de 96 bits depuis UID (0x5C..0x67) en une seule rafale (renvoie un objet bytes de longueur 12). L'UID est garanti unique pour chaque module et ne change pas lors des reflashages.
dev.read_label() -> str
Lit l'étiquette utilisateur de 8 octets depuis LABEL (0x68..0x6F). ASCII, complétée par des zéros ; renvoie une chaîne (NUL retiré). Chaîne vide si aucune étiquette n'est définie.
dev.set_label(label: str) -> None
Écrit une étiquette de 8 octets. La chaîne est tronquée à 8 octets ou complétée par des zéros. L'écriture se fait octet par octet (rbAmp n'incrémente pas automatiquement les écritures ; le paquet fait la boucle sur les octets). Après l'écriture, un dev.save_user_config() est nécessaire pour que l'étiquette survive à une réinitialisation.
Lève : RbAmpIOError en cas d'échec de communication.
dev.is_provisioned() -> bool
Vérifie si le module a suivi la configuration initiale. Il contrôle REG_ERROR != 0xFB (DEV_ERR_FLASH_PARAMS_BAD) — 0xFB est positionné par le firmware lorsque le bloc de configuration utilisateur est vide ou corrompu. Un module neuf d'usine renvoie False — un save_user_config() est nécessaire après le premier réglage du modèle de CT et de l'adresse.
Sur la v1.3, ce code est normal pour un module vierge (et non fatal). N'interrompez pas le provisionnement à la première apparition de 0xFB.
dev.save_user_config() -> None
6.5 Provisionnement — flashage neuf + SAVE (api-reference) · 8.6 Provisionnement après flashage neuf (api-reference)
Émet CMD_SAVE_USER_CONFIG (opcode 0x32) — enregistre le bloc de configuration utilisateur en flash : SENSOR_CLASS, CT_MODEL par voie, I2C_ADDRESS, FLEET_CONFIG, GROUP_ID, LABEL. Il n'enregistre pas les paramètres d'étalonnage d'usine.
Bloque le thread pendant ~700 ms (cycle d'effacement + écriture de la flash). Pendant l'appel, n'essayez pas d'accéder au module depuis d'autres tâches.
Lève : RbAmpIOError / RbAmpTimeoutError.
: la confirmation qu'une valeur a bien été écrite en flash exige un redémarrage + une relecture. Voir la section « Modèle d'erreur v1.3 » ci-dessous.
Modèle d'erreurs v1.3 — deux canaux indépendants
Les erreurs ont deux canaux indépendants qui fonctionnent différemment. Comprendre la différence est essentiel pour interpréter correctement l'état du module.
| Canal A — côté client, synchrone | Canal B — côté DUT, asynchrone durable | |
|---|---|---|
| Où il réside | Validation interne au paquet (_validate_ct_code etc.) |
REG_ERROR (0x02) + EVENT_FLAGS.bit3 (0x2A) |
| Quand elle se déclenche | Avant la transaction I²C (la bibliothèque intercepte) | Après que le firmware accepte une écriture et la rejette |
| Ce que voit le maître | Le setter lève RbAmpParamError ; REG_ERROR sur l'appareil reste à 0x00 |
REG_ERROR = le code de rejet immédiatement ; bit3 se verrouille quelques centaines de millisecondes après la transaction |
| Collant | non (juste une exception) | dernière écriture de REG_ERROR ; bit3 collant W1C |
| Chemin typique | Un argument hors des bornes admises (channel ∉ {0,1,2}, code hors de l'ensemble caractérisé, sensor_class hors de l'énumération) | Une écriture de registre brute que le paquet ne pré-valide pas (dev._io.write_reg() de bas niveau avec un octet invalide) |
Canal A — validation côté client (setters du paquet)
Tous les setters du paquet (set_sensor_class, set_ct_model, set_ct_model_ch, configure_channels, etc.) vérifient d'abord les arguments par rapport aux valeurs autorisées. Si un argument est hors plage, le setter lève RbAmpParamError, sans aucune transaction I²C. Par conséquent, REG_ERROR sur l'appareil est laissé intact :
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)
Cela signifie : si vous voulez savoir exactement pourquoi un setter a échoué, la source fiable est l'exception elle-même (RbAmpParamError.args / str(e)). REG_ERROR sur l'appareil ne vous dit rien dans ce scénario.
Canal B — rejet côté DUT (asynchrone durable)
Si une écriture est passée par l'I²C (la bibliothèque ne l'a pas interceptée parce que l'argument semblait valide) mais que le firmware l'a rejetée, la seconde voie entre en jeu :
-
read_last_error()contient immédiatement le code de cause (par exemple0xFE = DEV_ERR_PARAM). C'est le résultat de la dernière écriture : toute écriture réussie suivante l'écrase. Vous devez le lire immédiatement après votre écriture, avant toute autre transaction. -
has_error()— l'indicateur collant W1C deEVENT_FLAGS.bit3. Il ne se verrouille pas instantanément : sur banc, un délai de quelques centaines de millisecondes a été mesuré entre la transaction rejetée et le passage à l'état levé de bit3.
⚠ N'utilisez pas has_error() pour valider une écriture que vous venez de faire. Pour le résultat de cette écriture précise, seul read_last_error() est fiable, lu immédiatement après l'écriture et avant toute autre transaction (plus l'exception du setter). has_error() est le canal asynchrone pour une surveillance par scrutation de « quelque chose a-t-il défailli entre deux contrôles », et non une validation synchrone.
Effacer une erreur durable — effacer les deux (REG_ERROR et bit3)
bit3 est recalculé par le firmware toutes les quelques centaines de millisecondes à partir de l'état courant de REG_ERROR. Ainsi, un simple clear_event_flags(1 << 3) ne fonctionnera pas — bit3 est aussitôt remis à l'état levé depuis le REG_ERROR pas encore effacé. L'ordre correct :
dev.clear_error() # zero REG_ERROR
dev.clear_event_flags(1 << 3) # reset sticky bit3
Si vous voulez de l'atomicité, aucune écriture rejetée ne doit s'intercaler entre elles.
dev.read_last_error() -> int
3. DATA_VALID (0xCE) ne passe jamais à 1 (troubleshooting) · Codes d'erreur (REG_ERROR = 0x02) (troubleshooting) · 4 · Carte des registres (production v1.3) (api-reference)
Lit directement le registre REG_ERROR (0x02) du périphérique (une seule lecture filaire) — le résultat de la dernière transaction acceptée avec succès sur le bus (une écriture ou une commande). Non collant : toute écriture réussie suivante l'écrase avec son propre résultat. Utilisé dans le canal B (rejet côté DUT) pour le code de cause étendu.
dev.has_error() -> bool
Une aide pratique sur EVENT_FLAGS.bit3 (ERROR_OCCURRED). Renvoie True si bit3 est levé. Collant W1C ; non effacé avant un effacement explicite (avec une réserve — voir la section « Effacer une erreur durable » ci-dessus).
dev.read_event_flags() -> int / dev.clear_event_flags(mask: int) -> None
4.4 Configuration de la flotte (0x27..0x2F) (api-reference) · 8.8 Flux d'événements de seuil — écriture du seuil → déclenchement → effacement W1C (api-reference)
EVENT_FLAGS (0x2A) est un octet de drapeaux collants ; les bits précis sont décrits dans la spécification (dont ERROR_OCCURRED bit3). L'effacement se fait par écriture (write-1-to-clear).
dev.clear_error() -> None
Codes d'erreur (REG_ERROR = 0x02) (troubleshooting) · 6.7 Rétablissement après erreur — arbre de décision (api-reference)
Émet CMD_CLEAR_ERROR (opcode 0x31) — remet REG_ERROR à zéro. Nécessaire pour effacer une erreur durable, en complément de clear_event_flags(1 << 3).
Configuration multi-canaux (v1.3)
Sur les modules multi-canaux (I2, I3), chaque canal de courant a son propre modèle de capteur CT. L'utilitaire atomique pour la configuration en bloc est configure_channels().
dev.configure_channels(cls: RbAmpSensorClass, models: Sequence[int], n: int = None) -> None
Parameters:
-
cls— la classe de capteur (RbAmpSensorClass.SCT_013pour les pinces SCT-013 ;WIRED_CT/BUILTIN_CTréservées). -
models— une séquence de codes de modèle de CT (un par voie). n— la longueur (facultatif ; par défaut =len(models)).
En interne, la fonction effectue :
set_sensor_class(cls)une fois.-
Pour chaque voie : préparer
REG_CT_MODEL = models[k]+CMD_SET_CT_MODEL_CHk. -
Une seule
CMD_SAVE_USER_CONFIGterminale à la fin — c'est-à-dire un seul cycle d'effacement + écriture de la flash pour toute la configuration.
Limité à la variante : si len(models) dépasse le nombre de canaux de la variante, les éléments en trop sont ignorés.
Raises:
-
RbAmpParamError—clsoumodels[k]invalide (validation côté client par classe ;REG_ERRORsur l'appareil reste à0x00). -
RbAmpIOError— erreur de bus. RbAmpTimeoutError— délai d'écriture en flash dépassé.
Codes admis par classe : SCT_013 → {1, 2, 3, 4, 5, 6, 7} ; un code hors de cet ensemble lève RbAmpParamError avant tout envoi sur le bus. Voir 03 · Choix du capteur.
dev.read_ct_model_ch(ch: int) -> int
4.7 Miroirs de vérification du modèle de TC (0x51..0x53) (api-reference) · 8.10 Relecture du miroir de vérification du modèle de TC (contrôle après liaison) (api-reference)
Lit le modèle de capteur CT appliqué (miroir de vérification) sur un canal précis, depuis le registre 0x51 (ch0) / 0x52 (ch1) / 0x53 (ch2). C'est une relecture depuis la RAM, pas une confirmation de persistance — pour confirmer la sauvegarde en flash, utilisez dev.reset() + une relecture du miroir.
RbAmpFleet — gérer plusieurs modules
La classe RbAmpFleet est la principale surface de haut niveau du paquet v1.3. Elle gère une collection de modules sur un bus I²C partagé : découverte, provisionnement, agrégation des interrogations, agrégation des erreurs, instantanés synchrones via une diffusion General-Call.
Une flotte est liée à un seul bus (en général SMBus(1) sur CPython ou I2C(0, ...) sur MicroPython). Le plafond souple du nombre de modules est RBAMP_FLEET_MAX_MODULES = 16.
Cycle de vie
RbAmpFleet(bus, max_modules: int = 16)
Après del fleet, tous les handles adoptés sont libérés.
Découverte — scan()
Configuration multi-modules (initialization) · Interrogation multi-modules — trois stratégies (realtime-polling) · Problèmes multi-modules (troubleshooting)
fleet.scan(match_product: bool = True) -> int
Sonde le bus sur la plage 0x08..0x77. Pour chaque adresse qui acquitte :
-
Contrôle l'identité (
PRODUCT_ID,HW_VARIANT,CAPABILITY). Simatch_product = True, il exige une correspondance avec le PRODUCT_ID rbAmp. -
Lance le détecteur de conflit. Les adresses suspectes vont dans la liste
excluded, pas dans la flotte.
Renvoie le nombre de modules ajoutés à la flotte.
Lève : RbAmpIOError si le bus est bloqué (canari de blocage de niveau 2).
Accès au module
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
Scrutation — poll_all()
Configuration multi-modules (initialization) · Interrogation multi-modules — trois stratégies (realtime-polling)
fleet.poll_all() -> list[tuple[RbAmpSnapshot | None, RbAmpFleetPoll]]
Interroge tous les modules de la flotte en un seul appel. Renvoie une liste de tuples ; pour chaque module :
- un
RbAmpSnapshotouNone(en cas d'échec) - un POD
RbAmpFleetPollavec les champsaddr,ok,channels
Tolérant aux MISS : un module silencieux n'annule pas la scrutation des autres.
Agrégation
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 additionne la puissance active sur tous les canaux de tous les modules. Sur les variantes I il n'y a pas de puissance active → elles contribuent 0. Dans le canon, 80 % du résultat ≈ la puissance active du module secteur.
fleet.aligned_snapshot(group=0) -> list[dict]
Instantané de période cohérent sur toute la flotte, sur toutes les voies de chaque membre : diffuse un instantané General-Call, puis lit la puissance moyenne d'instantané de chaque membre synchronisé pour chaque voie (read_period_avg_p). Renvoie un dict par membre, dans l'ordre de la flotte, avec les clés addr, in_sync, period_valid, avg_p (liste, une entrée par voie ; None si le membre a manqué le tick ou n'a pas répondu). L'instantané n'aligne que les moyennes de période — les lectures vivantes (I, P, PF) ne peuvent pas être alignées entre voies.
Adressage et contrôle des conflits
fleet.assign_address(dev: RbAmp, new_addr: int) -> None
fleet.check_conflict(addr: int) -> bool # collision detected?
assign_address réadresse un module existant de la flotte à une nouvelle adresse : en interne — validation en deux phases + réinitialisation ; le descripteur dans la flotte est mis à jour automatiquement.
check_conflict est une vérification en lecture seule, au mieux, pour une adresse précise. Pour parcourir toutes les adresses connues, itérez sur la flotte.
Provisionnement
6.5 Provisionnement — flashage neuf + SAVE (api-reference)
⚠ Dans la version actuelle de rbamp, le provisionnement se fait via dev.prepare_address_change() + dev.commit_address_change() sur un handle RbAmp(bus, 0x50) créé à la main, puis fleet.add(dev). Voir l'extrait dans 06 · Exemples, scénario 2.
DOIT : exactement un module vierge sur le bus au moment du provisionnement. Deux modules à 0x50 simultanément sont physiquement indiscernables sur I²C — ils ne peuvent pas être distingués, même avec du matériel spécial.
Synchronisation GC de la flotte — instantanés synchrones sur toute la flotte
General Call (diffusion à l'adresse 0x00) (initialization) · Multi-modules — instantané simultané (period-metering) · 6.3 Instantané par diffusion GC — synchronisation de flotte sur option (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]
Pour une synchronisation serrée des instantanés (décalage < 1 ms sur toute la flotte), on utilise un instantané de diffusion General-Call I²C.
-
enable_gc_all(group)définit le drapeauGC_ENABLEde FLEET_CONFIG +GROUP_IDsur tous les modules de la flotte, émetCMD_SAVE_USER_CONFIGsur chacun (persistant). Un redémarrage des modules est obligatoire après activation — effectué automatiquement. Renvoie le nombre de modules où l'activation a réussi. -
gc_latch(group, tick, settle_ms)envoie la trame GCA5 27 group tick_lo tick_hià l'adresse0x00. Sitick=None, le tick est incrémenté automatiquement par un compteur interne. Renvoie le tick de diffusion. -
check_sync(expected_tick)relitGC_TICK (0x59)sur chaque module. Renvoie une liste de PODRbAmpFleetSyncavec les champs :
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
Configuration de parc par appareil (v1.3)
Ces méthodes fonctionnent directement avec un seul module (sans flotte).
dev.enable_gc(enable: bool = True) -> None
Appel général (diffusion à l'adresse 0x00) (initialization) · 4.4 Configuration de parc (0x27..0x2F) (api-reference)
enable_gc(True) écrit 1 dans le drapeau GC_ENABLE de FLEET_CONFIG (0x27), l'enregistre en flash et réinitialise — le module commencera à accepter les instantanés GC après le démarrage. enable_gc(False) efface le bit de façon symétrique. Bloque pendant environ 1 seconde (stabilisation de SAVE_USER_CONFIG + stabilisation après réinitialisation). Idempotent : sans effet si l'état courant correspond déjà à l'état demandé.
dev.read_fleet_config() -> int
Lit l'octet FLEET_CONFIG (0x27). Utile pour confirmer la relecture.
dev.set_group_id(group: int) -> None / dev.read_group_id() -> int
GROUP_ID (0x28) est un filtre de trame GC : le module ne réagit qu'aux trames GC dont le group_id correspond. Par défaut = 0x00 (diffusion).
dev.read_gc_tick() -> int
Lit GC_TICK (0x59) — la dernière valeur de tick reçue d'une trame GC. 0xFFFF = le module n'a jamais reçu de trame GC depuis le démarrage.
RbAmp.broadcast_latch_group(bus, group: int = 0, tick: int = 0) -> bool
Méthode statique. Un envoi bas niveau de la trame GC A5 27 group tick_lo tick_hi directement sur bus (sans flotte). Utile si une flotte n'a pas encore été créée, ou si vous voulez un contrôle manuel du compteur de ticks.
RbAmp.broadcast_latch(bus) -> bool
Une méthode statique. Une enveloppe historique — équivalente à broadcast_latch_group(bus, group=0, tick=0). Pour les développements nouveaux, la forme explicite broadcast_latch_group avec son propre tick pour la vérification témoin est préférée.
: la capacité d'instantané General-Call (CAP_GC_LATCH, signalée par REG_CAPABILITY) doit être présente sur le firmware et GC doit être activé sur chaque module (dev.enable_gc(True) ou fleet.enable_gc_all() bascule le drapeau GC_ENABLE de FLEET_CONFIG, désactivé par défaut). Un module neuf aux réglages d'usine n'accepte pas GC — par conception, pour éviter une diffusion accidentelle sur un bus de mise en service. Si GC est désactivé sur toute la flotte, le bus rejette la trame GC au niveau NACK ; c'est détectable, pas une perte silencieuse. Sur un module ancien sans CAP_GC_LATCH, l'enveloppe revient à un instantané séquentiel par appareil.
Diagnostic
dev.set_logger(log_callable) -> None
Un récepteur de diagnostic facultatif. log_callable prend un seul argument str. S'il est défini, le paquet journalise brièvement les résultats de probe(), les instantanés périmés et les rejets de mode.
Usage typique :
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
Compteur des valeurs flottantes rejetées par le filtre de cohérence (!isfinite(x) or |x| > 10000). En régime établi — 0. Une valeur non nulle après l'atténuation par nouvelles tentatives signale généralement un artefact rare de la pile I²C qui a traversé la couche de nouvelles tentatives.
Compteurs de diagnostic de MachineI2CBackend (MicroPython uniquement)
MachineI2CBackend (le backend interne sous MicroPython) expose deux compteurs :
-
backend.retry_exhaustion_count— nombre de fois où la boucle de nouvelles tentatives a été épuisée sans succès (uneRbAmpIOErrora été levée) -
backend.retry_count_total— nombre de fois où la boucle de nouvelles tentatives a réussi à se rétablir par une nouvelle tentative silencieuse
Ces compteurs sont accessibles via l'API avancée :
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) n'a pas de couche de nouvelles tentatives — le pilote I²C du noyau Linux n'est pas soumis au motif de NACK.
dev.read_seq_digest() -> int
Lit l'octet de séquence du condensat (0..255). Il change chaque fois que le module valide un nouveau jeu de lectures ; deux lectures qui renvoient la même valeur proviennent donc du même commit — utile comme contrôle de cohérence autour d'une scrutation par lots. C'est un simple marqueur de changement (pas une somme de contrôle).
dev.reset_counters() -> None
Remet à zéro tous les compteurs (RbAmp + le backend s'il s'agit d'un MachineI2CBackend). À utiliser au début d'un test de longue durée.
Métadonnées et constantes de protocole
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 et COMMANDS sont des dictionnaires de protocole générés automatiquement :
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
Utilisé à l'intérieur du paquet. Exposé pour les utilisateurs avancés qui font du transit brut via leur propre backend ; les utilisateurs ordinaires n'y touchent pas.
Détails du protocole filaire
Pour le portage / le débogage à l'analyseur logique.
Lectures de registres — incrémentation automatique
Une lecture en rafale renvoie N octets consécutifs à partir de addr. Sous CPython, via bus.read_i2c_block_data(addr, start_reg, N) — une seule transaction.
Écritures de registres — octet par octet (PAS d'incrémentation automatique)
⚠ Les écritures ne s'incrémentent PAS automatiquement. Une écriture en rafale n'écrit que le premier octet.
Un registre multi-octets s'écrit octet par octet :
# 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)
Concerne les multi-octets inscriptibles : LABEL (0x68-0x6F), U_GAIN/I_GAIN (f32, réservé à l'usine), NF (u16), THRESH (u16). Lectures — les rafales sont admises.
Exception : la trame de diffusion GC (5 octets à l'adresse 0x00) suit un chemin de protocole filaire distinct (réception General-Call), émise comme une seule transaction I²C.
Détection de variante
L'octet SKU faisant autorité est REG_HW_VARIANT (0x55) (dev.hw_variant) :
| valeur | SKU |
|---|---|
0x01 |
UI1 |
0x02 |
UI2 |
0x03 |
UI3 |
0x04 |
I1 |
0x05 |
I2 |
0x06 |
I3 |
Instantané de diffusion General-Call
Activation par module via le drapeau GC_ENABLE de REG_FLEET_CONFIG. Désactivé par défaut. Activé via CMD_SAVE_USER_CONFIG + CMD_RESET. Après la réinitialisation, le module écoute la trame de diffusion à l'adresse 0x00 :
addr=0x00 | A5 27
A5— magique ;27— le code opérationCMD_LATCH_PERIOD.—0x00= appel général (all-call), sinon il doit correspondre àREG_GROUP_ID (0x28).— un compteur de période sur 16 bits.
Détection des modes de défaillance (2 niveaux, C.10 confirmé sur matériel) :
- NACK de l'adresse GC : si GC est désactivé sur toute la flotte,
bus.write_i2c_block_data(0x00, ...)lèveOSError(ou l'équivalent du backend). C'est une erreur franche, pas un abandon silencieux. - Témoin par module : si aucun NACK n'est survenu, lisez
REG_PERIOD_VALID (0x07)sur chaque module.1= instantané réussi ;0= GC désactivé sur ce module ou période vide.
Modèle d'erreurs (v1.3)
REG_ERROR (0x02)— résultat de la dernière écriture, NON collant. Lisez-le IMMÉDIATEMENT APRÈS l'opération.EVENT_FLAGS (0x2A) bit3— signal durable (collant W1C). Détection d'erreur canonique via 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
Références
- 05 · Démarrage rapide — votre premier script fonctionnel
- 06 · Exemples — scénarios fonctionnels
-
10 · Dépannage — décoder les erreurs et corriger les problèmes courants
-
Source :
__init__.py,_rbamp_core.py,_snapshot.py,_energy.py,_io_micropython.py,_io_smbus.py
Source et signalements : rb-amp/rbamp-python · cette page dans le dépôt : docs/09_api_reference.md (v1.6.1)