01 · Vue d'ensemble
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
RbAmpStaleErroret 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
- 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(ouI2/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 bilanmains − Σ(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.
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 |
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.
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)
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
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
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
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
validavant la lecture ; sur un instantané périmé, il lèveRbAmpStaleError. -
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 —
float64 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
┌─────────────────────────────────────────────────────┐
│ 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.
Le schéma Python standard :
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()
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()
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
- 02 · Gammes de modules — quelle gamme de modules pour quelle tâche
-
04 · Câblage — pull-ups, longueur du bus, câblage par hôte (RPi / ESP32 / RP2040 / STM32)
-
05 · Démarrage rapide — le premier script fonctionnel pour les deux environnements
-
06 · Exemples — parcours de scénarios prêts à l'emploi
-
09 · Référence API — chaque classe, méthode, propriété et exception publique
-
10 · Dépannage — quand quelque chose ne fonctionne pas
Source et signalements : rb-amp/rbamp-python · cette page dans le dépôt : docs/01_overview.md (v1.6.1)