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

01 · Überblick

rbAmp-Signalkette: Sensor → Modul → I²C → Master → Cloud / Home Assistant

Was rbAmp ist

rbAmp ist ein kompaktes Hardwaremodul zur präzisen Messung von Netzwechselstromparametern über die I²C-Schnittstelle. Es basiert auf einem Mikrocontroller mit integriertem, galvanisch getrenntem Analogfrontend und Werkskalibrierung im Flash.

Aus Sicht des Integrators verhält sich das Modul wie ein Standard-I²C-Slave: Sie erzeugen RbAmp(bus, 0x50), rufen dev.begin() auf und erhalten einsatzbereite Werte über Eigenschaften und Methoden. Derselbe Quellcode läuft auf MicroPython (mit machine.I2C) und auf CPython (mit smbus2) — das Backend wird automatisch anhand des Typs des Bus-Objekts gewählt.

In dieser Dokumentation verwendete Begriffe

  • Modulreihe — BASIC oder STANDARD (STD): die Produktreihe des Moduls (siehe 02).
  • Variante — UI1, UI2, UI3, I1, I2, I3 (und UI5/UI7): wie viele Stromkanäle vorhanden sind und ob das Modul einen Spannungseingang hat.
  • Firmware-Version / Version des Modul-Images — die Software im Modul; einige STD-Aufrufe brauchen ein hinreichend aktuelles Image.
  • RT-Messwert — ein Momentanwert (Spannung, Strom, Leistung), den das Modul alle 100 ms aktualisiert.
  • Periode / Snapshot — ein Snapshot friert die Summen der bisherigen Periode ein und startet die nächste; ein Periodensnapshot ist das eingefrorene Ergebnis (mittlere Leistung je Kanal).
  • Veralteter Snapshot — das Modul hatte keinen frischen Snapshot bereit; die Bibliothek löst RbAmpStaleError aus, und der nächste gültige Snapshot deckt das gesamte Intervall ab.
  • Primer — der erste Snapshot, den begin() nimmt; er verwirft alles, was seit dem Einschalten aufgelaufen ist.
  • GC (General Call) — ein Broadcast-I²C-Frame, der mehrere Module veranlasst, im selben Augenblick ihren Snapshot zu nehmen.
  • DRDY — optionaler Pin, der etwa alle 100 ms pulst, sobald neue RT-Daten bereitstehen.

Ein Modul oder viele

Ein Modul oder viele: Beginnen Sie mit einem RbAmp; verwenden Sie RbAmpFleet für mehrere. Das Python-Paket rbamp arbeitet mit einem einzelnen Modul und auch mit einer Gruppe von Modulen an einem I²C-Bus. Das kanonische Mehrmodul-Szenario ist ein Master-Modul an der Netzeinspeisung plus N Module an einzelnen Lasten, alle an einem Bus, gesteuert von einem einzigen ESP32 / RPi / SBC. Die Bibliothek stellt dafür die Klasse RbAmpFleet bereit — ein einziges Objekt, über das Sie den Bus scannen, alle Module in einem Aufruf abfragen, Gesamtleistung und die Bilanz „Einspeisung − Σ(Verbraucher)“ erhalten, Fehler jedes Moduls abfangen und bei Bedarf Periodensnapshots mit einem Broadcast-Befehl synchronisieren.

Mehrkanal-Module werden ebenfalls unterstützt — die reinen Strom-Module I2 / I3 (zwei bzw. drei Stromwandler) und die mit Spannungsmessung ausgestatteten UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 Stromkanäle, mit Leistung, PF und Wh je Kanal). Jeder Kanal hat sein eigenes Sensormodell. Das ist typisch für eine Unterverteilung, wo ein einziger Messpunkt mehrere Abgänge überwacht.

Die Arbeit mit einem einzelnen Modul ist der Minimalfall derselben Bibliothek: Die Klasse RbAmp ist der Baustein, auf dem RbAmpFleet aufsetzt. Wenn nur ein Modul am Bus hängt, verwenden Sie dasselbe Handle direkt — die Flotten-API wird nicht benötigt.

Das 80-%-Szenario — Netzanschluss + N Unterlasten

Ein Modul an der Netzeinspeisung und je ein Modul pro Teillast teilen sich einen I²C-Bus mit dem Master, der sie alle mit einem einzigen Flottenaufruf abfragt.

  • 1 Modul an der Einspeisung (Netz) — Gesamtverbrauch und Netzqualität.
  • N Module an einzelnen Lasten — Messung je Kanal.
  • Auch Mehrkanal-Module passen auf diesen Fall: ein UI2 / UI3 / UI5 / UI7 (oder I2 / I3) kann mehrere Lasten messen, jede auf eigenem Kanal — N Module müssen nicht N Lasten bedeuten.
  • Ein einziger Aufruf fleet.poll_all() fragt alles ab; die Bilanz Netz − Σ(Teillasten) zeigt „den Rest“ (Grundverbrauch, nicht gemessene Lasten, Leckagen).

  • Ein gemeinsamer Master-Zeitstempel → korrekte Wh-Messung ohne Drift zwischen den Modulen.

Sicherheit

Wichtiges Architekturdetail. Die I-Varianten (I1/I2/I3) messen nur Strom — sie haben keine Spannung, keine Wirkleistung und keinen PF. Wirkenergie (Wh) und Leistung werden nur auf den UI-Varianten berechnet (die ein Spannungs-Frontend haben). Im kanonischen Aufbau übernimmt eine einzelne UI1 am Netzeinspeisepunkt die Rolle des „Netzzählers“ (Energiemessung); die Sub-Zähler-Rolle (Stromdetail je Last) übernehmen I2/I3-Module (oder UI2 / UI3 / UI5 / UI7, wenn Leistung und Wh je Last benötigt werden).

Details finden Sie in Kapitel 06 · Beispiele, Szenario 1 („Netz + N Teillasten — der 80-%-Kanon“). Zur API siehe Kapitel 09 · API-Referenz, Abschnitt „Flottenverwaltung“.

Was rbAmp misst

Größe Python-Typ Bereich
Effektivspannung U_rms float, V 0…300 V
Spitzenspannung U_peak float, V 0…450 V
Effektivstrom I_rms float, A hängt vom gewählten Sensor ab — siehe 03_sensor_selection.md
Spitzenstrom I_peak float, A abhängig vom gewählten Sensor
Wirkleistung P (in RT vorzeichenbehaftet) float, W abhängig vom gewählten Sensor
Leistungsfaktor PF float −1…+1
Netzfrequenz int, Hz 50 / 60 Hz (erkannt)
Periodengemittelte P float, W wie P
Hinweis

Der RT-Wert der Wirkleistung P ist auf jeder Modulreihe immer vorzeichenbehaftet (negativ bedeutet Einspeisung ins Netz). Das Verhalten des periodengemittelten Werts (snap.avg_p[ch] in RbAmpPeriodSnapshot) hängt von der Modulreihe ab — siehe den Abschnitt „Modulreihen“ unten und 02_tiers.md.

Verdrahtung

Das Modul verbindet sich mit vier Leitungen auf der Niederspannungsseite mit dem Host; alles, was das Netz berührt, bleibt im Gehäuse.

Draht Zweck
VCC +5 V (4.5..5.5 V), Stromaufnahme ~15 mA, Spitze ~25 mA
GND gemeinsam mit dem Host (erforderlich)
SDA, SCL I²C, 3.3-V-Logik, 5-V-tolerant. Eingebaute Pull-ups 4.7 kΩ
DRDY optional, Open-Drain: LOW für ~10 µs alle ~100 ms

Die Standardadresse ist 0x50 (7-Bit, Änderungsbereich 0x08..0x77). Die empfohlene Geschwindigkeit für MicroPython auf dem ESP32 ist 50 kHz; für CPython über den I²C-Kernel ist sie üblicherweise 100 kHz (das NACK-Muster tritt über die Linux-Kernel-API nicht auf).

Die vollständigen Regeln (Buslänge, Pull-up-Empfehlungen an einem Bus mit mehreren Modulen, Verdrahtungsdiagramme für RPi / ESP32 / RP2040 / STM32) stehen in Kapitel 04 · Verdrahtung.

Modullinien (Kurzübersicht)

BASIC und STANDARD (STD)-Module werden ausgeliefert; STANDARD wird von dieser Bibliothek ab 1.6.0 unterstützt.

BASIC ist eine einseitige (nur Verbrauch) Messung nach der Logik eines klassischen mechanischen Zählers:

Modulstufe RT-Leistung dev.power[ch] Periodenakkumulator snap.avg_p[ch] Wh-Zähler des Pakets
BASIC vorzeichenbehaftet (negativ = Einspeisung ins Netz, in Echtzeit sichtbar) jedes 100-ms-Fenster der mittleren P wird auf max(P, 0) begrenzt, bevor es zum Periodenakkumulator addiert wird monoton — reine Verbrauchsmessung
STANDARD (STD) vorzeichenbehaftet dieselben Aufrufe wie bei BASIC; Quelle sind die Energiezähler des Moduls oder Latch-Bank 0, gewählt bei begin(); Energie ist netto (Export wird abgezogen) dev.energy integriert die Periode; die eigenen Summen des Moduls: read_std_energy() (siehe Kapitel 02)

Details finden Sie in Kapitel 02 · Modulreihen. Auf Paketebene wird unabhängig von der Modulreihe dieselbe Klasse RbAmp verwendet; die Unterschiede zeigen sich in den Werten, die das Modul liefert.

Hinweis

Bidirektionale Messung auf BASIC: dev.energy.wh(ch) auf der BASIC-Modulreihe liefert nur Verbrauch. Wenn Sie Export separat erfassen müssen, samplen Sie die Echtzeitleistung dev.power[0] (oder dev.read_power(0)) mit ~10 Hz und teilen die positiven und negativen Samples selbst in zwei Akkumulatorvariablen auf. Ein Beispiel finden Sie in 06_examples.md, Szenario „Bidirektionale Messung auf Masterseite“.

Was dieses Paket macht

Die Hauptaufgabe ist, den Protokollaustausch zu verbergen und den Anwendercode von der Routine der Registerarbeit, der Byte-Reihenfolge und den Einschwingzeiten nach Befehlen zu entlasten. Darüber hinaus berechnet das Paket die Energie (Wh) — das Modul liefert nur die periodengemittelte Leistung, und der Master integriert mit time.monotonic() / time.ticks_us().

Ohne das Paket (direkter Registerzugriff über smbus2)

Python
import struct
from smbus2 import SMBus, i2c_msg

# Read U_RMS — burst-read 4 bytes (auto-increment is supported on reads).
with SMBus(1) as bus:
    buf = bytes(bus.read_i2c_block_data(0x50, 0x86, 4))
u_rms = struct.unpack("

Mit dem Paket

Python
from smbus2 import SMBus
from rbamp import RbAmp

with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.begin()
    u_rms = dev.voltage          # property (one call = one transaction)
    # or: u_rms = dev.read_voltage()

Eine Periode lesen — ohne das Paket

Python
import time, struct

with SMBus(1) as bus:
    # Snapshot + 50 ms settle + ready-flag check + assemble 4 bytes of avg_p
    bus.write_byte_data(0x50, 0x01, 0x27)   # REG_COMMAND, CMD_LATCH_PERIOD
    t_latch = time.monotonic()
    time.sleep(0.050)                        # settle

    bus.write_byte(0x50, 0x07)
    if bus.read_byte(0x50) & 0x01 == 0:
        # snapshot is stale — keep the previous t_prev_latch, so the next
        # good snapshot covers the full interval
        raise SystemExit("stale snapshot")

    # ...read 4 bytes of avg_p, struct.unpack, integrate Wh:
    #   dt_s = time.monotonic() - t_prev_latch
    #   E_Wh += avg_p * dt_s / 3600

Eine Periode lesen — mit dem Paket

Python
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
    dev.begin()
    snap = dev.read_period_snapshot()        # snapshot + settle + valid + read + Wh tick
    print(snap.avg_p[0], "W")
    print(dev.energy.wh(0), "Wh")

Intern garantiert das Paket:

  • Eine Pause von 50 ms nach CMD_LATCH_PERIOD und ein korrekter Snapshot-Lesevorgang.
  • Vor dem Lesen eine Prüfung des Flags valid; bei einem veralteten Snapshot wird RbAmpStaleError ausgelöst.

  • Behält den vorherigen Zeitstempel bei einem veralteten Snapshot, damit der nächste gute Snapshot das volle Intervall abdeckt und Wh exakt bleibt.

  • Kanalweise Wh-Akkumulation in doppelter Genauigkeit (CPython — 64-Bit-float; MicroPython — abhängig vom Build, siehe 04 · Verdrahtung).

  • Automatisches Laden der Kalibrierkoeffizienten, wenn der Stromsensor über dev.set_sensor_class(cls) + dev.set_ct_model(code) gewählt wird — der Anwender muss die internen Kalibrierregister nicht kennen.

Wann das Paket und wann der direkte Buszugriff verwendet wird

Aufgabe Paket Direktzugriff über smbus2 / machine.I2C
Lesen von U / I / P / PF / Frequenz ✅ nur zum Debuggen mit einem Logikanalysator
Periodenbezogene Energiemessung ✅ nur wenn die Wh außerhalb des Pakets gespeichert werden (z. B. in einer Datenbank auf Masterseite)
Mehrere Module an einem Bus ✅ (über sequenzielle Snapshots + gemeinsame Einschwingzeit) —
Bidirektionale Messung auf BASIC ✅ (über RT-Lesevorgänge — siehe 06_examples.md) Alternative — eigene Echtzeit-Leseschleife
Asynchrones Streaming über asyncio / uasyncio ✅ (async for snap in dev.stream_period()) schwierig — kein eingebauter asynchroner Wrapper
Portierung auf eine andere Plattform n/a ✅ — siehe rbamp-docs (Registerkarte und Protokoll)

Für alle typischen Aufgaben in den ersten Zeilen ist das Paket der richtige Weg.

Architektur

Wo ein Python-Skript sitzt: Skript, rbamp-Paket, I²C-Backend und das rbAmp-Modul, mit der I²C-Geschwindigkeit für jeden Host.

Text
┌─────────────────────────────────────────────────────┐
│  User code (.py)                                    │
│   from smbus2 import SMBus                          │
│   from rbamp import RbAmp, RbAmpSensorClass         │
│   with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:    │
│       # __enter__ calls dev.begin() itself;         │
│       # explicit begin() shown for transparency     │
│       dev.set_sensor_class(RbAmpSensorClass.SCT_013)│
│       dev.set_ct_model(3)                           │
│       snap = dev.read_period_snapshot()             │
│       dev.energy.wh(0)                              │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Public API of the RbAmp class (rbamp/__init__.py)  │
│   ┌─────────────────────────────────────────────┐   │
│   │ Lifecycle:      begin / probe / wait_ready  │   │
│   │ RT properties:  .voltage / .power[ch] /     │   │
│   │                 .current[ch] / .frequency   │   │
│   │ RT methods:     read_voltage / read_power / │   │
│   │                 read_all                    │   │
│   │ Period:         latch_period /              │   │
│   │                 read_period_snapshot        │   │
│   │ Async:          stream_period               │   │
│   │ Configuration:  set_sensor_class /          │   │
│   │                 set_ct_model                │   │
│   │ Diagnostics:    retry_exhaustion_count /    │   │
│   │                 sanity_reject_count         │   │
│   │ Exceptions:     RbAmpError → IOError /      │   │
│   │                 TimeoutError / StaleError / │   │
│   │                 ParamError / ModeError /    │   │
│   │                 VersionError                │   │
│   └─────────────────────────────────────────────┘   │
│                       │                             │
│                       ▼                             │
│   ┌─────────────────────────────────────────────┐   │
│   │ Backend selection (inside __init__):        │   │
│   │  bus.readfrom_mem  → MachineI2CBackend      │   │
│   │  bus.read_byte_data → SMBusBackend          │   │
│   │  duck-typed        → custom (FTDI / mocks)  │   │
│   └─────────────────────────────────────────────┘   │
│                       │                             │
│                       ▼                             │
│   ┌─────────────────────────────────────────────┐   │
│   │ Instance state:                             │   │
│   │  • RbAmpEnergy — Wh accumulator             │   │
│   │  • RbAmpSnapshot / RbAmpPeriodSnapshot      │   │
│   │  • Time of last snapshot (monotonic)           │   │
│   └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  Backend — native I²C on the host platform:         │
│   smbus2 (CPython)  /  machine.I2C (MicroPython)    │
└─────────────────────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────┐
│  rbAmp module at address 0x50                       │
│   • U / I / P / PF measurement pipeline (~100 ms)   │
│   • Period accumulator (atomic CMD_LATCH_PERIOD)    │
└─────────────────────────────────────────────────────┘

Ausnahmehierarchie

Anders als die Arduino-Bibliothek (wo Fehler über lastError() + einen Rückgabecode gemeldet werden) und die ESP-IDF-Komponente (wo sie über esp_err_t gemeldet werden), verwendet das Python-Paket das klassische Python-Muster — eine Ausnahmehierarchie.

Ausnahmehierarchie des Pakets rbamp: jeder Fehler leitet sich von RbAmpError ab, das sich von OSError ableitet.

Das übliche Python-Muster:

Python
from rbamp import RbAmp, RbAmpStaleError, RbAmpError

try:
    snap = dev.read_period_snapshot()
except RbAmpStaleError:
    # Snapshot is stale — the package keeps the previous timestamp, the next good snapshot covers the full interval
    continue
except RbAmpError as e:
    log.warning("rbAmp failure: %s", e)

Interaktionsdiagramme

Der Ablauf von dev.begin()

Folge von Bustransaktionen, die begin() ausführt: Version lesen, die Modulreihe erkennen, den Primer-Snapshot senden, dann zurückkehren.

Text
code          RbAmp                Backend             rbAmp module
  │             │                    │                       │
  ├─dev.begin()►                     │                       │
  │             ├─read_u8(REG_VERSION)►                      │
  │             │                    ├──[0x50, 0x03]────────►│
  │             │                    │◄────────────────ACK───┤
  │             │                    ├──[read 1 byte]───────►│
  │             │                    │◄──────────────[0x04]──┤
  │             │◄─────── version_byte ─────┤                  │
  │             │                    │                       │
  │             ├─read_float_le(U_RMS)►(4 single-byte reads) │
  │             │  → 226.3 V         │                       │
  │             │  → has_voltage_hw = True                   │
  │             │                    │                       │
  │             ├─write_cmd(LATCH)──►│                       │
  │             │                    ├──[0x50, 0x01, 0x27]──►│
  │             │  sleep(50ms)       │                       │
  │             │                    │                       │
  │◄────self────┤  (or raises RbAmpIOError on failure)        │

Der erste Snapshot ist ein Primer (das Modul liefert, was es seit dem Einschalten akkumuliert hat, was für die Tarifmessung ungeeignet ist). Das Paket vermerkt selbst, dass dieser Snapshot verworfen werden muss — Anwendercode sieht ihn nie.

Der Ablauf von dev.read_period_snapshot()

Ablauf von read_period_snapshot(): Periodensnapshot nehmen, Snapshot-Block lesen, die Energie auf dem Master integrieren (bei BASIC) bzw. die Zähler des Geräts auslesen (bei STD).

Text
code          RbAmp                Backend             rbAmp module
  │             │                    │                       │
  ├─read_period_snapshot()►          │                       │
  │             ├─write_cmd(LATCH)──►│  t_now = time.monotonic()
  │             │                    │                       │
  │             │  sleep(50ms)       │                       │
  │             │                    │                       │
  │             ├─is_period_valid()─►│                       │
  │             │  → True            │                       │
  │             │                    │                       │
  │             ├─read_float_le(AVG_P0)►(4 reads)            │
  │             ├─read_float_le(MAX_P0)►(4 reads)            │
  │             ├─read_u32_le(LATCH_MS)►(4 reads)            │
  │             │                    │                       │
  │             │  dt = t_now − last_latch                    │
  │             │  energy.wh[ch] += avg_p[ch] × dt / 3600    │
  │             │  last_latch = t_now                         │
  │             │                    │                       │
  │◄─snap──────┤                    │                       │

Der atomare Snapshot auf Modulseite garantiert, dass jede Messung innerhalb einer Periode in genau einem Snapshot landet — keine Duplikate, keine Verluste an der Periodengrenze.

Zuordnung zur direkten Register-API

Eine Tabelle für Anwender, die von ihrer eigenen direkten Zugriffsimplementierung umsteigen:

Direkte API (smbus2 / machine.I2C) Entsprechung im Paket
Manuelles 4-Byte-Lesen + struct.unpack dev.voltage (Eigenschaft) oder dev.read_voltage()
Kanalweises read_byte × 4 dev.power[ch] (_ChannelProxy) oder dev.read_power(ch)
write_byte_data(0x50, 0x01, 0x27); time.sleep(0.05) dev.latch_period(); time.sleep(0.05) (oder direkt dev.read_period_snapshot())
Prüfen von read_byte(0x07) & 1 dev.is_period_valid() oder das Feld snap.valid
Manuelle Formel E_Wh += avg_p × dt / 3600 dev.energy.wh(0) — wird automatisch aktualisiert
Manuelle Konfiguration des Stromsensors über die direkte Register-API dev.set_sensor_class(cls) + dev.set_ct_model(code) — Werkvoreinstellungen werden automatisch geladen

Was als Nächstes kommt


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