05 · Schnellstart
Ein fünfminütiges Hallo-Welt-Beispiel: Paket installieren, Modul anschließen, Sensor auswählen und den ersten RT-Wert sowie den ersten Periodensnapshot (Wh) lesen. Dieses Tutorial behandelt beide Laufzeitumgebungen parallel — MicroPython (auf ESP32 / RP2040 / STM32 / Pyboard) und CPython (auf Raspberry Pi / Orange Pi / Rock Pi / x86 + USB-I²C).
Für die Details (Pinbelegung für einen bestimmten Host, Mehrmodul-Bus, Wahl eines SCT-013 nach Bereich) siehe die Nachbarkapitel:
-
04 · Verdrahtung — Hardware-Details und Pin-Tabellen je Host
-
03 · Auswahl des Stromsensors — welches SCT-013-Modell und warum
Was Sie benötigen
⚠ Netzsicherheit. Netzspannung kann tödlich sein. Trennen und sichern Sie den Stromkreis gegen Wiedereinschalten, bevor Sie die L/N-Klemmen anschließen oder die Zange anbringen; Arbeiten an der Netzverkabelung und im Inneren eines Verteilers überlassen Sie einer Elektrofachkraft. Klemmen Sie nur einen Leiter (L) — niemals das ganze Kabel (klemmen Sie L und N zusammen, zeigt die Messung etwa 0). Die Zange selbst arbeitet berührungslos.
- Ein rbAmp-Modul (beliebige Modulreihe, UI1 zur Vereinfachung)
- Einer dieser Hosts:
-
CPython: Raspberry Pi (jedes Modell) / Orange Pi 5 / Rock Pi 5 / x86 + USB-I²C-Dongle
-
MicroPython: ESP32 (DevKitC / S2 / S3 / C3) / RP2040 (Pico / Pico W) / STM32 (Pyboard / Nucleo)
-
Eine SCT-013-Stromzange, bemessen für Ihren maximalen Strom (5 A / 10 A / 30 A / 50 A / 100 A)
- Eine 5-V-Versorgung für das Modul (vom USB-5V des Hosts oder extern)
- Ein zu messender Wechselstromkreis (eine Lampe, ein Wasserkocher oder ein Haushaltsgerät)
Welchen Weg gehe ich?
Prüfen Sie dev.is_std (oder das SKU-Etikett am Modul — siehe 02 · Modulreihen). STD-Modul: überspringen Sie Schritt 4–5 und gehen Sie zu 06 · Beispiele, Szenario 11. BASIC-Modul: folgen Sie allen Schritten. Schritt 3 und Schritt 4 sind für beide gleich.
Schritt 1 — Paket installieren
CPython (auf einem Linux-SBC oder x86)
pip install rbamp
(Auf einem Debian/Ubuntu-System können Sie die Systemalternative smbus2 verwenden: sudo apt install python3-smbus; empfohlen wird jedoch das smbus2 aus pip, da es den Kontextmanager with SMBus(...) unterstützt.)
Verify:
rbamp --version # rbamp 1.6.0
rbamp --bus 1 scan # I²C scan, should show 0x50
MicroPython (auf ESP32 und anderen)
mpremote mip install github:rb-amp/rbamp-python
Oder kopieren Sie das Paket manuell:
mpremote cp -r path/to/rbamp/ :rbamp/
Das Paket wird auf dem Gerät nach /lib/rbamp/ installiert.
Schritt 2 — Verdrahtung
Vier Leitungen plus optional DRDY:
| rbAmp-Pin | Host |
|---|---|
VCC |
+5 V (Bereich 4.5..5.5 V) |
GND |
GND |
SDA |
I²C SDA (RPi-Pin 3, ESP32 GPIO21, RP2040 GPIO0 usw.) |
SCL |
I²C SCL (RPi Pin 5, ESP32 GPIO22, RP2040 GPIO1 usw.) |
Die Versorgung muss 5 V betragen. Die I²C-Leitungen arbeiten mit 3.3-V-Logik, sind aber 5-V-tolerant. Die Modulplatine hat bereits eingebaute 4.7-kΩ-Pull-up-Widerstände — für ein einzelnes Modul sind keine externen nötig.
Die vollständige Pinbelegung für jeden Host finden Sie in 04 · Verdrahtung.
Die SCT-013-Stromzange wird nur um den Außenleiter (L) geklemmt, wobei der Pfeil am Zangenkörper in Stromrichtung zur Last zeigt. Mehr dazu in 04 · Verdrahtung.
⚠ Netzsicherheit. Netzspannung kann tödlich sein. Trennen und sichern Sie den Stromkreis gegen Wiedereinschalten, bevor Sie die L/N-Klemmen anschließen oder die Zange anbringen; Arbeiten an der Netzverkabelung und im Inneren eines Verteilers überlassen Sie einer Elektrofachkraft. Klemmen Sie nur einen Leiter (L) — niemals das ganze Kabel (klemmen Sie L und N zusammen, zeigt die Messung etwa 0). Die Zange selbst arbeitet berührungslos.
Schritt 3 — Erstes Skript (RT-Lesen)
Ein minimales Skript: Teilen Sie dem Modul einmalig mit, welche Zange Sie verwenden, und lesen Sie dann U / I / P / PF. Die Modellcodes stehen in Schritt 4; 3 unten ist der SCT-013-030. Die Tabelle der Modulreihen / Varianten steht in 02 · Modulreihen.
CPython-Version
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass
with SMBus(1) as bus:
with RbAmp(bus, 0x50) as dev:
# the context manager's __enter__ automatically calls dev.begin()
# the module variant is detected automatically
variant = dev.read_variant()
label = dev.read_label() or "(unset)"
print(f"Module ready: variant={variant} label={label!r}")
# variant codes: see the table in 02 · Module lines
# Once per installation (saved in the module's flash):
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
dev.set_ct_model(3) # SCT-013-030, see Step 4
while True:
try:
print(f"U={dev.voltage:.1f}V "
f"I={dev.read_current(0):.3f}A "
f"P={dev.read_power(0):.1f}W "
f"PF={dev.read_power_factor(0):.3f}")
except RbAmpError as e:
print("read failed:", e)
time.sleep(1)
Run:
python quick_read.py
MicroPython-Version
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpError, RbAmpSensorClass
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000) # ESP32 default
with RbAmp(i2c, 0x50) as dev:
dev.set_sensor_class(RbAmpSensorClass.SCT_013) # once per installation
dev.set_ct_model(3) # SCT-013-030, see Step 4
print("Module ready.")
while True:
try:
print("U={:.1f}V I={:.3f}A P={:.1f}W PF={:.3f}".format(
dev.voltage, dev.read_current(0),
dev.read_power(0), dev.read_power_factor(0)))
except RbAmpError as e:
print("read failed:", e)
time.sleep(1)
(Unter MicroPython wird .format() statt f-Strings verwendet — aus Leistungsgründen und zur Kompatibilität mit älteren Ports; auf neueren Ports funktionieren f-Strings ebenfalls.)
Run:
mpremote run quick_read.py
Erwartete Ausgabe bei eingeschalteter Last (die Werte hängen von Ihrer Last ab):
Module ready.
U=230.4V I=0.523A P=119.8W PF=0.987
U zeigt ungefähr die Netzspannung (220–240 V bei 230-V-Netzen). Ohne Last ist I etwa 0 und PF nicht definiert (es kann nan, 0 oder einen Platzhalter anzeigen) — die genaue Form spielt keine Rolle, solange der Strom null ist. Bleibt I bei eingeschalteter Last bei 0.000 A, prüfen Sie die Zange (ein Leiter, richtige Richtung) und den Modellcode, dann siehe 10 · Fehlerbehebung.
Schritt 4 — Konfiguration des Stromsensors
Sie müssen dem Modul die Sensorklasse und das Modell mitteilen (geschieht im Skript von Schritt 3). Ohne das werden die Kalibrierkoeffizienten nicht geladen, und die Strommesswerte bleiben bei null. Rufen Sie immer zuerst set_sensor_class() auf, dann set_ct_model(code).
Wählen Sie den Code, der zu Ihrem Stromwandler passt:
code |
Modell | Bereich | Typische Anwendung |
|---|---|---|---|
| 1 | SCT-013-005 | 0..5 A | Kleine Lasten, eine einzelne Steckdose |
| 2 | SCT-013-010 | 0..10 A | Kühlschrank, Waschmaschine |
| 3 | SCT-013-030 | 0..30 A | Haushaltseinspeisung bis ca. 7 kW |
| 4 | SCT-013-050 | 0..50 A | Ladestation für E-Autos, elektrische Heizung |
| 6 | SCT-013-020 | 0..20 A | Mittlere Einspeisung, Geräte mit 3–4 kW |
Mehr zur Auswahl — 03 · Auswahl des Stromsensors.
Diese beiden Aufrufe erfolgen einmalig bei der Erstinstallation — die Auswahl wird im Flash des Moduls gespeichert und übersteht einen Reset. Die Gesamtzeit beträgt etwa 1.4 Sekunden (zwei Flash-Schreibvorgänge × je ~700 ms).
Bei späteren Skriptläufen müssen Sie set_sensor_class() und set_ct_model() nicht erneut aufrufen (das Modul merkt sich die Werte). Ein erneuter Aufruf mit dem Wert, den das Modul bereits hält, ist ein No-Op.
Schritt 5 — Energieabrechnung (Wh)
Das Modul liefert nur Momentanwerte plus die mittlere Leistung über eine Periode. Die Wh selbst berechnet das Paket mit der Master-Uhr (time.monotonic() unter CPython, time.ticks_ms() unter MicroPython):
E_Wh += avg_P × master_dt_s / 3600
[W] [seconds] → [Wh]
wobei master_dt_s die Sekunden zwischen zwei erfolgreichen Aufrufen von dev.read_period_snapshot() sind.
Warten Sie eine volle Periode, bevor Sie das erste read_period_snapshot() aufrufen. begin() startet bereits eine Periode. Ein Snapshot direkt danach deckt daher nur einen Bruchteil einer Sekunde ab, und Wh liest ~0. Aus diesem Grund schlafen die folgenden Schleifen zuerst 60 s.
Der Wh-Zähler wird im Speicher geführt. Er startet nach einem Neustart des Skripts oder des Geräts bei 0. Für eine absolute Summe speichern Sie dev.energy.wh(0) selbst. Auf BASIC-Modulen wird Export nicht gezählt (siehe 02 · Modulreihen). Auf einem STD-Modul funktionieren dieselben Aufrufe, und der Wert ist Nettoenergie (Export wird abgezogen); begin() wählt die Quelle — die Energiezähler des Moduls oder Latch-Bank 0 — und die erste Periode beginnt bei begin(). Die eigenen Lebenszeitsummen des Moduls stehen in read_std_energy() (Szenario 11 in 06 · Beispiele).
Eine minimale Vorlage für die periodische Bilanzierung (einmal pro Minute):
CPython-Version (Periodenzähler)
import time
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
dev.set_ct_model(3) # SCT-013-030
while True:
time.sleep(60) # 60-second period
try:
snap = dev.read_period_snapshot()
except RbAmpStaleError:
print("snapshot stale — skip")
continue
except RbAmpError as e:
print("snapshot failed:", e)
continue
print(f"avg P over period: {snap.avg_p[0]:.2f} W "
f"accumulated: {dev.energy.wh(0):.4f} Wh "
f"dt={snap.master_dt_ms} ms")
MicroPython-Version (Periodenzähler)
import time
from machine import I2C, Pin
from rbamp import RbAmp, RbAmpSensorClass, RbAmpStaleError, RbAmpError
i2c = I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000)
with RbAmp(i2c, 0x50) as dev:
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
dev.set_ct_model(3)
while True:
time.sleep_ms(60_000)
try:
snap = dev.read_period_snapshot()
except RbAmpStaleError:
print("snapshot stale — skip")
continue
except RbAmpError as e:
print("snapshot failed:", e)
continue
print("avg P over period: {:.2f} W accumulated: {:.4f} Wh dt={} ms".format(
snap.avg_p[0], dev.energy.wh(0), snap.master_dt_ms))
Nach Schritt 4 wurden die Aufrufe set_sensor_class() und set_ct_model() bereits einmal ausgeführt und im Flash des Moduls gespeichert; in der Vorlage oben sind sie für erneute Läufe des Skripts vorgesehen — das Modul ignoriert einen wiederholten Aufruf mit demselben Wert.
Was read_period_snapshot() intern macht:
- Sendet dem Modul den Periodensnapshot-Befehl (
CMD_LATCH_PERIOD). - Wartet 50 ms, während das Modul den Snapshot vorbereitet.
-
Prüft das Bereitschaftsflag (
snap.valid); liest die mittlere / Spitzenleistung. -
Aktualisiert den internen Wh-Zähler:
dev.energy.wh(ch) += avg_p[ch] × dt / 3600. - Bei einem veralteten Snapshot löst er
RbAmpStaleErroraus und behält den vorherigen Zeitstempel, sodass der nächste erfolgreiche Snapshot das volle Intervall abdeckt und Wh exakt bleibt.
dev.begin() startet die erste Periode selbst (als Primer) und verwirft, was das Modul seit dem Einschalten akkumuliert hat, sodass der Anwendercode diese Daten nie sieht.
Erwartete Ausgabe:
avg P over period: 120.18 W accumulated: 2.0036 Wh dt=60012 ms
avg P over period: 120.21 W accumulated: 4.0073 Wh dt=60005 ms
...
Variante mit asynchronem Streaming (optional)
Für Anwendungen mit asyncio (CPython) bzw. uasyncio (MicroPython) gibt es einen asynchronen Generator dev.stream_period(interval_s=...):
import asyncio
from smbus2 import SMBus
from rbamp import RbAmp, RbAmpSensorClass
async def main():
with SMBus(1) as bus, RbAmp(bus, 0x50) as dev:
dev.set_sensor_class(RbAmpSensorClass.SCT_013)
dev.set_ct_model(3)
# Once a minute, with built-in stale handling (skip_stale=True)
async for snap in dev.stream_period(interval_s=60.0):
print(f"{snap.avg_p[0]:.2f} W, {dev.energy.wh(0):.4f} Wh")
asyncio.run(main())
Auf MicroPython funktioniert es genauso (import uasyncio as asyncio).
Mehr zu asynchronen Szenarien — 06 · Beispiele, das Szenario „Asynchrones Periodenstreaming“.
Schritt 6 — Schnellstart für eine Flotte aus N Modulen
Dieser Schnellstart zeigt die Arbeit mit einem einzelnen Modul. Das eigentliche kanonische Szenario des Pakets sind mehrere Module an einem Bus über RbAmpFleet (Netz + N Teillasten). Das vollständige Beispiel steht in Kapitel 06 · Beispiele, Szenario 1 „Netz + N Teillasten — der 80-%-Kanon“. Ein minimales Flotten-Grundgerüst (CPython):
import time
from smbus2 import SMBus
from rbamp import RbAmpFleet
with SMBus(1) as bus:
fleet = RbAmpFleet(bus)
added = fleet.scan()
print(f"fleet: {added} modules; excluded: {fleet.excluded}")
while True:
snaps = fleet.poll_all()
total_w = fleet.total_power()
n_ok = sum(1 for snap, info in snaps if info.ok)
print(f"fleet: {n_ok}/{len(fleet)} OK, total P = {total_w:.1f} W")
time.sleep(0.2)
Die MicroPython-Version ist identisch — ersetzen Sie SMBus(1) durch I2C(0, scl=Pin(22), sda=Pin(21), freq=50_000).
Im kanonischen 80-%-Szenario ist eines der Module ein UI1 an der Netzeinspeisung (es liefert total_power() und total_energy_wh()), und die übrigen, I2/I3, sind Strom-Unterzähler. Die Details und fortgeschrittenen Szenarien (Zerlegung Netz + Teillasten, GC-Synchronisierung für eng abgestimmte Snapshots, Provisionierungsablauf) stehen in Kapitel 06.
Was als Nächstes kommt
- 01 · Übersicht — was rbAmp ist und was das Paket tut
- 02 · Modulreihen — welche Modulreihe für welche Aufgabe
-
06 · Beispiele — Arbeitsszenarien: Netz + N Teillasten (der 80-%-Kanon), Provisionierungsablauf, Mehrkanal mit gemischten CTs, GC-Synchronisierung der Flotte, MQTT, Deep Sleep, asynchrones Streaming
-
07 · DIY-Integrationen — Home Assistant / Node-RED / OpenHAB
-
08 · Cloud-Integrationen — AWS IoT / Azure / GCP / InfluxDB
-
09 · API-Referenz — die vollständige öffentliche API (einschließlich
RbAmpFleet+ Mehrkanal + Fehlermodell v1.3 + Identität & Provisionierung) -
10 · Fehlerbehebung — wenn etwas nicht funktioniert (MicroPython@ESP32 i2c-hang, dreischichtig, latch_ms ist ein diagnostischer Timer, RbAmpStaleError durch den Master-Hold-Anker)
Quelle & Issues: rb-amp/rbamp-python · diese Seite im Repo: docs/05_quickstart.md (v1.6.1)