rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten (Edit on GitHub)

Beispiele

Dieses Kapitel führt durch 11 Szenarien (10 in der Tabelle unten plus Szenario 11) — vom minimalen „Hello World“ bis zum Produktionsbetrieb. Die meisten Szenarien haben parallele Implementierungen in MicroPython (unter examples_upy/) und CPython (unter examples_cpython/). Der Code unten ist eine Verdichtung der Kernlogik, kein vollständiges Skript; die vollständigen Versionen liegen in den entsprechenden Beispieldateien.

# Szenario MicroPython CPython
1 Schnelles Lesen 01_quick_read.py 01_quick_read.py
2 Periodenzähler + lokale Anzeige 02_oled_period.py 02_period_meter.py
3 Überwachung von 3 Modulen an einem Bus 03_multi_module.py 03_multi_module_broadcast.py
4 UI3 + MQTT pro Kanal 04_mqtt.py 04_mqtt_publisher.py
5 Bidirektionale Messung auf Masterseite 07_bidirectional_energy.py 05_bidirectional_energy.py
6 Energiebilanz des gesamten Hauses (mehrere Module + MQTT) 08_home_energy_balance.py 07_home_energy_balance.py
7 Protokollierung der Ereigniserkennung (EMA) 09_event_detection_logger.py keine Datei
8 Lokaler rotierender Logger keine Datei 08_rotating_file_logger.py
9 Batteriebetriebener Deep-Sleep-Logger 06_deep_sleep.py (nicht zutreffend)
10 Asynchrones Streaming über stream_period 05_async_streaming.py keine Datei (Code in Szenario 10)
Hinweis

Alle Szenarien setzen voraus, dass Sensorklasse und CT-Modell bereits über dev.set_sensor_class() + dev.set_ct_model() konfiguriert sind (siehe 05 · Schnellstart, Schritt 4). Das geschieht einmalig bei der Installation — die Einstellungen werden im Flash des Moduls gespeichert und überstehen einen Reset.


Szenario 1 — Schnelllesezugriff

Ziel: U / I / P / PF / Frequenz einmal pro Sekunde ausgeben. Das ist dasselbe „Hello World“, das Sie in 05 · Schnellstart geschrieben haben, nur mit dev.read_all() — einem Einzellesevorgang des gesamten RT-Blocks in eine RbAmpSnapshot-Struktur.

CPython-Version

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

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

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

MicroPython-Version

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

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

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

Was auf dem Bus geschieht: dev.read_all() auf einem UI3 führt etwa 53 Byte-Transaktionen aus (13 Gleitkommawerte × 4 Byte + 1 Frequenzbyte). Bei 50 kHz mit Reserve für Wiederholungen liegt das in der Größenordnung von 25–30 ms. Wenn Sie nicht jeden Wert brauchen, verwenden Sie die Zugriffe pro Eigenschaft (dev.voltage, dev.read_current(ch)).


Szenario 2 — Periodenzähler + lokale Anzeige

Ziel: ein Wh-Zähler, einmal pro Minute aktualisiert, auf einer lokalen Anzeige. Auf MicroPython ein SSD1306-OLED am selben I²C-Bus. Auf CPython Textausgabe auf stdout (Sie können ein Zeichen-LCD über GPIO anschließen oder eine Webseite verwenden — siehe Szenario 6).

MicroPython-Version (SSD1306-OLED)

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

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

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

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

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

CPython-Version (Periodenzähler, ohne Anzeige)

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

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

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

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

Umgang mit veralteten Snapshots. dev.read_period_snapshot() löst RbAmpStaleError aus, wenn das Modul bis zum Lesezeitpunkt keinen neuen Snapshot vorbereitet hat. Das Paket behält den vorherigen Zeitstempel, sodass der nächste erfolgreiche Snapshot das gesamte Intervall abdeckt und die Wh exakt bleiben. Ein übliches try/except-Muster in Python.


Szenario 3 — Überwachung von 3 Modulen an einem Bus

Ziel: 3 Module an den Adressen 0x50 / 0x51 / 0x52 abfragen, kohärent als Snapshot erfassen, sodass sich ihre Leistungen pro Kanal auf derselben Netzperiode summieren.

Kohärenter Snapshot

Ein General-Call-Frame (A5 27 ) veranlasst jedes Modul, das sich mit fleet.enable_gc_all() angemeldet hat, seinen Snapshot zu nehmen — Flotten-Versatz unter 10 µs, damit die Summen zusammenpassen. fleet.gc_latch() sendet den Frame und gibt den Broadcast-tick zurück; fleet.check_sync() liest den bezeugten Tick jedes Moduls zurück, sodass Sie ein Modul markieren können, das den Frame verpasst hat. (Auf der Firmware v1.0/v1.1 war General-Call nicht verfügbar, und dieses Szenario fiel auf sequentielle Snapshots je Gerät zurück.) Siehe 09 · API-Referenz für RbAmpFleet.

CPython-Version

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

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

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

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

    while True:
        time.sleep(60)

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

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

MicroPython-Version

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

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

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

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

while True:
    time.sleep(60)

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

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

Szenario 4 — UI3 + MQTT pro Kanal

Ziel: Ein UI3-Modul mit 3 CT-Zangen an drei unabhängigen Leitungen. Wh-Zähler pro Kanal, einmal pro Minute an MQTT veröffentlicht. Zeigt, dass dev.energy.wh(ch) auf jedem Kanal unabhängig arbeitet — kein manuelles Array total_wh[3] auf der Masterseite nötig.

CPython (über paho-mqtt; Installation mit pip install paho-mqtt)

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

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

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

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

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

MicroPython (über umqtt.simple)

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

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

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

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

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

Unter MicroPython ist umqtt.simple ein synchroner, blockierender Client. Für eine asynchrone Variante verwenden Sie mqtt_as (ein asyncio-MQTT-Client) — siehe auch Szenario 10.

Für vollständiges HA-Auto-Discovery auf Basis dieses Musters siehe 07 · DIY-Integrationen.


Szenario 5 — Bidirektionale Messung auf Masterseite

Ziel: die vorzeichenbehaftete Momentanleistung in Bruttoverbrauch und Bruttoexport aufteilen. Verwenden Sie dieses Muster auf der BASIC-Modulreihe, wo die Firmware negative Werte in snap.avg_p[ch] (periodengemittelte Leistung) kappt — samplen Sie dev.read_power(0) (Momentanleistung, auf allen Modulreihen vorzeichenbehaftet) mit 10 Hz auf der Masterseite und sortieren Sie die Werte selbst.

CPython-Version

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

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

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

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

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

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

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

MicroPython-Version

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

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

    while True:
        time.sleep_ms(100)

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

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

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

Bei einem STANDARD-Modul (STD) funktionieren die Periodenaufrufe unverändert; die Energie ist netto (Export wird abgezogen). Die eigenen Bezugs- und Einspeisezähler des Moduls stehen in read_std_energy() (Szenario 11). Diese Aufteilung auf dem Master ist nur bei BASIC-Modulen nötig, um Bezug brutto und Einspeisung brutto getrennt auszuweisen.


Szenario 6 — Energiebilanz des gesamten Hauses

Ziel: 3 Module — Netz (bidirektional), Solar (nur Erzeugung), Lasten (UI3 für einzelne Geräte). Ein kombiniertes Dashboard wird einmal pro Minute veröffentlicht.

(Benötigt pip install paho-mqtt.)

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

GC_GROUP = 0

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

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

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

    while True:
        time.sleep(60)

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

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

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

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

Auf BASIC-Modulen wird Export von energy.wh() nicht gezählt, daher sind die Werte solar und mains oben nur Verbrauch. Für eine explizite Trennung von Bruttoverbrauch und Bruttoexport am Netz kombinieren Sie dies mit dem Muster aus Szenario 5 (eine eigene 10-Hz-Schleife über mains.read_power(0) in einem Hintergrund-threading.Thread auf CPython oder uasyncio.create_task auf MicroPython).


Szenario 7 — Protokollierung von Ereignissen (EMA)

Ziel: Bei jedem 100-ms-RT-Fenster die momentane Leistung mit einem exponentiellen gleitenden Mittelwert vergleichen. Signifikante Abweichungen protokollieren — Lasten wie Mikrowelle, Wasserkocher oder Haartrockner „erscheinen“ im Protokoll als Ein- bzw. Ausschaltereignisse.

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

EMA_ALPHA = 0.05
EVENT_THRESHOLD_W = 200.0

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

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

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

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

Auf MicroPython wenden Sie dieselben Ersetzungen an: time.sleep → time.sleep_ms und time.time() → time.time() (auf den meisten Ports verfügbar) oder time.ticks_ms().

Kombinieren Sie dies mit der MQTT-Veröffentlichung aus Szenario 4 für Automationen auf HA-Seite.


Szenario 8 — Lokaler rotierender Logger (CPython)

Ziel: einen Periodensnapshot einmal pro Minute über den Standard-logging.handlers.RotatingFileHandler in eine rotierende CSV-Datei schreiben. Nützlich für eigenständige Installationen ohne WiFi / MQTT oder als Puffer für verzögerte Cloud-Synchronisation.

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

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

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

Auf MicroPython ist das Standardmodul logging.handlers nicht verfügbar — für ein lokales Log verwenden Sie ein einfaches with open("log.csv", "a") plus manuelle Rotation über os.stat() + os.rename(). Das vollständige Beispiel steht in examples_upy/09_event_detection_logger.py.

Für verzögerte Cloud-Synchronisation (lokal protokollieren, einmal pro Stunde senden) siehe den Abschnitt „Hybrid: lokale Speicherung + Sync“ in 08 · Cloud-Integrationen.


Szenario 9 — batteriebetriebener Deep-Sleep-Logger (nur MicroPython)

Ziel: ein ESP32 (MicroPython) wacht alle 10 Minuten auf, nimmt einen einzelnen Periodensnapshot, veröffentlicht per WiFi+MQTT und geht zurück in den Deep Sleep. Die Energie wird über RTC-Speicher über die Schlafzyklen hinweg erhalten.

Sicherheit

⚠ Wichtiger Hinweis zu Deep Sleep und Firmware v1.0/v1.1. Bei der aktuellen Firmware startet dev.begin() einen CMD_LATCH_PERIOD-Primer, der den Periodenakkumulator der Firmware zurücksetzt. Das bedeutet: Nach dem Aufwachen aus Deep Sleep können Sie nicht einfach read_period_snapshot() aufrufen — dieser Aufruf würde einen weiteren Snapshot nehmen und nahezu null liefern, da nur die ~50 ms seit dem Primer abgedeckt sind. Das richtige Muster unten verwendet skip_latch=True, um die während des Schlafintervalls aufgelaufenen Daten zu lesen, und die bekannte Schlafdauer (machine.deepsleep(SLEEP_MS)) als dt — time.ticks_ms() nach dem Aufwachen kann eine unzuverlässige Quelle sein.

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

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

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

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

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

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

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

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

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

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

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

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

    save_state(RTC_MAGIC, rtc_total_wh, primer_done=True)

machine.deepsleep(SLEEP_MS)

Das vollständige Sketch (mit WiFi-Einrichtung, MQTT-Veröffentlichung, RTC-Magic-Marker-Schutz) steht in examples_upy/06_deep_sleep.py.

Energiebudget (ESP32-WROOM an einem Li-Ion mit 2000 mAh, 10-Minuten-Intervall):

  • Aktiver Zyklus: ~3 s (WiFi + MQTT + I²C) bei ~80 mA → ~0.07 mAh pro Wake
  • Schlaf: ~10 µA (RTC + erhaltene Domänen)
  • ~10 mAh pro Tag → 2000 mAh reichen etwa 6 Monate

CPython-Hosts (Raspberry Pi usw.) laufen typischerweise 24/7 an einer Stromversorgung — Deep Sleep greift hier nicht. Für CPython im Batteriebetrieb siehe den Abschnitt zu Stromverbrauch und dem systemd-Suspend in 08 · Cloud-Integrationen.


Szenario 10 — Asynchrones Streaming über stream_period (nur in Python verfügbar)

Ziel: Integration in eine bestehende asyncio- / uasyncio-Event-Loop. Das Paket stellt einen asynchronen Generator dev.stream_period(interval_s=...) bereit, der den periodischen Snapshot samt automatischer Behandlung veralteter Werte kapselt.

CPython (über asyncio + paho-mqtt-asyncio, oder flach)

Python
import asyncio
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass

async def main():
    with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
        # Once per minute, skip_stale=True (default) — stale snapshots are
        # automatically skipped without raising RbAmpStaleError
        async for snap in dev.stream_period(interval_s=60.0):
            print(f"P={snap.avg_p[0]:.2f} W,  Wh={dev.energy.wh(0):.4f}")

asyncio.run(main())

MicroPython (über uasyncio)

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

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

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

asyncio.run(main())

Parameter von stream_period(interval_s=, skip_stale=):

  • interval_s — der Zeitraum zwischen Snapshots (empfohlen ≥ 30 s)
  • skip_stale=True (Standard) — veraltete Snapshots werden automatisch übersprungen; der Generator rückt einfach zum nächsten Intervall vor

  • skip_stale=False — veraltete Snapshots werden mit snap.valid=False geliefert, und der Aufrufer entscheidet, was damit geschieht

Vollständige Beispiele — examples_upy/05_async_streaming.py (MicroPython) und das asyncio-Gegenstück in den CPython-Beispielen.


Szenario 11 — STD-Energie auf dem Gerät (CPython)

Ziel: Bei einem STANDARD-Modul (STD) die eigenen Lebensdauer-Energiezähler des Moduls auslesen und melden, was in jedem Intervall verbraucht wurde. Für dieses Szenario gibt es keine eigene Beispieldatei; der Code unten ist vollständig.

Hinweis

Die Energiemessung auf dem Gerät wurde auf CPython (smbus2) validiert. Der 16-Bit-Pfad für MicroPython ist implementiert, aber noch nicht an Hardware validiert — für dieses Szenario bitte CPython verwenden.

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

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

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

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

std_energy_delta() ist bei einem Stromausfall sicher: Ein Zähler, der etwas niedriger zurückkommt, wird als Zuwachs null gewertet. Werte pro Kanal stehen in now.ch_import_uwh[ch] / ch_export_uwh[ch] für ch < now.channels.

Die Periodenaufrufe auf einem STD-Modul

Die Periodenaufrufe aus Szenario 2 funktionieren auf einem STD-Modul wie auf BASIC; die Energie ist netto (Export wird abgezogen):

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

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

begin() wählt die Periodenquelle nach dem, was das Modul meldet: seine Energiezähler (die Periode ist die Differenz zweier Messwerte; es wird kein Latch-Befehl gesendet) oder bei einem Modul nur mit Latch-Bänken die Latch-Bank 0. Latch-Bänke sind auch direkt verfügbar — siehe „Latch-Bänke“ in 09 · API-Referenz.


Übersichtstabelle der Szenarien

# LOC Laufzeit I²C-Bus Periode? DRDY? MQTT? Persistenz
1 ~25 beide dediziert nein nein nein nein
2 ~35 beide (OLED auf uPy) gemeinsam mit OLED (uPy) ja nein nein RAM
3 ~50 beide gemeinsam, 3 Module ja nein nein RAM
4 ~50 beide dediziert ja nein ja retained MQTT
5 ~40 beide dediziert nein (RT) nein nein RAM (vom Master verwaltet)
6 ~60 beide gemeinsam, 3 Module ja nein ja retained MQTT
7 ~40 beide dediziert nein (RT) nein nein RAM
8 ~30 CPython dediziert ja nein nein Datei des rotierenden Logs
9 ~50 nur MicroPython dediziert ja nein ja RTC-Speicher + MQTT
10 ~25 beides (asyncio/uasyncio) dediziert ja nein (optional) RAM
11 ~20 CPython (STD-Modul) dediziert nein (im Gerät) nein nein Lebensdauer-Zähler des Moduls

Produktiver Einsatz (nur CPython)

Für einen 24/7-Dauerbetrieb auf einem Linux-SBC wird ein systemd-Dienst empfohlen. Das vollständige Beispiel steht in examples_cpython/10_systemd_service.py (es enthält einen Helfer --install, der die Unit-Datei /etc/systemd/system/rbamp.service erzeugt).

Grundstruktur:

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

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

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

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

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

log.info("rbAmp daemon stopped")

Und das Gerät selbst:

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

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

[Install]
WantedBy=multi-user.target

Zum Starten: sudo systemctl enable --now rbamp. Logs: journalctl -u rbamp -f.

Was als Nächstes kommt


← Schnellstart | Inhalt | DIY-Integrationen →


Quelle & Probleme: rb-amp/rbamp-python · diese Seite im Repository: docs/06_examples.md


Quelle & Probleme: rb-amp/rbamp-python · diese Seite im Repository: docs/06_examples.md (v1.6.1)