02 · Modulstufen
Was eine Modulreihe ist
rbAmp-Module gibt es in zwei Modulreihen: BASIC und STANDARD (STD). Eine Modulreihe ist ein vollständiges Paket aus Hardware-Revision und Firmware, kein Software-Flag. Der Wechsel zwischen Modulreihen erfordert einen physischen SKU-Wechsel, kein Firmware-Update.
Aus Sicht von Paket und Anwendercode gilt: eine RbAmp-Klasse bedient jede Modulreihe, und die gängigen Leser (voltage, current, power, power_factor, frequency) funktionieren bei allen. Die Modulreihe wird bei begin() automatisch erkannt. STANDARD-(STD)-Module stellen zusätzlich die STD-only-Aufrufe bereit (Energie auf dem Gerät usw., siehe unten); ein solcher Aufruf auf einem BASIC-Modul löst RbAmpNotSupportedError aus.
Aktueller Stand
BASIC- und STANDARD-Module werden von dieser Bibliothek unterstützt (STANDARD ab 1.6.0).
| Modulstufe | Auslieferung |
|---|---|
| BASIC | ✅ ja |
| STANDARD (STD) | ✅ ja (von dieser Bibliothek ab 1.6.0 unterstützt) |
BASIC — Einstiegs-Modulreihe für die Verbrauchsmessung
Hardware
Ein kostenoptimierter analoger Pfad, der für typische Haushaltslasten geeignet ist. Das Modul enthält ein galvanisch getrenntes analoges Frontend, einen integrierten Spannungsregler und eine werkseitige Kalibrierung im Flash-Speicher.
Verhalten der Firmware
Die Logik eines klassischen mechanischen Ferraris-Zählers — der Zählerstand läuft nur vorwärts; Einspeisung ins Netz wird nicht abgezogen.
Die drei "Ebenen" der Wirkleistungswerte verhalten sich unterschiedlich:
| Signal | Bedeutung | Verhalten bei BASIC |
|---|---|---|
dev.power[ch] / dev.read_power(ch) |
momentane RT-Leistung, Aktualisierung ~100 ms | vorzeichenbehaftet — ein negativer Wert ist in Echtzeit sichtbar (Einspeisung) |
snap.avg_p[ch] (aus dev.read_period_snapshot()) |
Durchschnittsleistung über die Periode | jedes 100-ms-Fenster der mittleren P wird begrenzt auf max(P, 0), bevor es zum Periodenakkumulator addiert wird |
dev.energy.wh(ch) |
vom Paket akkumulierte Wh | monoton — nur Verbrauch; Einspeisung wird nicht gezählt |
Anders gesagt: Der Anwender sieht die Einspeisung im RT-Messwert, aber sie ist im Wh-Zähler des Pakets bei BASIC nicht enthalten.
Typische Anwendungen
-
Haushalte ohne eigene Erzeugung (keine Solarmodule, Windkraftanlagen, Batteriesysteme)
-
Teilzählung rein verbrauchender Lasten (Warmwasserbereiter, Motoren, Haushaltsgeräte)
-
Verbrauchsüberwachung im Gebäude, wo bidirektionale Messung nicht nötig ist
Bidirektionale Messung auf BASIC (masterseitig)
Wenn Sie die Einspeisung ins Netz auf einem BASIC-Modul getrennt erfassen müssen, tun Sie das auf der Masterseite. Die RT-Leistung dev.power[0] ist vorzeichenbehaftet (oder die gleichwertige Methode dev.read_power(0)), also:
import time
from rbamp import RbAmp, RbAmpIOError
def bidirectional_loop(dev):
consume_wh = 0.0
export_wh = 0.0
t_prev = time.monotonic()
while True:
# Sample RT power at 10 Hz — matches the firmware-commit
# cadence (100 ms per channel). Faster yields empty repeated
# reads; slower loses resolution on sharp load transitions.
time.sleep(0.1)
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.0:
consume_wh += dwh
else:
export_wh += -dwh
Unter MicroPython ersetzen Sie time.monotonic() durch time.ticks_ms() / time.ticks_diff() (genauer und speichersparend auf eingebetteten Plattformen) und time.sleep(0.1) durch time.sleep_ms(100). Unter CPython sind keine Änderungen nötig.
Ein vollständiges Arbeitsbeispiel des Musters finden Sie in 06_examples.md, im Szenario „Bidirektionale Messung auf Masterseite“, sowie in den Quelldateien examples_upy/07_bidirectional_energy.py und examples_cpython/05_bidirectional_energy.py.
STANDARD (STD) — ausgelieferte Modulreihe
STANDARD-Module sind eine ausgelieferte Modulreihe, die diese Bibliothek ab Version 1.6.0 unterstützt. Sie verwenden ein anderes (16-Bit-)Registerabbild als BASIC; die Bibliothek verbirgt den Unterschied — dieselbe Klasse RbAmp, dieselbe I²C-Verdrahtung und Adresse sowie dieselben gemeinsamen Leser.
Was die Bibliothek auf einem STD-Modul ergänzt:
-
Energie auf dem Gerät:
dev.read_std_energy()liefert die eigenen Lebensdauer-Zähler des Moduls — Wirkenergie Bezug / Einspeisung / netto sowie Blindenergie, in den Auflösungen Wh, mWh und µWh, mit Werten pro Kanal.RbAmp.std_energy_delta(prev, now)liefert die zwischen zwei Messwerten verbrauchte Energie und ist stromausfallsicher. Für diese Zähler integrieren Sie auf dem Master keine Leistung. -
Periodenmessung:
read_period_snapshot()und die übrigen Periodenaufrufe funktionieren wie bei BASIC.begin()wählt die Quelle — die Energiezähler des Moduls (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. Die Energie ist netto (Export wird abgezogen). -
Latch-Bänke (Module, die sie melden):
dev.std_arm_banks(mask),dev.std_latch(bank),dev.std_read_latch(bank),RbAmp.std_latch_wh(snap, dt_ms). -
Mehrphasen-Hilfsfunktionen:
dev.read_voltage_angle(phase),dev.read_phase_sequence(),dev.read_reactive(ch)(nur STD; bei BASIC wird Blindleistung von dieser Bibliothek nicht bereitgestellt),dev.read_apparent(ch). -
Anlaufstrom:
dev.get_start_current()/dev.set_start_current(µA)+dev.save_config(). -
Vollständige Blöcke:
dev.read_std_voltage(),read_std_channel(),read_std_totals(),read_std_config(),read_std_health(),dev.set_time().
Notes:
-
Einige STD-Aufrufe brauchen ein hinreichend aktuelles Modul-Image (Mikro-Einheiten-Energiezähler, Spannungswinkel, Anlaufstrom). Stellt das Modul ein solches nicht bereit, löst der Aufruf
RbAmpNotSupportedError(„nicht verfügbar“) aus. -
Verwenden Sie
dev.is_std, um im Anwendungscode zu verzweigen. -
Konfiguration von Sensorklasse und CT-Modell, Reset und Adressänderung, die Identitätsregister, der Fehler-/Ereigniskanal, die Flottenhilfsfunktionen und
wait_ready()sind nur für BASIC; bei einem STD-Modul lösen sieRbAmpNotSupportedErroraus. -
Energie auf dem Gerät, Winkel und Anlaufstrom sind auf CPython (
smbus2) validiert. Der 16-Bit-Pfad für MicroPython ist implementiert, aber noch nicht an Hardware validiert — verwenden Sie für diese Funktionen CPython, bis eine Versionsnotiz etwas anderes sagt.
Vollständige Signaturen: 09 · API-Referenz.
Modulreihe zur Laufzeit erkennen
In der aktuellen Firmware gibt es kein explizites Register für die „Modulreihe“. Indirekte Hinweise sind über die Handle-Eigenschaften verfügbar:
# Firmware version — opaque byte
fw = dev.firmware_version
# Presence of a voltage sensor (UI* variants vs I*-only)
voltage_hw = dev.has_voltage_hw
# Number of current channels (1 / 2 / 3 on BASIC; 5 / 7 on UI5 / UI7)
channels = dev.channels
# BASIC variant byte (1=UI1, 2=UI2, 3=UI3, 4=I1, 5=I2, 6=I3, 7=UI5, 8=UI7)
variant = dev.read_variant()
# Module line: True on an STD module (detected in begin())
is_std = dev.is_std
: dev.is_std zeigt Ihnen die Modulreihe (STD oder BASIC). Die übrigen Angaben (Firmware-Version, Kanalzahl, Vorhandensein eines Spannungssensors, Variante) beschreiben das Modul, identifizieren aber nicht die Modulreihe. dev.read_variant() ist das Varianten-Byte von BASIC; verwenden Sie das SKU-Etikett auf dem Modulgehäuse als maßgebliche Quelle für das Produkt.
Wo modulreihenabhängige Stellen in der Dokumentation gekennzeichnet sind
In den Paket-Texten und der kanonischen Dokumentation sind modulreihenabhängige Funktionen ausdrücklich gekennzeichnet, zum Beispiel:
— dieser Aufruf ist auf einem BASIC-Modul nicht verfügbar.
Oder umgekehrt, BASIC-spezifisches Verhalten:
: Der Zähler dev.energy.wh(ch) ist monoton — Einspeisung ins Netz wird nicht gezählt. Für die Zweirichtungsmessung siehe das Szenario „Zweirichtungsmessung auf Masterseite“ in 06_examples.md, oder verwenden Sie ein STANDARD-Modul, bei dem die Periodenenergie netto ist und dev.read_std_energy() getrennte Bezugs- und Einspeisezähler hat.
Wie es weitergeht
-
03 · Auswahl des Stromsensors — welcher SCT-013 für welche Aufgabe
-
04 · Verdrahtung — Hardware-Details für jeden Host (RPi / ESP32 / RP2040 / STM32 / Pyboard)
-
06 · Beispiele — Szenarien für BASIC, einschließlich bidirektionaler Messung auf Masterseite
-
09 · API-Referenz — die vollständige öffentliche API
Quelle & Issues: rb-amp/rbamp-python · diese Seite im Repo: docs/02_tiers.md (v1.6.1)