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

05 · Démarrage rapide

Un tutoriel de cinq minutes : installer le paquet, câbler le module, sélectionner un capteur, et lire votre première valeur RT et votre premier instantané de période (Wh). Ce tutoriel couvre les deux environnements en parallèle — MicroPython (sur ESP32 / RP2040 / STM32 / Pyboard) et CPython (sur Raspberry Pi / Orange Pi / Rock Pi / x86 + USB-I²C).

Pour les détails (brochage pour un hôte précis, bus multi-modules, choix d'un SCT-013 selon la plage), voir les chapitres voisins :

Ce dont vous avez besoin

Sécurité

⚠ Sécurité secteur. La tension du secteur peut tuer. Coupez et verrouillez le circuit avant de raccorder les bornes L/N ou de poser la pince ; confiez le câblage secteur et tout travail dans un tableau à une personne qualifiée. Serrez un seul conducteur (L) — jamais le câble entier (serrer L et N donne environ 0). La pince elle-même est sans contact.

  • Un module rbAmp (n'importe quelle gamme, UI1 par simplicité)
  • Un de ces hôtes :
  • CPython : Raspberry Pi (tous modèles) / Orange Pi 5 / Rock Pi 5 / x86 + dongle USB-I²C

  • MicroPython : ESP32 (DevKitC / S2 / S3 / C3) / RP2040 (Pico / Pico W) / STM32 (Pyboard / Nucleo)

  • Une pince CT SCT-013 de calibre correspondant à votre courant maximal (5 A / 10 A / 30 A / 50 A / 100 A)

  • Une alimentation 5 V pour le module (depuis le USB-5V de l'hôte ou une source externe)
  • Un circuit en courant alternatif à mesurer (une lampe, une bouilloire ou un appareil domestique)

Quelle voie suivre ?

Vérifiez dev.is_std (ou l'étiquette SKU sur le module — voir 02 · Gammes de modules). Module STD : sautez les étapes 4 et 5 et allez à 06 · Exemples, scénario 11. Module BASIC : suivez toutes les étapes. Les étapes 3 et 4 sont identiques pour les deux.

Le chemin vers une première lecture : branchez le module, réglez le modèle de pince, puis lisez la tension, le courant et la puissance.

Étape 1 — Installer le paquet

CPython (sur SBC Linux ou x86)

Shell
pip install rbamp

(Sur un système Debian/Ubuntu, vous pouvez utiliser l'alternative système smbus2 sudo apt install python3-smbus, mais le smbus2 de pip est recommandé — il prend en charge le gestionnaire de contexte with SMBus(...).)

Verify:

Shell
rbamp --version          # rbamp 1.6.0
rbamp --bus 1 scan       # I²C scan, should show 0x50

MicroPython (sur ESP32 et autres)

Shell
mpremote mip install github:rb-amp/rbamp-python

Ou copiez le paquet manuellement :

Shell
mpremote cp -r path/to/rbamp/ :rbamp/

Le paquet s'installe dans /lib/rbamp/ sur l'appareil.

Étape 2 — Câblage

Quatre fils plus DRDY facultatif :

Broche rbAmp Hôte
VCC +5 V (plage 4.5..5.5 V)
GND GND
SDA SDA I²C (RPi broche 3, ESP32 GPIO21, RP2040 GPIO0/etc.)
SCL SCL I²C (RPi broche 5, ESP32 GPIO22, RP2040 GPIO1/etc.)

L'alimentation doit être de 5 V. Les lignes I²C fonctionnent en logique 3.3 V mais tolèrent le 5 V. La carte du module intègre déjà des résistances de pull-up de 4.7 kΩ — pour un seul module, aucune externe n'est nécessaire.

Le tableau complet du brochage de chaque hôte se trouve dans 04 · Câblage.

La pince SCT-013 se fixe autour du seul conducteur de phase (L), la flèche sur le corps de la pince pointant dans le sens du courant vers la charge. Voir plus dans 04 · Câblage.

Branchez la pince sur le fil L avec sa flèche orientée vers la charge, et les bornes de référence secteur.

Sécurité

⚠ Sécurité secteur. La tension du secteur peut tuer. Coupez et verrouillez le circuit avant de raccorder les bornes L/N ou de poser la pince ; confiez le câblage secteur et tout travail dans un tableau à une personne qualifiée. Serrez un seul conducteur (L) — jamais le câble entier (serrer L et N donne environ 0). La pince elle-même est sans contact.

Étape 3 — Premier script (lecture RT)

Un script minimal : indiquez au module quelle pince vous utilisez (une fois), puis lisez U / I / P / PF. Les codes de modèle sont listés à l'étape 4 ; 3 ci-dessous correspond à la SCT-013-030. Le tableau gamme de modules / variante se trouve dans 02 · Gammes de modules.

Version CPython

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass

with SMBus(1) as bus:
    with RbAmp(bus, 0x50) as dev:
        # the context manager's __enter__ automatically calls dev.begin()
        # the module variant is detected automatically
        variant = dev.read_variant()
        label = dev.read_label() or "(unset)"
        print(f"Module ready: variant={variant}  label={label!r}")
        # variant codes: see the table in 02 · Module lines
        # Once per installation (saved in the module's flash):
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)   # SCT-013-030, see Step 4
        while True:
            try:
                print(f"U={dev.voltage:.1f}V  "
                      f"I={dev.read_current(0):.3f}A  "
                      f"P={dev.read_power(0):.1f}W  "
                      f"PF={dev.read_power_factor(0):.3f}")
            except RbAmpError as e:
                print("read failed:", e)
            time.sleep(1)

Run:

Shell
python quick_read.py

Version MicroPython

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)   # ESP32 default
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)   # once per installation
    dev.set_ct_model(3)                              # SCT-013-030, see Step 4
    print("Module ready.")
    while True:
        try:
            print("U={:.1f}V  I={:.3f}A  P={:.1f}W  PF={:.3f}".format(
                dev.voltage, dev.read_current(0),
                dev.read_power(0), dev.read_power_factor(0)))
        except RbAmpError as e:
            print("read failed:", e)
        time.sleep(1)

(Sous MicroPython, .format() est utilisé à la place des f-strings — pour la performance et la compatibilité avec les anciens ports ; sur les ports récents, les f-strings fonctionnent aussi.)

Run:

Shell
mpremote run quick_read.py

Sortie attendue avec une charge allumée (les valeurs dépendent de votre charge) :

Text
Module ready.
U=230.4V  I=0.523A  P=119.8W  PF=0.987
Sécurité

U affiche à peu près la tension du secteur (220-240 V pour les réseaux 230 V). Sans charge, I vaut ~0 et PF est indéfini (il peut afficher nan, 0, ou un marqueur) — la forme exacte n'a pas d'importance tant que le courant est nul. Si I reste à 0.000 A avec la charge en marche, vérifiez la pince (un seul conducteur, bon sens) et le code de modèle, puis consultez 10 · Dépannage.

Étape 4 — Configuration du capteur de courant

Vous devez indiquer au module la classe et le modèle du capteur (fait dans le script de l'étape 3). Sans cela, les coefficients de calibration ne sont pas chargés et les lectures de courant restent à zéro. Appelez toujours set_sensor_class() en premier, puis set_ct_model(code).

Choisissez le code qui correspond à votre pince :

code Modèle Plage Usage typique
1 SCT-013-005 0..5 A Petites charges, une seule prise
2 SCT-013-010 0..10 A Réfrigérateur, lave-linge
3 SCT-013-030 0..30 A Alimentation domestique jusqu'à ~7 kW
4 SCT-013-050 0..50 A Borne de recharge VE, chauffage électrique
6 SCT-013-020 0..20 A Alimentation moyenne, appareils de 3–4 kW

Pour aller plus loin sur le choix — 03 · Sélection du capteur de courant.

Remarque

Ces deux appels sont faits une seule fois à la première installation — le choix est enregistré en flash du module et survit à une réinitialisation. Le temps total est d'environ 1.4 seconde (deux écritures flash × ~700 ms chacune).

Aux exécutions suivantes du script, vous n'avez pas besoin d'appeler set_sensor_class() ni set_ct_model() (le module s'en souvient). Les rappeler avec la valeur déjà détenue par le module est un no-op.

Étape 5 — Comptabilisation de l'énergie (Wh)

Le module ne renvoie que des grandeurs instantanées plus la puissance moyenne sur une période. Les Wh eux-mêmes sont calculés par le paquet, à partir de l'horloge maître (time.monotonic() sous CPython, time.ticks_ms() sous MicroPython) :

Text
E_Wh += avg_P × master_dt_s / 3600
        [W]    [seconds]      →  [Wh]

où master_dt_s est le nombre de secondes entre deux appels réussis à dev.read_period_snapshot().

Remarque

Attendez une période complète avant le premier read_period_snapshot(). begin() démarre déjà une période, donc un instantané pris juste après ne couvre qu'une fraction de seconde et les Wh affichent ~0. Les boucles ci-dessous attendent donc 60 s au départ pour cette raison.

Le compteur de Wh est conservé en mémoire. Il repart de 0 après un redémarrage du script ou du module. Pour un total absolu, enregistrez vous-même dev.energy.wh(0). Sur les modules BASIC, l'export n'est pas comptabilisé (voir 02 · Gammes de modules). Sur un module STD, les mêmes appels fonctionnent et la valeur est l'énergie nette (l'export se soustrait) ; begin() choisit la source — les compteurs d'énergie du module, ou le latch bank 0 — et la première période démarre à begin(). Les totaux à vie propres au module se trouvent dans read_std_energy() (scénario 11 dans 06 · Exemples).

Un gabarit minimal de comptabilité périodique (une fois par minute) :

Version CPython (compteur de période)

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)   # SCT-013-030

    while True:
        time.sleep(60)   # 60-second period

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print(f"avg P over period: {snap.avg_p[0]:.2f} W   "
              f"accumulated: {dev.energy.wh(0):.4f} Wh   "
              f"dt={snap.master_dt_ms} ms")

MicroPython, version (compteur de période)

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    dev.set_sensor_class(RbAmpSensorClass.SCT_013)
    dev.set_ct_model(3)

    while True:
        time.sleep_ms(60_000)

        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            print("snapshot stale — skip")
            continue
        except RbAmpError as e:
            print("snapshot failed:", e)
            continue

        print("avg P over period: {:.2f} W   accumulated: {:.4f} Wh   dt={} ms".format(
            snap.avg_p[0], dev.energy.wh(0), snap.master_dt_ms))
Remarque

Après l'étape 4, les appels set_sensor_class() et set_ct_model() ont déjà été exécutés une fois et enregistrés en flash du module ; dans le modèle ci-dessus, ils sont là pour les relances du script — le module ignore un appel répété avec la même valeur.

Ce que fait read_period_snapshot() en coulisses :

  1. Envoie au module la commande d'instantané de période (CMD_LATCH_PERIOD).
  2. Attend 50 ms pendant que le module prépare l'instantané.
  3. Vérifie le drapeau « prêt » (snap.valid) ; lit la puissance moyenne / crête.

  4. Met à jour le compteur interne de Wh : dev.energy.wh(ch) += avg_p[ch] × dt / 3600.

  5. Sur un instantané obsolète, il lève RbAmpStaleError et conserve l'horodatage précédent, de sorte que l'instantané valide suivant couvre tout l'intervalle et que les Wh restent exacts.

dev.begin() démarre lui-même la première période (une amorce) et écarte ce que le module a accumulé depuis la mise sous tension, afin que le code utilisateur ne voie jamais ces données.

Sortie attendue :

Text
avg P over period: 120.18 W   accumulated: 2.0036 Wh   dt=60012 ms
avg P over period: 120.21 W   accumulated: 4.0073 Wh   dt=60005 ms
...

Variante de streaming asynchrone (facultative)

Pour les applications utilisant asyncio (CPython) ou uasyncio (MicroPython), il existe un générateur asynchrone dev.stream_period(interval_s=...) :

Python
import asyncio
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass

async def main():
    with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
        dev.set_sensor_class(RbAmpSensorClass.SCT_013)
        dev.set_ct_model(3)

        # Once a minute, with built-in stale handling (skip_stale=True)
        async for snap in dev.stream_period(interval_s=60.0):
            print(f"{snap.avg_p[0]:.2f} W,  {dev.energy.wh(0):.4f} Wh")

asyncio.run(main())

Cela fonctionne de la même façon sous MicroPython (import uasyncio as asyncio).

Pour en savoir plus sur les scénarios asynchrones — 06 · Exemples, le scénario « Diffusion de période asynchrone ».

Étape 6 — Démarrage rapide pour une flotte de N modules

Ce démarrage rapide montre la prise en main d'un seul module. Le scénario canonique réel du paquet concerne plusieurs modules sur un même bus via RbAmpFleet (secteur + N charges secondaires). Pour l'exemple complet, voir le chapitre 06 · Exemples, scénario 1 « Secteur + N charges secondaires — le canon 80 % ». Un squelette minimal de flotte (CPython) :

Python
import time
from smbus2 import SMBus
from rbamp import RbAmpFleet

with SMBus(1) as bus:
    fleet = RbAmpFleet(bus)
    added = fleet.scan()
    print(f"fleet: {added} modules; excluded: {fleet.excluded}")

    while True:
        snaps = fleet.poll_all()
        total_w = fleet.total_power()
        n_ok = sum(1 for snap, info in snaps if info.ok)
        print(f"fleet: {n_ok}/{len(fleet)} OK, total P = {total_w:.1f} W")
        time.sleep(0.2)

La version MicroPython est identique — remplacez SMBus(1) par I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000).

Dans le scénario canonique 80 %, l'un des modules est un UI1 sur l'arrivée secteur (il fournit total_power() et total_energy_wh()), et les autres, I2/I3, sont des sous-compteurs de courant. Les détails et les scénarios avancés (désagrégation arrivée + sous-charges, synchronisation GC pour des instantanés étroitement synchronisés, flux de provisionnement) sont au chapitre 06.

Suite

  • 01 · Vue d'ensemble — ce qu'est rbAmp et ce que fait le paquet
  • 02 · Gammes de modules — quelle gamme de modules pour quelle tâche
  • 06 · Exemples — scénarios de travail : secteur + N sous-charges (le canon 80 %), flux de provisionnement, multi-voies à CT mixtes, synchronisation GC de flotte, MQTT, veille profonde, streaming asynchrone

  • 07 · Intégrations DIY — Home Assistant / Node-RED / OpenHAB

  • 08 · Intégrations cloud — AWS IoT / Azure / GCP / InfluxDB

  • 09 · Référence API — l'API publique complète (y compris RbAmpFleet + multi-voies + modèle d'erreur v1.3 + identité et provisionnement)

  • 10 · Dépannage — si quelque chose ne fonctionne pas (blocage i2c MicroPython@ESP32 en trois couches, latch_ms est une minuterie de diagnostic, RbAmpStaleError ancrage maître maintenu)


Sources et problèmes : rb-amp/rbamp-python · cette page dans le dépôt : docs/05_quickstart.md (v1.6.1)