rbAmp
FR
Boutique
Docs
Mis à jour · Modifier sur GitHub [Edit on GitHub]

01 · Vue d'ensemble

Chaîne de signal rbAmp : capteur → module → I²C → maître → cloud / Home Assistant

Qu'est-ce que rbAmp

rbAmp est un module matériel compact pour la mesure de précision des paramètres du secteur alternatif via l'interface I²C. Il est construit autour d'un microcontrôleur doté d'un front-end analogique isolé intégré et d'une calibration d'usine stockée en flash.

Du point de vue de l'intégrateur, le module se comporte comme un esclave I²C standard : vous créez RbAmp(bus, 0x50), appelez dev.begin() et obtenez des valeurs prêtes à l'emploi via les propriétés et méthodes. Le même code fonctionne sous MicroPython (avec machine.I2C) et sous CPython (avec smbus2) — le backend est sélectionné automatiquement selon le type de l'objet bus.

Termes utilisés dans cette documentation

  • Gamme de modules — BASIC ou STANDARD (STD) : la gamme de produits du module (voir 02).
  • Variante — UI1, UI2, UI3, I1, I2, I3 (et UI5/UI7) : nombre de canaux de courant, et présence ou non d'une entrée de tension sur le module.
  • Version du firmware / version de l'image du module — le logiciel à l'intérieur du module ; certains appels STD exigent une image assez récente.
  • Lecture RT — une lecture instantanée (tension, courant, puissance), rafraîchie par le module toutes les 100 ms.
  • Période / instantané — un instantané fige les totaux de la période écoulée et démarre la suivante ; un instantané de période est le résultat figé (puissance moyenne par canal).
  • Instantané périmé — le module n'avait pas d'instantané frais prêt ; la bibliothèque lève RbAmpStaleError et le prochain bon instantané couvre tout l'intervalle.
  • Amorce — le premier instantané pris par begin() ; il écarte ce qui s'est accumulé depuis la mise sous tension.
  • GC (General Call) — une trame I²C de diffusion unique qui fait prendre leur instantané à plusieurs modules au même instant.
  • DRDY — broche facultative qui impulse environ toutes les 100 ms lorsque de nouvelles données temps réel sont prêtes.

Un module ou plusieurs

Un module ou plusieurs : commencez avec un RbAmp ; utilisez RbAmpFleet pour plusieurs. Le paquet rbamp fonctionne avec un module seul et aussi avec un groupe de modules sur un même bus I²C. Le scénario multi-modules canonique est un module maître à l'arrivée secteur plus N modules sur des charges individuelles, tous sur un seul bus, pilotés par un seul ESP32 / RPi / SBC. La bibliothèque fournit la classe RbAmpFleet — un seul objet par lequel vous scannez le bus, interrogez tous les modules en un appel, obtenez la puissance totale et le bilan « arrivée − Σ(consommateurs) », détectez les erreurs de chaque module et, au besoin, synchronisez les instantanés de période par une commande de diffusion.

Les modules multi-canaux sont également pris en charge — les I2 / I3 à courant seul (deux ou trois TC) et les UI2 / UI3 / UI5 / UI7 équipés de tension (2 / 3 / 5 / 7 canaux de courant, avec puissance, FP et Wh par canal). Chaque canal a son propre modèle de capteur. C'est typique d'un sous-tableau, où un seul point d'installation surveille plusieurs départs.

Travailler avec un seul module est le cas minimal de la même bibliothèque : la classe RbAmp est le bloc de base sur lequel RbAmpFleet est construit. Si vous n'avez qu'un module sur le bus, utilisez directement ce même descripteur — l'API de flotte n'est pas nécessaire.

Le scénario des 80 % — arrivée principale + N sous-charges

Un module sur l'arrivée secteur et un module par sous-charge partagent un bus I²C avec le maître, qui les interroge tous avec un seul appel de flotte.

  • 1 module sur l'arrivée (secteur) — consommation totale et qualité du réseau.
  • N modules sur des charges individuelles — comptage par canal.
  • Les modules multi-canaux conviennent aussi à ce cas : un seul UI2 / UI3 / UI5 / UI7 (ou I2 / I3) peut mesurer plusieurs charges, chacune sur son propre canal — N modules ne signifient pas obligatoirement N charges.
  • Un seul appel fleet.poll_all() interroge tout ; le bilan mains − Σ(sub_loads) montre « le reste » (consommation de fond, charges non mesurées, fuites).

  • Une seule horloge maître partagée → comptage des Wh juste, sans dérive inter-modules.

Sécurité

Point d'architecture important. Les variantes I (I1/I2/I3) ne mesurent que le courant — elles n'ont ni tension, ni puissance active, ni PF. L'énergie active (Wh) et la puissance ne sont calculées que sur les variantes UI (qui disposent d'un étage d'entrée en tension). Dans le déploiement canonique, le rôle de « compteur secteur » (mesure de l'énergie) est tenu par une seule UI1 à l'arrivée secteur ; le rôle de sous-compteur (détail de courant par charge) est tenu par des modules I2/I3 (ou par UI2 / UI3 / UI5 / UI7 lorsque la puissance et les Wh sont nécessaires par charge).

Pour les détails, voir le chapitre 06 · Exemples, scénario 1 (« Arrivée + N sous-charges — le canon 80 % »). Pour l'API, voir le chapitre 09 · Référence API, section « Gestionnaire de flotte ».

Ce que mesure rbAmp

Grandeur Type Python Plage
Tension efficace RMS U_rms float, V 0…300 V
Tension de crête U_peak float, V 0…450 V
Courant efficace RMS I_rms float, A dépend du capteur choisi — voir 03_sensor_selection.md
Courant crête I_peak float, A dépend du capteur sélectionné
Puissance active P (signée en RT) float, W dépend du capteur sélectionné
Facteur de puissance PF float −1…+1
Fréquence du secteur int, Hz 50 / 60 Hz (détecté)
P moyenne sur la période float, W identique à P
Remarque

La valeur RT de la puissance active P est toujours signée sur toute gamme de module (négatif signifie export vers le réseau). Le comportement de la valeur moyennée sur la période (snap.avg_p[ch] dans RbAmpPeriodSnapshot) dépend de la gamme de module — voir la section « Gammes de modules » ci-dessous et 02_tiers.md.

Câblage

Le module se connecte à l'hôte par quatre fils côté basse tension ; tout ce qui touche le secteur reste à l'intérieur du boîtier.

Wire Objet
VCC +5 V (4.5..5.5 V), courant ~15 mA, crête ~25 mA
GND commun avec l'hôte (obligatoire)
SDA, SCL I²C, logique 3.3 V, tolérant au 5 V. Tirages intégrés 4.7 kΩ
DRDY facultatif, drain ouvert à l'état BAS ~10 µs toutes les ~100 ms

L'adresse par défaut est 0x50 (7 bits, plage de changement 0x08..0x77). La vitesse recommandée pour MicroPython sur ESP32 est 50 kHz ; pour CPython via l'I²C du noyau, c'est généralement 100 kHz (le motif de NACK n'apparaît pas via l'API du noyau Linux).

Les règles complètes (longueur du bus, recommandations de pull-up sur un bus multi-modules, schémas de câblage pour RPi / ESP32 / RP2040 / STM32) se trouvent au chapitre 04 · Câblage.

Gammes de modules (aide-mémoire)

Les modules BASIC et STANDARD (STD) sont livrés ; STANDARD est pris en charge par cette bibliothèque à partir de la 1.6.0.

BASIC est un comptage à sens unique (consommation seule), suivant la logique d'un compteur mécanique classique :

Gamme de modules Puissance RT dev.power[ch] Accumulateur de période snap.avg_p[ch] Compteur de Wh du paquet
BASIC signée (négative = injection vers le réseau, visible en temps réel) chaque fenêtre de 100 ms de la puissance moyenne P est ramenée à max(P, 0) avant d'être ajoutée à l'accumulateur de période monotone — mesure de la seule consommation
STANDARD (STD) signé mêmes appels que BASIC ; la source est les compteurs d'énergie du module ou le latch bank 0, choisi à begin() ; l'énergie est nette (l'export se soustrait) dev.energy intègre la période ; les totaux propres au module : read_std_energy() (voir le chapitre 02)

Pour plus de détails, voir le chapitre 02 · Gammes de modules. Au niveau du paquet, la même classe RbAmp est utilisée quelle que soit la gamme de module ; les différences apparaissent dans les valeurs renvoyées par le module.

Remarque

Mesure bidirectionnelle sur BASIC : dev.energy.wh(ch) sur la gamme BASIC ne donne que la consommation. Si vous devez comptabiliser l'export à part, échantillonnez la puissance temps réel dev.power[0] (ou dev.read_power(0)) à environ 10 Hz et séparez vous-même les échantillons positifs et négatifs dans deux variables d'accumulation. Pour un exemple, voir 06_examples.md, scénario « Mesure bidirectionnelle côté maître ».

Ce que fait ce paquet

Le rôle principal est de masquer l'échange de protocole et d'épargner au code utilisateur la routine du travail sur les registres, l'ordre des octets et les temps de stabilisation après les commandes. En outre, le paquet calcule l'énergie (Wh) — le module ne renvoie que la puissance moyenne sur la période, et le maître fait l'intégration à l'aide de time.monotonic() / time.ticks_us().

Sans le paquet (accès direct aux registres via smbus2)

Python
import struct
from smbus2 import SMBus, i2c_msg

# Read U_RMS — burst-read 4 bytes (auto-increment is supported on reads).
with SMBus(1) as bus:
    buf = bytes(bus.read_i2c_block_data(0x50, 0x86, 4))
u_rms = struct.unpack("

Avec le paquet

Python
from smbus2 import SMBus
from rbamp import RbAmp

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.begin()
    u_rms = dev.voltage          # property (one call = one transaction)
    # or: u_rms = dev.read_voltage()

Lire une période — sans le paquet

Python
import time, struct

with SMBus(1) as bus:
    # Snapshot + 50 ms settle + ready-flag check + assemble 4 bytes of avg_p
    bus.write_byte_data(0x50, 0x01, 0x27)   # REG_COMMAND, CMD_LATCH_PERIOD
    t_latch = time.monotonic()
    time.sleep(0.050)                        # settle

    bus.write_byte(0x50, 0x07)
    if bus.read_byte(0x50) & 0x01 == 0:
        # snapshot is stale — keep the previous t_prev_latch, so the next
        # good snapshot covers the full interval
        raise SystemExit("stale snapshot")

    # ...read 4 bytes of avg_p, struct.unpack, integrate Wh:
    #   dt_s = time.monotonic() - t_prev_latch
    #   E_Wh += avg_p * dt_s / 3600

Lire une période — avec le paquet

Python
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.begin()
    snap = dev.read_period_snapshot()        # snapshot + settle + valid + read + Wh tick
    print(snap.avg_p[0], "W")
    print(dev.energy.wh(0), "Wh")

En interne, le paquet garantit :

  • Une stabilisation de 50 ms après CMD_LATCH_PERIOD, et une lecture correcte de l'instantané.
  • Un contrôle de l'indicateur valid avant la lecture ; sur un instantané périmé, il lève RbAmpStaleError.

  • Conserver l'horodatage précédent sur un instantané obsolète, afin que le bon instantané suivant couvre tout l'intervalle et que les Wh restent exacts.

  • Accumulation des Wh par canal en double précision (CPython — float 64 bits ; MicroPython — dépend du build, voir 04 · Câblage).

  • Chargement automatique des coefficients de calibration lorsque le capteur de courant est choisi via dev.set_sensor_class(cls) + dev.set_ct_model(code) — l'utilisateur n'a pas besoin de connaître les registres de calibration internes.

Quand utiliser le paquet, quand utiliser l'accès direct au bus

Tâche Paquet Accès direct via smbus2 / machine.I2C
Lecture de U / I / P / FP / fréquence ✅ seulement pour le débogage à l'analyseur logique
Comptage d'énergie par période ✅ seulement si les Wh sont stockés hors du paquet (par ex. dans une base de données côté maître)
Plusieurs modules sur un bus ✅ (via instantané séquentiel + stabilisation partagée) —
Comptage bidirectionnel sur BASIC ✅ (via les lectures RT — voir 06_examples.md) alternative — votre propre boucle de lecture temps réel
Diffusion asynchrone via asyncio / uasyncio ✅ (async for snap in dev.stream_period()) difficile — pas de wrapper asynchrone intégré
Portage vers une autre plateforme n/a ✅ — voir rbamp-docs (table des registres et protocole)

Pour toutes les tâches typiques des premières lignes, le paquet est la voie à suivre.

Architecture

Où se trouve un script Python : script, paquet rbamp, backend I²C et module rbAmp, avec la vitesse I²C de chaque hôte.

Text
┌─────────────────────────────────────────────────────┐
│  User code (.py)                                    │
│   from smbus2 import SMBus                          │
│   from rbamp import RbAmp, RbAmpSensorClass         │
│   with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:    │
│       # __enter__ calls dev.begin() itself;         │
│       # explicit begin() shown for transparency     │
│       dev.set_sensor_class(RbAmpSensorClass.SCT_013)│
│       dev.set_ct_model(3)                           │
│       snap = dev.read_period_snapshot()             │
│       dev.energy.wh(0)                              │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Public API of the RbAmp class (rbamp/__init__.py)  │
│   ┌─────────────────────────────────────────────┐   │
│   │ Lifecycle:      begin / probe / wait_ready  │   │
│   │ RT properties:  .voltage / .power[ch] /     │   │
│   │                 .current[ch] / .frequency   │   │
│   │ RT methods:     read_voltage / read_power / │   │
│   │                 read_all                    │   │
│   │ Period:         latch_period /              │   │
│   │                 read_period_snapshot        │   │
│   │ Async:          stream_period               │   │
│   │ Configuration:  set_sensor_class /          │   │
│   │                 set_ct_model                │   │
│   │ Diagnostics:    retry_exhaustion_count /    │   │
│   │                 sanity_reject_count         │   │
│   │ Exceptions:     RbAmpError → IOError /      │   │
│   │                 TimeoutError / StaleError / │   │
│   │                 ParamError / ModeError /    │   │
│   │                 VersionError                │   │
│   └─────────────────────────────────────────────┘   │
│                       │                             │
│                       ▼                             │
│   ┌─────────────────────────────────────────────┐   │
│   │ Backend selection (inside __init__):        │   │
│   │  bus.readfrom_mem  → MachineI2CBackend      │   │
│   │  bus.read_byte_data → SMBusBackend          │   │
│   │  duck-typed        → custom (FTDI / mocks)  │   │
│   └─────────────────────────────────────────────┘   │
│                       │                             │
│                       ▼                             │
│   ┌─────────────────────────────────────────────┐   │
│   │ Instance state:                             │   │
│   │  • RbAmpEnergy — Wh accumulator             │   │
│   │  • RbAmpSnapshot / RbAmpPeriodSnapshot      │   │
│   │  • Time of last snapshot (monotonic)           │   │
│   └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Backend — native I²C on the host platform:         │
│   smbus2 (CPython)  /  machine.I2C (MicroPython)    │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  rbAmp module at address 0x50                       │
│   • U / I / P / PF measurement pipeline (~100 ms)   │
│   • Period accumulator (atomic CMD_LATCH_PERIOD)    │
└─────────────────────────────────────────────────────┘

Hiérarchie des exceptions

Contrairement à la bibliothèque Arduino (où les erreurs sont signalées via lastError() + un code de retour) et au composant ESP-IDF (où elles le sont via esp_err_t), le paquet Python utilise le schéma Python classique — une hiérarchie d'exceptions.

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

Le schéma Python standard :

Python
from rbamp import RbAmp, RbAmpStaleError, RbAmpError

try:
    snap = dev.read_period_snapshot()
except RbAmpStaleError:
    # Snapshot is stale — the package keeps the previous timestamp, the next good snapshot covers the full interval
    continue
except RbAmpError as e:
    log.warning("rbAmp failure: %s", e)

Diagrammes d'interaction

Le déroulement de dev.begin()

Séquence des transactions de bus que begin() effectue : lecture de la version, détection de la gamme du module, envoi de l'instantané d'amorce, puis retour.

Text
code          RbAmp                Backend             rbAmp module
  │             │                    │                       │
  ├─dev.begin()►                     │                       │
  │             ├─read_u8(REG_VERSION)►                      │
  │             │                    ├──[0x50, 0x03]────────►│
  │             │                    │◄────────────────ACK───┤
  │             │                    ├──[read 1 byte]───────►│
  │             │                    │◄──────────────[0x04]──┤
  │             │◄─────── version_byte ─────┤                  │
  │             │                    │                       │
  │             ├─read_float_le(U_RMS)►(4 single-byte reads) │
  │             │  → 226.3 V         │                       │
  │             │  → has_voltage_hw = True                   │
  │             │                    │                       │
  │             ├─write_cmd(LATCH)──►│                       │
  │             │                    ├──[0x50, 0x01, 0x27]──►│
  │             │  sleep(50ms)       │                       │
  │             │                    │                       │
  │◄────self────┤  (or raises RbAmpIOError on failure)        │

Le premier instantané est une amorce (le module renvoie ce qu'il a accumulé depuis la mise sous tension, ce qui ne convient pas à la mesure tarifaire). Le paquet enregistre de lui-même que cet instantané doit être écarté — le code utilisateur ne le voit jamais.

Le déroulement de dev.read_period_snapshot()

Séquence de read_period_snapshot() : prendre l'instantané de période, lire le bloc d'instantané, intégrer l'énergie sur le maître pour BASIC ou lire les compteurs embarqués pour STD.

Text
code          RbAmp                Backend             rbAmp module
  │             │                    │                       │
  ├─read_period_snapshot()►          │                       │
  │             ├─write_cmd(LATCH)──►│  t_now = time.monotonic()
  │             │                    │                       │
  │             │  sleep(50ms)       │                       │
  │             │                    │                       │
  │             ├─is_period_valid()─►│                       │
  │             │  → True            │                       │
  │             │                    │                       │
  │             ├─read_float_le(AVG_P0)►(4 reads)            │
  │             ├─read_float_le(MAX_P0)►(4 reads)            │
  │             ├─read_u32_le(LATCH_MS)►(4 reads)            │
  │             │                    │                       │
  │             │  dt = t_now − last_latch                    │
  │             │  energy.wh[ch] += avg_p[ch] × dt / 3600    │
  │             │  last_latch = t_now                         │
  │             │                    │                       │
  │◄─snap──────┤                    │                       │

L'instantané atomique côté module garantit que chaque mesure d'une période tombe dans exactement un instantané — ni doublon, ni perte à la frontière de la période.

Correspondance avec l'API de registres directe

Un tableau pour ceux qui migrent depuis leur propre travail d'accès direct :

Accès direct à l'API (smbus2 / machine.I2C) Équivalent du paquet
Lecture manuelle de 4 octets + struct.unpack dev.voltage (propriété) ou dev.read_voltage()
read_byte par canal × 4 dev.power[ch] (_ChannelProxy) ou dev.read_power(ch)
write_byte_data(0x50, 0x01, 0x27); time.sleep(0.05) dev.latch_period(); time.sleep(0.05) (ou directement dev.read_period_snapshot())
Vérification de read_byte(0x07) & 1 dev.is_period_valid() ou le champ snap.valid
Formule manuelle E_Wh += avg_p × dt / 3600 dev.energy.wh(0) — mis à jour automatiquement
Configuration manuelle du capteur de courant via l'API de registres directe dev.set_sensor_class(cls) + dev.set_ct_model(code) — les préréglages d'usine sont chargés automatiquement

Suite


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