rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten [Edit on GitHub]

02 · Modulstufen

Die Modullinien BASIC und STANDARD (STD) nebeneinander: Energie auf dem Master bei BASIC, auf dem Modul bei STD.

Was eine Modullinie ist

Prüfen Sie das Etikett an Ihrem Modul; dev.line() gibt nach begin() die Linie aus.

rbAmp gibt es in Modullinien: BASIC und STANDARD (STD). Eine Modullinie ist eine vollständige Paarung aus Hardwarerevision und Firmware, kein Software-Flag. Ein Wechsel zwischen Modullinien erfordert einen physischen SKU-Wechsel, kein Firmware-Update.

Aus Sicht der Bibliothek und Ihres Codes gilt: eine Klasse RbAmp bedient beide Produktlinien. begin() erkennt, ob ein Modul BASIC oder STANDARD (STD) ist, und leitet jeden Aufruf intern weiter; die gemeinsamen Methoden (readVoltage(), readCurrent(), readPower(), readPeriodSnapshot(), energy() …) funktionieren auf beiden. Die STD-Linie ergänzt eigene Aufrufe — Blind- und Scheinleistung, Lesen von Blöcken je Kanal, vorzeichenbehaftete Lebensdauer-Energiezähler — siehe 09 · API-Referenz.

Aktueller Status

Die Stufe BASIC und die Linie STANDARD (STD) sind ausgelieferte Modullinien; diese Bibliothek unterstützt beide (STANDARD (STD) ab Bibliothek 1.6.0, siehe README).

Stufe Auslieferung
BASIC ✅ ja
STANDARD (STD) ✅ ja (Bibliothek 1.6.0+)

BASIC — Einstiegsstufe für die Verbrauchsmessung

Hardware

Ein kostenoptimierter Analogpfad für typische Haushaltslasten. Das Modul enthält ein galvanisch getrenntes Analogfrontend, einen Onboard-Spannungsregler und eine im Flash gespeicherte Werkskalibrierung.

Verhalten der Firmware

Die Logik eines klassischen mechanischen Ferraris-Zählers — der Zählerstand läuft nur vorwärts; die Einspeisung ins Netz wird nicht abgezogen.

Die drei "Ebenen" der Wirkleistungswerte verhalten sich unterschiedlich:

Signal Bedeutung Verhalten bei BASIC
dev.readPower(ch) momentane RT-Leistung, aktualisiert etwa alle 100 ms vorzeichenbehaftet — ein negativer Wert ist in Echtzeit sichtbar (Einspeisung)
PERIOD_AVG_P_W (innerhalb von readPeriodSnapshot) Durchschnittsleistung über die Periode der Mittelwert der Wirkleistung jedes 100-ms-Fensters wird begrenzt auf max(P, 0), bevor er zum Periodenakkumulator addiert wird
dev.energy().wh(ch) Vom Bibliothek akkumulierte Wh monoton — nur Verbrauch; Einspeisung wird nicht gezählt

Anders gesagt: der Anwender sieht die Einspeisung im RT-Messwert, sie fehlt aber im Wh-Zähler der Bibliothek auf BASIC.

Typische Anwendungsfälle

  • Haushalte ohne eigene Erzeugung (keine Solarmodule, Windkraftanlagen oder Batteriespeicher)

  • Zähler für rein verbrauchende Lasten (Warmwasserbereiter, Motoren, Haushaltsgeräte)

  • Verbrauchsüberwachung im Gebäude, wo bidirektionale Messung nicht nötig ist

Bidirektionale Messung auf BASIC (masterseitig)

Energieabrechnung auf BASIC (Verbrauch im Modul, Einspeisung auf dem Master integriert) und auf STANDARD (STD) (Import-, Export- und Nettozähler im Modul).

Wenn Sie die Einspeisung in das Netz auf einem BASIC-Modul getrennt erfassen müssen, tun Sie das auf der Masterseite. Die RT-Leistung dev.readPower(0) ist vorzeichenbehaftet, daher gilt:

C++
double consume_wh = 0.0;
double export_wh  = 0.0;
uint32_t t_prev_ms = millis();

void loop() {
    // Sample RT power at 10 Hz — matches the firmware-commit cadence
    // (100 ms per channel). Faster gives empty repeat reads; slower
    // loses resolution on abrupt load transitions.
    //
    // delay() blocks the loop — incompatible with concurrent work
    // (LCD refresh, MQTT, networking). For sketches with other tasks,
    // replace it with a non-blocking millis() / scheduler pattern.
    delay(100);
    uint32_t t_now_ms = millis();
    float dt_s = (t_now_ms - t_prev_ms) / 1000.0f;
    t_prev_ms = t_now_ms;

    float p = dev.readPower(0);
    if (isnan(p)) return;

    double dwh = (double)p * dt_s / 3600.0;
    if (p >= 0) consume_wh += dwh;
    else        export_wh  += -dwh;
}

Ein vollständiges funktionierendes Beispiel finden Sie in 06_examples.md (das Szenario BidirectionalEnergy) und in examples/06_BidirectionalEnergy/.

STANDARD (STD) — bidirektionale Linie

STANDARD-(STD)-Module sind eine ausgelieferte Modullinie. Die Bibliothek erkennt sie in begin() (dev.line() == RbAmpLine::Std) und verwendet dieselbe Verdrahtung und dieselbe gemeinsame API wie BASIC (siehe 04 · Verdrahtung).

Was die STD-Linie hinzufügt

Bei einem STD-Modul mit gespeicherten Zählern kommen die Perioden-/Momentaufnahme-API und die Energie aus den eigenen Zählern des Moduls (ältere STD-Images nutzen die Momentaufnahmebänke des Moduls); die CT-Modellangabe ist beim STD nur eine Bezeichnung und setzt keine Verstärkung.

  • Vorzeichenbehaftete Energie: Import und Export werden getrennt erfasst. Bei Modulen, die persistente Lebensdauer-Zähler führen, übernehmen dev.energy() und readPeriodSnapshot() die eigenen Werte des Moduls (wh_net = Import − Export), und stdReadEnergy() liefert die Rohzähler (Wh, mWh und auf Images, die sie bereitstellen, µWh / µvarh).

  • Weitere Größen (bei BASIC stellt diese Bibliothek keine Blindleistung bereit): readReactivePower(ch), readApparentPower(ch), stdReadChannel(ch) (I / P / Q / S / PF / Spitze in einem Burst) und, wenn aktiviert, aus Oberschwingungen abgeleitete Werte (THD, Verschiebungs-PF).

  • Module mit mehreren Kanälen / Spannungen: Die Kanalanzahl kommt vom Modul; stdReadVoltage(v), Summen je Phase mit stdReadTotals(k).

  • Diagnose und Service: stdReadHealth(), Modulzeit, Verlauf und Ereignisprotokoll, Identifikation per UID, Firmware-Update über I²C.

Alles davon ist Aufruf für Aufruf aufgeführt in 09 · API-Referenz § STD-Linien-API.

Abhängigkeit vom Image.

Einige STD-Funktionen hängen von der Image-Version des Moduls ab: Energiezähler mit Mikroauflösung, der Anlaufstrom für die Energie, Spannungsphasenwinkel und die Phasenfolge benötigen eine Image-Version von mindestens 0x0001007B (dev.stdReadImageVersion()); bei einem älteren Image werden sie als "nicht verfügbar" gemeldet. Nur für STD gedachte Aufrufe an einem BASIC-Modul liefern RB_ERR_NOT_IMPLEMENTED.

Typische Anwendungsfälle

  • Haushalte mit Dach-Solarstromerzeugung
  • Haushalte mit Windkraftanlagen
  • Batteriespeichersysteme
  • Rückspeisende Lasten
  • V2G (Fahrzeug-zu-Netz) EV-Laden

So erkennen Sie die Linie zur Laufzeit

So erkennen Sie, welche Modullinie Sie besitzen: Lesen Sie das Etikett oder rufen Sie nach begin() die Funktion line() auf.

C++
if (!dev.begin()) { /* see dev.errorString() */ }

// Product line, detected by begin(): BASIC or STANDARD (STD)
RbAmpLine line = dev.line();          // RbAmpLine::Basic / RbAmpLine::Std

// Firmware version — opaque byte
uint8_t fw = dev.firmwareVersion();

// Presence of a voltage sensor (UI* variants vs I*-only)
bool voltage_hw = dev.hasVoltageHw();

// Number of current channels
uint8_t channels = dev.channels();

// Full SKU — variant byte (REG_HW_VARIANT)
RbAmpVariant variant = dev.readVariant();   // UI1, UI2, UI3, I1, I2, I3, UI5, UI7 …
Hinweis

: line() zeigt BASIC oder STANDARD (STD) an. Die übrigen Angaben (Firmwareversion, Kanalanzahl, Spannungssensor, SKU) beschreiben die Hardware. Das SKU-Etikett auf dem Gehäuse des Moduls bleibt die maßgebliche Quelle für das Produkt.

Wo stufenabhängige Punkte in der Dokumentation gekennzeichnet sind

Im gesamten Bibliothekstext und in der kanonischen Dokumentation sind stufenabhängige Funktionen ausdrücklich gekennzeichnet, zum Beispiel:

nur STANDARD (STD)

— dies ist bei 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 bidirektionale Messung siehe das Beispiel BidirectionalEnergy oder verwenden Sie ein STANDARD-(STD)-Modul.

Was als Nächstes kommt


Quelle & Probleme: rb-amp/rbamp-arduino · diese Seite im Repo: docs/02_tiers.md (v1.6.2)