01 · Überblick
rbAmp ist ein kompaktes Hardwaremodul zur präzisen Messung von Netzwechselstromparametern über die I²C-Schnittstelle. Es basiert auf einem Mikrocontroller mit integriertem, galvanisch getrenntem Analogfrontend und Werkskalibrierung im Flash.
Was rbAmp ist
Der Hauptzweck der Bibliothek — Überwachung mehrerer Lasten
components/rbamp ist dafür ausgelegt, mit einer Gruppe von Modulen an einem einzigen I²C-Bus gleichzeitig zu arbeiten, statt ein einzelnes Gerät zu steuern. Das kanonische Szenario ist ein Hauptmodul am Netzeinspeisepunkt plus N Module an einzelnen Lasten, alle an einem Bus, von einem ESP32 gesteuert. Die Bibliothek stellt ein Fleet-Handle bereit: ein einziges Objekt, über das Sie den Bus scannen, jedes Modul in einem Aufruf abfragen, die Gesamtleistung und die Bilanz „Einspeisung − Σ(Lasten)“ erhalten, Fehler je Modul abfangen und — bei Bedarf — Periodensnapshots mit einem Broadcast-Befehl synchronisieren.
Mehrkanal-Module werden ebenfalls unterstützt — die reinen Strommodule I2 / I3 (2 / 3 Stromkanäle) und die mit Spannung ausgestatteten UI2 / UI3 / UI5 / UI7 (2 / 3 / 5 / 7 Stromkanäle, mit Leistung, PF und Wh je Kanal). Jeder Kanal hat sein eigenes CT-Sensormodell. Das ist typisch für eine Unterverteilung, bei der ein Einspeisepunkt mehrere Abgänge überwacht: Ein Modul liefert eine Aufschlüsselung je Kanal, ohne ein eigenes Modul an jedem Abgang.
Wichtiges Architekturdetail. Leistung und Wh benötigen eine UI-Variante; eine Bilanz „Netz minus Summe der Lasten“ braucht ein UI-Modul an jeder Last. Die I-Varianten (I1/I2/I3) messen nur Strom — sie haben keine Spannung, keine Wirkleistung und keinen PF. Wirkenergie (Wh) und Leistung werden nur auf den UI-Varianten berechnet (die ein Spannungs-Frontend haben). Im kanonischen Aufbau übernimmt die Rolle „Netzzähler“ (Gesamtenergie) eine einzelne UI1 am Netzeingang, während die Rolle Teilzähler (Stromdetail je Last) von I2/I3-Modulen übernommen wird (oder von UI2 / UI3 / UI5 / UI7, wenn Leistung und Wh je Last nötig sind).
Die Arbeit mit einem einzelnen Modul ist der Minimalfall derselben Bibliothek: rbamp_handle_t ist der Baustein, auf dem die Flotte aufbaut. Haben Sie ein einziges Modul am Bus, verwenden Sie direkt dasselbe Handle — keine Flotten-API nötig.
Das 80-%-Szenario — Netzanschluss + N Unterlasten
- 1 Modul am Einspeisepunkt (Netz) — Gesamtverbrauch und Netzqualität.
- N Module an einzelnen Lasten — Abrechnung je Kanal.
- Auch Mehrkanal-Module passen zu diesem Fall: Ein UI2 / UI3 / UI5 / UI7 (oder I2 / I3) kann mehrere Lasten messen, jede auf ihrem eigenen Kanal — N Module müssen nicht N Lasten bedeuten.
-
Ein einzelner Flottenaufruf
rbamp_fleet_poll_all()fragt alles ab; die BilanzNetz − Σ(Teillasten)zeigt den „Rest“ (Grundverbrauch, nicht erfasste Lasten, Leckagen). -
Eine gemeinsame Master-Zeitmarke → korrekte Wh-Buchung ohne Drift zwischen den Modulen (siehe 02_tiers.md und den Abschnitt zur Master-Wanduhr in 09_api_reference.md).
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 | float, V | 0…300 V |
| Spitzenspannung U_peak | float, V | 0…450 V |
| Effektivstrom I_rms | float, A | hängt vom gewählten Sensor ab — siehe 03_sensor_selection.md |
| Spitzenstrom I_peak | float, A | abhängig vom gewählten Sensor |
| Wirkleistung P (in RT vorzeichenbehaftet) | float, W | abhängig vom gewählten Sensor |
| Leistungsfaktor PF | float | −1…+1 |
| Netzfrequenz | uint8, Hz | 50 / 60 Hz (erkannt) |
| P über eine Periode gemittelt | float, W | wie P |
Der Echtzeitwert der Wirkleistung P ist auf jeder Modullinie immer vorzeichenbehaftet (negativ = Einspeisung ins Netz). Das Verhalten des periodengemittelten Werts (avg_p[ch] in rbamp_period_snapshot_t) hängt von der Modullinie ab — siehe Abschnitt „Module lines“ unten und 02_tiers.md.
Verdrahtung
Das Modul ist mit vier Leitungen auf der NS-Seite mit dem Master verbunden. Die einzige Netzreferenz (der L/N-Spannungseingang bei UI*-Varianten) sitzt hinter einem galvanisch getrennten Teiler, und die CT-Zange koppelt magnetisch ohne elektrischen Kontakt; siehe 04 · Verdrahtung, „Netz- und CT-Anschluss“ (Netzspannung kann tödlich sein — lesen Sie zuerst die Warnung dort).
| Draht | Zweck |
|---|---|
VCC |
+5 V (4.5..5.5 V), ~15 mA, Spitze ~25 mA. Eingebauter Spannungsregler und Filterung |
GND |
gemeinsam mit dem Master (erforderlich) |
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 ~10 µs alle ~100 ms |
Die Standardadresse ist 0x50 (7-Bit, einstellbarer Bereich 0x08..0x77), die empfohlene Geschwindigkeit ist 50 kHz am ESP32 (siehe den Abschnitt zur Disziplin aus Wiederholung und Plausibilität weiter unten). Kaltstart bis zur ersten gültigen Messung ist ~250 ms.
Die vollständigen Regeln (Buslänge, Pull-up-Empfehlungen an einem Multi-Modul-Bus, Verdrahtungsschemata für die verschiedenen ESP32-Ziele) stehen im Kapitel 04 · Verdrahtung.
Modullinien (Kurzübersicht)
BASIC und STANDARD (STD)-Module werden ausgeliefert. BASIC folgt der Logik eines klassischen mechanischen Zählers — einseitige Abrechnung (nur Verbrauch); STD führt vorzeichenbehaftete Energiezähler:
| Stufe | RT-Leistung P |
Akkumulator pro Periode avg_p[ch] |
Wh-Zähler der Komponente |
|---|---|---|---|
| BASIC | vorzeichenbehaftet (negativ = Einspeisung ins Netz, in Echtzeit sichtbar) | jedes 100-ms-Fenster der mittleren P wird auf max(P, 0) begrenzt, bevor es zum Periodenakkumulator addiert wird |
monotonic — Buchung nur des Verbrauchs |
| STANDARD (STD) | vorzeichenbehaftet; zudem Blind- und Scheinleistung | Snapshot-Bänke oder Zählerdifferenzen — die Einspeisung bleibt erhalten (Bezug und Einspeisung werden getrennt gezählt) | vorzeichenbehafteter Nettowert (negativ = Nettoeinspeisung) |
Details siehe Kapitel 02 · Modulstufen. Auf Komponentenebene wird dasselbe rbamp_handle_t-Handle unabhängig von der Stufe verwendet — rbamp_begin() erkennt die Modulstufe (rbamp_line()); die Unterschiede zeigen sich in den Werten, die das Modul liefert, und in den zusätzlichen rbamp_std_*-Aufrufen, die ein STD-Modul anbietet.
Bidirektionale Abrechnung auf BASIC: rbamp_energy_wh(dev, ch) auf der BASIC-Stufe liefert nur den Verbrauch. Wenn Sie die Einspeisung getrennt erfassen müssen, fragen Sie die Echtzeitleistung rbamp_read_power(dev, 0, &p) mit ~10 Hz ab und teilen die positiven und negativen Abtastwerte selbst in zwei Akkumulatorvariablen auf. Ein Beispiel finden Sie in 06_examples.md (Szenario 9, „Bidirektionale Messung auf der Master-Seite“).
Was diese Komponente leistet
esp_timer_get_time().
Die Komponente übernimmt auch die Periodenbuchführung: Sie nimmt einen Snapshot, wartet, bis sich das Modul eingeschwungen hat, prüft, dass der Snapshot gültig ist, und integriert Wh gegen die Master-Uhr (rbamp_read_period_snapshot() und rbamp_energy_wh(), siehe 05 · Schnellstart, Schritt 5). Der Vergleich auf Registerebene („ohne die Komponente“), das Architekturdiagramm, die Interaktionsdiagramme und die Zuordnungstabelle stehen in 09 · API-Referenz, Anhang „Under the hood“.
Logging und Kconfig
Anders als bei der Arduino-Bibliothek, wo der Log-Strom zur Laufzeit konfiguriert wird (setLogStream(&Serial)), gilt hier das übliche ESP-IDF-Muster: Die Komponente protokolliert unter dem Tag "rbamp" über esp_log. Die Log-Stufe wird zur Compilezeit festgelegt über die Kconfig-Auswahl CONFIG_RBAMP_LOG_LEVEL_* (NONE / ERROR / WARN / INFO / DEBUG, standardmäßig INFO). Bei NONE werden die Log-Strings vollständig aus dem Binary entfernt.
Der Laufzeitfilter funktioniert ebenfalls (über esp_log_level_set("rbamp", ...)), ist aber von oben durch den Compile-Zeit-Level begrenzt.
Sechs CONFIG_RBAMP_*-Symbole sind in idf.py menuconfig → Komponentenkonfiguration → rbAmp-Client (Component config → rbAmp client) verfügbar:
| Symbol | Zweck | Standard |
|---|---|---|
CONFIG_RBAMP_DEFAULT_I2C_FREQ_HZ |
SCL-Frequenz für den gemeinsamen Bus | 50000 (50 kHz) |
CONFIG_RBAMP_I2C_TIMEOUT_MS |
Timeout beim Senden/Empfangen | 100 ms |
CONFIG_RBAMP_NACK_RETRY_ATTEMPTS |
Wiederholungsversuche je Einbyte-Lesevorgang | 3 |
CONFIG_RBAMP_NACK_RETRY_GAP_MS |
Pause zwischen Wiederholungsversuchen | 5 ms |
CONFIG_RBAMP_DISABLE_ENERGY |
den Wh-Akkumulator aus dem Build entfernen | n |
CONFIG_RBAMP_LOG_LEVEL_* |
Kompilierzeit-Stufe der Log-Strings | INFO |
Mehr Details finden Sie in 09 · API-Referenz, Abschnitt „Compile-time configuration“.
Was als Nächstes kommt
- 02 · Modulstufen — welche Stufe für welche Aufgabe
- 04 · Verdrahtung — Pull-ups, Buslänge, Pinbelegung der ESP32-Familie
- 05 · Schnellstart — Ihr erstes funktionierendes Projekt
- 06 · Beispiele — Schritt-für-Schritt-Anleitungen zu fertigen IDF-Projekten
- 09 · API-Referenz — jede öffentliche Funktion
- 10 · Fehlerbehebung — wenn etwas nicht funktioniert
Quelle & Issues: rb-amp/rbamp-esp-idf · diese Seite im Repo: docs/01_overview.md (v1.7.3)