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

01 · Überblick

Signalkette vom Stromwandler über das Modul rbAmp und I²C zum Master und weiter zur Cloud oder zu Home Assistant.

Was rbAmp ist

rbAmp ist ein kompaktes Hardwaremodul zur Präzisionsmessung von Netzwechselstromgrößen über die I²C-Schnittstelle. Es besitzt ein integriertes galvanisch getrenntes Analogfrontend und eine im Flash gespeicherte Werkskalibrierung.

Aus Sicht des Integrators verhält sich das Modul wie ein Standard-I²C-Slave: Versorgung anschließen, Register lesen, und Sie erhalten fertige Werte in physikalischen Einheiten. Auf der Masterseite ist keine Signalverarbeitung nötig.

Der Hauptzweck der Bibliothek — Überwachung mehrerer Lasten

Die Arduino-Bibliothek RbAmp ist dafür gebaut, eine Gruppe von Modulen gleichzeitig an einem einzigen I²C-Bus zu betreiben, nicht ein einzelnes Gerät. Der Standardfall ist ein Hauptmodul am Netzanschluss plus N Module an einzelnen Lasten, alle an einem Bus, betrieben von einem einzigen Arduino/ESP32. Die Bibliothek stellt die Klasse RbAmpFleet bereit — ein einziges Objekt, über das Sie den Bus scannen, alle Module mit einem Aufruf abfragen, die Gesamtleistung und die Bilanz „Einspeisung − Σ(Lasten)“ erhalten, Fehler je Modul abfangen und bei Bedarf die Periodensnapshots per 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 aufgesetzt ist. Haben Sie ein einziges Modul am Bus, verwenden Sie direkt denselben Handle — die Fleet-API ist nicht nötig.

Das 80-%-Szenario — Netzanschluss + N Unterlasten

Ein Modul am Netzanschluss und ein Modul je Unterlast, alle an einem gemeinsamen I²C-Bus, der von einem einzigen Master gelesen wird.

  • 1 Modul am Netzanschluss — Gesamtverbrauch und Netzqualität.
  • N Module an einzelnen Lasten — Messung je Kanal.
  • Auch Mehrkanal-Module passen auf diesen Fall: ein UI2 / UI3 / UI5 / UI7 (oder I2 / I3) kann mehrere Lasten messen, jede auf eigenem Kanal — N Module müssen nicht N Lasten bedeuten.
  • Ein einziger Aufruf fleet.pollAll() fragt alles ab; die Bilanz Netz − Σ(Unterlasten) zeigt „den Rest“ (Grundverbrauch, nicht gemessene Lasten, Leckagen).

  • Ein gemeinsamer Master-Zeitstempel → korrekte Wh-Messung ohne Drift zwischen den Modulen (siehe 02_tiers.md und den Abschnitt zur Wanduhr des Masters in 09_api_reference.md).

Sicherheit

Wichtiges architektonisches Detail. Die I-Varianten (I1/I2/I3) messen nur Strom — sie haben keine Spannung, keine Wirkleistung und keinen PF. Wirkenergie (Wh) und Leistung werden nur bei UI-Varianten berechnet (die einen Spannungseingang haben). In der kanonischen Installation übernimmt eine einzelne UI1 am Netzeinspeisepunkt die Rolle des "Netzzählers" (Tarif- / Periodenmessung); die Rolle des Unterzählers (Stromdetails je Last) übernehmen I2/I3-Module (oder UI2 / UI3 / UI5 / UI7, wenn Leistung und Wh je Last benötigt werden).

Details finden Sie im Kapitel 06 · Beispiele, Szenario 1 ("Netz + N Teillasten — der 80-%-Kanon"). Zur API siehe Kapitel 09 · API-Referenz, Abschnitt "Fleet-Manager".

Was rbAmp misst

Größe Typ Bereich
Effektivspannung U_rms float32, V 0…300 V
Spitzenspannung U_peak float32, V 0…450 V
Effektivstrom I_rms float32, A hängt vom gewählten Sensor ab — siehe 03_sensor_selection.md
Spitzenstrom I_peak float32, A abhängig vom gewählten Sensor
Wirkleistung P (in RT vorzeichenbehaftet) float32, W abhängig vom gewählten Sensor
Leistungsfaktor PF float32 −1…+1
Netzfrequenz uint8, Hz 50 / 60 Hz (erkannt)
Periodengemittelte P float32, W wie bei P
Hinweis

Der RT-Wert der Wirkleistung P ist auf jeder Modulstufe immer vorzeichenbehaftet (negativ bedeutet Einspeisung ins Netz). Das Verhalten des periodengemittelten Werts (PERIOD_AVG_P_W) hängt von der Modulstufe ab — siehe Abschnitt „Modulstufen“ unten und 02_tiers.md.

Anschluss

Das Modul verbindet sich mit dem Master über vier Leitungen auf der Niederspannungsseite; alles, was das Netz berührt, bleibt innerhalb des Gehäuses.

Draht Zweck
VCC +5 V (4.5..5.5 V), Strom ca. 15 mA, Spitze ca. 25 mA. Onboard-Regler und Filterung
GND gemeinsam mit dem Master (zwingend)
SDA, SCL I²C, 3.3-V-Logik, 5-V-tolerant. Eingebaute 4.7-kΩ-Pull-ups gegen 3.3 V
DRDY optional, Open-Drain LOW für ca. 10 µs alle ca. 100 ms

Die Standardadresse ist 0x50 (7-Bit, Änderungsbereich 0x08..0x77), bei 100 kHz (UNO / Mega / STM32 / RP2040) oder 50 kHz (ESP32 / ESP8266); verwenden Sie nicht 400 kHz. Kaltstart bis zur ersten gültigen Messung ca. 250 ms.

Die vollständigen Regeln (Buslänge, Pull-up-Empfehlungen auf einem Mehrmodul-Bus, Verdrahtungsschemata mit verschiedenen Hosts) stehen in Kapitel 04 · Anschluss.

Modulstufen (Kurzübersicht)

Die Stufe BASIC realisiert eine einseitige (nur Verbrauch) Messung nach der Logik eines klassischen mechanischen Zählers; die Linie STANDARD (STD) ist eine zweite ausgelieferte Modullinie mit vorzeichenbehafteter (Import / Export) Energie:

Stufe RT-Leistung P Periodenakkumulator PERIOD_AVG_P_W Bibliotheks-Wh-Zähler
BASIC vorzeichenbehaftet (negativ = Einspeisung ins Netz, in Echtzeit sichtbar) jedes 100-ms-Fenster des mittleren P wird auf max(P, 0) begrenzt, bevor es dem Periodenakkumulator hinzugefügt wird monoton — erfasst nur den Verbrauch
STANDARD (STD) vorzeichenbehaftet Bezug und Einspeisung getrennt erfasst (Snapshot-Bänke oder die gespeicherten Lebensdauerzähler des Moduls) Nettoenergie = Import − Export (wh_net, stdReadEnergy())

Details stehen im Kapitel 02 · Modulstufen. Auf Bibliotheksebene wird dieselbe RbAmp-Klasse unabhängig von der Stufe verwendet; die Unterschiede zeigen sich in den Werten, die das Modul liefert.

Hinweis

Bidirektionale Messung auf BASIC: dev.energy().wh(ch) der Bibliothek liefert auf der Stufe BASIC nur den Verbrauch. Wenn Sie die Einspeisung getrennt erfassen müssen, fragen Sie die Wirkleistung im RT-Modus dev.readPower(0) mit etwa 10 Hz ab und teilen Sie die positiven und negativen Abtastwerte selbst auf zwei Akkumulatorvariablen auf. Ein Beispiel steht in 06_examples.md (das Szenario BidirectionalEnergy).

Was diese Bibliothek tut

Die Hauptaufgabe ist, den Protokollaustausch zu verbergen und das Anwendungsprogramm von der Routine der Registerarbeit, der Byte-Reihenfolge und den Einschwingzeiten nach Befehlen zu entlasten. Außerdem berechnet die Bibliothek die Energie (Wh) — das Modul liefert nur die periodengemittelte Leistung, die Integration übernimmt der Master mit seiner eigenen Uhr.

Hinweis

Bauen Sie für ESPHome? Verwenden Sie stattdessen die externe Komponente statt dieser Bibliothek direkt — sie integriert das rbAmp-Protokoll nativ in die ESPHome-YAML-Verarbeitung.

Ohne die Bibliothek (direkter Registerzugriff)

C++
// Reading U_RMS — in four transactions.
Wire.beginTransmission(0x50);
Wire.write(0x86);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
uint8_t b0 = Wire.read();
// ...repeat for b1, b2, b3...
float u_rms;
uint8_t buf[4] = {b0, b1, b2, b3};
memcpy(&u_rms, buf, 4);

Mit der Bibliothek

C++
float u_rms = dev.readVoltage();

Die Periode auslesen — ohne Bibliothek

C++
Wire.beginTransmission(0x50);
Wire.write(0x01); Wire.write(0x27);   // CMD_LATCH_PERIOD
Wire.endTransmission();
uint32_t t_latch_ms = millis();
delay(50);                            // settling time after the command

Wire.beginTransmission(0x50);
Wire.write(0x07);
Wire.endTransmission(false);
Wire.requestFrom((uint8_t)0x50, (uint8_t)1);
if ((Wire.read() & 0x01) == 0) {
    // snapshot is stale — t_latch_ms must STILL be recorded,
    // otherwise the next snapshot will count Wh over two periods
    t_prev_latch_ms = t_latch_ms;   // <-- this line is easy to forget
    return;
}
// ...read 4 bytes of avg_p, assemble the float, integrate Wh:
//   float dt_s = (millis() - t_prev_latch_ms) / 1000.0f;
//   E_Wh += avg_p × dt_s / 3600.0f;

Die Periode lesen — mit der Bibliothek

C++
RbAmpPeriodSnapshot snap;
if (dev.readPeriodSnapshot(snap)) {
    // snap.avg_p[0] is filled,
    // dev.energy().wh(0) was incremented by avg_p × master_dt_s / 3600,
    // master_dt_ms is accounted for and saved for the next cycle.
}

Intern garantiert die Bibliothek:

  • Eine Einschwingzeit von 50 ms nach CMD_LATCH_PERIOD und ein korrektes Lesen der Momentaufnahme (atomare Momentaufnahme auf Modulseite).

  • Prüfung des Flags PERIOD_VALID vor dem Lesen.

  • Zeitpunkt gegen die Uhr des Masters festhalten, auch bei einer veralteten Momentaufnahme (schützt vor Doppelzählung der Wh in der nächsten Periode).

  • Wh-Akkumulation je Kanal mit doppelter Genauigkeit.

  • Automatisches Laden der Kalibrierkoeffizienten, wenn ein Stromsensor über setSensorClass(class) + setCTModel(code) gewählt wird — der Anwender muss die Register NF/GAIN nicht kennen.

Wann die Bibliothek und wann der direkte Registerzugriff

Aufgabe Bibliothek Direkter Registerzugriff
Lesen von U / I / P / PF / Frequenz ✅ nur zum Debuggen mit einem Logikanalysator
Periodenbezogene Energiemessung ✅ nur wenn Wh außerhalb der Bibliothek gespeichert werden (z. B. in einer Datenbank auf der Masterseite)
Mehrere Module an einem Bus ✅ —
Bidirektionale Messung auf BASIC ✅ (über RT-Lesungen — siehe 06_examples.md) Alternative — eigene Schleife aus RT-Lesungen und manueller Integration
Portierung auf eine Nicht-Arduino-Plattform n/a ✅ — siehe 09 · API-Referenz, Abschnitt "Details zum Bus-Protokoll"
Harte RAM-Grenze (AVR Uno) ca. 42 B je RbAmp-Instanz + 63 B je Snapshot; machbar, aber knapp bei mehreren Modulen (3 Module × ca. 42 B + 3 × 63 B ≈ 315 B belegen bereits einen spürbaren Anteil am RAM-Budget der Anwendung) ✅ wenn die Bibliotheksinstanz nicht passt

Für alle typischen Aufgaben in den ersten Zeilen passt die Bibliothek genau.

Architektur

Wo Ihr Sketch steht: Sketch, RbAmp-Bibliothek, Wire (I²C) und das rbAmp-Modul an der Standardadresse 0x50.

Interaktionsdiagramme

Der Ablauf von begin()

Ablauf von begin(): Versionslesezugriff, Erkennung der Linie, Vorlauf-Momentaufnahme (verworfen), dann bereit.

Die erste Momentaufnahme ist ein Vorlauf (das Modul liefert, was es seit dem Einschalten akkumuliert hat, und das ist für die Tarifzählung ungeeignet). Die Bibliothek merkt sich selbst, dass diese Momentaufnahme verworfen werden muss — der Anwendercode sieht sie nie.

Der Ablauf von readPeriodSnapshot(snap)

Ablauf von readPeriodSnapshot(): Die Bibliothek schließt die Periode auf dem Modul ab, liest die Momentaufnahme, integriert die Energie mit der Uhr des Masters und gibt das Ergebnis an den Sketch zurück.

Der atomare Snapshot auf Modulseite garantiert, dass jede Messung innerhalb der Periode in genau einem Snapshot landet — keine Doppelungen, keine Verluste an der Periodengrenze.

Zuordnung zur direkten Register-API

Eine Tabelle für Umsteiger aus eigenen Arbeiten, die auf direktem Zugriff aufbauen:

Direkte API Gleichwertig über die Bibliothek
Manuelles Lesen von 4 Byte + memcpy dev.readVoltage() / dev.readPower(ch)
Wire.write(0x01); Wire.write(0x27); delay(50) dev.latchPeriod(); delay(50) (oder einfach dev.readPeriodSnapshot())
Prüfung von Wire.read(0x07) & 1 dev.isPeriodValid()
Die manuelle Formel E_Wh += avg_p × dt_s / 3600 dev.energy().wh(0) — wird automatisch aktualisiert
Manuelle Konfiguration des Stromsensors über die direkte Register-API dev.setSensorClass(class) + dev.setCTModel(code) — Werkvoreinstellungen werden automatisch geladen

Was als Nächstes kommt


Quelle und Probleme: rb-amp/rbamp-arduino · diese Seite im Repository: docs/01_overview.md (v1.6.2)