02 · Modulstufen
rbAmp wird in zwei Modulreihen geliefert: BASIC und STANDARD (STD). Jede Stufe ist eine vollständige Kombination aus Hardwarerevision und Firmware-Build, kein bloßes Flag in der Firmware. Der Wechsel zwischen den Stufen erfordert den physischen Austausch des Moduls, kein Firmware-Update.
Die ESPHome-Komponente arbeitet mit beiden Modulreihen aus einem YAML: Das Schema ist gemeinsam, und die Komponente erkennt die angeschlossene Modulreihe (BASIC oder STANDARD (STD)) beim Start automatisch. Die Unterschiede liegen darin, welche Daten das Modul tatsächlich liefert und welche YAML-Schlüssel auf der jeweiligen Modulreihe sinnvoll sind.
Stufen
BASIC — Einstiegsstufe
Die Firmware behält die unidirektionale Verbrauchsmessung bei: Die mittlere Wirkleistung über eine Periode kann nie negativ werden — Gegenrichtungsabschnitte im Fenster werden vor der Integration auf null gesetzt. Das verhält sich ähnlich wie ein klassischer mechanischer Ferraris-Zähler.
- Die Energie wird auf dem ESP32 aus der Periodenmittel-Leistung integriert, die das Modul nach jedem Snapshot liefert, und im Flash des ESP32 (NVS) gespeichert.
- Der Sensor
energy_exportedexistiert im YAML-Schema (aus Kompatibilitätsgründen), auf BASIC veröffentlicht er aber immer0. - Die Gesamtenergie-Sensoren (
energy_total,energy_exported_total,energy_net,reactive_energy,reactive_energy_exported) werden auf BASIC validiert, veröffentlichen aber nie. - Typische Anwendungen: Wohnungen ohne eigene Erzeugung, Unterzählung einzelner Verbraucher (Warmwasserbereiter, Motoren, Haushaltsgeräte, Heizung/Lüftung/Klima).
STANDARD (STD) — bidirektional, Energie im Gerät
STANDARD (STD) ist die aktuelle Modulreihe. Sie misst Bezug und Einspeisung getrennt und führt ihre eigenen kumulativen Energiezähler im Modul.
- Dasselbe YAML. Die Komponente erkennt beim Start ein STANDARD-Modul (STD) und übernimmt Kanalanzahl, Variante und verfügbare Funktionen vom Modul. Sie setzen keine Stufe und brauchen
topology:nicht. - Energie aus den Zählern des Moduls. Die Komponente akkumuliert die Zähler des Moduls, statt die Leistung selbst zu integrieren, sodass die Summen Neustarts sowohl des ESP32 als auch des Moduls überstehen, über Neustarts des Moduls und Zählerresets hinweg monoton bleiben und nicht driften. Die Werte werden zusätzlich alle 5 Minuten und beim sauberen Herunterfahren (Neustart / OTA) im Flash des ESP32 (NVS) gespeichert.
- Neue Sensoren:
energy_total,energy_exported_total,energy_net(Bezug − Einspeisung, kann sinken),reactive_energy,reactive_energy_exported— Gesamtsummen über alle Kanäle; bei Dreispannungsvarianten zusätzlichvoltage_angle_b,voltage_angle_cundphase_sequence. - Energie je Kanal
energyundenergy_exported(mitbidirectional: true) stammen aus denselben Zählern. start_current_ua:legt einen Anlaufstrom fest, unterhalb dessen ein Kanal keine Energie zählt, damit Rauschen bei Nulllast nicht in die Zähler schleicht.- Typische Anwendungen: Häuser mit Solar- oder Windstrom, Batteriespeicher, E-Auto-Ladestationen und jede Installation, in der Import und Export getrennt gemessen werden müssen, sowie Installationen, bei denen Energiesummen Neustarts überstehen müssen.
Bei einem STD-Modul kommt die Energie aus den eigenen Zählern des Moduls; latch_interval gilt nur für BASIC.
Schlüssel, die nur für die BASIC-Modulreihe existieren (fleet_gc_enable:, group_id:, broadcast_latch:, latch_interval: für den Energiepfad auf Master-Seite) werden auf einem STANDARD-Modul mit einer Protokollzeile ignoriert.
Fähigkeitsmatrix
| Fähigkeit | BASIC | STANDARD |
|---|---|---|
| Effektivspannung (RMS) | ja | ja |
| Effektivstrom (RMS) (1..3 Kanäle, mehr bei Varianten mit mehr Kanälen) | ja | ja |
| Wirkleistung (vorzeichenbehafteter Float) | ja | ja |
| Leistungsfaktor | ja | ja |
| Blindleistung (vom Modul gelesen, Kanäle 0..2; vorzeichenlos, berechnet als √(S² − P²), enthält Verzerrungen; keine Genauigkeit angegeben) | ja | ja |
| Scheinleistung (nur CH0) | ja (U × I[0], auf dem ESP32 berechnet) |
ja (vom Modul) |
| Netzfrequenz | ja | ja |
Sensor energy (Bezug in Wh), im NVS gespeichert |
ja (auf dem ESP32 integriert) | ja (aus Zählern im Gerät) |
Sensor energy_exported (benötigt bidirectional: true) |
immer 0 | ja |
| Energie überlebt Neustarts von ESP32 und Modul | nur ESP32 | ja |
Gesamtsummen: energy_total, energy_exported_total, energy_net |
nein | ja |
Blindenergie: reactive_energy, reactive_energy_exported |
nein | ja |
start_current_ua: |
nein | ja |
voltage_angle_b/_c, phase_sequence (Varianten mit drei Spannungen) |
nein | ja |
Kanalweise ct_models: |
ja | nur wenn das Modul kanalweise Modelle speichert; andernfalls mit einer Protokollzeile verweigert |
fleet_gc_enable: / group_id: General-Call-Synchronisation |
ja (Firmware v1.3+) | ignoriert |
Die Komponente liest nur, was für Sensoren deklariert ist — ein nicht deklariertes Register wird nie angefragt.
YAML-Schlüssel nach Stufe
bidirectional: (Standard false)
Aktiviert die Sensoren für die Exportenergie je Kanal (energy_exported, energy_exported_1, energy_exported_2).
rbamp:
id: solar_meter
address: 0x51
bidirectional: true # meaningful on STANDARD; on BASIC the export sensors read 0
Bei STANDARD stammt die Exportenergie aus den Zählern des Moduls. Bei BASIC akzeptiert das Schema den Schlüssel ohne Fehler, aber energy_exported liefert immer 0. Die Gesamtsummen-Sensoren energy_exported_total und energy_net brauchen diesen Schlüssel nicht.
sensor_class: — Sensorfamilie festlegen
rbamp:
id: meter1
sensor_class: SCT_013 # default SCT_013
Auf beiden Modulreihen akzeptiert. Ab Firmware v1.2 wird der Wert in den Flash geschrieben und ist eine Voraussetzung für das Schreiben des CT-Modells: Das Modul verweigert das Schreiben des Modells, wenn die Klasse nicht gesetzt ist. Einen Wert, den das Modul bereits hat, schreibt es nicht erneut.
Aufzählungswerte: SCT_013 (geteilte SCT-013-Zangen, Standard), WIRED_CT und BUILTIN_CT (Module, die zusammen mit ihrem eigenen eingebauten Sensor kalibriert geliefert werden). Bei einem solchen werkseitig gepaarten Modul wird eine Änderung von Klasse oder Modell aus dem YAML mit einer Protokollzeile abgewiesen, um die individuelle Kalibrierung zu schützen.
ct_model: / ct_models: — CT-Klemmenmodell
Ein einziges globales Profil für alle Kanäle:
rbamp:
id: meter1
ct_model: SCT_013_030 # all channels — SCT-013-030
Oder ein Profil je Kanal (für UI3 mit gemischten Zangen):
rbamp:
id: meter_ui3
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
Bei beiden Modulreihen akzeptiert, gegenseitig ausschließend. Bei Firmware v1.2+ lädt das Modul für das gewählte Modell automatisch die Werkskoeffizienten — keine weiteren Kalibrierschritte nötig. Bei älterer Firmware wird der Wert als Modellmarkierung gespeichert.
- Ein Wechsel des SCT-Nennwerts erhält die Werksgenauigkeit: Die Komponente schließt den Wechsel ab (ein Neustart des Moduls im Ablauf ist bei Firmware bis 1.4.19 normal; neuere Firmware korrigiert im Modul) und skaliert die Messwerte auf den gewählten Sensor.
- Schreibschutz: Ein gleicher Wert wird nicht geschrieben; bei einem werkseitig gepaarten Modul wird die Änderung mit einer Protokollzeile verweigert.
ct_model_force: true(Dienstoption, nur gültig zusammen mitct_model:/ct_models:) setzt dies bewusst außer Kraft. - Kanalweise
ct_models:bei einem STANDARD-Modul setzen voraus, dass das Modul die Modelle pro Kanal speichert; sonst verweigert die Komponente laut (Warnung, Schlüssel werden ignoriert) — verwenden Siect_model:.
Zur Auswahl eines Modells siehe 03_sensor_selection.md.
new_address: — einmalige I²C-Adressvergabe
rbamp:
id: meter1
address: 0x50
new_address: 0x51 # one-shot; remove after a successful boot
Auf beiden Modulreihen akzeptiert. Bei Firmware v1.3+ ist die Adressänderung produktionstauglich — die Komponente verwendet ein zweiphasiges Commit-Protokoll (vormerken → scharfschalten → committen → neu starten) ohne besonderen Modus. Bei Legacy-Firmware (v1.0-v1.2) erfordert der einphasige Fallback den Werks-Provisioning-Modus; das Verfahren zur Aktivierung erfahren Sie in der Modul-Dokumentation oder beim Lieferanten. Der Werks-Provisioning-Modus ist auf allen Firmwareversionen weiterhin erforderlich für Kalibrierung (saveGains) und Zurücksetzen auf Werkseinstellungen.
Ablauf über einen einzigen Start: Die Komponente fragt die aktuelle Adresse ab, schreibt die neue Adresse und speichert sie im Flash, setzt das Modul zurück und prüft die Antwort auf der neuen Adresse. Nach Erfolg aktualisieren Sie das YAML auf address: 0x51 und entfernen new_address:. Stellt die Komponente fest, dass die alte Adresse stumm ist, während die neue antwortet, passt sie sich automatisch an und protokolliert eine Warnung (falls ein früherer Start die Änderung bereits angewendet hat).
fleet_gc_enable: / group_id: — synchroner Snapshot für einen Mehrmodul-Bus
rbamp:
- id: meter1
fleet_gc_enable: true # v1.3 production path — recommended
group_id: 1 # cluster id (modules in the same group snapshot together)
Ist sie aktiviert, sendet die Komponente einen 5-Byte-General-Call-Frame an die I²C-Broadcast-Adresse — sie synchronisiert den Periodensnapshot aller Module in derselben group_id in einer einzigen Transaktion.
Bei BASIC-Firmware v1.3 ist der General-Call-Snapshot per Opt-in aktivierbar und an eine Fähigkeit gebunden. Die Komponente prüft beim Start, ob die Firmware ihn ankündigt, und aktiviert den Pfad automatisch, wenn YAML-Schlüssel und Firmware übereinstimmen. Bei Alt-Firmware (v1.0..v1.2) wird er nicht angekündigt; die Komponente weicht auf einen sequenziellen Snapshot je Modul aus und protokolliert eine Informationszeile. Bei einem STANDARD-Modul werden diese Schlüssel mit einer Protokollzeile ignoriert.
Der veraltete Schlüssel broadcast_latch: wird aus Gründen der Abwärtskompatibilität vom Schema weiter akzeptiert, hat aber keine Wirkung. Verwenden Sie fleet_gc_enable: + group_id:.
Der Versatz zwischen Modulen auf einem 50-kHz-Bus liegt in der Größenordnung von ~540 µs × N, was weniger als 0.003 % einer 60-Sekunden-Periode ausmacht. Bei täglichen HA-Summen ist diese Ungleichmäßigkeit nicht wahrnehmbar.
topology: — Topologiehinweis
rbamp:
id: meter1
topology: SINGLE # SINGLE / SPLIT_PHASE / THREE_PHASE
Optional und bei STANDARD-Modulen nicht nötig, dort kommen Kanalanzahl und Variante vom Modul selbst. Bei BASIC-Modulen leitet die Komponente die Kanalanzahl aus den deklarierten Sensor-Slots ab (wenn current_1 deklariert ist, gibt es mindestens 2 Kanäle). Der Schlüssel ist kosmetisch und erscheint in der Protokollzeile dump_config.
drdy_pin: — optionaler Interrupt für Datenbereitschaft
rbamp:
id: meter1
drdy_pin: GPIO15
Auf beiden Modulreihen akzeptiert. Verbindet sich mit dem optionalen Open-Drain-Ausgang DRDY des Moduls. Der Pin wird konfiguriert und protokolliert, die Momentanregister werden aber unabhängig davon über update_interval abgefragt. Bei einem typischen update_interval: 60s kann der Schlüssel entfallen.
Erfordert einen 10-kΩ-Pull-up am Master-GPIO gegen 3.3 V (der Ausgang ist Open-Drain; auf Modulseite gibt es keinen internen Pull-up). Siehe 04_hardware.md.
Übersichtstabelle — YAML-Schlüssel × Modulreihe
| YAML-Schlüssel | BASIC | STANDARD | Hinweise |
|---|---|---|---|
address: |
ja | ja | — |
update_interval: |
ja | ja | Minimum 1s |
latch_interval: |
ja | n/a | Entkoppelt den Snapshot-/Energietakt vom Lesetakt; STANDARD liest seine Zähler bei jedem update() |
drdy_pin: |
ja | ja | Optional, benötigt einen 10-kΩ-Pull-up; wird nicht als Lese-Auslöser verwendet |
topology: |
ja | nicht nötig | Informativer Hinweis |
sensor_class: |
ja | ja | Nicht neu geschrieben, wenn gleich; bei werkseitig gepaarten Modulen verweigert |
ct_model: / ct_models: |
ja | ja | Gegenseitig ausschließend; die Liste je Kanal setzt bei STANDARD ein Modul voraus, das sie speichert |
ct_model_force: |
ja | ja | Dienstoption; das Schema verlangt einen Modellschlüssel |
bidirectional: |
akzeptiert (Export liest 0) | funktioniert | Nötig für die Sensoren energy_exported* je Kanal |
start_current_ua: |
wird mit einer Warnung ignoriert | funktioniert | 0 oder 10..2540 in Schritten von 10 |
new_address: |
ja | ja | Produktions-OK bei BASIC-Firmware v1.3+; einmalig |
fleet_gc_enable: / group_id: / broadcast_latch: |
ja | ignoriert | Die Synchronisation per General-Call ist ein Merkmal der BASIC-Linie |
Sensor energy_exported |
immer 0 | funktioniert | Benötigt bidirectional: true |
energy_total, energy_exported_total, energy_net, reactive_energy[_exported] |
veröffentlicht nie | funktioniert | Gesamtsummen aus Zählern am Gerät |
voltage_angle_b/_c, phase_sequence |
veröffentlicht nie | funktioniert bei Dreiphasen-Varianten mit Firmware, die diese bereitstellt | Siehe 09 §2.2–2.3 |
Phasensensoren (voltage_a/b/c, current_a/b/c, …) |
keine Werte | veröffentlichen für die Kanäle, die das Modul meldet | Details in 09 §2.2 |
Wie es weitergeht
- 03_sensor_selection.md — Auswahl einer CT-Zange und das Verhalten von
ct_model:/ct_models: - 04_hardware.md — physische Verdrahtung, GPIO-Auswahl
Quelle und Probleme: rb-amp/rbamp-esphome · diese Seite im Repository: docs/02_tiers.md (v1.9.1)