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

09 · YAML-Schema-Referenz

rbAmp-Registerkarte — Adressraum der Seite 0 (0x00..0xFF)

Atomarer Periodensnapshot — ein Schreibvorgang schließt die Periode und öffnet die nächste

Dieses Kapitel ist die vollständige Referenz für das YAML-Schema der externen ESPHome-Komponente rbamp. Steht ein Schlüssel nicht hier, existiert er im Schema nicht.

Ein YAML für beide Modulreihen. Beim Start erkennt die Komponente, welche Modulreihe (BASIC oder STANDARD (STD)) angeschlossen ist, und passt sich automatisch an: Kanalanzahl, Variante und verfügbare Funktionen kommen vom Modul selbst, daher sind im YAML weder ein Schlüssel topology: noch ein Stufenwechsel nötig. Schlüssel, die nur für eine Generation gelten, sind unten gekennzeichnet; ein Schlüssel, den das angeschlossene Modul nicht erfüllen kann, wird mit einer Protokollzeile ignoriert und führt nie zu einem harten Fehler.

Contents:

  1. Komponentenblock — rbamp:
  2. Sensorplattform — sensor.platform: rbamp
  3. Datenfluss und Zeitverhalten
  4. I²C-Bus-Einstellungen

1. Komponentenblock — rbamp:

Der oberste Block rbamp: registriert eine Komponenteninstanz. Er erbt von PollingComponent (das update_interval bereitstellt) und i2c.I2CDevice (das address und das I²C-Bus-Handle bereitstellt). MULTI_CONF: True bedeutet, dass beliebig viele Blöcke rbamp: in einem YAML koexistieren können, jeder mit eigenem I²C-Slave.

YAML
rbamp:
  id: meter1
  address: 0x50
  update_interval: 60s
  drdy_pin: GPIO4
  sensor_class: SCT_013
  ct_model: SCT_013_030
  # or, for a UI3 with mixed clamps:
  # ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
  bidirectional: false
  new_address: 0x51
  fleet_gc_enable: false
  group_id: 0
  latch_interval: 60s
  start_current_ua: 400     # STANDARD only, see below
  # ct_model_force: true    # service option, see below

Jeder Schlüssel ist optional. topology: und broadcast_latch: werden aus Gründen der Abwärtskompatibilität weiterhin akzeptiert (siehe ihre Einträge).


id

Attribut Wert
Typ id (ESPHome-Kennung)
Standard Automatisch erzeugt
Erforderlich Nein

Vergibt eine stabile Kennung für die Instanz. Sensoren verweisen darauf über rbamp_id: meter1. Bei mehreren Blöcken rbamp: ist eine explizite id erforderlich.

YAML
rbamp:
  id: kitchen_meter

address

Attribut Wert
Typ i2c_address (7 Bit, 0x08..0x77)
Standard 0x50
Erforderlich Nein

Die aktuelle I²C-Adresse des rbAmp-Moduls. Die Werkseinstellung ist 0x50. Nach einer Adressänderung (über new_address) aktualisieren Sie diesen Schlüssel auf den neuen Wert und entfernen new_address.

Gültiger Bereich: 0x08..0x77 (die reservierten 7-Bit-I²C-Adressen sind ausgeschlossen).

YAML
rbamp:
  address: 0x52   # three modules on the bus: 0x50, 0x51, 0x52

Querverweis: das I²C-Bus-Protokoll in der API-Referenz; Adressänderung im Betrieb zum Ändern der Adresse nach dem Start.


update_interval

Attribut Wert
Typ time (ESPHome-Dauerzeichenfolge)
Standard 60s
Erforderlich Nein

Wie oft update() läuft. Jeder Aufruf:

  1. Sendet den Snapshot-Befehl und plant ein nicht blockierendes Timeout von 50 ms zum Lesen des Periodensnapshots (BASIC-Module; bei STANDARD-Modulen kommt die Energie aus den eigenen Zählern des Moduls, siehe energy_total).
  2. Prüft das Statusregister; ist das Modul bereit, veröffentlicht es alle gebundenen Momentan-Sensoren.

Der Standardwert von 60 s ist sinnvoll: Das Modul aktualisiert seine Periodenmittelleistung intern etwa alle ~100 ms, aber die Energieintegration auf Master-Seite braucht ein ausreichend langes Fenster, um korrekt zu sein. Bei 60 s und einer mittleren Last von 60 W verliert ein verpasster Snapshot ≤ 1 Wh.

Der kleinste erlaubte Wert ist 1s: Das Schema lehnt alles Kleinere ab, und esphome config meldet eine Diagnose. Werte unter 5–10 s bringen für die enge Synchronisation nichts und belasten nur den Bus.

YAML
rbamp:
  update_interval: 30s   # more frequent dashboard updates, more traffic

latch_interval

Attribut Wert
Typ time (ESPHome-Dauerzeichenfolge)
Standard Wie update_interval
Erforderlich Nein
Seit v1.4

Wie oft die Komponente den Snapshot-Befehl sendet und eine Wh-Probe integriert. Wenn gesetzt, wird der Snapshot-Zyklus vom RT-Lesetakt entkoppelt — update_interval: steuert weiterhin, wie oft die Register V/I/P/PF/Q gelesen und veröffentlicht werden, während latch_interval: steuert, wie oft der Periodenakkumulator per Snapshot erfasst und Wh integriert wird.

Die Energieintegration fügt über die Wirkleistungsgenauigkeit des Moduls hinaus keinen eigenen Fehler hinzu, unabhängig vom Verhältnis: Die Integration auf dem Master nutzt die tatsächliche Wanduhr-Differenz dt zwischen aufeinanderfolgenden Snapshot-Ereignissen, daher erzeugen längere Snapshot-Intervalle nur gröbere Integrationsschritte.

Muss >= update_interval sein (ein kürzerer Wert wird bei der Konfigurationsprüfung abgelehnt — die zusätzlichen Snapshots würden keine beobachtbaren Daten liefern).

Ist er nicht gesetzt, läuft der Snapshot bei jedem update()-Aufruf (Verhalten v1.3 mit einem Takt, abwärtskompatibel).

YAML
rbamp:
  update_interval: 3s        # RT V/I/P/PF refreshed every 3 s
  latch_interval: 60s        # snapshot + Wh integration once a minute

Nützlich, wenn Buslast oder CPU-Konkurrenz auf der Masterseite eine Rolle spielt — Mehrmodul-Flotten, ESP8266-Hosts (Einkern; WLAN-ISRs konkurrieren während I²C-Transaktionen um die CPU) oder gemeinsam genutzte I²C-Busse mit anderen Geräten.


drdy_pin

Attribut Wert
Typ gpio_input_pin_schema
Standard Keine (optional)
Erforderlich Nein

Verbindet den Open-Drain-Ausgang DRDY des Moduls mit einem GPIO des ESP32. Ist er angegeben, wird der Pin beim Start in setup() konfiguriert.

Hinweis

Der Pin wird in dump_config protokolliert, dient aber nicht als Lesetrigger — die Momentanregister werden über update_interval abgefragt. Die Deklaration des Pins ändert das Verhalten nicht.

YAML
rbamp:
  drdy_pin: GPIO4

sensor_class

Attribut Wert
Typ enum (SCT_013, WIRED_CT, BUILTIN_CT)
Standard SCT_013
Erforderlich Nein

Legt die Stromsensor-Familie auf Modulseite fest. 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. Bei älterer Firmware wird der Wert vom Schema akzeptiert und beim Upgrade automatisch übernommen.

Wert Bedeutung
SCT_013 Split-Core-SCT-013-Klemmen — der Standard
WIRED_CT Modul, mit eigenem eingebautem Sensor gemeinsam kalibriert geliefert
BUILTIN_CT Modul, das zusammen mit seinem eigenen eingebauten Sensor kalibriert geliefert wird

Schreibschutz. Die Komponente schreibt nie eine Klasse, die das Modul bereits hat (ein wiederholter Start schreibt nichts). Bei einem Modul, das zusammen mit seinem angebauten Sensor kalibriert wurde (WIRED_CT / BUILTIN_CT), wird eine Klassen- oder Modelländerung aus dem YAML verweigert — mit einer klaren Protokollzeile, weil der Schreibvorgang die individuelle Kalibrierung durch eine allgemeine Einstellung ersetzen würde. Lassen Sie sensor_class: und ct_model: bei solchen Modulen aus dem YAML, oder siehe ct_model_force.

YAML
rbamp:
  sensor_class: SCT_013   # default; may be omitted

Zur Wahl der Zange und der Familie siehe 03_sensor_selection.md.


ct_model

Attribut Wert
Typ enum (SCT_013_005, _010, _020, _030, _050)
Standard Keine (optional)
Erforderlich Nein

Schreibt die Kennung des CT-Zangenmodells in den Flash des Moduls. Ab Firmware v1.2 lädt dies automatisch die Werkskoeffizienten für das gewählte Modell — keine weiteren Kalibrierschritte nötig. Ein Wert, der dem bereits im Modul gespeicherten entspricht, wird nicht geschrieben.

YAML-Wert Code Nennstrom Status v1.3
SCT_013_005 1 5 A Produktion
SCT_013_010 2 10 A Produktion
SCT_013_020 6 20 A Produktion (neu in v1.3)
SCT_013_030 3 30 A Produktion (Standard-SKU)
SCT_013_050 4 50 A Produktion
Hinweis

Der Satz zulässiger Klassen für SCT_013 ist {1, 2, 3, 4, 5, 6, 7} (SCT_013_100 ist Code 5, SCT_013_060 ist Code 7; die Codereihenfolge entspricht nicht der Nennwertreihenfolge). Nicht passende Werte werden bei esphome config über cv.Invalid abgewiesen. Mehr dazu unter 03 · Auswahl des Stromsensors.

YAML
rbamp:
  ct_model: SCT_013_030

Einmal in setup() angewendet. Jeder Schreibvorgang geht mit einem Flash-Schreiben von ca. 700 ms einher (das Modul verweigert in dieser Zeit alle I²C-Operationen durch NACK — die Komponente speist den Watchdog automatisch).

Der Wechsel des SCT-Nennwerts erhält die Genauigkeit. Jedes SCT-Modul wird werkseitig auf den SCT-013-030 kalibriert. Wählen Sie einen anderen Nennwert, bleiben Strom, Leistung und Energie korrekt: Bei Firmware bis 1.4.19 schließt die Komponente das Schreiben des Modells mit einem Modul-Neustart ab (das gehört zum normalen Ablauf und erscheint im Log) und skaliert die Messwerte dann auf den gewählten Sensor; neuere Firmware führt den Wechsel auf dem Modul selbst durch, und die Komponente lässt die Messwerte unverändert. Spannung und Leistungsfaktor sind nicht betroffen. Dafür ist keine YAML-Änderung nötig.

Schreibschutz. Ein gleicher Wert wird nie geschrieben, und bei einem werkseitig gepaarten Modul (sensor_class: WIRED_CT / BUILTIN_CT) wird das Schreiben mit einer Protokollzeile verweigert — siehe sensor_class.

Gegenseitig ausschließend mit ct_models: — pro Block rbamp: darf nur einer von beiden verwendet werden.

Mehr dazu siehe 03_sensor_selection.md. Querverweis: die Referenz zu ct_model.


ct_models

Attribut Wert
Typ Liste mit 1–16 Enum-Werten
Standard Keine (optional)
Erforderlich Nein

CT-Zangenmodelle je Kanal — für Module mit gemischten Zangen auf verschiedenen Kanälen. Akzeptiert dieselben Aufzählungswerte wie ct_model:. Das Schema akzeptiert 1 bis 16 Einträge; die Position in der Liste ist der Kanalindex. Die Komponente wendet so viele Einträge an, wie das Modul Kanäle hat (1 für UI1, 2 für UI2, 3 für UI3 usw.); überzählige Einträge werden mit einer Warnung ignoriert.

YAML
rbamp:
  id: ui3_meter
  ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
  # CH0=5A for standby loads (maximum resolution),
  # CH1=30A for main household loads,
  # CH2=20A for a water heater / medium-power branch (~3-5 kW)
  # For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A)

Ab Firmware v1.2 erhält jeder Kanal einen eigenen Satz Werkskoeffizienten, unabhängig voneinander. Die gesamte Einrichtungszeit beim Start beträgt ca. 2–3 Sekunden (ca. 700 ms Flash-Schreibvorgang je Kanal).

STANDARD-Module. Kanalweise Modelle werden nur von Modulen gespeichert, die eine dauerhafte kanalweise Speicherung ankündigen. Bei einem Modul ohne diese Fähigkeit verweigert die Komponente laut (eine Warnung, dass ct_models: von diesem Gerät nicht unterstützt wird, Schlüssel ignoriert), statt einen Wert zu schreiben, der sich nach einem Stromzyklus still zurücksetzen würde — verwenden Sie dort das einzelne ct_model:.

Es gelten dieselben Schreibschutzregeln wie für ct_model: (gleiche Werte werden nicht geschrieben; werkseitig gepaarte Module verweigern die Änderung).

Schließt sich gegenseitig aus mit ct_model:.


ct_model_force

Attribut Wert
Typ bool
Standard false
Erforderlich Nein

Dienstoption. Überschreibt den Schreibschutz: Die Komponente wendet dann die Voreinstellung ct_model: / ct_models: an, auch wenn das Modul werkseitig gepaart ist oder bereits denselben Wert hält. Dies ersetzt die individuelle Kalibrierung des Moduls durch die generische Voreinstellung für dieses Modell. Verwenden Sie es daher nur bewusst, führen Sie es einmal aus und entfernen Sie es anschließend.

Das Schema lehnt ct_model_force: true ab, solange nicht auch ct_model: oder ct_models: vorhanden ist, damit das Flag nicht im YAML auf eine spätere Modellzeile „scharf“ liegen bleibt.

YAML
rbamp:
  ct_model: SCT_013_030
  ct_model_force: true   # one-off; remove both lines after the operation

start_current_ua

Attribut Wert
Typ Ganzzahl, Mikroampere
Erlaubte Werte 0 (aus) oder 10..2540 in Schritten von 10
Standard Keine (es gilt der eigene Standard des Moduls)
Erforderlich Nein
Gilt für STANDARD-Module mit Energiezählern im Gerät; anderswo mit Warnung ignoriert

Anlaufstrom für die Energieerfassung. Solange der Strom eines Kanals unter diesem Wert liegt, zählt das Modul auf diesem Kanal keine Energie. Ohne ihn ist die gemessene Leistung bei Nulllast Rauschen beider Vorzeichen und schleicht langsam in Import- und Exportzähler. Momentanwerte (Strom, Leistung usw.) sind nicht betroffen — nur die Energiezähler.

Werte außerhalb der erlaubten Menge (z. B. 15 oder 3000) lehnt das Schema ab, sodass ein ungültiger Wert nie den Bus erreicht. Die Einstellung wird im Modul gespeichert und nach dem Schreiben geprüft; ein Wert, der dem gespeicherten entspricht, wird nicht neu geschrieben.

YAML
rbamp:
  start_current_ua: 400

Den gespeicherten Wert können Sie aus einem Lambda mit id(meter1).read_start_current_ua() zurücklesen (liefert 65535, wenn nicht verfügbar).


period_banks

Attribut Wert
Typ Liste der Bankeinträge
Einträge je Liste 1..8, jede bank: (0..7) genau einmal aufgeführt
Standard Keine
Erforderlich Nein
Gilt für STANDARD-Module, die Snapshot-Bänke ankündigen (Image 0x7E und neuer); bei jedem anderen Modul bleiben die Einträge nicht verfügbar, und das Protokoll meldet das einmal beim Start

Das Modul führt acht unabhängige Snapshot-Bänke. Jeder Eintrag misst eine Periode — die Zeit zwischen zwei Erfassungen derselben Bank, gemessen mit dem Takt des ESP32 — und veröffentlicht die Mittelwerte, Spitzen und die Energie der Periode. Nutzen Sie das für „Energie pro Stunde“, „Spitzenstrom seit dem letzten Tastendruck“ und ähnliche Fragen, die die laufenden Summen nicht beantworten.

Schlüssel Bedeutung
bank Banknummer 0..7. Bank 0 ist auf Modulen mit Energiezählern im Gerät frei; auf einem Modul ohne Zähler verwendet die Komponente Bank 0 selbst, und der Eintrag wird mit einer Warnung ignoriert.
interval Optionaler automatischer Erfassungstakt, mindestens 1s. Ohne ihn wird die Bank nur durch die Aktion rbamp.latch_bank erfasst.
power, reactive_power, apparent_power Mittelwert über die Periode.
energy, energy_exported Wh importiert / exportiert im Zeitraum (keine Zähler — sie tragen state_class: measurement).
max_power, max_current, max_voltage, min_voltage Extremwerte innerhalb der Periode.
period_length Die Periodenlänge in Sekunden, gemessen vom ESP32.
channels Optionale Liste, ein Eintrag pro Stromkanal (erster Eintrag = Kanal 0), jeweils mit power, energy, energy_exported.

Der erste Latch einer Bank nach dem Start oder nach einem Neustart des Moduls startet nur die Periode; seine Werte werden verworfen, und die Sensoren veröffentlichen ab dem nächsten Latch. Latches verschiedener Bänke liegen mindestens 150 ms auseinander.

YAML
rbamp:
  id: meter1
  period_banks:
    - bank: 1
      interval: 1h
      power: {name: "Hour average power"}
      energy: {name: "Hour energy"}
      max_current: {name: "Hour peak current"}
    - bank: 2                    # latched by hand
      energy: {name: "Energy since last press"}
      period_length: {name: "Since last press, s"}

button:
  - platform: template
    name: "Latch bank 2"
    on_press:
      - rbamp.latch_bank:
          id: meter1
          bank: 2

Ein vollständiges Beispiel finden Sie in example/std_banks.yaml.


bidirectional

Attribut Wert
Typ bool
Standard false
Erforderlich Nein

Aktiviert den Exportenergiepfad je Kanal (energy_exported, energy_exported_1, energy_exported_2). Bei true wird die Exportenergie getrennt von der Importenergie akkumuliert.

Bei einem STANDARD-Modul stammt die Exportenergie aus den eigenen Zählern des Moduls, sie überlebt daher Neustarts und ist monoton. Bei einem BASIC-Modul ist die Leitung unidirektional: Die Sensoren energy_exported_* werden vom Schema akzeptiert, veröffentlichen aber 0.

Deklarieren Sie energy_exported (oder _1 / _2) unter sensor.platform: rbamp nur, wenn bidirectional: true gesetzt ist. Die Gesamtsummen-Sensoren energy_exported_total und energy_net brauchen diesen Schlüssel nicht.

YAML
rbamp:
  bidirectional: true   # needed for the per-channel energy_exported* sensors

new_address

Attribut Wert
Typ i2c_address (0x08..0x77)
Standard Keine (optional)
Erforderlich Nein

Löst beim Start einen einmaligen Wechsel der I²C-Adresse aus. Sie muss sich von address unterscheiden — der Validator meldet einen Fehler, wenn sie gleich sind.

Bei Firmware v1.3 wird ein zweiphasiger Commit verwendet — produktionstauglich ohne Werks-Provisioning-Sperre. Kompatibilitätsverhalten:

Firmware Verhalten
Bietet den zweiphasigen Adress-Commit an (v1.3+) Produktionspfad — gestaffeltes Schreiben, ausdrückliche Bestätigung, Commit, erneute Aufzählung.
Nicht angekündigt (Alt-Firmware v1.0-v1.2) Legacy-Fallback — einphasiges Schreiben, erfordert den Werkseinstellungsmodus. Protokolliert WARN_FACTORY_MODE_REQUIRED, wenn sich das Gerät nicht im Provisioning-Modus befindet.

STANDARD-Module unterstützen new_address: ebenfalls; die Komponente wendet es an und bindet sich auf dieselbe Weise an die neue Adresse.

Der vollständige Ablauf läuft einmal in setup():

  1. Die aktuelle address prüfen. Antwortet das Modul dort nicht, aber unter new_address, übernimmt die Komponente die neue Adresse mit einer Warnung (unter der Annahme, dass ein früherer Start die Änderung bereits angewendet hat) und überspringt den Schreibvorgang.
  2. Prüfen Sie, ob die Firmware den zweiphasigen Commit anbietet. Ja → Produktionspfad (siehe unten). Nein → Legacy-Pfad mit der Prüfung des Provisioning-Modus.
  3. Produktionspfad (v1.3): neue Adresse vorbereiten, bestätigen, übernehmen → ca. 700 ms warten → new_address erneut prüfen. Ein Gating über den Werks-Provisionierungsmodus ist nicht erforderlich.
  4. Alter Weg (v1.0-v1.2): einphasiger Schreibvorgang, erfordert den Werks-Provisionierungsmodus auf Modulseite.
  5. Die Komponente wechselt ihre interne I²C-Adresse über i2c::I2CDevice::set_i2c_address() auf new_address und prüft, ob das Modul antwortet.
  6. Antwortet das Modul nach der Änderung nicht, ruft die Komponente mark_failed() auf und stoppt.

Nach erfolgreicher Änderung: Aktualisieren Sie das YAML auf address: und entfernen new_address:. Ist das Modul beim nächsten Start unter der neuen Adresse, new_address: aber noch im YAML, schlägt die Prüfung der alten Adresse beim Start fehl, die Prüfung der neuen gelingt, die Komponente passt sich mit einer Warnung an, und es wird nichts neu geschrieben.

Sicherheit

⚠ Nur im Werksmodus bei Alt-Firmware (v1.0-v1.2).

Serienmäßige Produktionsmodule mit älterer Firmware wurden mit deaktiviertem Provisioning-Modus ausgeliefert. Das Schreiben von new_address: auf ein solches Modul ohne Factory-Modus wird abgewiesen (Warnung WARN_FACTORY_MODE_REQUIRED). Bei Firmware v1.3 entfällt diese Einschränkung — die Komponente erkennt den Produktions-OK-Pfad automatisch.

⚠ Neuaufzählung nach dem Commit. Nach einem erfolgreichen Commit setzt das Modul zurück und zählt unter der neuen Adresse neu auf. Folgeaufrufe innerhalb desselben setup() gehen transparent an die neue Adresse — aber jeder andere Master am Bus (ein Roh-I²C-Werkzeug, eine Debug-Sonde, ein anderer ESP32) hält das Modul so lange für unter der alten Adresse, bis er seinen eigenen Zustand aktualisiert.

YAML
rbamp:
  address: 0x50
  new_address: 0x51   # remove this line after the first successful boot

Wiederherstellung: Wurde die Adressänderung angewendet, das Modul antwortet aber nicht, siehe 10_troubleshooting.md → „Adresse geändert, das Modul antwortet aber nicht“.

Querverweis: die Referenz zur Adressänderung zur Laufzeit.


fleet_gc_enable (v1.3 NEU)

Attribut Wert
Typ bool
Standard false
Erforderlich Nein
Gilt für BASIC-Module mit Unterstützung des General-Call-Snapshots (Firmware v1.3+); bei STANDARD mit einer Protokollzeile ignoriert

Aktivierung per Opt-in: Ermöglicht den Empfang des General-Call-Snapshots vom Master. Sendet der ESP32 einen 5-Byte-GC-Frame an die Adresse 0x00, nehmen alle Module mit fleet_gc_enable: true (und passender group_id:) gleichzeitig einen Snapshot ihrer Periodenakkumulatoren zu einem einzigen Zeitpunkt auf dem Draht. Das liefert enge Synchronisation zwischen den Unterzählern.

Fähigkeitsverhalten: Beim Start prüft die Komponente, ob die Firmware den General-Call-Snapshot ankündigt. Tut sie es nicht → Warnung + Überspringen ohne Anwendung:

Text
[W][rbamp:xxx]: fleet_gc_enable requested but the module does not advertise general-call latch;
firmware v1.0-v1.2 doesn't support General-Call. Falling back to sequential
latch (~270 µs × N inter-module skew at 50 kHz).

Persistenz: Beim Anwenden schreibt die Komponente REG_FLEET_CONFIG.bit0, speichert über CMD_SAVE_USER_CONFIG im Flash und setzt das Gerät zurück — der GC-Modus wird bei der Initialisierung konfiguriert, nicht live umgeschaltet. Über den Vergleich Lesen-Vergleichen-Schreiben geschieht dies beim ersten Start einmal; spätere Starts überspringen es.

YAML
rbamp:
  - id: mains
    fleet_gc_enable: true     # opt-in, capability-gated
    group_id: 1               # see below
  - id: boiler
    fleet_gc_enable: true
    group_id: 1               # same group → synchronized

Querverweis: die Referenz zur Fleet-Group-Commit-Synchronisation, 04_hardware.md Mehrmodul-Flotte.


group_id (v1.3 NEU)

Attribut Wert
Typ uint8_t (0..255)
Standard 0
Erforderlich Nein
Gilt für BASIC-Module; auf STANDARD mit Protokollzeile ignoriert

Eine Clusterkennung für die selektive GC-Snapshot. Das Modul akzeptiert einen GC-Frame nur, wenn das Gruppenfeld im Frame mit dieser group_id übereinstimmt ODER gleich 0x00 ist (Gesamtaufruf).

Anwendungsfälle:

  • Mehrmandantenbetrieb: Ein ESP32 steuert mehrere unabhängige Cluster von Modulen (z. B. 3 Wohnungen in einem Schaltschrank). Cluster 1 = group_id: 1, Cluster 2 = group_id: 2. Der Master sendet einen GC-Frame mit group=1 → nur Cluster 1 nimmt einen Snapshot.

  • Einzelner Mandant: group_id: 0 belassen (alle Adressen) oder group_id: 1 als Bezeichnung setzen — das Verhalten ist identisch, alle Module nehmen einen Snapshot.

Persistenz: Geschrieben in REG_GROUP_ID und über Lesen-Vergleichen-Schreiben im Flash gespeichert. Eine Änderung erfordert einen Start.

YAML
rbamp:
  - id: apt1_mains
    group_id: 1
  - id: apt2_mains
    group_id: 2

broadcast_latch (veraltet, Legacy-Stand v0.4.0)

Attribut Wert
Typ bool
Standard false
Erforderlich Nein
Status Veraltet — ersetzt durch fleet_gc_enable: (v1.3+).

Ein veralteter Alias für den General-Call-Broadcast-Snapshot. In v1.3 akzeptiert das Schema diesen Schlüssel als No-Op (für eine nicht-brechende Migration von YAML v0.4.0), er hat aber keine Wirkung. Für neuen Code verwenden Sie fleet_gc_enable: — es ist fähigkeitsgesteuert und funktioniert mit Firmware v1.3.

Er wird in einer künftigen Nebenversion entfernt; im Protokoll erscheint eine Veralterungswarnung:

Text
[W][rbamp:xxx]: 'broadcast_latch:' is deprecated since v1.3 — use
'fleet_gc_enable:' instead. This key has no effect.

Querverweis: die Referenz zum Fleet-Group-Commit.


topology

Attribut Wert
Typ enum (SINGLE, SPLIT_PHASE, THREE_PHASE)
Standard SINGLE
Erforderlich Nein

Optionaler Hinweis, aus Gründen der Abwärtskompatibilität beibehalten. Auf STANDARD-Modulen wird er nicht benötigt: Die Komponente liest Kanalanzahl, Variante und Fähigkeiten aus dem Modul selbst und dimensioniert die Entitätsmenge daraus. Bei BASIC-Modulen wird die Kanalanzahl aus den deklarierten Slots current[_1/_2] abgeleitet; topology: ändert nur die Zeile, die dump_config ausgibt.

YAML
rbamp:
  topology: SINGLE         # cosmetic; may be omitted

2. Sensorplattform — sensor.platform: rbamp

Jeder Block sensor: deklariert einen Satz benannter Sensoren, die an die übergeordnete Komponente rbamp: gebunden sind. Der einzige Pflichtschlüssel im Block ist rbamp_id.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"

Alle Felder unter dem Block sensor: sind optional, mit einer Regel: power, energy, power_factor, reactive_power und apparent_power benötigen voltage UND current, deklariert im selben Block (die nummerierten Kanalsensoren power_N, energy_N, power_factor_N, reactive_power_N benötigen current_N und voltage); andernfalls schlägt esphome config mit „power requires current to also be declared“ fehl. Fügen Sie internal: true zu einem benötigten Sensor hinzu, den Sie nicht als Home-Assistant-Entität möchten. Deklarieren Sie nur die Größen, die Ihr Szenario braucht — die Komponente liest nur die Register, die den deklarierten Sensoren entsprechen.

rbamp_id

Attribut Wert
Typ use_id(RbAmpComponent)
Erforderlich Ja

Verweist auf den Block rbamp:, an den diese Sensorgruppe gebunden ist.


2.1 Einzelne Felder

Für Module mit einer Spannung (UI1, UI2, UI3, I1, I2, I3 und Varianten mit mehr Kanälen) verwendet. Alle Felder sind optional. Die Mischung mit phasenbezogenen Feldern (voltage_a, voltage_angle_b usw.) führt zu einem Validierungsfehler.

Slots gibt es für bis zu sieben Stromkanäle: current und current_1 ... current_6, ebenso power, energy und power_factor mit denselben Suffixen (power_3, energy_5, ...). energy_exported gibt es für die Kanäle 0..2 (energy_exported, energy_exported_1, energy_exported_2). Ein Slot über der vom Modul gemeldeten Kanalanzahl veröffentlicht nie. reactive_power gibt es nur für die Kanäle 0..2 (reactive_power, reactive_power_1, reactive_power_2); reactive_power_3 ... reactive_power_6 akzeptiert das Schema, sie veröffentlichen aber nie.

Jedes Feld akzeptiert die Standard-Unterschlüssel von ESPHome sensor.sensor_schema: name, id, filters, unit_of_measurement, accuracy_decimals, icon usw.

voltage

Attribut Wert
Einheit V
device_class voltage
state_class measurement
accuracy_decimals 1
Quelle Effektivwert der Netzspannung (Momentanwert-Register des Moduls)

Effektivwert der Netzspannung. Wird bei jedem update() gelesen, sobald das Modul bereit ist. Der 4-Byte-Float wird mit Wiederholung je Byte gelesen (3 Versuche × 5 ms) und durchläuft eine Prüfung mit std::isfinite() sowie |val| < 10000.

Null ist ein gültiger zu veröffentlichender Wert: Ein Netzausfall oder Spannungseinbruch ergibt U ≈ 0 V und wird ungefiltert an HA weitergegeben — der Plausibilitätsfilter verwirft nur NaN/Inf, nicht legitime Nullwerte.

YAML
voltage:
  name: "Mains Voltage"
  filters:
    - sliding_window_moving_average:
        window_size: 3
        send_every: 1

current / current_1 ... current_6

Attribut Wert
Einheit A
device_class current
state_class measurement
accuracy_decimals 3

Effektivstrom für die Kanäle 0, 1, 2, … Kanal 0 ist die Haupt-CT-Klemme; die Kanäle 1 und 2 sind bei den Varianten UI2 / UI3 und I2 / I3 vorhanden, die Kanäle 3..6 bei Varianten mit mehr Kanälen.

Bei einem BASIC-Modul wird die aktive Kanalanzahl aus der Anzahl der deklarierten Slots abgeleitet: Wird nur current deklariert, verwendet die Komponente 1 Kanal; mit current und current_1 sind es 2; mit zusätzlich current_2 sind es 3. Bei einem STANDARD-Modul kommt die Kanalanzahl vom Modul selbst; deklarierte Slots darüber hinaus veröffentlichen einfach nie.

YAML
current:
  name: "Phase Current"
current_1:
  name: "Load 1 Current"
current_2:
  name: "Load 2 Current"

power / power_1 ... power_6

Attribut Wert
Einheit W
device_class power
state_class measurement
accuracy_decimals 1
Abhängigkeiten power erfordert current + voltage; power_N erfordert current_N + voltage

Wirkleistung in Watt, vorzeichenbehaftet. Negative Werte = Rückspeisung (Einspeisung ins Netz) bei STANDARD-Modulen. Bei BASIC werden negative Momentanwerte innerhalb des Periodenfensters auf Firmware-Ebene auf 0 begrenzt — der Periodenmittelwert ist ≥ 0. Die Momentan-Wirkleistung kann im Moment der Einspeisung noch negativ anzeigen.

Die Deklaration von power ohne current + voltage löst einen Validierungsfehler aus: power requires current to also be declared.

YAML
power:
  name: "Active Power"

energy / energy_1 ... energy_6

Attribut Wert
Einheit Wh
device_class energy
state_class total_increasing
accuracy_decimals 3
Abhängigkeiten energy benötigt current + voltage; energy_N benötigt current_N + voltage

Akkumulierte Bezugsenergie (Import) in Wh für den Kanal.

  • STANDARD-Module — die Komponente akkumuliert die eigenen Energiezähler des Moduls. Summen überleben Neustarts sowohl des ESP32 als auch des Moduls und sind monoton (sie springen nicht zurück, wenn das Modul neu startet oder ein Zähler zurückgesetzt wird).
  • BASIC-Module — auf dem ESP32 aus der Periodenmittel-Leistung berechnet, die das Modul nach jedem Snapshot liefert:
Text
E_Wh[ch] += avg_P_W[ch] * master_dt_s / 3600

In beiden Fällen wird der Wert alle 5 Minuten und bei einem sauberen Herunterfahren (Neustart / OTA) im Flash des ESP32 (NVS) gespeichert und vor dem ersten publish_state beim Start wiederhergestellt — damit das HA-Energie-Dashboard einen momentanen Wert von 0 nicht als Zählerreset deutet. Bei BASIC verliert ein plötzlicher Stromausfall höchstens die letzten 5 Minuten Energie (≈ 5 Wh bei durchschnittlich 60 W). Ändert sich das NVS-Layout (Versionssprung), beginnt der Zähler bei 0.

state_class: total_increasing ist für das HA-Energie-Dashboard erforderlich. Der Wert steigt monoton; er sinkt bei normalem Betrieb nicht.

YAML
energy:
  name: "Mains Energy"

energy_exported / energy_exported_1 / energy_exported_2

Attribut Wert
Einheit Wh
device_class energy
state_class total_increasing
accuracy_decimals 3
Abhängigkeiten Erfordert current + voltage + bidirectional: true

Exportenergie (Einspeisung) in Wh für die Kanäle 0..2, getrennt von energy akkumuliert. Setzen Sie bidirectional: true im Block rbamp:, wenn Sie diese Sensoren deklarieren. Bei STANDARD-Modulen stammen die Werte aus den Zählern des Moduls (dauerhaft, monoton). Bei BASIC-Modulen werden die Sensoren akzeptiert, liefern aber 0.

power_factor / power_factor_1 ... power_factor_6

Attribut Wert
Einheit (dimensionless)
device_class power_factor
state_class measurement
accuracy_decimals 3
Abhängigkeiten Benötigt current + voltage für den entsprechenden Slot

Leistungsfaktor im Bereich −1..+1. Ein negativer PF bedeutet eine voreilende oder nacheilende Last; die Vorzeichenkonvention legt die Firmware fest. Der Plausibilitätsfilter (§B.5) verwirft Werte außerhalb von |pf| > 10000; eine untere Grenze gibt es nicht.

YAML
power_factor:
  name: "Power Factor"

reactive_power / reactive_power_1 / reactive_power_2

Attribut Wert
Einheit VAr
device_class reactive_power
state_class measurement
accuracy_decimals 1
Abhängigkeiten Benötigt current + voltage für den entsprechenden Slot

Blindleistung in var. Vorzeichenlos (≥ 0), berechnet als √(S² − P²), enthält Verzerrungen; keine Genauigkeit angegeben. Induktive und kapazitive Lasten werden nicht unterschieden. Wird bei jedem update()-Zyklus vom Modul gelesen; veröffentlicht nur für die Kanäle 0..2 (reactive_power_3 ... reactive_power_6 werden vom Schema akzeptiert, veröffentlichen aber nie). Für Blindleistung ist keine Genauigkeit angegeben.

YAML
reactive_power:
  name: "Reactive Power"
Hinweis

Hinweis zu device_class: reactive_power — ESPHome akzeptiert ihn (Konstante DEVICE_CLASS_REACTIVE_POWER), und der Wert wird an Home Assistant weitergereicht. Die offizielle device_class-Liste von Home Assistant hat sich jedoch im Lauf der Zeit geändert: In manchen Versionen ist reactive_power in der Oberfläche verfügbar und funktioniert mit der Einheit VAr, in anderen wird der Sensor als allgemeiner Sensor ohne spezielles Symbol oder Einheitenumrechnung angezeigt. Die Daten selbst werden immer veröffentlicht (sie sind lediglich ein state); die einzige Frage ist, wie HA den Sensor in Lovelace darstellt. Erscheint der Sensor in Ihrer HA-Version als unbekannt, ist das kosmetisch und keine funktionale Regression. Entfernen Sie den Schlüssel reactive_power: aus dem YAML, wenn Sie den Sensor nicht verwenden.

apparent_power

Attribut Wert
Einheit VA
device_class apparent_power
state_class measurement
accuracy_decimals 1
Quelle Auf dem Master berechnet: S = V_rms × I_rms[0]
Abhängigkeiten Erfordert current + voltage

Scheinleistung in VA. Von der Komponente aus U_rms und I0_rms berechnet, die im selben update()-Zyklus gelesen werden — kein eigenes Register wird gelesen. Beide Lesungen müssen im selben Zyklus gelingen; schlägt auch nur eine fehl (Wiederholungen erschöpft), wird in diesem Zyklus kein Zustand veröffentlicht, und der letzte Wert in HA bleibt erhalten.

apparent_power steht in SHARED_FIELDS und funktioniert bei jeder Topologie, hängt aber für die U × I-Berechnung von voltage und current ab.

YAML
apparent_power:
  name: "Apparent Power"

2.2 Phasenbezogene Felder (Varianten mit mehreren Spannungen)

Bei Modulen mit mehr als einem Spannungseingang (Split-Phase- und Drehstromvarianten) werden die Sensoren je Phase deklariert. Das Schema akzeptiert die phasenbezogene Gruppe bei jedem Modul; ein Slot veröffentlicht nur, wenn das angeschlossene Modul den entsprechenden Kanal tatsächlich meldet, andernfalls bleibt er ohne Wert.

Einzelne und phasenbezogene Felder schließen sich gegenseitig aus innerhalb eines Blocks sensor:. Der Validator meldet einen Fehler:

Text
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...).

Alle phasenbezogenen Felder teilen dieselben sensor_schema-Standardwerte wie ihre einphasigen Gegenstücke (dieselben Einheiten, device_class, state_class, accuracy_decimals).

Feld Einheit device_class
voltage_a / _b / _c V Spannung
current_a / _b / _c A current
power_a / _b / _c W power
power_total W power
energy_a / _b / _c Wh energy
energy_exported_a / _b / _c Wh energy
power_factor_a / _b / _c — power_factor
reactive_power_a / _b / _c VAr reactive_power
voltage_angle_b / _c ° —

voltage_angle_b und voltage_angle_c veröffentlichen den Phasenwinkel der Spannungen B und C in Grad, bezogen auf Phase A (Phase A ist die 0°-Referenz, deshalb gibt es kein voltage_angle_a). Sie erfordern Modul-Firmware, die die Winkel liefert; bei älterer Firmware protokolliert die Komponente beim Start eine Warnung, und die Sensoren veröffentlichen nie. Solange der Winkel nicht bestimmt werden kann, ist der Wert „unbekannt“.

Hinweis

Die Abhängigkeitsprüfung je Phase wird bei phasenbezogenen Feldern nicht erzwungen (nur _SINGLE_SLOT_DEPS für einphasige Varianten).

Example:

YAML
rbamp:
  id: panel_meter
  address: 0x50

sensor:
  - platform: rbamp
    rbamp_id: panel_meter
    voltage_a:
      name: "Phase A Voltage"
    voltage_b:
      name: "Phase B Voltage"
    voltage_c:
      name: "Phase C Voltage"
    current_a:
      name: "Phase A Current"
    current_b:
      name: "Phase B Current"
    current_c:
      name: "Phase C Current"
    power_total:
      name: "Total Active Power"
    voltage_angle_b:
      name: "Phase B Angle"
    voltage_angle_c:
      name: "Phase C Angle"

2.3 Gemeinsame Felder (topologieunabhängig)

Diese Felder funktionieren in jeder Topologiegruppe, auch wenn kein einphasiger oder phasenbezogener Stromsensor deklariert ist (ein Aufbau nur mit Spannung oder nur mit Frequenz).

frequency

Attribut Wert
Einheit Hz
device_class frequency
state_class measurement
accuracy_decimals 0

Netzfrequenz. Unplausible Werte (das Modul meldet „noch nicht gemessen“) werden verworfen, ohne sie zu veröffentlichen; so entsteht im HA-Entity während des Aufwärmens kein Übergang „Unbekannt“ → 0 Hz → 50 Hz.

YAML
frequency:
  name: "Mains Frequency"

apparent_power

Siehe den Eintrag unter den einzelnen Feldern oben. apparent_power benötigt current und voltage, gehört daher in einen einphasigen Sensorblock.

energy_total / energy_exported_total / energy_net

Sensor Einheit state_class Bedeutung
energy_total Wh total_increasing Importierte Energie, alle Kanäle des Moduls
energy_exported_total Wh total_increasing Exportierte Energie, alle Kanäle des Moduls
energy_net Wh total Bezug minus Einspeisung. Kann sinken.

Gesamtsummen über alle Kanäle des Moduls, aus den eigenen Energiezählern des Moduls (STANDARD-Module). Sie überleben Neustarts des ESP32 und des Moduls, sind über Neustarts des Moduls und Zählerresets hinweg monoton (außer energy_net, das die Differenz zweier monotoner Werte ist) und werden ebenfalls alle 5 Minuten sowie bei einem sauberen Herunterfahren ins NVS gespeichert. Sie brauchen keinen Schlüssel bidirectional: und keine begleitende Deklaration von current/voltage.

Bei einem Modul ohne Energiezähler im Gerät (BASIC) validieren diese Schlüssel, veröffentlichen aber nie; die Komponente protokolliert beim Start eine Warnung. Verwenden Sie dort die Sensoren energy je Kanal.

YAML
sensor:
  - platform: rbamp
    rbamp_id: meter1
    energy_total:
      name: "Energy Imported"
    energy_exported_total:
      name: "Energy Exported"
    energy_net:
      name: "Energy Net"

reactive_energy / reactive_energy_exported

Attribut Wert
Einheit varh
state_class total_increasing
accuracy_decimals 3

Blindenergie (Bezug / Einspeisung) über alle Kanäle, aus denselben Zählern am Gerät und mit derselben Persistenz wie energy_total. Nur STANDARD-Module; bei anderen werden die Schlüssel akzeptiert, veröffentlichen aber nie.

phase_sequence

Attribut Wert
Einheit —
accuracy_decimals 0

Phasenfolge eines Dreispannungsmoduls: 1 = vorwärts, 2 = rückwärts, 3 = abnormal. „Unknown“, solange sie nicht bestimmt werden kann (weniger als drei aktive Spannungseingänge). Erfordert eine Modul-Firmware, die dies bereitstellt; andernfalls protokolliert die Komponente beim Start eine Warnung und der Sensor veröffentlicht nie. In einem Lambda liefert id(meter1).get_phase_sequence_str() "forward", "reverse", "abnormal", "n/a" oder "unavailable".


2.4 Schema-Prüfregeln

Der Python-Validator _validate_topology_consistency wendet zwei Klassen von Regeln bei esphome config / zur Kompilierzeit an — noch bevor C++-Code läuft.

Gegenseitiger Ausschluss der Topologie

Einzelne Felder (voltage, current, current_1 usw.) und phasenbezogene Felder (voltage_a, voltage_b usw.) können nicht gemeinsam in einem Block sensor: stehen. Ein Versuch, sie zu mischen:

Text
Cannot mix single-phase fields (voltage, current, current_1, ...) with
phased fields (voltage_a/b/c, current_a/b/c, ...). Pick one group based
on your rbAmp SKU.

Die phasenbezogene Gruppe enthält voltage_angle_b / voltage_angle_c.

Begleitanforderungen je Slot (nur einphasig)

Jedes abgeleitete Feld benötigt die Eingabefelder, die das Modul zur Berechnung braucht:

Deklariertes Feld Erforderliche Begleitschlüssel
power / _1 ... _6 current (oder _1 ... _6, gleiches Suffix) + voltage
energy / _1 ... _6 current (oder _1 ... _6, gleiches Suffix) + voltage
power_factor / _1 ... _6 current (oder _1 ... _6, gleiches Suffix) + voltage
reactive_power / _1 / _2 current (oder _1 ... _6, gleiches Suffix) + voltage
apparent_power current + voltage

energy_exported*, energy_total, energy_exported_total, energy_net, reactive_energy* und phase_sequence haben keine begleitenden Schema-Pflichtschlüssel.

Ein fehlender Begleitschlüssel löst aus:

Text
`power` requires `current` to also be declared — the underlying chip
cannot compute it without that input.

Weitere Regeln auf Ebene des Blocks rbamp:

Regel Beschreibung
ct_model: ↔ ct_models: schließen sich gegenseitig aus Pro Block rbamp: darf nur einer von beiden verwendet werden — sonst ein Validierungsfehler.
new_address ≠ address Stimmen sie überein — cv.Invalid.
address im Bereich 0x08..0x77 cv.i2c_address wird angewendet.
update_interval ≥ 1s Kürzere Intervalle werden abgelehnt.
latch_interval ≥ update_interval Ein kürzerer Snapshot-Takt wird abgewiesen.
ct_models: hat 1..16 Einträge Längere Listen werden abgelehnt.
group_id ist 0..255 Werte außerhalb des Bereichs werden abgewiesen.
start_current_ua ist 0 oder 10..2540 in Schritten von 10 Jeder andere Wert wird abgelehnt.
ct_model_force: true erfordert ct_model: oder ct_models: Für sich allein abgewiesen.
period_banks: — jede bank einmal, interval ≥ 1s Eine doppelte Bank, eine Bank außerhalb von 0..7 oder ein kürzeres Intervall wird abgelehnt.
CT-Modellcode gültig für die festgelegte sensor_class Ein für die Klasse nicht zulässiger Code wird mit der Liste der erlaubten Werte abgewiesen.

Alle Validierungsfehler werden bei esphome compile mit einer verständlichen Meldung gemeldet, die auf den betreffenden Schlüssel zeigt. Um einen Konfigurationsfehler zu finden, muss keine Hardware geflasht werden.


3. Datenfluss und Timing

Der konzeptionelle Ablauf eines einzelnen update()-Zyklus:

Text
Module (autonomous)                  ESP32 (ESPHome component)
─────────────────────────────────   ────────────────────────────────────────────
Measures & computes the
instantaneous block (RMS / P / PF / Q)
  ↓ (~100 ms per cycle)
Atomically publishes the block       update() fires every update_interval (60 s)
of instantaneous registers            ↓
  ↓                                 phase 1 — snapshot:
                                      write the snapshot command
Closes the period accumulator,        50 ms timeout (non-blocking)
opens a new one                       ↓ (main loop keeps running)
  ↓
  wait 50 ms                        phase 2 — period snapshot:
                                      read the valid flag
                                      read per-channel average powers
                                      E_Wh[ch] += avg_P × dt_s / 3600
                                      save to NVS if 5 minutes elapsed
                                      ↓
                                    phase 3 — instantaneous values:
                                      read the status register
                                      read U_rms, I[0..n]_rms, P[0..n],
                                            PF[0..n], Q[0..n], frequency
                                      publish all bound sensors
                                      ↓
                                    Push state to HA over the native API
Hinweis

Das Diagramm zeigt den BASIC-Ablauf auf Snapshot-Basis. Ein STANDARD-Modul führt seine eigenen Energiezähler: Bei jedem update() liest die Komponente die Momentanwerte und den Zählerstand (eine kohärente Transaktion) und addiert die Differenz zu ihren laufenden Summen, sodass der Snapshot-Schritt für die Energie nicht verwendet wird.

Charakteristische Zeiten:

Ereignis Takt
Interner Commit des Momentanwert-Blocks durch das Modul ca. 100 ms
Aufruf von update() update_interval (standardmäßig 60 s)
Settle-Timeout nach dem Snapshot-Befehl 50 ms (nicht blockierend)
In NVS speichern Alle 5 Minuten
Pause zwischen den Wiederholungen je Byte 5 ms, bis zu 3 Versuche
Flash-Schreibfenster beim Schreiben des Modells ca. 700 ms (das Modul antwortet während der ganzen Zeit mit NACK)

Das Zeitlimit für das Einschwingen nach dem Snapshot blockiert nicht — der kooperative ESPHome-Scheduler bedient WLAN, API und andere Komponenten während der 50 ms Wartezeit weiter. Die restlichen Phasen von update() (Lesen der Momentanregister) laufen unmittelbar nach der Rückkehr aus der Snapshot-Phase.

Die Warnung [W][component:522]: rbamp took a long time for an operation (XXX ms) ist erwartbar und unschädlich, wenn sie erscheint. Bei Firmware v1.3 liest die Komponente den Block der Momentanwerte über einen einzigen Burst-Read (READ mit Auto-Increment), sodass ein gesunder Zyklus deutlich unter 30 ms bleibt. Die Warnung erscheint, wenn der Burst-Pfad auf einzelne Registerlesungen zurückfällt (4 Transaktionen pro Float, bis zu 36 Transaktionen bei 50 kHz, plus Wiederholungen) — typischerweise wegen eines grenzwertigen Busses oder Legacy-Firmware ohne READ-Burst-Fähigkeit.


4. I²C-Bus-Einstellungen

Die Komponente rbamp übernimmt den I²C-Bus aus dem obersten Block i2c:. Empfohlene Einstellungen für die aktuelle Firmware:

YAML
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz   # 100 kHz causes periodic NACKs; 50 kHz reduces them ~5x
  scan: true         # optional: logs the addresses found at boot

Bustakt: 50kHz auf ESP-IDF-basierten Mastern verwenden (ESP32 mit ESPHome oder Arduino). Das Modul meldet bei 100 kHz regelmäßig NACKs (ein merklicher Anteil der Transaktionen) wegen eines bekannten Zusammenspiels mit dem ESP-IDF-Treiber i2c_master (bestätigt im esp-idf-Issue #9426, von Espressif als „Won't Do“ markiert). Firmware v1.1/v1.3 hat die Modulseite gehärtet, das Zusammenspiel mit dem Treiber bleibt aber — 50 kHz ist die dauerhafte Empfehlung. Die dreischichtige Abschwächung der Komponente (Wiederholung + Plausibilität + 50 kHz) senkt die effektive Rate fehlerhafter Lesungen unter 1 %.

Pull-up-Widerstände: 4.7 kΩ gegen 3.3 V an SDA und SCL werden empfohlen. Größere Werte (10 kΩ) verlängern die Anstiegszeit und erhöhen die NACK-Rate bei 100 kHz.

Mehrere Geräte: Der I²C-Bus des ESP32 unterstützt bis zu 112 Geräte mit eindeutigen 7-Bit-Adressen. Verwenden Sie address: und new_address:, um jedem Modul eine eindeutige Adresse zuzuweisen. scan: true im Block i2c: protokolliert beim Start jede antwortende Adresse — prüfen Sie, dass jedes Modul erkannt wird, bevor Sie die Periodenmessung aktivieren.

Hinweis

Die vollständige Registerkarte auf Drahtebene und der Befehlssatz des Moduls stehen auf der öffentlichen API-Referenzseite. Für den typischen Nutzer des YAML-Schemas genügt dieses Kapitel — jedes Register ist hinter der deklarativen Schnittstelle der Komponente verborgen.


5. Identitätsschnittstelle (v1.3 NEU) — öffentliche C++-Methoden

Die Komponente v1.3 stellt Identitäts- und Diagnose-Getter bereit, die über ein YAML-lambda: und über die Template-Plattform erreichbar sind. Alle Methoden geben einen std::string (für die Kompatibilität mit text_sensor) oder primitive Typen zurück — es gibt keine Ausnahmen, alles läuft über den zwischengespeicherten Zustand.

Methode Rückgabetyp Quelle Beschreibung
get_variant_str() std::string REG_HW_VARIANT (0x55) "UI1"/"UI2"/"UI3"/"I1"/"I2"/"I3"/"UNK" — die Variante des Moduls
get_capability_hex() std::string Fähigkeitsregister "0xNNNN" — die 16-Bit-Fähigkeits-Bitmap, zur Diagnose
get_uid_hex() std::string REG_UID (0x5C × 12 Bytes) 24-stelliger Hex-Wert (96-Bit-Chip-UID)
get_last_error_str() std::string REG_ERROR (0x02) "OK"/"ERR_PARAM"/"ERR_BUSY"/"ERR_LATCH"/"ERR_CRC"
get_event_flags() uint8_t REG_EVENT_FLAGS (0x03) hartnäckige Bits: Bit3=ERR_LATCH, Bit5=ADDR_CHANGED usw.
get_firmware_version() uint8_t REG_VERSION (0x01) das Versionsbyte des Moduls (z. B. 0x04 bei der BASIC-Firmware v1.3)
get_std_image_version() uint32_t Nur STANDARD Laufende Modul-Image-Version; 0 = unbekannt oder BASIC
get_phase_sequence_str() std::string Nur STANDARD "forward"/"reverse"/"abnormal"/"n/a"/"unavailable"
read_start_current_ua() uint16_t Nur STANDARD Frisch gelesener gespeicherter Anlaufstrom in µA; 65535 = nicht verfügbar
read_gc_tick_received() uint16_t REG_GC_LAST_TICK (0x58) zuletzt erfasster Tick-Wert aus dem GC-Frame
get_capability_cached() uint16_t zwischengespeicherte Fähigkeits-Bitmap die beim Start gelesene Bitmap, ohne Bus-Transaktion

Caching: variant / capability / uid / firmware_version werden einmal in setup() gelesen und zwischengespeichert — wiederholte Aufrufe gehen nicht auf den Bus. last_error_str() / event_flags() / gc_tick werden bei jedem Aufruf gelesen, um aktuell zu bleiben.

Verwendung über einen Template-text_sensor

YAML
text_sensor:
  - platform: template
    name: "Mains variant"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_variant_str();'
    # → entity_id: sensor.mains_variant, value: "UI1"

  - platform: template
    name: "Mains capability"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_capability_hex();'
    # → the capability bitmap as hex, "0xNNNN" (diagnostics only)

  - platform: template
    name: "Mains UID"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_uid_hex();'

  - platform: template
    name: "Mains last error"
    update_interval: 30s
    lambda: 'return id(mains_meter).get_last_error_str();'

  - platform: template
    name: "Mains firmware version"
    update_interval: 30s
    lambda: 'char b[8]; snprintf(b, sizeof(b), "0x%02X", id(mains_meter).get_firmware_version()); return std::string(b);'

Diese text_sensors erscheinen in HA als sensor.mains_variant usw. — praktisch für Inventar-Dashboards, Asset-Tracking und die Kontrolle nach dem Flashen.

Verwendung über lambda: in Automationen

YAML
sensor:
  - platform: rbamp
    rbamp_id: mains
    energy: { name: "Mains Energy" }

# Read the stored values from a lambda (e.g. in an on_boot automation)
esphome:
  on_boot:
    then:
      - lambda: |-
          ESP_LOGI("meter", "variant=%s", id(mains).get_variant_str().c_str());

6. Flotte und GC-Synchronisation (v1.3 NEU)

transmit_gc_frame() — programmatische GC-Aussendung

C++
bool transmit_gc_frame();

Sendet einen 5-Byte-General-Call-Snapshot-Frame an die Bus-Adresse 0x00. Das Gruppenbyte ist die group_id: der Instanz, und der Tick ist ein automatisch hochzählender Zähler; die Methode liefert true, wenn der Buszugriff erfolgreich war. Nur BASIC-Module — auf einem STANDARD-Modul protokolliert sie eine Warnung und tut nichts:

Text
START | 0x00 | A | 0xA5 | A | 0x27 | A | group | A | tick_lo | A | tick_hi | A | STOP

Alle Module mit fleet_gc_enable: true + einer passenden group_id: (oder group_id: 0) nehmen einen Snapshot ihrer Periodenakkumulatoren synchron zu einem einzigen Drahtzeitpunkt. Der Tick-Wert wird von jedem Modul zur Synchronprüfung gespeichert (read_gc_tick_received()).

Automatisches Senden: Die Komponente sendet automatisch in update() einen GC-Frame, wenn fleet_gc_enable: true gesetzt ist und die Firmware den General-Call-Snapshot ankündigt. Ein manuelles Senden ist nur für zusätzliche Synchronisation nötig (z. B. bei einem Auslöser auf HA-Seite).

Fähigkeitsprüfung: Bietet die Firmware keinen General-Call-Snapshot an — Warnung, kein Senden.

fleet_apply_now() — Lesen-Vergleichen-Schreiben erneut erzwingen

C++
bool fleet_apply_now();

Wiederholt das Lesen-Vergleichen-Schreiben für die Fleet-Einstellungen erzwungen: liest die Fleet-Konfiguration und die Gruppen-ID des Moduls erneut, vergleicht sie mit fleet_gc_enable: / group_id: aus dem YAML und schreibt die Differenz. Liefert false (und tut nichts) auf einem STANDARD-Modul.

Anwendungsfall: nach einem Zurücksetzen des Moduls auf Werkseinstellungen mit einem Debug-Werkzeug oder zur Prüfung nach dem OTA, ob die Flottenkonfiguration angewendet wurde.


7. Dienste der nativen API (v1.3 NEU) — Wiederherstellungsautomationen

Die Komponente v1.3 registriert Dienste nicht automatisch — das erledigt das YAML. Die öffentlichen Methoden write_clear_error() / write_reset() / transmit_gc_frame() sind aber für das Muster api: services: ausgelegt. Kanonische Rezepte:

YAML
api:
  port: 6053

  services:
    # Recovery: clear REG_ERROR + EVENT_FLAGS bit3
    - service: mains_clear_error
      then:
        - lambda: 'id(mains).write_clear_error();'

    # Maintenance: soft reset (preserves flash)
    - service: mains_reset
      then:
        - lambda: 'id(mains).write_reset();'

    # Fleet: manual GC snapshot (beyond the auto-emit in update())
    - service: fleet_latch_now
      then:
        - lambda: 'id(mains).transmit_gc_frame();'   # group = this instance's group_id, tick auto-increments

    # Maintenance: force fleet-config re-apply (post-OTA verify)
    - service: mains_fleet_apply
      then:
        - lambda: 'id(mains).fleet_apply_now();'

Danach kann HA die Dienste aus Automationen heraus aufrufen:

YAML
automation:
  - alias: "Auto-clear meter error on detection"
    trigger:
      platform: state
      entity_id: sensor.mains_last_error
      from: "OK"
    action:
      - delay: 60s   # wait one update_interval to confirm a persistent error
      - service: esphome._mains_clear_error
      - condition: state
        entity_id: sensor.mains_last_error
        state: "ERR_PARAM"
      - service: persistent_notification.create
        data:
          title: "Meter parameter error"
          message: "Meter at {{ states('sensor.mains_capability') }} reports ERR_PARAM after auto-clear retry. Check YAML config."

8. Fehler und Wiederherstellung (v1.3) — REG_ERROR vs. EVENT_FLAGS bit3

In v1.3 hat das Modul zwei unabhängige Fehlerkanäle:

Kanal Register Latch-Semantik Löschen
Synchronisation (letzter Schreibvorgang) REG_ERROR (0x02) letzter Schreibvorgang gewinnt, wird durch die nächste Operation überschrieben write_clear_error() oder die nächste erfolgreiche Operation
Asynchron dauerhaft REG_EVENT_FLAGS bit3 (0x03) hartnäckig; setzt sich nach einigen hundert Millisekunden erneut, wenn die Ursache nicht behoben ist write_clear_error() (ein Aufruf löscht beides)

Lesemuster

C++
// Sync — fresh after the last operation
std::string err = id(mains).get_last_error_str();    // "ERR_PARAM" / "OK" / ...

// Durable — sticky bit3, sees errors even between polls
uint16_t flags = id(mains).get_event_flags();
bool latched_error = (flags & (1 << 3)) != 0;

Wiederherstellungssemantik

Das Zurücksetzen von REG_ERROR allein reicht nicht, wenn die Firmware Bit3 erneut setzt:

C++
id(mains).write_clear_error();                       // clears REG_ERROR + EVENT bit3
delay(300);                                          // wait for the re-latch window
uint16_t flags_after = id(mains).get_event_flags();
if (flags_after & (1 << 3)) {
    // Root cause not resolved — firmware re-latched bit3
    ESP_LOGW("rbamp", "ERROR persists after clear — check config / param");
}

Für eine vollständige Wiederherstellung:

  1. Ursache beheben (CT-Modellcode im YAML korrigieren, sensor_class richtig setzen).
  2. write_clear_error() — löscht REG_ERROR + EVENT_FLAGS bit3.
  3. Prüfen Sie über get_event_flags() nach ca. 300 ms, dass Bit3 nicht erneut gesetzt ist.

Siehe 10_troubleshooting.md §6 Fehler und Wiederherstellung.


Quelle & Probleme: rb-amp/rbamp-esphome · diese Seite im Repo: docs/09_api_reference.md (v1.9.1)