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

02 · Modulstufen

Die Modulreihen BASIC und STANDARD (STD) und was jede bietet.

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)

BASIC zählt nur den Verbrauch auf dem Modul, während die Einspeisung auf dem Master behandelt wird; STD führt die kumulativen Zähler auf dem Gerät.

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:

Python
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 sie RbAmpNotSupportedError aus.

  • 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

So erkennen Sie zur Laufzeit, ob das angeschlossene Modul ein BASIC- oder ein STANDARD-(STD)-Modul ist.

In der aktuellen Firmware gibt es kein explizites Register für die „Modulreihe“. Indirekte Hinweise sind über die Handle-Eigenschaften verfügbar:

Python
# 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
Hinweis

: 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:

Nur STD

— dieser Aufruf ist auf einem BASIC-Modul nicht verfügbar.

Oder umgekehrt, BASIC-spezifisches Verhalten:

BASIC

: 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


Quelle & Issues: rb-amp/rbamp-python · diese Seite im Repo: docs/02_tiers.md (v1.6.1)