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

Exemples

Ce chapitre parcourt 11 scénarios (10 dans le tableau ci-dessous, plus le scénario 11) — d'un minimal « hello world » jusqu'à un déploiement de production. La plupart des scénarios ont des implémentations parallèles en MicroPython (dans examples_upy/) et en CPython (dans examples_cpython/). Le code ci-dessous est une distillation de la logique clé, pas un script complet ; les versions complètes se trouvent dans les fichiers d'exemple correspondants.

# Scénario MicroPython CPython
1 Lecture rapide 01_quick_read.py 01_quick_read.py
2 Compteur de période + affichage local 02_oled_period.py 02_period_meter.py
3 Surveillance de 3 modules sur un bus 03_multi_module.py 03_multi_module_broadcast.py
4 UI3 + MQTT par voie 04_mqtt.py 04_mqtt_publisher.py
5 Mesure bidirectionnelle côté maître 07_bidirectional_energy.py 05_bidirectional_energy.py
6 Bilan énergétique de toute la maison (multi-modules + MQTT) 08_home_energy_balance.py 07_home_energy_balance.py
7 Journalisation de la détection d'événements (EMA) 09_event_detection_logger.py pas de fichier
8 Enregistreur tournant local pas de fichier 08_rotating_file_logger.py
9 Enregistreur sur batterie en veille profonde 06_deep_sleep.py (sans objet)
10 Diffusion asynchrone via stream_period 05_async_streaming.py pas de fichier (code au scénario 10)
Remarque

Tous les scénarios supposent que la classe de capteur et le modèle de CT sont déjà configurés via dev.set_sensor_class() + dev.set_ct_model() (voir 05 · Démarrage rapide, étape 4). Cela se fait une fois, à l'installation — les réglages sont enregistrés en flash du module et survivent à une réinitialisation.


Scénario 1 — Lecture rapide

Objectif : afficher U / I / P / PF / fréquence une fois par seconde. C'est le même « hello world » que dans 05 · Démarrage rapide, mais avec dev.read_all() — une lecture ponctuelle de tout le bloc temps réel dans une seule structure RbAmpSnapshot.

Version CPython

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

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        try:
            s = dev.read_all()
        except RbAmpError as e:
            print("read fail:", e)
            time.sleep(1)
            continue

        line = f"U={s.voltage:.1f} V  f={s.frequency} Hz   "
        for ch in range(s.channels):
            line += f"I{ch}={s.current[ch]:.2f}A  P{ch}={s.power[ch]:.1f}W  "
        print(line)
        time.sleep(1)

Version MicroPython

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

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    while True:
        try:
            s = dev.read_all()
        except RbAmpError as e:
            print("read fail:", e)
            time.sleep(1)
            continue

        print("U={:.1f} V  f={} Hz".format(s.voltage, s.frequency))
        for ch in range(s.channels):
            print("  I{}={:.2f}A  P{}={:.1f}W".format(
                ch, s.current[ch], ch, s.power[ch]))
        time.sleep(1)

Ce qui se passe sur le bus : dev.read_all() sur un UI3 effectue environ 53 transactions d'octets (13 valeurs flottantes × 4 octets + 1 octet de fréquence). À 50 kHz avec la marge de nouvelles tentatives, cela représente de l'ordre de 25 à 30 ms. Si vous n'avez pas besoin de toutes les valeurs, utilisez les accesseurs par propriété (dev.voltage, dev.read_current(ch)).


Scénario 2 — Compteur de période + affichage local

Objectif : un compteur de Wh, mis à jour une fois par minute, sur un écran local. Sur MicroPython — un OLED SSD1306 sur le même bus I²C. Sur CPython — sortie texte sur stdout (vous pouvez brancher un LCD caractères via GPIO ou utiliser une page web — voir le scénario 6).

MicroPython, version (OLED SSD1306)

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

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
oled = SSD1306_I2C(128, 64, i2c)   # OLED on the same bus, addr 0x3C

with RbAmp(i2c, 0x50) as dev:
    snapshots_ok = 0
    snapshots_bad = 0

    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
            snapshots_ok += 1
        except RbAmpStaleError:
            snapshots_bad += 1
            continue

        oled.fill(0)
        oled.text("rbAmp Energy Meter", 0, 0)
        oled.text("{:.1f} W".format(snap.avg_p[0]), 0, 16, 1)
        oled.text("Wh: {:.4f}".format(dev.energy.wh(0)), 0, 32)
        oled.text("ok={} bad={}".format(snapshots_ok, snapshots_bad), 0, 48)
        oled.show()

Version CPython (compteur de période, sans écran)

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

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    snapshots_ok = 0
    snapshots_bad = 0

    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
            snapshots_ok += 1
        except RbAmpStaleError:
            snapshots_bad += 1
            print("stale snapshot — skipping")
            continue

        print(f"P = {snap.avg_p[0]:.2f} W   "
              f"Wh = {dev.energy.wh(0):.4f}   "
              f"ok={snapshots_ok} bad={snapshots_bad}   "
              f"dt={snap.master_dt_ms} ms")

Gestion des instantanés périmés. dev.read_period_snapshot() lève RbAmpStaleError si le module n'a pas réussi à préparer un nouvel instantané au moment de la lecture. Le paquet conserve l'horodatage précédent, si bien que le prochain instantané réussi couvre tout l'intervalle et que les Wh restent exacts. Un motif standard try/except Python.


Scénario 3 — surveillance de 3 modules sur un bus

Objectif : interroger 3 modules aux adresses 0x50 / 0x51 / 0x52, en les instantanant de façon cohérente pour que leurs puissances par voie s'additionnent sur la même période secteur.

Instantané cohérent

Une seule trame General-Call (A5 27 ) fait prendre leur instantané à chaque module qui s'est inscrit avec fleet.enable_gc_all() — décalage de la flotte < 10 µs, donc les totaux s'additionnent. fleet.gc_latch() envoie la trame et renvoie le tick de diffusion ; fleet.check_sync() relit le tick constaté par chaque module, afin de repérer celui qui a manqué la trame. (Sur le firmware v1.0/v1.1, General-Call n'était pas disponible et ce scénario revenait à des instantanés séquentiels par appareil.) Voir 09 · Référence API pour RbAmpFleet.

Version CPython

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

ADDRS = [0x50, 0x51, 0x52]
GC_GROUP = 0

with SMBus(1) as bus:
    fleet = RbAmpFleet(bus)
    for addr in ADDRS:
        try:
            dev = RbAmp(bus, addr); dev.begin()
        except RbAmpError as exc:
            print(f"skip 0x{addr:02X}: {exc}"); continue
        fleet.add(dev)

    # one-time: persist the General-Call snapshot opt-in on every module
    fleet.enable_gc_all(group=GC_GROUP)

    while True:
        time.sleep(60)

        tick = fleet.gc_latch(group=GC_GROUP)     # one all-call frame snapshots the bus
        time.sleep(0.050)                         # single shared settle
        sync = fleet.check_sync(expected_tick=tick)

        for dev, s in zip(fleet, sync):
            if not s.in_sync:                     # this module missed the frame
                print(f"  0x{s.addr:02X}  MISSED tick 0x{tick:04X}")
                continue
            try:
                snap = dev.read_period_snapshot(settle_ms=0, skip_latch=True)
            except RbAmpStaleError:
                continue
            print(f"  0x{dev.address:02X}  P={snap.avg_p[0]:.0f} W  "
                  f"Wh={dev.energy.wh(0):.3f}")
        print(f"  fleet ΣWh={fleet.total_energy_wh():.3f}  "
              f"in_sync={sum(s.in_sync for s in sync)}/{len(sync)}")

Version MicroPython

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

ADDRS = [0x50, 0x51, 0x52]
GC_GROUP = 0
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)

fleet = RbAmpFleet(i2c)
for addr in ADDRS:
    try:
        dev = RbAmp(i2c, addr); dev.begin()
    except RbAmpError as exc:
        print("skip 0x{:02X}:".format(addr), exc); continue
    fleet.add(dev)

fleet.enable_gc_all(group=GC_GROUP)           # one-time, persisted

while True:
    time.sleep(60)

    tick = fleet.gc_latch(group=GC_GROUP)     # one all-call frame
    time.sleep_ms(50)                         # single shared settle
    sync = fleet.check_sync(expected_tick=tick)

    for dev, s in zip(fleet, sync):
        if not s.in_sync:
            print("  0x{:02X}  MISSED tick".format(s.addr))
            continue
        try:
            snap = dev.read_period_snapshot(settle_ms=0, skip_latch=True)
        except RbAmpStaleError:
            continue
        print("  0x{:02X}  P={:.0f} W  Wh={:.3f}".format(
            dev.address, snap.avg_p[0], dev.energy.wh(0)))

Scénario 4 — UI3 + MQTT par voie

Objectif : un module UI3 avec 3 pinces CT sur trois lignes indépendantes. Compteurs de Wh par voie, publiés sur MQTT une fois par minute. Montre que dev.energy.wh(ch) fonctionne indépendamment sur chaque voie — inutile d'un tableau manuel total_wh[3] côté maître.

CPython (via paho-mqtt ; installer avec pip install paho-mqtt)

Python
import time, json
from smbus2 import SMBus
import paho.mqtt.client as mqtt_client
from rbamp import RbAmp, RbAmpStaleError, RbAmpSensorClass

CH_NAMES = ["main", "heatpump", "lights"]

mqtt = mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION2, "rbamp-ui3")
mqtt.connect("192.168.1.10", 1883, keepalive=60)
mqtt.loop_start()

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            continue

        for ch in range(dev.channels):
            payload = json.dumps({
                "power":  round(snap.avg_p[ch], 1),
                "energy": round(dev.energy.wh(ch), 4),
            })
            mqtt.publish(f"rbamp/{CH_NAMES[ch]}/state",
                         payload, qos=1, retain=True)

MicroPython (via umqtt.simple)

Python
import time, ujson
from machine import I2C, Pin
from umqtt.simple import MQTTClient
from rbamp import RbAmp, RbAmpStaleError, RbAmpSensorClass

CH_NAMES = [b"main", b"heatpump", b"lights"]

mqtt = MQTTClient(b"rbamp-ui3", b"192.168.1.10",
                  port=1883, keepalive=60)
mqtt.connect()

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            continue

        for ch in range(dev.channels):
            payload = ujson.dumps({
                "power":  round(snap.avg_p[ch], 1),
                "energy": round(dev.energy.wh(ch), 4),
            })
            topic = b"rbamp/" + CH_NAMES[ch] + b"/state"
            mqtt.publish(topic, payload.encode(), qos=1, retain=True)
Remarque

Sous MicroPython, umqtt.simple est un client synchrone et bloquant. Pour une variante asynchrone, utilisez mqtt_as (un client MQTT asyncio) — voir aussi le scénario 10.

Pour l'auto-découverte HA complète au-dessus de ce schéma, voir 07 · Intégrations DIY.


Scénario 5 — Mesure bidirectionnelle côté maître

Objectif : séparer la puissance instantanée signée en consommation brute et export brut. Utilisez ce schéma sur la gamme BASIC, où le firmware écrête les valeurs négatives dans snap.avg_p[ch] (puissance moyennée sur la période) — échantillonnez dev.read_power(0) (puissance instantanée, signée sur toutes les gammes) à 10 Hz côté maître et répartissez les valeurs vous-même.

Version CPython

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpIOError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    consume_wh = 0.0
    export_wh  = 0.0
    t_prev = time.monotonic()
    last_print = t_prev

    while True:
        time.sleep(0.1)   # 10 Hz, matches the RT cadence

        t_now = time.monotonic()
        dt_s  = t_now - t_prev
        t_prev = t_now

        try:
            p = dev.read_power(0)
        except RbAmpIOError:
            continue

        dwh = p * dt_s / 3600.0
        if p >= 0:
            consume_wh += dwh
        else:
            export_wh  += -dwh

        # Print once per second
        if t_now - last_print >= 1.0:
            last_print = t_now
            print(f"P={p:.1f} W   "
                  f"cons={consume_wh:.4f} Wh  exp={export_wh:.4f} Wh  "
                  f"net={consume_wh - export_wh:.4f} Wh")

Version MicroPython

Python
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpIOError

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
    consume_wh = 0.0
    export_wh  = 0.0
    t_prev = time.ticks_ms()

    while True:
        time.sleep_ms(100)

        t_now = time.ticks_ms()
        dt_s  = time.ticks_diff(t_now, t_prev) / 1000
        t_prev = t_now

        try:
            p = dev.read_power(0)
        except RbAmpIOError:
            continue

        dwh = p * dt_s / 3600.0
        if p >= 0:
            consume_wh += dwh
        else:
            export_wh  += -dwh

Sur un module STANDARD (STD), les appels de période fonctionnent sans changement et l'énergie est nette (l'export se soustrait) ; les compteurs d'import et d'export propres au module se trouvent dans read_std_energy() (scénario 11). Cette répartition côté maître n'est nécessaire que sur les modules BASIC, pour un rapport séparé de consommation brute et d'export brut.


Scénario 6 — Bilan énergétique de toute la maison

Objectif : 3 modules — secteur (bidirectionnel), solaire (production seule), charges (UI3 pour le détail par appareil). Un tableau de bord combiné est publié une fois par minute.

(Nécessite pip install paho-mqtt.)

Python
import time, json
from smbus2 import SMBus
import paho.mqtt.client as mqtt_client
from rbamp import (RbAmp, RbAmpFleet, RbAmpError,
                   RbAmpStaleError, RbAmpSensorClass)

GC_GROUP = 0

with SMBus(1) as bus:
    mains = RbAmp(bus, 0x50)   # bidirectional mains
    solar = RbAmp(bus, 0x51)   # generation only
    loads = RbAmp(bus, 0x52)   # UI3 — per-appliance
    devs = [mains, solar, loads]
    for d in devs:
        d.begin()

    fleet = RbAmpFleet(bus)
    for d in devs:
        fleet.add(d)
    fleet.enable_gc_all(group=GC_GROUP)   # one-time, persisted

    mqtt = mqtt_client.Client(mqtt_client.CallbackAPIVersion.VERSION2, "home-balance")
    mqtt.connect("192.168.1.10", 1883, keepalive=60)
    mqtt.loop_start()

    while True:
        time.sleep(60)

        # One coherent all-call snapshot for the whole bus (see Scenario 3)
        tick = fleet.gc_latch(group=GC_GROUP)
        time.sleep(0.050)                     # single shared settle
        sync = fleet.check_sync(expected_tick=tick)

        try:
            sm = mains.read_period_snapshot(settle_ms=0, skip_latch=True)
            ss = solar.read_period_snapshot(settle_ms=0, skip_latch=True)
            sl = loads.read_period_snapshot(settle_ms=0, skip_latch=True)
        except RbAmpStaleError:
            continue

        payload = {
            "mains":  round(mains.energy.wh(0), 3),
            "solar":  round(solar.energy.wh(0), 3),
            "hp":     round(loads.energy.wh(0), 3),
            "ac":     round(loads.energy.wh(1), 3),
            "ev":     round(loads.energy.wh(2), 3),
        }
        mqtt.publish("home/energy/balance",
                     json.dumps(payload), qos=1, retain=True)

        # let a dashboard alarm on a partial fleet (a module that missed the frame)
        in_sync = sum(s.in_sync for s in sync)
        mqtt.publish("home/energy/sync/in_sync",
                     f"{in_sync}/{len(sync)}", qos=1, retain=True)

Sur les modules BASIC, l'export n'est pas compté par energy.wh(), donc les chiffres solar et mains ci-dessus ne concernent que la consommation. Pour une séparation explicite consommation brute / export brut au secteur, combinez ceci avec le schéma du scénario 5 (une boucle séparée à 10 Hz sur mains.read_power(0) dans un threading.Thread en arrière-plan sur CPython, ou uasyncio.create_task sur MicroPython).


Scénario 7 — journalisation de détection d'événements (EMA)

Objectif : sur chaque fenêtre RT de 100 ms, comparer la puissance instantanée avec une moyenne mobile exponentielle. Journaliser les écarts significatifs — les charges comme un micro-ondes, une bouilloire ou un sèche-cheveux « apparaissent » dans le journal sous forme d'événements de mise en marche / arrêt.

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpIOError

EMA_ALPHA = 0.05
EVENT_THRESHOLD_W = 200.0

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    try:
        p_ema = dev.read_power(0)   # seed so the first read isn't an event
    except RbAmpIOError:
        p_ema = 0.0

    while True:
        time.sleep(0.1)
        try:
            p = dev.read_power(0)
        except RbAmpIOError:
            continue

        delta = p - p_ema
        p_ema = (1 - EMA_ALPHA) * p_ema + EMA_ALPHA * p

        if abs(delta) > EVENT_THRESHOLD_W:
            action = "TURN_ON" if delta > 0 else "TURN_OFF"
            print(f"{time.time():.0f}  {action}  delta={delta:.0f} W  "
                  f"P={p:.0f} W  EMA={p_ema:.0f}")

Sur MicroPython, appliquez les mêmes substitutions : time.sleep → time.sleep_ms, et time.time() → time.time() (disponible sur la plupart des portages) ou time.ticks_ms().

Combinez ceci avec la publication MQTT du scénario 4 pour les automatisations côté HA.


Scénario 8 — Enregistreur local à rotation (CPython)

Objectif : écrire un instantané de période dans un fichier CSV à rotation une fois par minute via le logging.handlers.RotatingFileHandler standard. Utile pour les déploiements autonomes sans WiFi / MQTT, ou comme tampon pour une synchronisation cloud différée.

Python
import time, logging
from logging.handlers import RotatingFileHandler
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpStaleError

log = logging.getLogger("rbamp.csv")
log.setLevel(logging.INFO)
handler = RotatingFileHandler("rbamp.csv", maxBytes=1_000_000, backupCount=5)
handler.setFormatter(logging.Formatter("%(asctime)s,%(message)s",
                                       datefmt="%Y-%m-%dT%H:%M:%S"))
log.addHandler(handler)

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            log.warning("stale")
            continue
        log.info(f"{snap.avg_p[0]:.1f},{dev.energy.wh(0):.4f},"
                 f"{snap.master_dt_ms}")

Sur MicroPython le module standard logging.handlers n'est pas disponible — pour un journal local, utilisez un simple with open("log.csv", "a") plus une rotation manuelle via os.stat() + os.rename(). Voir l'exemple complet dans examples_upy/09_event_detection_logger.py.

Pour une synchronisation cloud différée (journaliser localement, envoyer une fois par heure), voir la section « Hybride : stockage local + synchronisation » dans 08 · Intégrations cloud.


Scénario 9 — Enregistreur sur batterie en deep sleep (MicroPython uniquement)

Objectif : un ESP32 (MicroPython) se réveille une fois toutes les 10 minutes, prend un seul instantané de période, publie via WiFi+MQTT, puis retourne en deep sleep. L'énergie est conservée entre les cycles de veille via la mémoire RTC.

Sécurité

⚠ Remarque importante sur la veille profonde et le firmware v1.0/v1.1. Sur le firmware actuel, dev.begin() émet une amorce CMD_LATCH_PERIOD qui remet à zéro l'accumulateur de période du firmware. Cela signifie qu'après un réveil de veille profonde, vous ne pouvez pas simplement appeler read_period_snapshot() par défaut — cet appel prendrait un nouvel instantané et renverrait des données quasi nulles, couvrant seulement les ~50 ms depuis l'amorce. Le schéma correct ci-dessous utilise skip_latch=True pour lire les données accumulées pendant l'intervalle de veille, et la durée de veille connue (machine.deepsleep(SLEEP_MS)) comme dt — time.ticks_ms() après le réveil peut être une source peu fiable.

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

# Publishing stub. Replace with real WiFi+MQTT logic —
# see Scenario 4 (mqtt_publisher) for a template. In a deep-sleep
# scenario, the WiFi stack is brought up/torn down on every wake,
# which eats up the bulk of the energy budget.
def publish_via_wifi(power_w, total_wh, dt_s):
    print("P=%.1f W  Wh=%.4f  dt=%.1f s" % (power_w, total_wh, dt_s))

SLEEP_MS = 10 * 60 * 1000             # 10 minutes — fixed interval
RTC_MAGIC = b"\xCA\xFE\xFE\xED"

# RTC slow memory: persisted across deep-sleep wakes
rtc = machine.RTC()
state = rtc.memory()                  # bytes; empty on cold boot

def save_state(magic, wh_total, primer_done):
    # Simple layout: 4 bytes magic + 8 bytes float wh + 1 byte primer_done
    import struct
    rtc.memory(magic + struct.pack("dB", wh_total, 1 if primer_done else 0))

def load_state():
    import struct
    if len(state) < 4 + 8 + 1 or state[:4] != RTC_MAGIC:
        return False, 0.0, False
    wh_total, primer_done_byte = struct.unpack("dB", state[4:4+9])
    return True, wh_total, bool(primer_done_byte)

valid, rtc_total_wh, primer_done = load_state()
if not valid:
    rtc_total_wh = 0.0
    primer_done = False

i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:    # __enter__ automatically calls begin() — the snapshot primer
    dev.energy.disable()         # the master owns Wh persistence itself

    if not primer_done:
        # First wake: the primer snapshot just discarded the "dirty" data.
        # Save the flag and go straight back to sleep — the next wake,
        # SLEEP_MS later, will get a full accumulator for the interval.
        save_state(RTC_MAGIC, rtc_total_wh, primer_done=True)
        machine.deepsleep(SLEEP_MS)

    # skip_latch=True reads what the begin() primer snapshot captured —
    # i.e. the accumulator for the elapsed sleep interval.
    snap = dev.read_period_snapshot(settle_ms=0, skip_latch=True)

    # Use the KNOWN sleep duration as dt
    dt_s = SLEEP_MS / 1000
    rtc_total_wh += snap.avg_p[0] * dt_s / 3600.0

    publish_via_wifi(snap.avg_p[0], rtc_total_wh, dt_s)  # stub

    save_state(RTC_MAGIC, rtc_total_wh, primer_done=True)

machine.deepsleep(SLEEP_MS)

Le croquis complet (avec la configuration WiFi, la publication MQTT, les gardes de marqueur magique RTC) se trouve dans examples_upy/06_deep_sleep.py.

Budget énergétique (ESP32-WROOM sur batterie Li-ion de 2000 mAh, intervalle de 10 minutes) :

  • Cycle actif : ~3 s (WiFi + MQTT + I²C) à ~80 mA → ~0.07 mAh par réveil
  • Veille : ~10 µA (RTC + domaines conservés)
  • ~10 mAh par jour → 2000 mAh tiennent environ 6 mois

Les hôtes CPython (Raspberry Pi, etc.) fonctionnent en général sur une alimentation 24/7 — la veille profonde ne s'applique pas. Pour un fonctionnement CPython sur batterie, voir la section sur la consommation et la mise en veille systemd dans 08 · Intégrations cloud.


Scénario 10 — Diffusion asynchrone via stream_period (fonction réservée à Python)

Objectif : s'intégrer à une boucle d'événements asyncio / uasyncio existante. Le paquet fournit un générateur asynchrone dev.stream_period(interval_s=...) qui encapsule l'instantané périodique et la gestion automatique des instantanés obsolètes.

CPython (via asyncio + paho-mqtt-asyncio, ou à plat)

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:
        # Once per minute, skip_stale=True (default) — stale snapshots are
        # automatically skipped without raising RbAmpStaleError
        async for snap in dev.stream_period(interval_s=60.0):
            print(f"P={snap.avg_p[0]:.2f} W,  Wh={dev.energy.wh(0):.4f}")

asyncio.run(main())

MicroPython (via uasyncio)

Python
import uasyncio as asyncio
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpSensorClass

async def reader(dev):
    async for snap in dev.stream_period(interval_s=60.0):
        print("P={:.2f} W,  Wh={:.4f}".format(snap.avg_p[0], dev.energy.wh(0)))

async def main():
    i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
    with RbAmp(i2c, 0x50) as dev:
        # Run reader + other async tasks in parallel
        await asyncio.gather(
            reader(dev),
            # other_async_task(),
        )

asyncio.run(main())

Paramètres de stream_period(interval_s=, skip_stale=) :

  • interval_s — la période entre les instantanés (≥ 30 s recommandé)
  • skip_stale=True (par défaut) — les instantanés périmés sont automatiquement ignorés ; le générateur passe simplement à l'intervalle suivant

  • skip_stale=False — les instantanés obsolètes sont produits avec snap.valid=False, et l'appelant décide quoi en faire

Exemples complets — examples_upy/05_async_streaming.py (MicroPython) et l'équivalent asyncio dans les exemples CPython.


Scénario 11 — énergie embarquée STD (CPython)

Objectif : sur un module STANDARD (STD), lire les compteurs d'énergie à vie du module et indiquer ce qui a été consommé sur chaque intervalle. Il n'existe pas de fichier d'exemple distinct pour ce scénario ; le code ci-dessous est complet.

Remarque

L'énergie embarquée est validée sur CPython (smbus2). Le chemin 16 bits MicroPython est implémenté mais pas encore validé sur matériel — préférez CPython pour ce scénario.

Python
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpNotSupportedError

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    if not dev.is_std:
        raise SystemExit("not an STD module")

    try:
        prev = dev.read_std_energy()
    except RbAmpNotSupportedError:
        raise SystemExit("this module does not provide on-device energy")

    while True:
        time.sleep(60)
        now = dev.read_std_energy()
        delta, restarted = RbAmp.std_energy_delta(prev, now)
        if delta is None:
            print("energy generation changed - readings not comparable")
        else:
            print("import %d Wh, export %d Wh, net %d Wh%s" % (
                delta.act_import_wh, delta.act_export_wh, delta.act_net_wh,
                " (module restarted)" if restarted else ""))
        prev = now

std_energy_delta() est sûre en cas de coupure de courant : un compteur qui revient légèrement plus bas est traité comme une augmentation nulle. Les chiffres par voie figurent dans now.ch_import_uwh[ch] / ch_export_uwh[ch] pour ch < now.channels.

Les appels de période sur un module STD

Les appels de période du scénario 2 fonctionnent sur un module STD comme sur BASIC ; l'énergie est nette (l'export se soustrait) :

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

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    while True:
        time.sleep(60)
        try:
            snap = dev.read_period_snapshot()
        except RbAmpStaleError:
            continue    # nothing to report for this period; the next one covers it
        print("avg %.1f W, net %.4f Wh, total %.4f Wh%s" % (
            snap.avg_p_total, snap.wh_net, dev.energy.wh(0),
            " (module restarted)" if snap.module_restarted else ""))

begin() choisit la source de période selon ce que le module signale : ses compteurs d'énergie (la période est la différence de deux lectures ; aucune commande de latch n'est envoyée) ou, sur un module ne disposant que de banques de latch, la banque de latch 0. Les banques de latch sont aussi accessibles directement — voir « Banques de latch » dans 09 · Référence API.


Tableau récapitulatif des scénarios

# LOC Exécution bus I²C Période ? DRDY? MQTT? Persistance
1 ~25 les deux dédié non non non non
2 ~35 les deux (OLED sur uPy) partagé avec l'OLED (uPy) oui non non RAM
3 ~50 les deux partagé, 3 modules oui non non RAM
4 ~50 les deux dédié oui non oui retained MQTT
5 ~40 les deux dédié non (RT) non non RAM (détenue par le maître)
6 ~60 les deux partagé, 3 modules oui non oui retained MQTT
7 ~40 les deux dédié non (RT) non non RAM
8 ~30 CPython dédié oui non non fichier de journal rotatif
9 ~50 MicroPython uniquement dédié oui non oui Mémoire RTC + MQTT
10 ~25 les deux (asyncio/uasyncio) dédié oui non (optional) RAM
11 ~20 CPython (module STD) dédié non (sur l'appareil) non non compteurs d'énergie à vie du module

Déploiement en production (CPython uniquement)

Pour un déploiement 24/7 de longue durée sur un SBC Linux, un service systemd est recommandé. L'exemple complet se trouve dans examples_cpython/10_systemd_service.py (il inclut une aide --install qui génère le fichier d'unité /etc/systemd/system/rbamp.service).

Structure de base :

Python
#!/usr/bin/env python3
# /usr/local/bin/rbamp_daemon.py  (make it executable: sudo chmod +x /usr/local/bin/rbamp_daemon.py)
import sys, signal, time, logging
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass

logging.basicConfig(level=logging.INFO,
                    format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("rbamp")

shutdown = False
def on_signal(sig, frame):
    global shutdown
    log.info("Received signal %d, shutting down gracefully", sig)
    shutdown = True

signal.signal(signal.SIGTERM, on_signal)
signal.signal(signal.SIGINT,  on_signal)

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    log.info("rbAmp daemon started")
    while not shutdown:
        try:
            snap = dev.read_period_snapshot()
            log.info("P=%.1f W, Wh=%.4f", snap.avg_p[0], dev.energy.wh(0))
        except Exception as e:
            log.warning("snapshot failed: %s", e)
        time.sleep(60)

log.info("rbAmp daemon stopped")

Et l'appareil lui-même :

INI
# /etc/systemd/system/rbamp.service
[Unit]
Description=rbAmp I2C AC sensor daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/rbamp_daemon.py
Restart=on-failure
RestartSec=5
# the user must be in the i2c group: sudo usermod -aG i2c pi
User=pi

[Install]
WantedBy=multi-user.target

Pour démarrer : sudo systemctl enable --now rbamp. Journaux : journalctl -u rbamp -f.

Suite


← Démarrage rapide | Sommaire | Intégrations DIY →


Source et signalements : rb-amp/rbamp-python · cette page dans le dépôt : docs/06_examples.md


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