rbAmp
FR
Boutique
Docs
Mis à jour le · Modifier sur GitHub (Edit on GitHub)

09 · Référence de l'API

Carte de registres du module : l'espace d'adresses de la page 0, de 0x00 à 0xFF

Instantané de période atomique : une seule écriture clôt la période courante et en ouvre une nouvelle

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

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

Import minimal pour une application typique :

Python
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 RbAmp couvre les modules BASIC et STANDARD (STD). La gamme est détectée automatiquement dans begin() (voir gamme de modules STD) ; vous ne la choisissez jamais.

  • Orientée classe : la classe principale RbAmp gè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 automatiquement dev.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 standard try / except (et non last_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

Python
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.

Hiérarchie des exceptions du paquet rbamp : chaque erreur dérive de RbAmpError, lui-même dérivé de OSError.

Remarque

: 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 :

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

RbAmpSensorClass

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

: 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.

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

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.

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

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

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

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

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

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 :

  1. Lit REG_VERSION — lève RbAmpIOError sur NACK, RbAmpVersionError si 0x00 / 0xFF est renvoyé.

  2. Met en cache la topologie (sur le firmware actuel, begin() ne fait pas de sondage automatique ; il utilise l'indication passée au constructeur).

  3. Lit U_rms pour déterminer si un capteur de tension est présent (seuil 1.0 V).

  4. Écrit CMD_LATCH_PERIOD (amorce) + attend 50 ms. Le premier instantané après la mise sous tension est écarté.

  5. Mémorise time.monotonic() (ou time.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

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

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

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

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

firmware_version 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.

Des fenêtres de mesure de 100 ms s'enchaînent, DRDY impulse une fois par fenêtre, et le maître lit le bloc de résultat atomique.

Propriétés

Python
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 :

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

Usage:

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

len(dev.current) est égal à dev.channels.

Méthodes (strictement équivalentes à la forme sous forme de propriété)

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

Lecture unique de l'ensemble du bloc RT

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

Sécurité

⚠️ 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'accumulateur dev.energy fonctionnent sur un module STD — voir « Comptabilité de période » ci-dessous. Les totaux à vie propres au module sont fournis par read_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_ms et wait_ready sont réservés à BASIC : sur un module STD, ils lèvent RbAmpNotSupportedError avant tout envoi sur le bus.

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

Lectures

Python
dev.read_std_voltage(phase=0)    -> RbAmpStdVoltage   # RMS, peak, THD, angle
dev.read_voltage_angle(phase=0)  -> (float, bool)     # (degrees, valid)
dev.read_phase_sequence()        -> int               # 0..3
dev.read_std_channel(ch=0)       -> RbAmpStdChannel   # I / P / Q / S / PF + harmonics
dev.read_std_totals(k=0)         -> RbAmpStdChannel   # totals block k (0 = grand total)
dev.read_reactive(ch=0)          -> float             # var
dev.read_apparent(ch=0)          -> float             # VA
dev.read_std_config()            -> RbAmpStdConfig
dev.read_std_health()            -> RbAmpStdHealth
  • read_voltage_angle(phase) — angle de phase de la tension par rapport à la phase 0, renvoyé sous la forme (degrees, valid). valid vaut False sur 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ève RbAmpNotSupportedError sur 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èvent RbAmpNotSupportedError (sur BASIC, la puissance réactive n'est pas exposée par cette bibliothèque).

  • read_std_totals(k) — bloc de totaux k ; k=0 est 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_restarted vaut True lorsque now.uptime_s < prev.uptime_s.
  • delta est un RbAmpStdEnergy contenant l'augmentation par champ, ou None lorsque le compteur generation a 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 ; net vaut 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.

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

Courant de démarrage et configuration

Python
dev.get_start_current()     -> int    # µA, 0 = off
dev.set_start_current(ua)   -> None
dev.save_config()           -> None   # persist writable STD config to flash (blocking)
dev.set_time(unix_epoch)    -> None   # set the module's clock
  • get_start_current() — 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 ; appelez save_config() pour la conserver après un redémarrage. Une valeur non prise en charge lève RbAmpParamError avant toute écriture sur le bus. La valeur doit être 0 (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ève RbAmpParamError. Réglez à nouveau l'heure après chaque redémarrage du module (read_std_health().time_valid vaut False tant que l'horloge n'est pas réglée).

  • get_start_current() / set_start_current() lèvent RbAmpNotSupportedError sur une image de module qui ne fournit pas le réglage du courant de démarrage ; RbAmpStdConfig.start_ua_supported indique 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.

Python
dev.std_arm_banks(mask)                 -> None            # bit i = bank i accumulates
dev.std_latch(bank)                     -> None            # snapshot + reset; does not wait
dev.std_read_latch(bank)                -> RbAmpStdLatch
RbAmp.std_latch_wh(snap, dt_ms, ch=0xFF) -> (wh_import, wh_export)
  • std_arm_banks(mask) — 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ès std_latch(). Une banque jamais verrouillée lève RbAmpStaleError. 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ève RbAmpStaleError : 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 sur dt_ms de l'horloge du maître. ch est un indice de canal, ou 0xFF (défaut) pour le total du module. Renvoie (wh_import, wh_export) ; l'export est nul ou négatif. Lève RbAmpStaleError pour un instantané sans échantillons.

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

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

Lit le bit « instantané prêt ». Renvoie True si le dernier instantané est frais.

dev.read_period_avg_power(ch=0) -> float

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

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

Durée de la période du point de vue de l'appareil, en ms.

Valeur de diagnostic.

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

Le point d'entrée recommandé pour la comptabilité par période. La séquence complète sous le capot :

  1. 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é).

  2. Sinon — écrivez CMD_LATCH_PERIOD.

  3. Capturez time.monotonic() pour calculer master_dt_ms.
  4. time.sleep(settle_ms / 1000) — 50 ms par défaut.
  5. 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).

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

  7. Mettez à jour l'horodatage et appelez energy.tick(snap) pour intégrer les Wh (sauf si l'accumulateur est désactivé via energy.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).

Python
async for snap in dev.stream_period(interval_s=60.0):
    # snap is an RbAmpPeriodSnapshot, .valid guaranteed True (by default skip_stale=True)
    print(snap.avg_p[0])
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
Sécurité

⚠ 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 :

Python
import asyncio

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

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

Un accumulateur de Wh par canal. Accessible par une propriété — le paquet en est propriétaire :

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

L'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 :

Text
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

Règle la classe du capteur de courant et l'enregistre en flash. Bloquant, ~705 ms.

Python
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 — cls hors de 0..3
  • RbAmpModeError — le module est appairé en usine (classe courante WIRED_CT / BUILTIN_CT) et cls diffè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
Remarque

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 aussi RbAmpParamError) — code absent de l'ensemble d'acceptation de la classe pour le REG_SENSOR_CLASS courant (pour SCT_013, il s'agit de {1, 2, 3, 4, 5, 6, 7})
  • RbAmpModeError — si set_sensor_class() n'a pas été appelé, ou si le module est appairé en usine (classe 2/3) et que le code diffère (utilisez set_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) :

Text
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

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.

Remarque

✅ 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.

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

Raises:

  • RbAmpParamError — channel hors de 0..dev.channels-1 ou code absent de l'ensemble accepté pour la classe (pour SCT_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 :

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

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 et dev.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é.
Python
dev.set_rating_correction(enabled: bool)  -> None   # default enabled
dev.rating_correction_enabled             -> bool
dev.ct_rating_scale(ch=0)                 -> float  # scale currently applied (1.0 = none)
dev.ct_rating_status(ch=0)                -> (action, detail) | None
dev.refresh_rating_correction()           -> None
  • set_rating_correction(enabled) — 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.0 lorsqu'aucune correction n'est active.

  • ct_rating_status(ch) — (action, detail) de la dernière évaluation d'un canal, ou None si le canal n'a jamais été évalué (par exemple, pas un canal SCT). action vaut l'une de : "unity", "ok", "needs_reset", "warn_uncal", "warn_gain" ; detail est un texte. Les actions warn_* 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.

Remarque

⛔ 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

É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_addr hors de 0x08..0x77 ou égal à l'adresse actuelle

  • RbAmpIOError — échec de communication

dev.commit_address_change() -> None

É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.

Sécurité

⚠ 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 :

Sécurité

⚠ 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.

Sécurité

⚠ 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

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

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

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.

Remarque

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

É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.

Relecture ≠ persistance

: 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 :

Python
from rbamp import RbAmp, RbAmpParamError

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

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 exemple 0xFE = 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 de EVENT_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.

Sécurité

⚠ 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 :

Python
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

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

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

É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_013 pour les pinces SCT-013 ; WIRED_CT/BUILTIN_CT ré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 :

  1. set_sensor_class(cls) une fois.
  2. Pour chaque voie : préparer REG_CT_MODEL = models[k] + CMD_SET_CT_MODEL_CHk.

  3. Une seule CMD_SAVE_USER_CONFIG terminale à 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 — cls ou models[k] invalide (validation côté client par classe ; REG_ERROR sur l'appareil reste à 0x00).

  • RbAmpIOError — erreur de bus.

  • RbAmpTimeoutError — délai d'écriture en flash dépassé.
Remarque

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

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

Python
RbAmpFleet(bus, max_modules: int = 16)

Après del fleet, tous les handles adoptés sont libérés.

Découverte — scan()

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

Sonde le bus sur la plage 0x08..0x77. Pour chaque adresse qui acquitte :

  1. Contrôle l'identité (PRODUCT_ID, HW_VARIANT, CAPABILITY). Si match_product = True, il exige une correspondance avec le PRODUCT_ID rbAmp.

  2. 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

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

Scrutation — poll_all()

Python
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 RbAmpSnapshot ou None (en cas d'échec)
  • un POD RbAmpFleetPoll avec les champs addr, ok, channels

Tolérant aux MISS : un module silencieux n'annule pas la scrutation des autres.

Agrégation

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

total_power 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

Python
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

Protocole natif

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

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

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.

  1. enable_gc_all(group) définit le drapeau GC_ENABLE de FLEET_CONFIG + GROUP_ID sur tous les modules de la flotte, émet CMD_SAVE_USER_CONFIG sur 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.

  2. gc_latch(group, tick, settle_ms) envoie la trame GC A5 27 group tick_lo tick_hi à l'adresse 0x00. Si tick=None, le tick est incrémenté automatiquement par un compteur interne. Renvoie le tick de diffusion.

  3. check_sync(expected_tick) relit GC_TICK (0x59) sur chaque module. Renvoie une liste de POD RbAmpFleetSync avec les champs :

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

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

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.

Précondition

: 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 :

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

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

dev.sanity_reject_count: int

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 (une RbAmpIOError a é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 :

Python
from rbamp._io_micropython import MachineI2CBackend
from rbamp import RbAmp

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

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

SMBusBackend (CPython) 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

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

REGISTERS et COMMANDS sont des dictionnaires de protocole générés automatiquement :

Python
from rbamp import REGISTERS, COMMANDS

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

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 + N bytes 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 bytes n'écrit que le premier octet.

Un registre multi-octets s'écrit octet par octet :

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

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

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 :

Text
addr=0x00 | A5 27   
  • A5 — magique ; 27 — le code opération CMD_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) :

  1. NACK de l'adresse GC : si GC est désactivé sur toute la flotte, bus.write_i2c_block_data(0x00, ...) lève OSError (ou l'équivalent du backend). C'est une erreur franche, pas un abandon silencieux.
  2. 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.
Python
# Canonical durable monitoring
event_flags = dev.read_reg(0x2A)
if event_flags & (1 << 3):
    last_err = dev.read_reg(0x02)
    # handle it
    dev.write_reg(0x2A, (1 << 3))   # W1C clear

Références


Source et signalements : rb-amp/rbamp-python · cette page dans le dépôt : docs/09_api_reference.md (v1.6.1)