rbAmp
DE
Shop
Docs
Aktualisiert

12 · MicroPython- und CircuitPython-Beispiele

Dieses Kapitel ist das Python-Gegenstück zu arduino-examples.md: dieselben zehn Szenarien, portiert auf MicroPython für ESP32 / RP2040 / ESP8266 / Pyboard, mit CircuitPython-Abweichungen dort, wo sich die beiden Dialekte unterscheiden.

Hinweis

Diese Beispiele sprechen den rbAmp direkt über die rohe I²C-Registerschnittstelle an. Sie sind für native, eingebettete oder anderweitig ressourcenbeschränkte Integrationen gedacht, bei denen direkte Steuerung nötig ist und jedes Byte auf dem Bus zählt.

Für eine bequemere, strukturierte Schnittstelle verwenden Sie die MicroPython-Bibliothek rbamp (siehe Tabelle der Client-Bibliotheken in der README). Die Bibliothek kapselt die Registerdetails hinter einer High-Level-Klasse RbAmp mit benannten Methoden (dev.voltage, dev.latch_period(), dev.read_period_snapshot() usw.), bietet synchrone sowie uasyncio-APIs, einen automatischen Wh-Akkumulator je Kanal, Hilfsfunktionen für Mehrmodul-Aufbauten und die Disziplin aus Wiederholung und Plausibilitätsprüfung nach SPEC §B.5 für ESP32-Portierungen über MachineI2CBackend(retry_attempts=…). Dasselbe Paket läuft unverändert auf CPython — siehe Tabelle der Client-Bibliotheken in der README. Die meisten Projekte sollten mit der Bibliothek beginnen und nur bei Bedarf auf die Roh-API zurückgreifen.

MicroPython vs. CircuitPython — Kurzübersicht

Die Python-Sprache ist dieselbe; die Module für den Gerätezugriff unterscheiden sich. Die Tabelle unten ordnet jedes in den Beispielen verwendete Konzept dem entsprechenden Modul bzw. der Klasse in jedem Dialekt zu.

Konzept MicroPython CircuitPython
I2C-Bus 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)
Einzelbyte-Lesen i2c.readfrom_mem(addr, reg, 1)[0] with i2c_device: i2c_device.write_then_readinto(bytes([reg]), buf, in_end=1) (mit adafruit_bus_device.I2CDevice)
Einzelbyte-Schreiben i2c.writeto_mem(addr, reg, bytes([val])) i2c_device.write(bytes([reg, val]))
GPIO-Eingang + 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)
oder keypad.Keys([board.D15], ...)
Schlafen (Sek. / ms) time.sleep(s) / time.sleep_ms(ms) time.sleep(s) (kein sleep_ms)
Monoton ms / µs time.ticks_ms(), time.ticks_us(), time.ticks_diff(a, b) time.monotonic_ns() / time.monotonic() (kein ticks_diff)
WiFi import network
wlan = network.WLAN(network.STA_IF)
import wifi
wifi.radio.connect(ssid, pwd) (ESP32-S2/S3/C3 mit nativem CP)
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="...")
Tiefschlaf import machine; machine.deepsleep(ms) import alarm; alarm.exit_and_deep_sleep_until_alarms(time_alarm)
RTC-Retention-Speicher machine.RTC().memory(buf) import alarm; alarm.sleep_memory[...]
Asynchron import uasyncio as asyncio import asyncio (CircuitPython 8+)

Jedes Beispiel unten ist in MicroPython geschrieben. Wo sich das CircuitPython-Pendant um mehr als eine einzige Import-Zeile unterscheidet, ist ein eigener Block „CircuitPython-Abweichungen“ angegeben.

Inhaltsverzeichnis der Beispiele

# Titel Schwierigkeit Ausgang MQTT DRDY Mehrere Module Bidirektional Anwendungsfall
1 Schnelles Lesen minimal REPL — — — — Schnelltest
2 60-Sekunden-Energiezähler auf OLED niedrig SSD1306 — — — — Gekapselter Wh-Zähler
3 Monitor für mehrere Module niedrig REPL — — ja (3) — Gesamthausüberwachung
4 Energiemonitor pro Gerät (UI3) mittel — ja — — — Unterzählung in HA
5 Bidirektional auf dem Master für ein BASIC-Modul mittel REPL — ja — ja (Master) Solar-Haushalt auf BASIC-Stufe
6 Gesamte Hausbilanz hoch — ja — ja (3) ja Gesamte Hausbilanz
7 Erkennung von Netzereignissen mittel REPL + SD — ja — — Ereignisprotokoll der Geräte
8 MQTT-Publisher mit HA-Auto-Discovery mittel — ja (+disco) — — optional Sofort einsatzbereite HA-Integration
9 Batteriebetriebener Remote-Logger mit Tiefschlaf mittel — ja — — — Messung für den Außen- bzw. Inselbetrieb
10 Zeittarif (TOU) mit NTP-Wanduhr mittel REPL ja — — optional Energiemessung mit Spitzen- / Nebenzeit-Tarif

Gemeinsamer Header für alle Beispiele

Jedes Beispiel setzt voraus, dass diese Hilfsfunktionen in derselben .py-Datei vorhanden sind (oder aus einer helpers.py importiert werden). Um Platz zu sparen, wird der Block in jedem Sketch nicht wiederholt.

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

CircuitPython-Abweichungen — gemeinsamer Header

CircuitPython verwendet adafruit_bus_device.i2c_device.I2CDevice (Wrapper je Slave) und hat kein time.ticks_ms. Entsprechende Hilfsfunktionen:

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")

Beispiel 1 — Schnelles Lesen (minimal)

Ziel: U, I, P, PF einmal pro Sekunde in einer REPL ausgeben. Hardware: ESP32 / RP2040 / Pico W + ein 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)

CircuitPython-Abweichung

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)

Beispiel 2 — 60-Sekunden-Energiezähler auf OLED

Ziel: Wh-Zähler einmal pro Minute aktualisiert, angezeigt auf einem 128×64-SSD1306. Hardware: ESP32 + rbAmp + SSD1306-OLED am selben Bus. Bilanzierung: unidirektional (BASIC-Stufe). Bibliothek: ssd1306.py aus den MicroPython-Beispielen (ein Standardtreiber in einer Datei).

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))
CircuitPython-Abweichung

: verwenden Sie adafruit_ssd1306 (Variante displayio oder framebuf). Der OLED-Konstruktor unterscheidet sich, der Rest der Schleife bleibt jedoch unverändert — ersetzen Sie die rb_*-Aufrufe durch die cp_*-Helfer und verwenden Sie time.monotonic() für dt_s.


Beispiel 3 — Überwachung mehrerer Module

Ziel: drei Module abfragen (Hauptzuleitung, Warmwasserbereiter, Klimaanlage) und die Summe ausgeben. Hardware: ESP32 + 3 × rbAmp UI1 bei 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)

Beispiel 4 — Energiemonitor pro Gerät (UI3)

Ziel: ein UI3-Modul mit drei Stromzangen an drei verschiedenen Lasten auf derselben Phase. Unabhängige Wh-Zähler je Last, jede Minute per MQTT veröffentlicht. Hardware: ESP32 + 1 × rbAmp UI3. Bibliothek: umqtt.simple (MicroPython) oder umqtt.robust für automatische Wiederverbindung.

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])
CircuitPython-Abweichung

: ersetzen Sie umqtt.simple.MQTTClient durch adafruit_minimqtt.MQTT(...) (benötigt einen socket_pool und einen ssl_context — siehe Adafruits WLAN-Anleitung). Die Messlogik bleibt unverändert.


Beispiel 5 — Bidirektional auf dem Master für ein BASIC-Modul

Ziel: bidirektionale Bilanzierung auf dem Master, während die Firmware des Moduls BASIC ist (der Periodenakkumulator klemmt negative Messwerte). Bei jeder DRDY-Flanke wird das RT-P_real gelesen und in Verbrauch und Einspeisung aufgeteilt. Hardware: ESP32 + rbAmp UI1 an einer Last mit Solarwechselrichter + DRDY an einem 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))
CircuitPython-Abweichung

: CircuitPython rät generell von benutzerdefinierten GPIO-IRQs ab. Verwenden Sie countio.Counter(board.D15, edge=countio.Edge.FALL) und fragen Sie dessen count aus der Hauptschleife ab, oder nutzen Sie keypad.Keys(...) für Flankenereignisse. Die Akkumulatorlogik bleibt identisch.


Beispiel 6 — Energiebilanz des Hauses

Ziel: ein vollständiges Bilanz-Dashboard. Drei Module:

  • rbAmp #1 am Hauptnetz (STD — bidirektional)
  • rbAmp #2 am Ausgang des Solarwechselrichters
  • rbAmp #3 UI3 an drei großen Lasten (Wärmepumpe, Klimaanlage, E-Auto)

Der Master berechnet total_consumed = solar_self_used + grid_consumed und solar_generated = solar_self_used + grid_exported. Hardware: ESP32 + 3 × rbAmp + WLAN + 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) stellt sicher, dass alle drei Module im selben Moment einen Snapshot erstellen — entscheidend für einen genauen Saldo. Der GC-Empfang ist optional (FLEET_CONFIG.bit0, Standard AUS, siehe Kapitel 02). Bei NACK fallen Sie auf einen sequentiellen Snapshot je Modul zurück (Versatz ~1 ms je Modul bei 50 kHz).
  • solar_self_used = solar_total − grid_exported; auf null begrenzen, um Messrauschen zu absorbieren.

Beispiel 7 — Erkennung von Netzereignissen

Ziel: bei jeder DRDY-Flanke die momentane P mit einem EMA vergleichen und signifikante Abweichungen auf einer SD-Karte protokollieren. Hardware: ESP32 + rbAmp + SD-Karte (SPI-gesteuert, z. B. über den MicroPython-Treiber sdcard.py). Anwendungsfall: automatische Erkennung großer Lastereignisse (Mikrowelle, Klimaanlage, Wasserkocher).

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
CircuitPython-Abweichung

: verwenden Sie adafruit_sdcard.SDCard + storage.mount(VfsFat(sdcard), "/sd"). Ersetzen Sie die IRQ durch countio.Counter(board.D15, edge=countio.Edge.FALL), das aus der Hauptschleife abgefragt wird.


Beispiel 8 — MQTT-Publisher mit Home-Assistant-Auto-Discovery

Ziel: eine sofort einsatzbereite HA-Integration. Der ESP32 verbindet sich mit WLAN und einem MQTT-Broker, veröffentlicht HA-Auto-Discovery-Konfigurationen (sodass die Entitäten ohne YAML erscheinen) und sendet jede Minute einen JSON-Status. Hardware: ESP32 + ein rbAmp UI1 + WLAN-Netz mit MQTT-Broker. Buchhaltung: unidirektional.

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)
CircuitPython-Abweichung

: verwenden Sie adafruit_minimqtt.MQTT mit einem Socket-Pool aus wifi.radio. Die Discovery-Payloads werden genauso aufgebaut. Den Socket-Grundaufbau finden Sie im MQTT- und HA-Discovery-Leitfaden von Adafruit.


Beispiel 9 — Batteriebetriebener Remote-Logger mit Tiefschlaf

Ziel: ein Logger für den Außen- bzw. Inselbetrieb, der alle 10 Minuten aufwacht, einen Zeitraum erfasst, per MQTT veröffentlicht und dann wieder in den Tiefschlaf geht. Die durchschnittliche Stromaufnahme liegt bei wenigen mA — eine Li-Ion-Zelle hält Monate. Hardware: ESP32 (oder ESP32-S3) + ein rbAmp UI1 + kleiner Li-Ion-Akku + Wi-Fi. Bilanzierung: unidirektional. Der Energiezählerstand bleibt über den Tiefschlaf im RTC-Speicher erhalten.

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)

Energiebudget (typisch, ESP32-WROOM):

  • Wachzeit pro Aufwachen: ~3 s.
  • Wachstrom: ~80 mA im Mittel → ~0.07 mAh pro Aufwachvorgang.
  • Ruhestrom: ~10 µA (RTC-Retention-Bereiche).
  • Ein Aufwachen alle 10 Minuten → ~10 mAh/Tag → ein einzelner 2000-mAh-Li-Ion hält ~6 Monate.
CircuitPython-Abweichung

: verwenden Sie alarm.time.TimeAlarm(monotonic_time=...) + alarm.exit_and_deep_sleep_until_alarms(alarm) statt machine.deepsleep. Speichern Sie total_wh in alarm.sleep_memory (ein bytearray übersteht den Tiefschlaf). NVM (microcontroller.nvm) übersteht sogar einen Stromausfall, ist aber durch Verschleiß begrenzt.


Beispiel 10 — Zeittarif (TOU) mit NTP-Wanduhr

Ziel: Energie nach einem Zeittarif abrechnen (unterschiedliche Preise für Spitzen- und Nebenzeiten). Der ESP32 führt über NTP eine echte Uhrzeit, ordnet jeden abgeschlossenen Zeitraum dem passenden Tarifblock zu, setzt die Tagessummen um Mitternacht zurück und veröffentlicht Payloads mit ISO-Zeitstempeln. Hardware: ESP32 + ein rbAmp UI1 + WiFi. Buchhaltung: unidirektional. Die Tarifblock-Logik funktioniert auch am STD — speisen Sie einfach beide Akkumulatoren hindurch.

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:

  • Das Python-Modul time ist auf den meisten Portierungen UTC-basiert — rechnen Sie mit time.gmtime(time.time() + offset_seconds) um. Für die volle Sommerzeitbehandlung kann eine kleine TZ-Tabelle oder die Bibliothek utimezone TZ_OFFSET_HOURS ersetzen.
  • Grenzfehler: Ein 60-s-Zeitraum, der 22:00 überschreitet, wird vollständig der Nebenzeit zugeordnet (Zeitstempel zum Erfassungszeitpunkt). Höchstens ~30 s Fehlzuordnung pro Tag — für die Abrechnung eines Haushaltstarifs vernachlässigbar.
  • Für bidirektionale STD-Messung rufen Sie accumulate() zweimal auf — einmal für den Verbrauchszweig und einmal für den Einspeisezweig — und veröffentlichen beide Summen aus Spitzen- und Nebenzeit.
CircuitPython-Abweichung

: verwenden Sie adafruit_ntp.NTP(socketpool, server="pool.ntp.org", tz_offset=2) + rtc.RTC().datetime = ntp.datetime, um die Systemuhr zu setzen, und lesen Sie sie dann über time.localtime(). Die Bucket-Logik bleibt identisch.


Vergleich der Beispiele

# Komplexität Ausgang MQTT DRDY Mehrere Module Bidirektional Persistenz Anwendungsfall
1 minimal REPL — — — — — Rauchtest
2 niedrig OLED — — — — RAM Zählerkasten
3 niedrig REPL — — ja (3) — — Heimüberwachung
4 mittel — ja — — — RAM pro Gerät in HA
5 mittel REPL — ja — ja (Master) RAM Solar-Haushalt auf BASIC-Stufe
6 hoch — ja — ja (3) ja RAM gesamte Hausbilanz
7 mittel REPL + SD — ja — — SD-Karte Ereigniserkennung
8 mittel — ja (+disco) — — optional RAM + MQTT HA-Auto-Discovery
9 mittel — ja — — — RTC-Speicher Logger für den Außen- bzw. Inselbetrieb
10 mittel REPL ja — — optional RAM + MQTT TOU Spitze/Nebenzeit mit NTP

Bewährte Verfahren

  • Prüfen Sie nach dem Booten immer DATA_VALID (Bit 0 des Registers 0xCE) und nach jedem CMD_LATCH_PERIOD PERIOD_VALID (Bit 0 von 0x07).
  • Warten Sie nach einem Snapshot mindestens 50 ms, bevor Sie ihn auslesen.
  • Der Master-Takt ist maßgeblich für Wh — verwenden Sie PERIOD_LATCH_MS (0xEC) nicht für die Energieberechnung.
  • Für Mehrmodul-Aufbauten liefert rb_broadcast_latch(i2c, tick) über General Call präzise Synchronisation. Der GC-Empfang ist optional je Modul (FLEET_CONFIG.bit0, Standard AUS). Bei NACK fallen Sie auf sequenzielle CMD_LATCH_PERIOD-Aufrufe je Modul zurück.
  • Persistenz auf dem Master ist zwingend für die Langzeitbuchhaltung — rbAmp speichert Wh nicht intern. Verwenden Sie RTC-Speicher (Beispiel 9), SD-Karte (Beispiel 7) oder MQTT-retained-Payloads (Beispiel 6).
  • MicroPython-IRQ-Handler müssen winzig sein (nur ein Flag setzen, kein I²C). Führen Sie alle I²C-Arbeiten in der Hauptschleife aus.
  • Für CircuitPython bevorzugen Sie countio.Counter oder keypad.Keys für Flankenereignisse statt eigener IRQs.

Wie geht es weiter

Nachdem Sie diese zehn Beispiele durchgearbeitet haben:

  • Zum High-Level-Paket rbamp siehe die Tabelle der Client-Bibliotheken in der README.
  • Zur ESPHome-Integration (deklaratives YAML) siehe tools/esphome-rbamp/docs/en/.
  • Für eine umfangreichere SBC-Umgebung (Raspberry Pi, vollständiges CPython) siehe die Tabelle der Client-Bibliotheken in der README.
  • Tasmota-Berry-Treiber — zurückgestellt (keine Bibliothek ausgeliefert).
  • Die hier verwendete formale I²C-Registerspezifikation steht in api-reference.md.