12 · Exemples MicroPython et CircuitPython
Ce chapitre est l'équivalent Python de arduino-examples.md : les mêmes dix scénarios, portés en MicroPython sur ESP32 / RP2040 / ESP8266 / Pyboard, avec les différences CircuitPython là où les deux dialectes diffèrent.
Ces exemples parlent directement à rbAmp via l'API I²C de registres bruts. Ils sont destinés aux intégrations natives, embarquées ou autrement contraintes en ressources, où le contrôle direct est requis et où chaque octet du bus compte.
Pour une interface plus pratique et structurée — utilisez la bibliothèque MicroPython rbamp (voir le tableau des bibliothèques clientes du README). La bibliothèque enveloppe les détails au niveau des registres derrière une classe RbAmp de haut niveau aux méthodes nommées (dev.voltage, dev.latch_period(), dev.read_period_snapshot(), etc.), des API synchrone et uasyncio, un accumulateur Wh automatique par canal, des fonctions utilitaires multi-modules et la discipline de réessai + contrôle de cohérence SPEC §B.5 pour les portages ESP32 via MachineI2CBackend(retry_attempts=…). Le même paquet fonctionne sans modification sous CPython — voir le tableau des bibliothèques clientes du README. La plupart des projets orientés utilisateur devraient partir de la bibliothèque et ne revenir à l'API brute que si nécessaire.
MicroPython vs CircuitPython — référence rapide
Le langage Python est le même ; les modules d'accès au matériel diffèrent. Le tableau ci-dessous associe chaque concept utilisé dans les exemples au module ou à la classe équivalent sur chaque dialecte.
| Concept | MicroPython | CircuitPython |
|---|---|---|
| Bus I2C | from machine import I2C, Pini2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000) |
import board, busioi2c = busio.I2C(board.SCL, board.SDA, frequency=50000) |
| Lecture d'un octet | i2c.readfrom_mem(addr, reg, 1)[0] |
with i2c_device: i2c_device.write_then_readinto(bytes([reg]), buf, in_end=1) (avec adafruit_bus_device.I2CDevice) |
| Écriture d'un octet | i2c.writeto_mem(addr, reg, bytes([val])) |
i2c_device.write(bytes([reg, val])) |
| Entrée GPIO + IRQ | pin = Pin(15, Pin.IN, Pin.PULL_UP)pin.irq(trigger=Pin.IRQ_FALLING, handler=fn) |
import digitalio, countiobtn = countio.Counter(board.D15, edge=countio.Edge.FALL)ou keypad.Keys([board.D15], ...) |
| Veille (s / ms) | time.sleep(s) / time.sleep_ms(ms) |
time.sleep(s) (pas de sleep_ms) |
| Millisecondes / microsecondes monotones | time.ticks_ms(), time.ticks_us(), time.ticks_diff(a, b) |
time.monotonic_ns() / time.monotonic() (sans ticks_diff) |
| WiFi | import networkwlan = network.WLAN(network.STA_IF) |
import wifiwifi.radio.connect(ssid, pwd) (ESP32-S2/S3/C3 avec CP natif) |
| MQTT | from umqtt.simple import MQTTClient |
import adafruit_minimqtt.adafruit_minimqtt as mqtt |
| NTP | import ntptime; ntptime.settime() |
import adafruit_ntp; ntp = adafruit_ntp.NTP(socketpool, server="...") |
| Veille profonde | import machine; machine.deepsleep(ms) |
import alarm; alarm.exit_and_deep_sleep_until_alarms(time_alarm) |
| Mémoire conservée RTC | machine.RTC().memory(buf) |
import alarm; alarm.sleep_memory[...] |
| Asynchrone | import uasyncio as asyncio |
import asyncio (CircuitPython 8+) |
Chaque exemple ci-dessous est écrit en MicroPython. Lorsque l'équivalent CircuitPython diffère de plus d'une seule ligne d'import, un bloc « Delta CircuitPython » explicite est fourni.
Table des matières des exemples
| # | Titre | Difficulté | Sortie | MQTT | DRDY | Multi-modules | Bidirectionnel | Cas d'usage |
|---|---|---|---|---|---|---|---|---|
| 1 | Lecture rapide | minimal | REPL | — | — | — | — | Test de fonctionnement |
| 2 | Compteur d'énergie sur 60 secondes sur OLED | faible | SSD1306 | — | — | — | — | Compteur Wh encapsulé |
| 3 | Surveillance multi-modules | faible | REPL | — | — | oui (3) | — | Surveillance de tout le foyer |
| 4 | Suivi d'énergie par appareil (UI3) | moyen | — | oui | — | — | — | Sous-comptage dans HA |
| 5 | Bidirectionnel côté maître sur un module BASIC | moyen | REPL | — | oui | — | oui (maître) | Maison solaire en gamme BASIC |
| 6 | Bilan énergétique de la maison | élevé | — | oui | — | oui (3) | oui | Bilan complet de la maison |
| 7 | Détection d'événements de puissance | moyen | REPL + SD | — | oui | — | — | Journal des événements des appareils |
| 8 | Publication MQTT avec découverte automatique HA | moyen | — | oui (+disco) | — | — | facultatif | Intégration HA prête à l'emploi |
| 9 | Enregistreur distant sur batterie avec veille profonde | moyen | — | oui | — | — | — | Compteur hors réseau / extérieur |
| 10 | Tarif heures pleines / heures creuses (TOU) avec horloge murale NTP | moyen | REPL | oui | — | — | facultatif | Mesure tarifaire heures pleines / heures creuses |
En-tête commun à tous les exemples
Chaque exemple suppose que ces fonctions utilitaires sont présentes dans le même fichier .py (ou importées depuis un helpers.py). Pour gagner de la place, le bloc n'est pas répété dans chaque esquisse.
"""
rbAmp raw-I2C helpers for MicroPython.
For CircuitPython, replace the I2C bring-up:
import board, busio
from adafruit_bus_device.i2c_device import I2CDevice
i2c_bus = busio.I2C(board.SCL, board.SDA, frequency=50000)
# then use I2CDevice(i2c_bus, addr) for each rbAmp, see notes in each example.
"""
import struct
import time
from machine import I2C, Pin # MicroPython
def rb_read_u8(i2c, addr, reg):
"""Read one byte from an rbAmp slave register.
:param i2c: machine.I2C instance.
:param addr: 7-bit slave address (e.g. 0x50).
:param reg: register address inside the slave.
:returns: the byte stored in the register.
"""
return i2c.readfrom_mem(addr, reg, 1)[0]
def rb_read_float_le(i2c, addr, reg):
"""Read a little-endian float32 from four consecutive registers.
rbAmp supports READ auto-increment (a single burst-read is valid for
atomicity). The per-byte form below is shown for clarity. WRITE
transactions, by contrast, are byte-at-a-time only. See chapter 11.
"""
b = bytes([rb_read_u8(i2c, addr, reg + i) for i in range(4)])
return struct.unpack('> 8) & 0xFF]))
return True
except OSError:
return False
def rb_wait_ready(i2c, addr, timeout_ms=2000):
"""Block until DATA_VALID bit 0 is 1, or raise OSError on timeout."""
t0 = time.ticks_ms()
while time.ticks_diff(time.ticks_ms(), t0) < timeout_ms:
if rb_read_u8(i2c, addr, 0xCE) & 0x01:
return
time.sleep_ms(50)
raise OSError("rbAmp at 0x{:02X} not ready".format(addr))
Delta CircuitPython — en-tête commun
CircuitPython utilise adafruit_bus_device.i2c_device.I2CDevice (enveloppe par esclave) et ne dispose pas de time.ticks_ms. Fonctions équivalentes :
import time
import struct
import board, busio
from adafruit_bus_device.i2c_device import I2CDevice
def cp_read_u8(dev, reg):
"""Read one byte from one register (CircuitPython)."""
buf = bytearray(1)
with dev:
dev.write_then_readinto(bytes([reg]), buf)
return buf[0]
def cp_read_float_le(dev, reg):
b = bytes(cp_read_u8(dev, reg + i) for i in range(4))
return struct.unpack('> 8) & 0xFF]))
return True
except OSError:
return False
finally:
i2c_bus.unlock()
def cp_wait_ready(dev, timeout_s=2.0):
t0 = time.monotonic()
while time.monotonic() - t0 < timeout_s:
if cp_read_u8(dev, 0xCE) & 0x01:
return
time.sleep(0.05)
raise OSError("rbAmp not ready")
Exemple 1 — Lecture rapide (minimale)
Objectif : afficher U, I, P, PF dans un REPL une fois par seconde. Matériel : ESP32 / RP2040 / Pico W + un rbAmp UI1.
from machine import I2C, Pin
import time
# I2C bus 0 on ESP32 default pins.
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
RB_ADDR = 0x50
# Wait until the first RT window has been computed.
rb_wait_ready(i2c, RB_ADDR)
ver = rb_read_u8(i2c, RB_ADDR, 0x03)
print("rbAmp version: 0x{:02X}".format(ver))
while True:
u = rb_read_float_le(i2c, RB_ADDR, 0x86) # RMS voltage, V
i_ = rb_read_float_le(i2c, RB_ADDR, 0x8E) # RMS current, A
p = rb_read_float_le(i2c, RB_ADDR, 0xA6) # active power, W (signed)
pf = rb_read_float_le(i2c, RB_ADDR, 0xB2) # power factor, signed
print("U={:.1f}V I={:.3f}A P={:+.1f}W PF={:+.3f}".format(u, i_, p, pf))
time.sleep(1)
Différences CircuitPython
import board, busio, time
from adafruit_bus_device.i2c_device import I2CDevice
i2c_bus = busio.I2C(board.SCL, board.SDA, frequency=50000)
dev = I2CDevice(i2c_bus, 0x50)
cp_wait_ready(dev)
print("rbAmp version: 0x{:02X}".format(cp_read_u8(dev, 0x03)))
while True:
u = cp_read_float_le(dev, 0x86)
i_ = cp_read_float_le(dev, 0x8E)
p = cp_read_float_le(dev, 0xA6)
pf = cp_read_float_le(dev, 0xB2)
print("U={:.1f}V I={:.3f}A P={:+.1f}W PF={:+.3f}".format(u, i_, p, pf))
time.sleep(1)
Exemple 2 — compteur d'énergie de 60 secondes sur OLED
Objectif : compteur Wh rafraîchi une fois par minute, affiché sur un SSD1306 128×64. Matériel : ESP32 + rbAmp + OLED SSD1306 sur le même bus. Comptabilité : unidirectionnelle (gamme BASIC). Bibliothèque : ssd1306.py des exemples MicroPython (pilote standard en un seul fichier).
from machine import I2C, Pin
import time
import ssd1306
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
RB_ADDR = 0x50
oled = ssd1306.SSD1306_I2C(128, 64, i2c) # OLED typically at 0x3C
rb_wait_ready(i2c, RB_ADDR)
# Primer snapshot — discard its result.
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
t_prev_ms = time.ticks_ms()
total_wh = 0.0
while True:
time.sleep(60)
# 1) Final snapshot — closes the period [t_prev_ms .. now].
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
t_now_ms = time.ticks_ms()
time.sleep_ms(50) # let firmware finalise the snapshot
# 2) Verify the snapshot is fresh.
if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
print("WARN: stale snapshot")
t_prev_ms = time.ticks_ms()
continue
# 3) Read time-averaged power, channel 0.
avg_p = rb_read_float_le(i2c, RB_ADDR, 0xDC)
# 4) Energy uses the MASTER clock (authoritative).
dt_s = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
e_wh = avg_p * dt_s / 3600.0
total_wh += e_wh
t_prev_ms = t_now_ms
# 5) Render on OLED.
oled.fill(0)
oled.text("P: {:6.1f} W".format(avg_p), 0, 0)
oled.text("dt: {:6.1f} s".format(dt_s), 0, 16)
oled.text("E: {:.2f} Wh".format(total_wh), 0, 32)
oled.show()
print("avg_P={:.1f} E_period={:.3f} total={:.3f}".format(avg_p, e_wh, total_wh))
: utilisez adafruit_ssd1306 (variante displayio ou variante framebuf). Le constructeur de l'OLED diffère, mais le reste de la boucle ne change pas — remplacez les appels rb_* par les fonctions d'aide cp_* et utilisez time.monotonic() pour dt_s.
Exemple 3 — Surveillance multi-modules
Objectif : interroger trois modules (alimentation principale, chauffe-eau, climatisation) et afficher le total. Matériel : ESP32 + 3 × rbAmp UI1 à 0x50, 0x51, 0x52.
from machine import I2C, Pin
import time
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
modules = ((0x50, "Mains "), (0x51, "Boiler"), (0x52, "AC "))
# I2C scan — confirm every module is present.
present = i2c.scan()
for addr, label in modules:
if addr not in present:
raise RuntimeError("{} at 0x{:02X} not on bus".format(label, addr))
print("All modules OK:", [hex(a) for a in present])
while True:
total_p = 0.0
print("---")
for addr, label in modules:
u = rb_read_float_le(i2c, addr, 0x86)
p = rb_read_float_le(i2c, addr, 0xA6)
print("[{}] U={:.1f} P={:+.1f} W".format(label, u, p))
total_p += p
print("TOTAL: {:.1f} W".format(total_p))
time.sleep(2)
Exemple 4 — Suivi d'énergie par appareil (UI3)
Objectif : un module UI3 avec trois pinces de courant sur trois charges différentes sur la même phase. Compteurs Wh indépendants par charge, publiés sur MQTT chaque minute. Matériel : ESP32 + 1 × rbAmp UI3. Bibliothèque : umqtt.simple (MicroPython) ou umqtt.robust pour la reconnexion automatique.
from machine import I2C, Pin
import network, time
from umqtt.simple import MQTTClient
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
RB_ADDR = 0x50
CH_NAMES = ("main", "heatpump", "lights")
# --- Wi-Fi ---
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("ssid", "password")
while not wlan.isconnected():
time.sleep(0.5)
# --- MQTT ---
mqtt = MQTTClient(client_id="rbamp-ui3", server="192.168.1.10")
mqtt.connect()
def mqtt_publish(ch_name, avg_p, e_wh):
"""Publish one channel's state to MQTT.
:param ch_name: short channel name (used in the topic).
:param avg_p: time-averaged power, W.
:param e_wh: accumulated channel energy, Wh.
"""
topic = "rbamp/{}/state".format(ch_name).encode()
payload = '{{"power":{:.1f},"energy":{:.4f}}}'.format(avg_p, e_wh).encode()
mqtt.publish(topic, payload)
rb_wait_ready(i2c, RB_ADDR)
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27) # primer snapshot
t_prev_ms = time.ticks_ms()
total_wh = [0.0, 0.0, 0.0]
while True:
time.sleep(60)
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
t_now_ms = time.ticks_ms()
time.sleep_ms(50)
if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
t_prev_ms = time.ticks_ms()
continue
# PERIOD_AVG_P_W per channel: I0 at 0xDC, I1 at 0xC2, I2 at 0xC6.
avg_p = (rb_read_float_le(i2c, RB_ADDR, 0xDC),
rb_read_float_le(i2c, RB_ADDR, 0xC2),
rb_read_float_le(i2c, RB_ADDR, 0xC6))
dt_s = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
t_prev_ms = t_now_ms
for ch in range(3):
e = avg_p[ch] * dt_s / 3600.0
total_wh[ch] += e
print("[{}] avg_P={:+.1f} W E_total={:.3f} Wh".format(
CH_NAMES[ch], avg_p[ch], total_wh[ch]))
mqtt_publish(CH_NAMES[ch], avg_p[ch], total_wh[ch])
: remplacez umqtt.simple.MQTTClient par adafruit_minimqtt.MQTT(...) (nécessite un socket_pool et un ssl_context — voir le guide WiFi d'Adafruit). La logique de comptage est inchangée.
Exemple 5 — Bidirectionnel côté maître sur un module BASIC
Objectif : implémenter la comptabilité bidirectionnelle côté maître pendant que le firmware du module est BASIC (l'accumulateur de période ramène les échantillons négatifs à zéro). Lire P_real RT à chaque front DRDY et séparer consommation / export. Matériel : ESP32 + rbAmp UI1 sur une charge avec onduleur solaire + DRDY relié à un GPIO.
from machine import I2C, Pin
import time
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
drdy = Pin(15, Pin.IN, Pin.PULL_UP)
RB_ADDR = 0x50
_data_ready = False
_e_consumed_wh = 0.0
_e_exported_wh = 0.0
_t_last_sample_ms = 0
def _drdy_isr(pin):
"""ISR for DRDY falling edge — only sets a flag (no I2C inside ISR)."""
global _data_ready
_data_ready = True
drdy.irq(trigger=Pin.IRQ_FALLING, handler=_drdy_isr)
rb_wait_ready(i2c, RB_ADDR)
_t_last_sample_ms = time.ticks_ms()
_last_print = time.ticks_ms()
print("Bidirectional accumulator started")
while True:
if not _data_ready:
time.sleep_ms(10)
continue
_data_ready = False
t_now = time.ticks_ms()
# Signed instantaneous P_real: + consume, − export.
p = rb_read_float_le(i2c, RB_ADDR, 0xA6)
dt_s = time.ticks_diff(t_now, _t_last_sample_ms) / 1000.0
_t_last_sample_ms = t_now
if p > 0:
_e_consumed_wh += p * dt_s / 3600.0
else:
_e_exported_wh += -p * dt_s / 3600.0
# Summary print every 5 s — not on every RT window.
if time.ticks_diff(t_now, _last_print) >= 5000:
_last_print = t_now
print("P={:+8.1f}W consumed={:.4f} Wh exported={:.4f} Wh net={:+.4f} Wh"
.format(p, _e_consumed_wh, _e_exported_wh,
_e_consumed_wh - _e_exported_wh))
: CircuitPython déconseille généralement les IRQ GPIO définies par l'utilisateur. Utilisez countio.Counter(board.D15, edge=countio.Edge.FALL) et interrogez son count depuis la boucle principale, ou keypad.Keys(...) pour les événements de front. La logique d'accumulation est identique.
Exemple 6 — bilan énergétique de la maison
Objectif : un tableau de bord complet du bilan. Trois modules :
- rbAmp n° 1 sur l'alimentation principale (STD — bidirectionnel)
- rbAmp n° 2 sur la sortie de l'onduleur solaire
- rbAmp n° 3 UI3 sur trois gros appareils (PAC, climatisation, VE)
Le maître calcule total_consumed = solar_self_used + grid_consumed et solar_generated = solar_self_used + grid_exported. Matériel : ESP32 + 3 × rbAmp + WiFi + MQTT.
from machine import I2C, Pin
import network, time, ujson as json
from umqtt.simple import MQTTClient
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
ADDR_MAINS = 0x50 # bidirectional (STD)
ADDR_SOLAR = 0x51 # generation only
ADDR_LOADS = 0x52 # UI3
# PERIOD_AVG_P_NEG address for the mains module — see the SKU datasheet
# of the STD product. Set to None on BASIC modules.
REG_PERIOD_AVG_P_NEG_MAINS = None
wlan = network.WLAN(network.STA_IF); wlan.active(True); wlan.connect("ssid", "password")
while not wlan.isconnected():
time.sleep(0.5)
mqtt = MQTTClient("home-balance", "192.168.1.10"); mqtt.connect()
# Wait until all three modules report DATA_VALID.
for addr in (ADDR_MAINS, ADDR_SOLAR, ADDR_LOADS):
rb_wait_ready(i2c, addr)
totals = {
"mains_in_wh": 0.0,
"mains_out_wh": 0.0,
"solar_total_wh": 0.0,
"loads_wh": [0.0, 0.0, 0.0],
}
gc_tick = 0
if not rb_broadcast_latch(i2c, gc_tick):
# GC NACK → fall back to per-module sequential snapshot.
for addr in (ADDR_MAINS, ADDR_SOLAR, ADDR_LOADS):
rb_write_u8(i2c, addr, 0x01, 0x27)
gc_tick += 1
t_prev_ms = time.ticks_ms()
print("Home balance started")
while True:
time.sleep(60)
if not rb_broadcast_latch(i2c, gc_tick):
for addr in (ADDR_MAINS, ADDR_SOLAR, ADDR_LOADS):
rb_write_u8(i2c, addr, 0x01, 0x27)
gc_tick = (gc_tick + 1) & 0xFFFF
t_now_ms = time.ticks_ms()
time.sleep_ms(50)
dt_s = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
t_prev_ms = t_now_ms
# --- MAINS (bidirectional, STD) ---
if rb_read_u8(i2c, ADDR_MAINS, 0x07) & 0x01:
avg_p_consume = rb_read_float_le(i2c, ADDR_MAINS, 0xDC)
avg_p_export = (rb_read_float_le(i2c, ADDR_MAINS, REG_PERIOD_AVG_P_NEG_MAINS)
if REG_PERIOD_AVG_P_NEG_MAINS is not None else 0.0)
totals["mains_in_wh"] += avg_p_consume * dt_s / 3600.0
totals["mains_out_wh"] += avg_p_export * dt_s / 3600.0
# --- SOLAR (generation only) ---
if rb_read_u8(i2c, ADDR_SOLAR, 0x07) & 0x01:
avg_p = rb_read_float_le(i2c, ADDR_SOLAR, 0xDC)
totals["solar_total_wh"] += avg_p * dt_s / 3600.0
# --- LOADS (UI3, three channels) ---
if rb_read_u8(i2c, ADDR_LOADS, 0x07) & 0x01:
for i, reg in enumerate((0xDC, 0xC2, 0xC6)): # I0, I1, I2
p = rb_read_float_le(i2c, ADDR_LOADS, reg)
totals["loads_wh"][i] += p * dt_s / 3600.0
# --- Derived balance figures ---
total_consumed = (totals["mains_in_wh"] + totals["solar_total_wh"]
- totals["mains_out_wh"])
solar_self_used = max(0.0, totals["solar_total_wh"] - totals["mains_out_wh"])
print("MAINS in={:.2f} out={:.2f}".format(totals["mains_in_wh"],
totals["mains_out_wh"]))
print("SOLAR gen={:.2f} self-used={:.2f} exported={:.2f}".format(
totals["solar_total_wh"], solar_self_used, totals["mains_out_wh"]))
print("LOADS HP={:.2f} AC={:.2f} EV={:.2f}".format(*totals["loads_wh"]))
print("TOTAL household consumed={:.2f} Wh".format(total_consumed))
payload = json.dumps({
"mains_in": totals["mains_in_wh"],
"mains_out": totals["mains_out_wh"],
"solar": totals["solar_total_wh"],
"self_used": solar_self_used,
"total_consumed": total_consumed,
"hp": totals["loads_wh"][0],
"ac": totals["loads_wh"][1],
"ev": totals["loads_wh"][2],
})
mqtt.publish(b"home/energy/balance", payload.encode(), retain=True)
Notes:
rb_broadcast_latch(i2c, tick)garantit que les trois modules font leur instantané au même moment — indispensable pour un bilan précis. La réception GC est facultative (FLEET_CONFIG.bit0, par défaut DÉSACTIVÉE, voir chapitre 02). En cas de NACK, repassez sur un instantané séquentiel module par module (décalage d'environ 1 ms par module à 50 kHz).solar_self_used = solar_total − grid_exported; ramenez à zéro pour absorber le bruit de mesure.
Exemple 7 — détection d'événements de puissance
Objectif : à chaque front DRDY, comparer la puissance instantanée P à une moyenne mobile exponentielle (EMA) et journaliser les écarts significatifs sur une carte SD. Matériel : ESP32 + rbAmp + carte SD (pilotée en SPI, par ex. via le pilote MicroPython sdcard.py). Cas d'usage : détection automatique des gros événements de charge (micro-ondes, climatisation, bouilloire).
from machine import I2C, Pin, SPI
import time, os, sdcard
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
drdy = Pin(15, Pin.IN, Pin.PULL_UP)
RB_ADDR = 0x50
# Mount the SD card on /sd (SPI bus 1, CS = GPIO 5).
spi = SPI(1, baudrate=1_000_000, sck=Pin(18), mosi=Pin(23), miso=Pin(19))
sd = sdcard.SDCard(spi, Pin(5))
os.mount(sd, "/sd")
EMA_ALPHA = 0.05 # ~2 s time constant at 10 Hz
EVENT_THRESHOLD_W = 200.0
_data_ready = False
def _drdy_isr(pin):
global _data_ready
_data_ready = True
drdy.irq(trigger=Pin.IRQ_FALLING, handler=_drdy_isr)
rb_wait_ready(i2c, RB_ADDR)
# Seed the EMA with the current power so we do not log a spurious startup event.
p_ema = rb_read_float_le(i2c, RB_ADDR, 0xA6)
print("Event detector started")
logfile = open("/sd/events.log", "a")
while True:
if not _data_ready:
time.sleep_ms(10)
continue
_data_ready = False
p = rb_read_float_le(i2c, RB_ADDR, 0xA6)
delta = p - p_ema
p_ema = (1 - EMA_ALPHA) * p_ema + EMA_ALPHA * p
if abs(delta) > EVENT_THRESHOLD_W:
event = "TURN_ON" if delta > 0 else "TURN_OFF"
line = "{} {} delta={:+.1f} W P={:.1f} W EMA={:.1f} W\n".format(
time.ticks_ms(), event, delta, p, p_ema)
print(line, end="")
logfile.write(line)
logfile.flush() # ensure the line hits the card
: utilisez adafruit_sdcard.SDCard + storage.mount(VfsFat(sdcard), "/sd"). Remplacez l'IRQ par countio.Counter(board.D15, edge=countio.Edge.FALL), interrogé depuis la boucle principale.
Exemple 8 — Publieur MQTT avec découverte automatique Home Assistant
Objectif : une intégration HA prête à l'emploi. L'ESP32 se connecte au WiFi et à un broker MQTT, publie les configurations HA Auto-discovery (les entités apparaissent sans aucun YAML) et émet un état JSON chaque minute. Matériel : ESP32 + un rbAmp UI1 + réseau WiFi avec un broker MQTT. Comptabilité : unidirectionnelle.
from machine import I2C, Pin
import network, time, ujson as json
from umqtt.simple import MQTTClient
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
RB_ADDR = 0x50
WIFI_SSID = "ssid"
WIFI_PASS = "password"
MQTT_HOST = "192.168.1.10"
MQTT_USER = "ha"
MQTT_PASS = "secret"
DEVICE_ID = "rbamp_main"
DEVICE_NAME = "Mains rbAmp"
# Bring up WiFi.
wlan = network.WLAN(network.STA_IF); wlan.active(True); wlan.connect(WIFI_SSID, WIFI_PASS)
while not wlan.isconnected():
time.sleep(0.5)
print("WiFi up:", wlan.ifconfig()[0])
mqtt = MQTTClient(DEVICE_ID, MQTT_HOST, user=MQTT_USER, password=MQTT_PASS)
mqtt.connect()
DEVICE = {
"identifiers": [DEVICE_ID],
"name": DEVICE_NAME,
"manufacturer": "rbAmp",
"model": "rbAmp UI*",
}
def publish_discovery_sensor(key, friendly, unit, dev_class, state_class):
"""Publish one HA discovery config (retained).
:param key: short id used in the topic and value_template.
:param friendly: HA friendly-name suffix.
:param unit: unit_of_measurement, or None.
:param dev_class: HA device_class string, or None.
:param state_class: 'measurement' or 'total_increasing'.
"""
cfg = {
"name": "{} {}".format(DEVICE_NAME, friendly),
"unique_id": "{}_{}".format(DEVICE_ID, key),
"state_topic": "rbamp/{}/state".format(DEVICE_ID),
"value_template": "{{{{ value_json.{} }}}}".format(key),
"state_class": state_class,
"device": DEVICE,
}
if unit: cfg["unit_of_measurement"] = unit
if dev_class: cfg["device_class"] = dev_class
topic = "homeassistant/sensor/{}/{}/config".format(DEVICE_ID, key).encode()
mqtt.publish(topic, json.dumps(cfg).encode(), retain=True)
def publish_discovery_all():
"""Publish the full set of HA discovery configs for one rbAmp module."""
publish_discovery_sensor("voltage", "Voltage", "V", "voltage", "measurement")
publish_discovery_sensor("current", "Current", "A", "current", "measurement")
publish_discovery_sensor("power", "Power", "W", "power", "measurement")
publish_discovery_sensor("energy", "Energy", "Wh", "energy", "total_increasing")
publish_discovery_sensor("frequency", "Frequency", "Hz", "frequency", "measurement")
publish_discovery_sensor("power_factor", "Power Factor", None, "power_factor", "measurement")
publish_discovery_sensor("apparent_power", "Apparent Power", "VA", "apparent_power", "measurement")
publish_discovery_sensor("reactive_power", "Reactive Power", "var", "reactive_power", "measurement")
publish_discovery_all()
rb_wait_ready(i2c, RB_ADDR)
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27) # primer snapshot
t_prev_ms = time.ticks_ms()
total_wh = 0.0
while True:
time.sleep(60)
# Snapshot + read period snapshot.
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
t_now_ms = time.ticks_ms()
time.sleep_ms(50)
if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
t_prev_ms = time.ticks_ms()
continue
avg_p = rb_read_float_le(i2c, RB_ADDR, 0xDC)
dt_s = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
total_wh += avg_p * dt_s / 3600.0
t_prev_ms = t_now_ms
# Live RT values.
u = rb_read_float_le(i2c, RB_ADDR, 0x86)
i_ = rb_read_float_le(i2c, RB_ADDR, 0x8E)
pf = rb_read_float_le(i2c, RB_ADDR, 0xB2)
q = rb_read_float_le(i2c, RB_ADDR, 0xD0)
freq = rb_read_u8(i2c, RB_ADDR, 0x20)
payload = json.dumps({
"voltage": u,
"current": i_,
"power": avg_p,
"energy": total_wh,
"frequency": freq,
"power_factor": pf,
"apparent_power": u * i_,
"reactive_power": q,
})
mqtt.publish("rbamp/{}/state".format(DEVICE_ID).encode(), payload.encode())
print("Published:", payload)
: utilisez adafruit_minimqtt.MQTT avec un pool de sockets issu de wifi.radio. Les charges utiles de découverte sont construites de la même façon. Voir le guide Adafruit sur MQTT + découverte HA pour le code de connexion.
Exemple 9 — Enregistreur distant sur batterie avec veille profonde
Objectif : un enregistreur extérieur / autonome qui se réveille toutes les 10 minutes, capture une période, publie via MQTT, puis retourne en veille profonde. Consommation moyenne de quelques mA — une cellule Li-ion tient plusieurs mois. Matériel : ESP32 (ou ESP32-S3) + un rbAmp UI1 + petite Li-ion + WiFi. Comptabilité : unidirectionnelle. L'énergie survit à la veille profonde via la mémoire RTC.
from machine import I2C, Pin, RTC, deepsleep
import network, time, struct, ujson as json
from umqtt.simple import MQTTClient
SLEEP_MS = 10 * 60 * 1000 # 10-minute wake interval
RB_ADDR = 0x50
# RTC retained memory layout (with a magic-marker sentinel so garbage RTC RAM
# after a brown-out or watchdog reset is NOT mistaken for valid state):
# uint32 magic == 0xCAFEFEED (4 bytes)
# double total_wh (8 bytes)
# uint32 wake_count (4 bytes)
# uint8 primer_done (1 byte) + 3 bytes pad
#
# NOTE on dt: we do NOT persist a microsecond counter because time.ticks_us()
# is monotonic SINCE BOOT — it resets to 0 on every deep-sleep wake, so
# carrying the previous value across sleep is meaningless. dt is approximated
# by the configured SLEEP_MS interval; for tighter accuracy use machine.RTC()
# .datetime() which DOES survive deep sleep.
_MAGIC = 0xCAFEFEED
_FMT = " timeout_s * 1000:
return None
time.sleep_ms(100)
return wlan
def publish_measurement(wake_count, dt_s, avg_p, total_e):
"""Publish one period sample via MQTT, retained."""
mqtt = MQTTClient("rbamp-remote", "192.168.1.10")
mqtt.connect()
payload = json.dumps({
"wake": wake_count,
"dt_s": round(dt_s, 1),
"avg_p": round(avg_p, 1),
"energy_wh": round(total_e, 3),
})
mqtt.publish(b"rbamp/remote/state", payload.encode(), retain=True)
mqtt.disconnect()
print("Published:", payload)
# ===== Main wake-handler — runs on every wake-up =====
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
total_wh, wake_count, primer_done = _rtc_load()
wake_count += 1
rb_wait_ready(i2c, RB_ADDR)
# First wake-up after a cold boot: primer snapshot only.
if not primer_done:
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
_rtc_save(total_wh, wake_count, 1)
print("Primer done — sleeping until first real period")
deepsleep(SLEEP_MS)
# Subsequent wake-ups: close the period and read its average power.
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
time.sleep_ms(50)
if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
print("WARN: stale snapshot — skipping this cycle")
_rtc_save(total_wh, wake_count, 1)
deepsleep(SLEEP_MS)
avg_p = rb_read_float_le(i2c, RB_ADDR, 0xDC)
# dt approximation: deep sleep + boot ≈ SLEEP_MS. time.ticks_us() resets
# every wake so a stored "previous" value would be meaningless; the
# configured interval is accurate to single-digit-% on the ESP32 RTC.
dt_s = SLEEP_MS / 1000.0
total_wh += avg_p * dt_s / 3600.0
_rtc_save(total_wh, wake_count, 1)
# Publish; fall back gracefully if WiFi is unreachable.
if wifi_connect(timeout_s=8):
try:
publish_measurement(wake_count, dt_s, avg_p, total_wh)
except Exception as e:
print("MQTT failed, value buffered in RTC:", e)
else:
print("WiFi failed — value buffered in RTC, retry next wake")
print("Deep sleep")
deepsleep(SLEEP_MS)
Budget énergétique (typique, ESP32-WROOM) :
- Durée d'éveil par réveil : environ 3 s.
- Courant au réveil : environ 80 mA en moyenne → environ 0.07 mAh par réveil.
- Courant en veille : environ 10 µA (domaines conservés RTC).
- Un réveil toutes les 10 min → environ 10 mAh par jour → une seule batterie Li-ion de 2000 mAh tient environ 6 mois.
: utilisez alarm.time.TimeAlarm(monotonic_time=...) + alarm.exit_and_deep_sleep_until_alarms(alarm) au lieu de machine.deepsleep. Conservez total_wh dans alarm.sleep_memory (un bytearray survit à la veille profonde). La NVM (microcontroller.nvm) survit même à une coupure de courant, mais son usure est limitée.
Exemple 10 — Tarif heures pleines / heures creuses (TOU) avec horloge murale NTP
Objectif : facturer l'énergie selon une grille tarifaire horaire (tarifs différents pour les heures pleines et creuses). L'ESP32 conserve une heure réelle via NTP, répartit chaque période clôturée dans le bon compartiment tarifaire, remet les totaux journaliers à zéro à minuit et publie des charges utiles avec des horodatages ISO. Matériel : ESP32 + un rbAmp UI1 + WiFi. Comptabilité : unidirectionnelle. La logique des compartiments fonctionne sur STD — il suffit de faire passer les deux accumulateurs par cette logique.
from machine import I2C, Pin
import network, ntptime, time, ujson as json
from umqtt.simple import MQTTClient
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
RB_ADDR = 0x50
WIFI_SSID = "ssid"
WIFI_PASS = "password"
MQTT_HOST = "192.168.1.10"
# Local UTC offset in hours. For DST, recompute on roll-over or use a TZ library.
# Example: Central European Summer Time = UTC+2.
TZ_OFFSET_HOURS = 2
# Time-of-use schedule: peak hours [PEAK_START_HOUR .. PEAK_END_HOUR), local time.
PEAK_START_HOUR = 8
PEAK_END_HOUR = 22
def wifi_connect():
wlan = network.WLAN(network.STA_IF); wlan.active(True)
wlan.connect(WIFI_SSID, WIFI_PASS)
while not wlan.isconnected():
time.sleep(0.5)
print("WiFi up:", wlan.ifconfig()[0])
def ntp_sync():
"""Synchronise the on-board RTC with NTP (UTC).
Returns True on success, False on persistent failure. DOES NOT raise —
a TOU meter that crashes when NTP is unreachable is worse than one that
skips bucketing for the current period and retries later.
"""
ntptime.host = "pool.ntp.org"
for _ in range(5):
try:
ntptime.settime()
t = time.gmtime()
print("NTP sync: {:04d}-{:02d}-{:02d} {:02d}:{:02d}:{:02d} UTC".format(*t[:6]))
return True
except Exception as e:
print("NTP retry:", e)
time.sleep(2)
print("WARN: NTP sync failed — tariff bucketing paused until next sync")
return False
def local_time():
"""Return current local time as a 9-tuple struct_time (year, mon, ..., wday, yday)."""
return time.gmtime(time.time() + TZ_OFFSET_HOURS * 3600)
def is_peak_hour(hour):
"""True if `hour` (0..23 local) is inside the peak tariff window.
For schedules that cross midnight (peak 22..6), change to
return hour >= PEAK_START_HOUR or hour < PEAK_END_HOUR
"""
return PEAK_START_HOUR <= hour < PEAK_END_HOUR
def iso_now():
"""Return the current local time as an ISO 8601 string with offset."""
t = local_time()
sign = "+" if TZ_OFFSET_HOURS >= 0 else "-"
return "{:04d}-{:02d}-{:02d}T{:02d}:{:02d}:{:02d}{}{:02d}00".format(
t[0], t[1], t[2], t[3], t[4], t[5], sign, abs(TZ_OFFSET_HOURS))
wifi_connect()
ntp_sync()
mqtt = MQTTClient("rbamp-tou", MQTT_HOST); mqtt.connect()
rb_wait_ready(i2c, RB_ADDR)
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27) # primer snapshot
t_prev_ms = time.ticks_ms()
print("TOU started: peak {:02d}:00..{:02d}:00 local".format(PEAK_START_HOUR, PEAK_END_HOUR))
# Tariff buckets.
today = {"peak_wh": 0.0, "off_peak_wh": 0.0, "yday": -1}
lifetime = {"peak_wh": 0.0, "off_peak_wh": 0.0}
def accumulate(e_wh, tm):
"""Add one period's energy to the right bucket; roll over the day at midnight.
:param e_wh: Wh in this period.
:param tm: local struct_time at the snapshot instant.
"""
yday = tm[7] # struct_time.tm_yday is index 7
if today["yday"] != yday:
if today["yday"] >= 0:
payload = json.dumps({
"yday": today["yday"],
"peak_wh": today["peak_wh"],
"off_peak_wh": today["off_peak_wh"],
"total_wh": today["peak_wh"] + today["off_peak_wh"],
})
mqtt.publish(b"rbamp/tou/day_close", payload.encode(), retain=True)
print("Day closed:", payload)
today["peak_wh"] = 0.0
today["off_peak_wh"] = 0.0
today["yday"] = yday
hour = tm[3] # struct_time.tm_hour is index 3
if is_peak_hour(hour):
today["peak_wh"] += e_wh
lifetime["peak_wh"] += e_wh
else:
today["off_peak_wh"] += e_wh
lifetime["off_peak_wh"] += e_wh
while True:
time.sleep(60)
rb_write_u8(i2c, RB_ADDR, 0x01, 0x27)
t_now_ms = time.ticks_ms()
time.sleep_ms(50)
if (rb_read_u8(i2c, RB_ADDR, 0x07) & 0x01) == 0:
t_prev_ms = time.ticks_ms()
continue
avg_p = rb_read_float_le(i2c, RB_ADDR, 0xDC)
dt_s = time.ticks_diff(t_now_ms, t_prev_ms) / 1000.0
e_wh = avg_p * dt_s / 3600.0
t_prev_ms = t_now_ms
tm = local_time()
accumulate(e_wh, tm)
peak = is_peak_hour(tm[3])
payload = json.dumps({
"ts": iso_now(),
"tariff": "peak" if peak else "off_peak",
"avg_p": round(avg_p, 1),
"period_wh": round(e_wh, 4),
"today_peak_wh": round(today["peak_wh"], 3),
"today_off_peak_wh": round(today["off_peak_wh"], 3),
"life_peak_wh": round(lifetime["peak_wh"], 3),
"life_off_peak_wh": round(lifetime["off_peak_wh"], 3),
})
mqtt.publish(b"rbamp/tou/state", payload.encode())
print(payload)
Notes:
- Le module
timede MicroPython est en UTC sur la plupart des ports — convertissez avectime.gmtime(time.time() + offset_seconds). Pour une gestion complète de l'heure d'été, une petite table de fuseaux ou la bibliothèqueutimezonepeut remplacerTZ_OFFSET_HOURS. - Erreur de frontière : une période de 60 s qui franchit 22:00 est entièrement attribuée aux heures creuses (horodatage à l'instant de la capture). Au plus environ 30 s de mauvaise attribution par jour — négligeable pour la facturation résidentielle.
- Pour la mesure bidirectionnelle STD, appelez
accumulate()deux fois — une fois côté consommation et une fois côté export — et publiez les deux jeux de totaux pointe / heures creuses.
: utilisez adafruit_ntp.NTP(socketpool, server="pool.ntp.org", tz_offset=2) + rtc.RTC().datetime = ntp.datetime pour régler l'horloge système, puis lisez-la via time.localtime(). La logique des compartiments reste identique.
Comparaison des exemples
| # | Complexité | Sortie | MQTT | DRDY | Multi-modules | Bidirectionnel | Persistance | Cas d'usage |
|---|---|---|---|---|---|---|---|---|
| 1 | minimal | REPL | — | — | — | — | — | test de fumée |
| 2 | faible | OLED | — | — | — | — | RAM | compteur encapsulé |
| 3 | faible | REPL | — | — | oui (3) | — | — | surveillance domestique |
| 4 | moyen | — | oui | — | — | — | RAM | par appareil dans HA |
| 5 | moyen | REPL | — | oui | — | oui (maître) | RAM | maison solaire en gamme BASIC |
| 6 | élevé | — | oui | — | oui (3) | oui | RAM | bilan complet du foyer |
| 7 | moyen | REPL + SD | — | oui | — | — | Carte SD | détection d'événements |
| 8 | moyen | — | oui (+disco) | — | — | facultatif | RAM + MQTT | Découverte automatique HA |
| 9 | moyen | — | oui | — | — | — | Mémoire RTC | enregistreur hors réseau / extérieur |
| 10 | moyen | REPL | oui | — | — | facultatif | RAM + MQTT | Heures pleines / heures creuses avec NTP |
Bonnes pratiques
- Vérifiez toujours
DATA_VALID(bit 0 du registre0xCE) après le démarrage etPERIOD_VALID(bit 0 de0x07) après chaqueCMD_LATCH_PERIOD. - Attendez au moins 50 ms après une capture avant de lire l'instantané.
- L'horloge maîtresse fait foi pour les Wh — n'utilisez pas
PERIOD_LATCH_MS(0xEC) pour le calcul de l'énergie. - Pour les configurations multi-modules,
rb_broadcast_latch(i2c, tick)via appel général assure une synchronisation précise. La réception GC est sur option par module (FLEET_CONFIG.bit0, par défaut DÉSACTIVÉE). Repli sur desCMD_LATCH_PERIODséquentiels par module en cas de NACK. - La persistance côté maître est obligatoire pour une comptabilité sur le long terme — rbAmp ne stocke pas les Wh en interne. Utilisez la mémoire RTC (exemple 9), la carte SD (exemple 7) ou les charges utiles MQTT conservées (exemple 6).
- Les gestionnaires d'IRQ MicroPython doivent rester minuscules (lever un drapeau, sans I²C). Effectuez tout le travail I²C dans la boucle principale.
- Pour CircuitPython, préférez
countio.Counteroukeypad.Keyspour les événements de front plutôt que des IRQ définies par l'utilisateur.
Et ensuite
Après avoir parcouru ces dix exemples :
- Pour le paquet de haut niveau
rbamp, voir le tableau des bibliothèques clientes du README. - Pour l'intégration ESPHome (YAML déclaratif), voir
tools/esphome-rbamp/docs/en/. - Pour un environnement SBC plus riche (Raspberry Pi, CPython complet), voir le tableau des bibliothèques clientes du README.
- Pilote Berry Tasmota — reporté (aucune bibliothèque livrée).
- La spécification formelle des registres I²C utilisée ici se trouve dans api-reference.md.