rbAmp
DE
Shop
Docs
Aktualisiert · Auf GitHub bearbeiten (Edit on GitHub)

02 · Modulstufen

Die beiden rbAmp-Modulreihen, BASIC und STANDARD (STD), und wo die Energie auf jeder berechnet wird.

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_exported existiert im YAML-Schema (aus Kompatibilitätsgründen), auf BASIC veröffentlicht er aber immer 0.
  • 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ätzlich voltage_angle_b, voltage_angle_c und phase_sequence.
  • Energie je Kanal energy und energy_exported (mit bidirectional: 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.

Energiebilanzierung bei BASIC (der Master integriert die mittlere Leistung je Periode) gegenüber STANDARD (der Master liest die kumulativen Zähler des Moduls).

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
Hinweis

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).

YAML
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

YAML
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:

YAML
rbamp:
  id: meter1
  ct_model: SCT_013_030   # all channels — SCT-013-030

Oder ein Profil je Kanal (für UI3 mit gemischten Zangen):

YAML
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 mit ct_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 Sie ct_model:.

Zur Auswahl eines Modells siehe 03_sensor_selection.md.

new_address: — einmalige I²C-Adressvergabe

YAML
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

YAML
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

YAML
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

YAML
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


Quelle und Probleme: rb-amp/rbamp-esphome · diese Seite im Repository: docs/02_tiers.md (v1.9.1)