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) |
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
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
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)
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)
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.
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
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
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)
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)
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)
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
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
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.)
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.
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.
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.
⚠ 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.
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)
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)
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 avecsnap.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.
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.
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) :
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 :
#!/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 :
# /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
-
07 · Intégrations DIY — Home Assistant / Node-RED / OpenHAB bâtis sur ces scénarios
-
08 · Intégrations cloud — AWS IoT / Azure / GCP / InfluxDB Cloud / webhook générique
-
09 · Référence API — chaque classe, méthode, propriété et exception publique
-
10 · Dépannage — quand les scénarios se comportent mal sur votre banc
← 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)