01 · Überblick
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
RbAmpStaleErroraus, 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
- 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(oderI2/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 BilanzNetz − Σ(Teillasten)zeigt „den Rest“ (Grundverbrauch, nicht gemessene Lasten, Leckagen). -
Ein gemeinsamer Master-Zeitstempel → korrekte Wh-Messung ohne Drift zwischen den Modulen.
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 |
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.
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)
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
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
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
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_PERIODund ein korrekter Snapshot-Lesevorgang. -
Vor dem Lesen eine Prüfung des Flags
valid; bei einem veralteten Snapshot wirdRbAmpStaleErrorausgelö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
┌─────────────────────────────────────────────────────┐
│ 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.
Das übliche Python-Muster:
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()
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()
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
- 02 · Modulreihen — welche Modulreihe für welche Aufgabe
-
04 · Verdrahtung — Pull-ups, Buslänge, Verdrahtung je Host (RPi / ESP32 / RP2040 / STM32)
-
05 · Schnellstart — das erste funktionierende Skript für beide Backends
-
06 · Beispiele — ein Rundgang durch fertige Szenarien
-
09 · API-Referenz — jede öffentliche Klasse, Methode, Eigenschaft und Ausnahme
-
10 · Fehlerbehebung — wenn etwas nicht funktioniert
Quelle & Probleme: rb-amp/rbamp-python · diese Seite im Repository: docs/01_overview.md (v1.6.1)