rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten

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

Überblick, wie Anwendung, Bibliothek, I²C-Bus und rbAmp-Module zusammenpassen.

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.

Sicherheit

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

Ein Master an einem gemeinsamen I²C-Bus mit einem Netzmodul an der Einspeisung und Teilmodulen an einzelnen Abzweigen, eine Zange je Modul.

  • 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 Bilanz Netz − Σ(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
Hinweis

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.

Hinweis

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

Zeitachse aufeinanderfolgender 100-ms-Messfenster, der optionalen Data-Ready-Impulse und eines vom Master ausgelösten Periodensnapshots.
Seine Hauptaufgabe ist, den Protokollaustausch zu verbergen und den Anwendercode von der Routine für Register, Byte-Reihenfolge und Abklingzeiten nach Befehlen zu entlasten. Zusätzlich die Komponenteberechnet Energie (Wh)— das Modul liefert nur die periodengemittelte Leistung, und die Integration erfolgt durch den Master überesp_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


Quelle & Issues: rb-amp/rbamp-esp-idf · diese Seite im Repo: docs/01_overview.md (v1.7.3)