rbAmp
FR
Boutique
Docs
Mis à jour le

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.

Remarque

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, Pin
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50000)
import board, busio
i2c = 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, countio
btn = 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 network
wlan = network.WLAN(network.STA_IF)
import wifi
wifi.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.

Python
"""
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 :

Python
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.

Python
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

Python
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).

Python
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))
Différences CircuitPython

: 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.

Python
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.

Python
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])
Différences CircuitPython

: 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.

Python
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))
Différences CircuitPython

: 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.

Python
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).

Python
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
Différences CircuitPython

: 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.

Python
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)
Différences CircuitPython

: 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.

Python
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.
Différences CircuitPython

: 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.

Python
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 time de MicroPython est en UTC sur la plupart des ports — convertissez avec time.gmtime(time.time() + offset_seconds). Pour une gestion complète de l'heure d'été, une petite table de fuseaux ou la bibliothèque utimezone peut remplacer TZ_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.
Différences CircuitPython

: 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 registre 0xCE) après le démarrage et PERIOD_VALID (bit 0 de 0x07) après chaque CMD_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 des CMD_LATCH_PERIOD sé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.Counter ou keypad.Keys pour 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.