01 · Überblick
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
- 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(oderI2/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 BilanzNetz − Σ(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).
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 |
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.
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.
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)
// 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
float u_rms = dev.readVoltage();
Die Periode auslesen — ohne Bibliothek
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
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_PERIODund ein korrektes Lesen der Momentaufnahme (atomare Momentaufnahme auf Modulseite). -
Prüfung des Flags
PERIOD_VALIDvor 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
Interaktionsdiagramme
Der Ablauf von begin()
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)
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
- 02 · Modulstufen — welche Stufe für welche Aufgabe
- 04 · Anschluss — Pull-ups, Buslänge, Mehrmodul-Konfiguration
- 05 · Schnellstart — der erste funktionierende Sketch
- 06 · Beispiele — eine Durchsicht fertiger Sketches
- 09 · API-Referenz — jede öffentliche Methode
- 10 · Fehlerbehebung — wenn etwas nicht funktioniert
Quelle und Probleme: rb-amp/rbamp-arduino · diese Seite im Repository: docs/01_overview.md (v1.6.2)