06 · YAML-Kochbuch
Dieses Kapitel beginnt mit den Leitszenarien — den realen Einsatzmustern, für die die Komponente in v1.3 entworfen wurde (Netz + N Unterlasten an einem Bus mit fleet_gc_enable-Synchronisation, Provisioning-Ablauf, mehrkanalige gemischte CT, Fleet-GC-Synchronisation). Danach folgen die Szenarien mit einem einzelnen Modul, vom minimalen UI1 bis zur Produktionsinstallation mit HA-Automationen.
Jedes Beispiel ist in sich geschlossen: Kopieren, Board-Namen und WLAN-Zugangsdaten eintragen, kompilieren und flashen. Wo ein Beispiel von der minimalen Vorlage abweicht, erklärt eine Anmerkung den Grund.
Cross-references:
- Komponentenschema, Registerkarte, Periodenzählprotokoll, Topologie mit mehreren Modulen, Fleet-GC-Synchronisation und die lockere Plausibilitätsregel für NACK: 09 · API-Referenz
| # | Szenario | Topologie | Wann verwenden |
|---|---|---|---|
| 1 | Netz + N Unterlasten — der 80-%-Kanon | UI1 + N× I2/I3 | Gesamthaus-Messung mit Aufschlüsselung nach Teilzweigen |
| 2 | Bereitstellungsablauf (neu → Flotte) | sequenziell einzeln | Inbetriebnahme einer neuen Charge von Modulen |
| 3 | Mehrkanalige gemischte CT (UI3 mit verschiedenen Zangen) | UI3 | Messung gemischter Lasten mit Genauigkeitsoptimierung |
| 4 | Fleet-GC-Synchronisation (enge Synchronität) | N× UI/I | Mehrmandanten-Cluster und Unterzählung |
| 5 | UI1 — einkanalig (minimal) | UI1 | Hello-World mit einem Modul |
| 6 | UI1 mit Anpassung | UI1 | Alle gängigen ESPHome-Stellschrauben |
| 7 | UI3 — Dreikanal mit gemischten Klemmen | UI3 | Einzelnes Modul mit mehreren Kanälen |
| 8 | Mehrmodul-Bus (GC-Synchronisation) | N× UI/I | fleet_gc_enable + group_id an drei Modulen |
| 9 | Einmalige I²C-Adressänderung | einzeln | Provisionierung eines einzelnen Moduls |
| 10..20 | HA-Integrationen und -Automationen | gemischt | Muster für den Produktivbetrieb |
| 21 | STANDARD (STD)-Modul — Gesamtenergie aus Zählern im Gerät | beliebig | Gesamtsummen, Blindenergie, start_current_ua: |
| 22 | Umschalten des SCT-Nennwerts, ct_model_force |
beliebig | Nennwert-Wechsel ohne Genauigkeitsverlust |
Szenarien 1–4 sind die Vorzeigebeispiele und zielen auf die kanonische v1.3-Installation des Pakets. Ihr Code nutzt fleet_gc_enable + Identitätsschnittstelle + Lesen-Vergleichen-Schreiben und wird an einem heterogenen Aufbau UI1+I2+I3 erprobt. Szenarien 5–22 sind Einzelmodul- und kompakte Muster. Szenario 8 ist die kurze Dreimodul-Buskonfiguration.
1 · Netz + N Unterlasten (der 80-%-Kanon) — integriertes Messsystem
Ziel: die kanonische Installation des Pakets — ein kohärentes Messsystem auf einer heterogenen Flotte, geschlossen innerhalb eines einzigen ESPHome-Starts (Erkennung → Konfiguration → GC aktivieren → Schleife [publish_state + automatischer GC-Tick]).
Hardware (Prüfaufbau UI1 + I2 + I3): UI1@0x50 + I2@0x51 + I3@0x52; ~0.58 A Last; Pull-ups gemäß der Zeile „3 Module“ in der Tabelle von 04_hardware.md (alle abtrennen, ein externes Paar 2.7–3.3 kΩ).
esphome:
name: home-fleet
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: INFO
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
# Three rbAmp modules on shared bus, all with fleet_gc_enable + group_id=1
# for synchronized period snapshots (tight sync between mains + sub-meters).
rbamp:
- id: mains_meter # UI1 on the mains feed
address: 0x50
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 1
- id: boiler_meter # I2 on the boiler + washing machine
address: 0x51
sensor_class: SCT_013
ct_models: [SCT_013_020, SCT_013_010]
fleet_gc_enable: true
group_id: 1
- id: panel_meter # I3 on the distribution-panel branches
address: 0x52
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: mains_meter
voltage: { name: "Mains Voltage" }
current: { name: "Mains Current" }
power: { name: "Mains Power", id: mains_power_state }
power_factor: { name: "Mains PF" }
energy: { name: "Mains Energy" }
frequency: { name: "Mains Frequency" }
- platform: rbamp
rbamp_id: boiler_meter
# I2 is a current-only module: it has no voltage input, so it reports currents only
# (power and energy need a UI module with voltage).
current: { name: "Boiler Current" } # 20A CT
current_1: { name: "Washer Current" } # 10A CT
- platform: rbamp
rbamp_id: panel_meter
current: { name: "Lighting Current" } # 5A CT
current_1: { name: "Appliances Current" } # 30A CT
current_2: { name: "Sub-panel Current" } # 20A CT
# Optional: template sensor for the household power (same sensor: list, not a second sensor: key)
- platform: template
name: "Household Total Power"
update_interval: 60s
accuracy_decimals: 0
unit_of_measurement: "W"
device_class: power
lambda: |-
// Sum of power from the mains meter only (sub-meters are a subset of the same mains)
auto v = id(mains_power_state);
return v.has_state() ? v.state : 0.0f;
Beispielausgabe (~0.58 A Last)
[I][i2c:136]: Found i2c device at address 0x50
[I][i2c:136]: Found i2c device at address 0x51
[I][i2c:136]: Found i2c device at address 0x52
[C][rbamp:450]: mains_meter: variant=UI1, capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: boiler_meter: variant=I2, capability=0x…, fleet_gc=on, group=1
[C][rbamp:450]: panel_meter: variant=I3, capability=0x…, fleet_gc=on, group=1
[I][rbamp:493]: GC latch enabled fleet-wide: 3 modules in group 1
ITER 1 @ 60s: GC tick=1, 3/3 in_sync
mains: V=232.6 I=5.79 P=1259 W E_total: 0 → 0.35 Wh
boiler: I=[11.58, 3.87] ; current-only
panel: I=[3.84, 2.55, 5.84] ; current-only
Hinweise zur Verwendung
-
Ein synchronisierter Takt — das gesamte System. Bei jedem Tick von
update_intervalsendet der ESP32 einen GC-Frame an 0x00 → alle 3 Module nehmen gleichzeitig zu demselben Zeitpunkt auf dem Draht einen Snapshot ihrer Periodenakkumulatoren (unter Last bestätigt: 3/3 in_sync). -
mains_powerin einer heterogenen Flotte = die Wirkleistung von UI1 (mains_meter). Die Unterzähler (I2/I3) liefern nur den Strom, ohne kanonische P-Größe. Im 80-%-Kanon entsprichtmains_powerungefähr der Gesamtleistung aller Verbraucher (mains_meter erfasst die Einspeisung). -
Wh bei BASIC-Modulen werden auf dem ESP32 gegen dessen eigenen Takt integriert (die Zeit zwischen den Snapshots), sodass alle Module der Flotte eine gemeinsame Zeitbasis haben. STANDARD-Module führen eigene Energiezähler, die die Komponente akkumuliert.
-
Resilient gegen Ausfälle. Fällt ein Modul vom Bus (Provisionierung / Stromzyklus), arbeiten die übrigen weiter; HA zeigt für dessen Entitäten „Nicht verfügbar“, bis es sich erholt.
2 · Provisionierungsablauf (neu → Flotte)
6.5 Provisionierung — frisches Flashen + SAVE (API-Referenz)
Ziel: das kanonische Inbetriebnahme-Verfahren für neue Module, vom Werk 0x50 bis zu eindeutigen Flotten-Adressen. Es zeigt den Zwei-Phasen-Adress-Commit (v1.3, produktionstauglich) und die nötige Disziplin „nur ein Neumodul am Bus gleichzeitig“.
Schritt 2.1 — UI1-Netz provisionieren (0x50 → 0x50, sensor_class + ct_model)
# Connect ONLY the UI1 to the bus. Flash this YAML.
rbamp:
- id: provisioning_target
address: 0x50
# new_address not needed — 0x50 is already fine for UI1
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: provisioning_target
voltage: { name: "Provision UI1 Voltage" }
current: { name: "Provision UI1 Current" }
text_sensor:
- platform: template
name: "Provision UI1 variant"
update_interval: 5s
lambda: 'return id(provisioning_target).get_variant_str();'
- platform: template
name: "Provision UI1 UID"
update_interval: 5s
lambda: 'return id(provisioning_target).get_uid_hex();'
- platform: template
name: "Provision UI1 capability"
update_interval: 5s
lambda: 'return id(provisioning_target).get_capability_hex();'
Prüfung: In HA sollten Sie sensor.provision_ui1_variant == "UI1" und sensor.provision_ui1_capability mit einer nicht-null hexadezimalen Bitmap sehen ("0x0000" bedeutet Alt-Firmware). Notieren Sie die UID für die Inventarverwaltung.
Schritt 2.2 — I2 provisionieren (0x50 → 0x51 über Zwei-Phasen-Commit)
Trennen Sie die UI1 vom Bus (sonst entsteht ein Adresskonflikt). Schließen Sie das Modul I2 an. Flashen Sie das aktualisierte YAML:
rbamp:
- id: provisioning_target
address: 0x50 # virgin address
new_address: 0x51 # ⚠ two-phase commit — production-OK on v1.3
sensor_class: SCT_013
ct_models: [SCT_013_020, SCT_013_010]
fleet_gc_enable: true
group_id: 1
Was beim Start passiert:
[I][rbamp:xxx]: provisioning_target: probe at 0x50 → OK (variant=I2)
[I][rbamp:xxx]: provisioning_target: new_address=0x51 requested
[I][rbamp:xxx]: provisioning_target: two-phase address change supported → production path
[D][rbamp:xxx]: provisioning_target: stage REG_I2C_ADDRESS=0x51
[D][rbamp:xxx]: provisioning_target: write REG_ADDR_COMMIT_MAGIC=0xA5
[D][rbamp:xxx]: provisioning_target: send CMD_COMMIT_ADDR → wait 700ms
[I][rbamp:xxx]: provisioning_target: re-probe 0x51 → OK, re-enumeration complete
[I][rbamp:xxx]: provisioning_target: i2c address handle updated to 0x51
Nach Erfolg: Aktualisieren Sie das YAML auf address: 0x51 und entfernen new_address:. Der nächste Start führt den Änderungsablauf nicht mehr aus.
Schritt 2.3 — I3 provisionieren (0x50 → 0x52) + für den Rest wiederholen
Dasselbe Muster wie 2.2: I2 trennen, das Neumodul I3 anschließen, das YAML mit new_address: 0x52 flashen, auf die Neuaufzählung warten und das YAML auf address: 0x52 aktualisieren.
🛑 MUSS: jeweils nur ein Neumodul am Bus. Sind zwei Neumodule gleichzeitig auf 0x50, antworten beide in der Adressphase und ziehen SDA gegeneinander → undefinierter Zustand, und kein Provisionierungsverfahren funktioniert.
Schritt 2.4 — die Flotte zusammensetzen
Sobald die Provisionierung aller Module abgeschlossen ist, aktualisieren Sie das YAML auf die endgültige Flottenkonfiguration (siehe Szenario §1 oben), deaktivieren die internen Pull-ups auf allen Modulen (3 Module = alle trennen) und setzen ein externes Paar von 2.7–3.3 kΩ am ESP32 — siehe die Pull-up-Tabelle in 04_hardware.md. Flashen Sie das endgültige YAML — alle Module sollten erkannt werden:
[D][i2c:136]: Found i2c device at address 0x50
[D][i2c:136]: Found i2c device at address 0x51
[D][i2c:136]: Found i2c device at address 0x52
Fehlerfälle (Provisionierung)
| Symptom | Ursache | Wiederherstellung |
|---|---|---|
Probe failed at 0x50 nach dem Flashen |
Modul nicht bestromt oder ein defekter Kontakt | VCC-, GND-, SDA- und SCL-Verbindung prüfen |
[W] Zwei-Phasen-Adressänderung nicht unterstützt |
Modul mit Legacy-Firmware (v1.0-v1.2) | Die einphasige Rückfalllösung erfordert den Werks-Provisionierungsmodus (siehe 04_hardware.md) |
[E] address change committed but re-probe at 0x51 failed |
Grenzwertiger Bus oder abgebrochener Commit | Starten Sie neu; wiederholt sich der Fehler, ist der externe Pull-up zu schwach oder es gibt einen EMI-Impuls |
[W] WARN_FACTORY_MODE_REQUIRED |
Legacy-Firmware ohne zweiphasige Adressänderung | Der Lieferant aktiviert den Werkseinstellungsmodus (außerhalb des Umfangs der Bibliothek) |
3 · Mehrkanalige gemischte CT (UI3 mit verschiedenen Zangen)
Ziel: zu zeigen, dass die CT-Modelle auf verschiedenen Kanälen eines einzelnen Moduls entsprechend dem Lastverhalten gemischt werden können. Die Komponente bindet die Kanäle nacheinander; die Reihenfolge spielt keine Rolle.
rbamp:
- id: panel_meter
address: 0x52
sensor_class: SCT_013
# Mixed-CT: small/medium/large on channels 0/1/2
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# The component binds channels one by one; the order does not matter.
# Each channel keeps its own model: ch0 = 5 A, ch1 = 30 A, ch2 = 20 A
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: panel_meter
current: { name: "Panel Lighting (5A CT)" } # ch0
current_1: { name: "Panel Appliances (30A CT)" } # ch1
current_2: { name: "Panel Boiler (20A CT)" } # ch2
# No voltage / power — this is an I3 SKU, current-only
text_sensor:
- platform: template
name: "Panel last error"
update_interval: 30s
lambda: 'return id(panel_meter).get_last_error_str();'
# → "OK" in a healthy state; "ERR_PARAM" if a CT model code is rejected
CT-Bindung beim Start prüfen
Nach dem Flashen und Starten steht im Protokoll:
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH0 mirror = 1 (SCT_013_005)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH1 mirror = 3 (SCT_013_030)
[D][rbamp:xxx]: panel_meter: REG_CT_MODEL_CH2 mirror = 6 (SCT_013_020)
[I][rbamp:xxx]: panel_meter: CT binding verified, all mirrors match YAML request
[C][component:246]: Setup panel_meter took ~2100ms (cold install: 3 × 700ms flash + verify)
Bei einem Warmstart (Spiegel stimmen überein), ohne Flash-Schreibvorgang:
[I][rbamp:xxx]: panel_meter: CT_MODEL[0..2] match YAML → SKIP flash erase
[C][component:246]: Setup panel_meter took 72ms (warm boot: read-compare only)
Beobachtetes Verhalten
- Gemischte CT-Bindung: die Codes [1, 3, 6] an einem Dreikanal-Modul bei 0x52 bleiben jeweils auf ihrem eigenen Kanal.
-
Ablehnung ungültiger Codes: Ein Code außerhalb des zulässigen Satzes der Klasse →
esphome configweist das Schema ab (cv.Invalid). Rutscht das YAML am Validator vorbei (manuelle Änderung / Legacy-Build), liefert die FirmwareREG_ERROR = 0xFE DEV_ERR_PARAM, und der Spiegel bleibt auf seinem vorherigen Wert. -
Dauer der Kaltinstallation: ~2.1 s beim UI3 (3 × ~700 ms Flash-Löschung).
- Dauer des Warmstarts: ~70 ms (das Lesen-Vergleichen-Schreiben überspringt jegliches Flash-Löschen).
- Latenzmessung: ca. 1.4 s vom Start von
setup()bis zur ersten Veröffentlichung (Prüfstand).
4 · GC-Synchronisation der Flotte (enge Synchronität)
Ziel: zu zeigen, dass die Flottensynchronisation 3/3 nicht akademisch ist, sondern eine reale Anforderung für Mandantenbetrieb (Unterzählung von Wohnungen an einer gemeinsamen Verteilung) und für präzise Unterzählung (das Netz von UI1 muss der Summe der Unterzähler-Leistungen bis auf die Dauer einer einzigen Periode entsprechen).
# Fleet config — all modules in one group for synchronized snapshots:
rbamp:
- id: tenant1_mains
address: 0x50
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 1
- id: tenant1_panel
address: 0x51
sensor_class: SCT_013
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
fleet_gc_enable: true
group_id: 1
- id: tenant2_mains # Independent tenant (separate group)
address: 0x52
sensor_class: SCT_013
ct_model: SCT_013_030
fleet_gc_enable: true
group_id: 2 # ⚠ different group → independent sync timeline
# Native API services for manual sync verification:
api:
port: 6053
services:
- service: emit_gc_tenant1
then:
- lambda: 'id(tenant1_mains).transmit_gc_frame();' # group = tenant1_mains group_id
- service: emit_gc_tenant2
then:
- lambda: 'id(tenant2_mains).transmit_gc_frame();' # group = tenant2_mains group_id
- service: check_sync_all
then:
- lambda: |-
uint16_t t1m = id(tenant1_mains).read_gc_tick_received();
uint16_t t1p = id(tenant1_panel).read_gc_tick_received();
uint16_t t2m = id(tenant2_mains).read_gc_tick_received();
ESP_LOGI("rbamp", "GC tick state: tenant1[mains=%u, panel=%u] tenant2[mains=%u]",
t1m, t1p, t2m);
text_sensor:
- platform: template
name: "Tenant1 GC tick (mains)"
update_interval: 30s
lambda: 'return std::to_string(id(tenant1_mains).read_gc_tick_received());'
- platform: template
name: "Tenant1 GC tick (panel)"
update_interval: 30s
lambda: 'return std::to_string(id(tenant1_panel).read_gc_tick_received());'
Beispielausgabe (10-Iterationen-Synchronisationstest)
[I][rbamp:572]: GC frame emit: group=1, tick=42, all 2 tenant1 modules ACK'd
[I][rbamp:580]: check_sync: tenant1_mains.tick=42 tenant1_panel.tick=42 → 2/2 in_sync
[I][rbamp:572]: GC frame emit: group=2, tick=42, tenant2 module ACK'd
[I][rbamp:580]: check_sync: tenant2_mains.tick=42 → 1/1 in_sync (tenant2 isolated)
ROUND 0: GC tick=1 → tenant1[1, 1] tenant2[1] → 3/3 in_sync
ROUND 1: GC tick=2 → tenant1[2, 2] tenant2[2] → 3/3 in_sync
ROUND 2: GC tick=3 → tenant1[3, 3] tenant2[3] → 3/3 in_sync
...
ROUND 9: GC tick=10 → tenant1[10,10] tenant2[10] → 3/3 in_sync
L8 soak: 180 cycles, 0 sync drops, 0 identity drops
Wie group_id bei Mehrmandanten hilft
Ohne group_id gibt es keine Trennung der Mandanten — alle Module reagieren auf jeden GC-Frame. Mit group_id:
- Die Module von Mieter 1 antworten nur auf GC-Frames mit
group=1(oder dem Gesamtaufrufgroup=0) - Die Module von Mieter 2 antworten nur auf GC-Frames mit
group=2
So kann der Master für die Mandanten getrennte GC-Frames zu unabhängigen Zeitpunkten senden — z. B. nach Mandantenperiode:
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
automation:
- alias: "Tenant 1 period snapshot"
trigger:
platform: time_pattern
seconds: "/60" # every 60 s
action:
- service: esphome._emit_gc_tenant1
- alias: "Tenant 2 period snapshot"
trigger:
platform: time_pattern
seconds: "/15" # every 15 s (high-resolution tenant)
action:
- service: esphome._emit_gc_tenant2
Validierung im Produktivbetrieb
- HA-Template-Sensor„mains_minus_subsum“ — ein Abweichungsindikator:YAML
sensor: - platform: template name: "Mains - SubSum (W)" update_interval: 60s unit_of_measurement: "W" lambda: |- // here the sub-meters are current-only, so this is a rough estimate: // mains_power - sum(sub_currents × V_mains) float v_mains = id(mains_voltage_state).state; float sub_i = id(sub_i0).state + id(sub_i1).state + id(sub_i2).state; return id(mains_power_state).state - sub_i * v_mains;
Eine Abweichung < 1 % von mains_power auf dem Prüfstand = Synchronisation korrekt.
- Integration nach Wanduhr — auch bei GC-Synchronisation 3/3 werden BASIC-Module gegen die eigene Uhr des ESP32 integriert, sodass ein kleiner Versatz zwischen den Modulen die Wh nicht verzerrt.
5 · UI1 — ein Kanal (minimal)
Quelle: ../example/ui1.yaml
Die einfachste nützliche Konfiguration: ein Spannungskanal, ein Stromkanal und sechs daraus abgeleitete Größen. Ein Ausgangspunkt für jede neue Installation — bei Bedarf um weitere Felder erweitern.
esphome:
name: rbamp-ui1
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "rbAmp UI1 Fallback"
password: !secret ap_password
captive_portal:
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended on ESP32; 100 kHz causes periodic NACKs due to ESP-IDF i2c_master driver interaction;
# 50 kHz reduces them ~5-10× — see the chapter end link.
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50
update_interval: 60s
ct_model: SCT_013_030 # CT clamp model — change it to match yours
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"
Was es zeigt: die minimal brauchbare Konfiguration. Die sechs Sensoren decken den Kernfall ab — Messung des gesamten Hauses oder einer einzelnen Last. Der Sensor energy hat bereits device_class: energy + state_class: total_increasing gesetzt, sodass er ohne weitere Einrichtung direkt im Energie-Dashboard von HA [Energy dashboard] erscheint. Das Periodenzählprotokoll (Snapshot / 50 ms Settle / mittlere Leistung lesen, auf dem Master-Takt integriert) ist in 09 · API-Referenz dokumentiert.
6 · UI1 mit Anpassung — alle gängigen ESPHome-Stellschrauben
rbAmp ist eine „gut erzogene“ ESPHome-Komponente. Jeder Slot (voltage, current, power, …) ist ein gewöhnliches ESPHome-Objekt sensor:. Der gesamte Standardsatz an Eigenschaften und Filtern funktioniert darauf. Sie brauchen weder lambda: noch eigene Templates — alles, was Sie mit pzemac / atm90e32 / cse7766 tun, funktioniert hier genauso. Das Beispiel zeigt die häufigsten Anpassungen in einem einzigen Block:
esphome:
name: rbamp-ui1-tuned
esp32:
board: esp32dev
framework:
type: arduino
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50
update_interval: 10s # ↑ Poll once / 10 s instead of the default 60 s —
# a denser graph, ~6× the I²C traffic.
ct_model: SCT_013_030
sensor:
- platform: rbamp
rbamp_id: meter1
# ──────────── Customizing names + precision + filters ────────────
voltage:
name: "Mains voltage" # Any name — it becomes the HA entity_id
accuracy_decimals: 1 # 226.7 instead of the default 226.70
filters:
# Linear calibration against a reference multimeter:
- calibrate_linear:
- 0.0 -> 0.0
- 230.0 -> 230.5
# Smoothing of sharp spikes (standard ESPHome):
- exponential_moving_average:
alpha: 0.3
send_every: 1
current:
name: "Load current"
accuracy_decimals: 3 # 0.755 instead of 0.75
filters:
# Mask the noise floor — drop values below 50 mA (50 mW at 230 V).
# The equivalent of the `noise_floor` option in pzemac / cse7766.
- lambda: 'return x < 0.05 ? 0.0f : x;'
power:
name: "Power"
accuracy_decimals: 1
filters:
# Throttle publications: no more than once / 30 s, even with update_interval 10 s.
- throttle: 30s
energy:
name: "Energy (Wh)"
# The standard device_class: energy + state_class: total_increasing
# are already set by the component — the Energy dashboard works.
filters:
# Convert Wh → kWh for a more familiar scale in Lovelace.
# (The HA Energy dashboard itself expects Wh, but if you want a graph in kWh,
# declare a second template sensor with a division rather than changing units here.)
- multiply: 0.001
unit_of_measurement: "kWh" # ← overrides the default "Wh"
accuracy_decimals: 3
frequency:
name: "Mains frequency"
accuracy_decimals: 2
power_factor:
name: "Power factor"
accuracy_decimals: 3
# Optional: a filter to hide PF at zero load (P ~ 0)
filters:
- lambda: 'return isnan(x) ? 0.0f : x;'
Was es zeigt:
-
Eigene Namen (
name:) werden zur HA-entity_id— zum Beispielsensor.rbamp_ui1_tuned_mains_voltage. Namen in jeder Sprache, auch kyrillisch, funktionieren. -
Ausgabegenauigkeit (
accuracy_decimals:) ist unabhängig vom Modul; das Modul liefert float32 mit maximaler Genauigkeit, und ESPHome kürzt den Wert für die Oberfläche. -
update_interval:muss nicht pro Sensor geändert werden — es ist eine Eigenschaft der Komponente (PollingComponent) und wird einmal im Blockrbamp:gesetzt. Wenn Sie seltenere Veröffentlichungen einzelner Sensoren wünschen, fügen Siefilters: - throttle:hinzu. -
filters:— der vollständige ESPHome-Satz: -
calibrate_linear— Punktkalibrierung gegen Ihre Referenz (Multimeter, Referenz-Amperemeter). -
exponential_moving_average/sliding_window_moving_average— Glättung. lambda— eine beliebige Transformation (Rauschbodenmaske, bedingte Null).multiply/offset— Arithmetik (zum Beispiel Wh → kWh).throttle/delta— Senken der Veröffentlichungsrate.-
unit_of_measurement:kann überschrieben werden (z. B. aufkWhmitmultiply: 0.001). HA übernimmt die neue Einheit automatisch. -
Kein
lambda:für den Grundbetrieb — alle Berechnungen für Effektivwerte, Leistung, Frequenz und Leistungsfaktor übernimmt das Modul. Der ESP32 benennt nur um, formatiert und filtert.
⚠ Überschreiben Sie device_class: für energy nicht — das HA-Energie-Dashboard erwartet streng device_class: energy + state_class: total_increasing. Die Einheitenumrechnung über multiply + unit_of_measurement: bleibt kompatibel, aber eine Änderung von device_class bricht das Dashboard.
Die vollständige Liste der Standard-Sensoreigenschaften und Filter steht in der offiziellen Dokumentation der ESPHome-Sensor Component. Diese Dokumentation gilt vollständig für rbAmp-Slots — es gibt keine Abweichungen vom Standard.
7 · UI3 — Dreikanal mit gemischten Klemmen
Quelle: ../example/ui3.yaml
Das Modul UI3 hat einen Spannungseingang und drei unabhängige Stromkanäle. Das kanonische Szenario ist, auf verschiedenen Kanälen unterschiedliche Klemmenmodelle einzusetzen: eine kleine Klemme für Verbraucher mit geringem Strom (maximale Auflösung) und eine große für die Hauptzuleitung (Reserve bei Spitzen).
esphome:
name: rbamp-ui3
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50
update_interval: 60s
# drdy_pin: GPIO15
ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]
# CH0=5A for standby consumers and LED lighting,
# CH1=30A for the main household loads,
# CH2=20A for the boiler / a medium-power branch (~3-5 kW)
# For currents above 50 A use SCT_013_060 (60 A) or SCT_013_100 (100 A).
sensor:
- platform: rbamp
rbamp_id: meter1
# Common (topology-independent)
voltage:
name: "Mains Voltage"
frequency:
name: "Mains Frequency"
apparent_power:
name: "CH0 Apparent Power"
# Channel 0 — primary current input (small consumers, 5A)
current:
name: "CH0 Current"
power:
name: "CH0 Power"
energy:
name: "CH0 Energy"
power_factor:
name: "CH0 Power Factor"
reactive_power:
name: "CH0 Reactive Power"
# Channel 1 — main loads (30A)
current_1:
name: "CH1 Current"
power_1:
name: "CH1 Power"
energy_1:
name: "CH1 Energy"
power_factor_1:
name: "CH1 Power Factor"
reactive_power_1:
name: "CH1 Reactive Power"
# Channel 2 — boiler / medium-power branch (20A)
current_2:
name: "CH2 Current"
power_2:
name: "CH2 Power"
energy_2:
name: "CH2 Energy"
power_factor_2:
name: "CH2 Power Factor"
reactive_power_2:
name: "CH2 Reactive Power"
Was es zeigt: alle drei Kanäle der UI3-SKU + gemischte Klemmenmodelle über ct_models:. Der Schema-Validator prüft, dass power_N und energy_N (und power_factor_N, reactive_power_N) current_N und voltage benötigen — deklarieren Sie power_1 ohne current_1, bricht die Kompilierung mit einer klaren Meldung ab. Jeder Kanal hat seinen eigenen, unabhängigen, im NVS gesicherten Akkumulator energy_*. Verwenden alle Kanäle dasselbe Klemmenmodell, nutzen Sie stattdessen das globale ct_model: statt ct_models:.
8 · Bus mit mehreren Modulen (drei rbAmp bei 0x50 / 0x51 / 0x52)
Quelle: ../example/multi_module.yaml
Drei Module an einem I²C-Bus — die Hauptzuleitung des Hauses, der Ausgang der Solarerzeugung und das E-Auto-Laden. Jedes hat einen eigenen Block rbamp: (im Komponentenschema MULTI_CONF = True).
esphome:
name: rbamp-multi
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: INFO
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz # recommended: at 100 kHz the ESP-IDF i2c_master driver interaction causes periodic
# NACKs are almost inevitable on every cycle
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
# Three independent rbamp: blocks — MULTI_CONF = True in the schema.
# On v1.3 firmware the general-call snapshot is opt-in via fleet_gc_enable +
# group_id (capability-gated on the firmware side). Modules in the same
# group snapshot in a single transaction, with ~540 µs skew per module. On legacy
# firmware (v1.0..v1.2) the component falls back to a sequential snapshot
# and logs an informational line. (The old broadcast_latch: key is still
# accepted by the schema but has no effect.)
rbamp:
- id: meter_house
address: 0x50
update_interval: 60s
fleet_gc_enable: true
group_id: 1
- id: meter_solar
address: 0x51
update_interval: 60s
fleet_gc_enable: true
group_id: 1
bidirectional: true # needed for energy_exported_*; on BASIC it
# publishes 0, on STANDARD it is real export energy
- id: meter_evcharger
address: 0x52
update_interval: 60s
fleet_gc_enable: true
group_id: 1
sensor:
- platform: rbamp
rbamp_id: meter_house
voltage:
name: "House Voltage"
current:
name: "House Current"
power:
name: "House Power"
energy:
name: "House Energy"
frequency:
name: "Mains Frequency"
- platform: rbamp
rbamp_id: meter_solar
voltage:
name: "Solar Voltage"
internal: true # hidden from HA — the same mains as House Voltage
current:
name: "Solar Current"
power:
name: "Solar Power"
energy:
name: "Solar Energy"
energy_exported:
name: "Solar Energy Exported"
- platform: rbamp
rbamp_id: meter_evcharger
voltage:
name: "EV Charger Voltage"
internal: true
current:
name: "EV Charger Current"
power:
name: "EV Charger Power"
energy:
name: "EV Charger Energy"
Was es zeigt: das Muster MULTI_CONF = True — deklarieren Sie so viele rbamp:-Blöcke, wie Module am Bus hängen. Jeder pflegt seinen eigenen NVS-Akkumulator, dessen Schlüssel aus der I²C-Adresse abgeleitet wird, sodass die drei Zähler über Neustarts hinweg unabhängig bleiben. Das Flag internal: true an den doppelten Spannungssensoren blendet die drei nahezu identischen Netzspannungs-Entitäten in HA aus, wenn alle Module dieselbe Phase messen. Zur Adressvergabe siehe Beispiel 2 unten.
Bedeutung von internal: true. Das Flag deaktiviert das Lesen des Registers vom Modul nicht — die Komponente liest die Spannung von jedem Modul bei jedem update_interval weiterhin (für die Leistungsberechnung nötig). Das Flag blendet den Sensor nur vor der Home-Assistant-API aus: Es wird keine Entität angelegt, er erscheint nicht in Lovelace und zählt nicht im Energie-Dashboard mit. Wollen Sie den I²C-Verkehr senken, deklarieren Sie den Slot voltage: unter sensor.platform: rbamp gar nicht — die Komponente fragt das Register dann nicht ab. Deklarieren Sie ihn, ist das Flag internal: rein kosmetisch.
Eine zweite Einschränkung betrifft die Adresseindeutigkeit am Bus:
⚠ Eindeutige Adressen liegen in der Verantwortung der Konfiguration. Das Komponentenschema (MULTI_CONF = True) prüft keine überlappenden address:-Werte zwischen rbamp:-Blöcken. Geben zwei Blöcke dieselbe address: 0x50 an, werden beide Deklarationen akzeptiert, und auf dem Bus antworten beide Ziele gleichzeitig — rechnen Sie mit I²C-Konflikten, verstümmelten Antworten oder Symptomen wie bei einem fehlenden Modul. Prüfen Sie vor dem Festschreiben des YAML, dass alle address:-Werte eindeutig sind (und nicht mit anderen I²C-Geräten am Bus kollidieren). Nach jeder Provisionierung mit new_address: aktualisieren Sie den Abschnitt rbamp: auf die neue Adresse — der alte Eintrag wird nicht automatisch ungültig.
Pull-ups an einem Bus mit mehreren Modulen
Alle drei Module werden mit werkseitigen 4.7-kΩ-Pull-ups ausgeliefert. Auf einem Bus mit drei Modulen ergibt sich parallel ~1.6 kΩ — höhere Stromaufnahme und grenzwertige Signalintegrität bei 50 kHz. Trennen Sie die Lötbrücken für Pull-ups auf allen drei Modulen und setzen ein externes Paar von 2.7–3.3 kΩ direkt an den ESP32 (die Zeile für 3 Module der Tabelle in 04_hardware.md).
Fortgeschritten: entkoppelter Snapshot-Takt für Flotten mit mehreren Modulen (v1.4+)
Flotten-Installationen zahlen die Snapshot-Kosten pro Modul und Zyklus: bei einem 3-Modul-Bus mit update_interval: 10s sind das 3× Snapshot-Schreibvorgang + 3× das 50-ms-Einschwingfenster alle 10 s — dazu die RT-Blocklesungen. Auf ESP8266-Hosts (Einkern; WLAN-ISRs konkurrieren während I²C-Transaktionen um die CPU) oder auf gemeinsam genutzten I²C-Bussen mit anderen Geräten wird dieser Mehraufwand als WLAN-Störungen oder veraltete Werte bei Nicht-rbAmp-Entitäten sichtbar.
latch_interval: (verfügbar seit v1.4, BASIC-Module) entkoppelt die beiden Takte: Die Lesungen des RT-Blocks (V/I/P/PF/Q) bleiben bei update_interval: — der Leser sieht auf dem Dashboard weiterhin frische Werte —, während die Integration Snapshot → Wh nur alle latch_interval: läuft. Die Integration verwendet die tatsächliche Wanduhrzeit zwischen den Snapshot-Ereignissen, sodass ein Snapshot-Intervall von 60 s einfach 60 s breite (und weiterhin korrekte) Integrationsschritte erzeugt. latch_interval muss ≥ update_interval sein.
rbamp:
- id: mod_mains
address: 0x50
update_interval: 10s # dashboard: fresh V/I/P/PF every 10 s
latch_interval: 60s # bus: snapshot + Wh integration once a minute
ct_models: [SCT_013_050, SCT_013_030, SCT_013_030]
fleet_gc_enable: true
group_id: 1
- id: mod_branches
address: 0x51
update_interval: 10s
latch_interval: 60s
ct_models: [SCT_013_005, SCT_013_030, SCT_013_050]
fleet_gc_enable: true
group_id: 1
Verringerung der Buslast gegenüber derselben Flotte ohne latch_interval:: Bei update_interval: 10s steuert jedes Modul pro Zyklus ca. 15 ms RT-Lesung + ca. 65 ms Snapshot und Einschwingen bei → ca. 80 ms pro Modul und Zyklus. Mit latch_interval: 60s wird der Snapshot mit Einschwingen nur einmal pro Minute ausgelöst → RT-Lesungen bleiben alle 10 s günstig, dazu ein kurzer Snapshot-Burst alle 60 s, insgesamt etwa 3× geringerer mittlerer Busanteil. Größere Flotten sparen proportional mehr.
Wann latch_interval: weggelassen werden kann: Installationen mit einem einzelnen Modul auf ESP32-Hosts, bei denen die Grundlast nichts kostet — der Einzeltakt-Standard von v1.3 ist einfacher und gleich korrekt.
9 · Einmalige Änderung der I²C-Adresse (0x50 → 0x51)
Quelle: ../example/address_change.yaml
Alle rbAmp-Module werden ab Werk auf die Adresse 0x50 gesetzt. Um mehrere Module an einem Bus zu betreiben, muss jedes vorher auf eine eigene, eindeutige Adresse umgeflasht werden, bevor sie parallel angeschlossen werden.
esphome:
name: rbamp-addr-change
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG # DEBUG shows the address-change lines
api:
ota:
- platform: esphome
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50 # current address — before the change
new_address: 0x51 # one-time target — DELETE this line after success
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "rbAmp Voltage (post-relocate)"
current:
name: "rbAmp Current (post-relocate)"
Was es zeigt: den einmaligen Ablauf der Adressänderung. Das Flashen dieses YAML lässt die Komponente das Verfahren einmal beim Start ausführen:
-
Probe
0x50. Ist0x50still und antwortet0x51bereits, wurde die Änderung in einem früheren Start angewendet; die Komponente passt sich an und protokolliert eine Warnung, die zum Aufräumen des YAML auffordert. -
Prüfen Sie, ob das Modul bereit ist, eine Provisionierung anzunehmen.
-
Die neue Adresse in den Flash schreiben (~700 ms), ein Soft-Reset (~300 ms) und erneut auf den Wechselstromzyklus einrasten.
-
Bestätigen Sie unter der neuen Adresse. Bei Erfolg zeigt das Protokoll
Address change confirmed at 0x51undIMPORTANT: update YAML to address: 0x51 and remove new_address:.
Firmware-Kompatibilität: Bei Firmware v1.3+ ist die Adressänderung produktionstauglich — die Komponente nutzt das Zwei-Phasen-Commit-Protokoll (Staging → Scharfschalten → Commit → Neustart) ohne besonderen Modus. Bei Alt-Firmware (v1.0-v1.2) setzt der einphasige Rückfall den Werks-Provisionierungsmodus voraus; das Vorgehen zum vorübergehenden Aktivieren entnehmen Sie der Modul-Dokumentation oder Ihrem Lieferanten.
Nach Erfolg: Bearbeiten Sie das YAML auf address: 0x51 und entfernen die Zeile new_address: 0x51. Erneut flashen. Ab dem nächsten Start verwendet die Komponente 0x51 normal, und der Änderungsablauf läuft nicht mehr.
Rückbau-Checkliste nach erfolgreicher Provisionierung
Damit im Repository keine „hängende“ Provisionierungsvariante zurückbleibt (zwei Alternativen, nie beide in eine Datei einfügen):
# BEFORE (provisioning):
rbamp:
id: meter1
address: 0x50 # the module's current address
new_address: 0x51 # the provisioning target
update_interval: 60s
# AFTER (production — applied next flash):
rbamp:
id: meter1
address: 0x51 # ← replaced with the new address
# new_address: 0x51 # ← DELETE the line (do not comment it out)
update_interval: 60s
Genau drei Änderungen:
- Ändern Sie den Wert von
address:von der alten auf die neue Adresse. - Löschen Sie die Zeile
new_address:(nicht auskommentieren). - Per OTA oder USB neu flashen.
Nach Schritt 3 sollte das Log eine normale dump_config-Zeile ohne die Warnung address change requested but current address matches new_address zeigen — das bedeutet, die Rücknahme war korrekt. Siehe auch 10_troubleshooting §4 „OTA direkt nach der Provisionierung mit new_address: lädt nicht“, falls das erste OTA nach der Rücknahme nicht startet.
10 · Prüfstand-Konfiguration mit Secrets
Quelle: ../example/bench-ui1.yaml
Das Muster bench-*.yaml ist für Entwicklungsrechner gedacht, auf denen WLAN-Zugangsdaten in der Konfiguration nötig sind, aber nicht in einem Commit landen dürfen. example/.gitignore schließt bench-*.yaml und secrets.yaml von der Versionsverwaltung aus.
esphome:
name: rbamp-ui1
esp32:
board: esp32dev
framework:
type: arduino
logger:
level: DEBUG
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "rbAmp UI1 Fallback"
password: !secret ap_password
captive_portal:
api:
ota:
- platform: esphome
web_server:
port: 80
version: 3 # optional: a local HTTP UI — handy for bench testing
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
scan: true
external_components:
- source:
type: local
path: ../components
components: [rbamp]
rbamp:
id: meter1
address: 0x50
update_interval: 60s
ct_model: SCT_013_030
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"
Die zugehörige secrets.yaml (in example/, nicht versioniert):
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"
Was es zeigt: Trennung der Anmeldedaten zur Kompilierzeit vom versionierten YAML über ESPHomes !secret. Wenn Sie bench-*.yaml in .gitignore auflisten, können Sie beliebig viele Testvarianten behalten, ohne Leckagerisiko. Verwenden Sie esphome run --device 192.168.0.173 example/bench-ui1.yaml für OTA nach der ersten Netzwerkverbindung oder esphome run --device COM6 example/bench-ui1.yaml für das erste USB-Flashen.
11 · Unterspannung und Netzausfall
Wenn die Netzversorgung unterbrochen wird, empfängt das isolierte analoge Frontend des Moduls kein Signal mehr. Das Spannungsregister fällt auf 0.0 V — ein gültiger endlicher IEEE-754-Float, der den Plausibilitätsfilter isfinite() der Komponente passiert. Die Filterrichtlinie der Komponente ist Absicht:
KEINE physikalischen Untergrenzen — Unterspannung (U = 0 V bei Netztrennung), Spannungseinbruch, Insel-/USV-Test und ausgelöster Leitungsschutz MÜSSEN an HA durchgereicht werden, damit der Nutzer den tatsächlichen Zustand sieht.
Zur Erkennung eines Netzausfalls ist kein besonderes YAML nötig — der Sensor voltage selbst liest 0.0 V.
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage" # reads 0.0 V when mains is disconnected
current:
name: "Mains Current"
power:
name: "Mains Power"
energy:
name: "Mains Energy"
HA-Automation: Alarm bei Netzausfall
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
# configuration.yaml or the Automations UI
automation:
- alias: "rbAmp mains loss alert"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_ui1_mains_voltage
below: 10 # U < 10 V = mains disconnected or a severe brownout
for:
seconds: 5 # debounce: sustained, not transient
action:
- service: notify.mobile_app_your_phone
data:
title: "Mains power lost"
message: >
Voltage dropped to {{ states('sensor.rbamp_ui1_mains_voltage') }} V
at {{ now().strftime('%H:%M:%S') }}.
Was es zeigt: das Verhalten der 0-V-Durchleitung als Quelle für ein Ereignis „Netzausfall“. Da die Komponente 0.0 V veröffentlicht, statt die Veröffentlichung zu überspringen, sehen HA-Automationen und das Energie-Dashboard das Spannungseinbruch-Ereignis in Echtzeit. Die Bedingung for: 5 seconds blockiert Fehlauslösungen während der ca. 250 ms Aufwärmphase nach dem Start (die Register lesen vor der ersten gültigen Messung 0).
12 · HA-Energie-Dashboard
Der Sensor energy (und energy_1, energy_2, energy_exported usw.) ist automatisch mit device_class: energy und state_class: total_increasing konfiguriert — genau das, was das HA-Energie-Dashboard für kumulative Verbrauchs- oder Erzeugungssensoren erwartet. Kein zusätzliches YAML nötig.
Nach der Erkennung:
- Einstellungen → Dashboards → Energie [Settings → Dashboards → Energy].
-
„Verbrauch hinzufügen“ → „Netzenergie“ (oder die gewünschte Bezugsmessung) wählen [Add Consumption → Mains Energy].
-
Wenn Sie Solar haben — „Erzeugung hinzufügen“ → Solarenergie wählen (aus
meter_solarim Beispiel mit mehreren Modulen).
Energiewerte werden in Wh angegeben. HA rechnet sie selbst für die Anzeige in kWh um. Die NVS-Persistenz der Komponente sorgt dafür, dass der Zähler einen Neustart des ESP32 übersteht, ohne einen falschen „Zählerreset“ in der HA-Statistik.
# Example: consumption + solar export for the HA Energy dashboard
# (assumes the rbamp: blocks meter_house and meter_solar from the multi-module example)
# energy / energy_exported need voltage AND current in the same block;
# internal: true keeps them out of Home Assistant.
sensor:
- platform: rbamp
rbamp_id: meter_house
voltage:
name: "House Voltage"
internal: true
current:
name: "House Current"
internal: true
energy:
name: "House Grid Import" # → HA Energy: grid consumption
- platform: rbamp
rbamp_id: meter_solar
voltage:
name: "Solar Voltage"
internal: true
current:
name: "Solar Current"
internal: true
energy:
name: "Solar Production" # → HA Energy: solar production
energy_exported:
name: "Solar Grid Export" # → HA Energy: return to grid
# needs bidirectional: true in rbamp:;
# real values on STANDARD (STD) modules,
# reads 0 on BASIC
13 · HA-Automationen auf rbAmp-Sensoren
Lastabwurf: Ein Relais schaltet ab, wenn ein Schwellenwert überschritten wird
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
automation:
- alias: "Load shedding — turn off non-critical loads at 3 kW"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_multi_house_power
above: 3000 # 3 kW threshold
for:
seconds: 10
action:
- service: switch.turn_off
target:
entity_id: switch.ev_charger_relay # the non-critical load relay
- alias: "Load shedding — restore when it drops below 2 kW"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_multi_house_power
below: 2000
for:
seconds: 30
action:
- service: switch.turn_on
target:
entity_id: switch.ev_charger_relay
Hinweis zur Leistungsfaktor-Korrektur
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
automation:
- alias: "Poor power factor notification"
trigger:
- platform: numeric_state
entity_id: sensor.rbamp_ui1_mains_power_factor
below: 0.7
for:
minutes: 5
action:
- service: persistent_notification.create
data:
title: "Low power factor"
message: >
Power factor is {{ states('sensor.rbamp_ui1_mains_power_factor') }}.
Check for large inductive loads (motors, old lighting ballasts).
Warnung bei Überschreitung des Tagesbudgets
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
automation:
- alias: "Daily energy budget — warning at 10 kWh"
trigger:
- platform: template
value_template: >
{{ states('sensor.energy_daily') | float(0) > 10000 }}
action:
- service: notify.mobile_app_your_phone
data:
message: "Daily energy usage exceeded 10 kWh."
14 · Lovelace-Karten
Anzeige — Live-Leistung
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
type: gauge
entity: sensor.rbamp_ui1_mains_power
min: 0
max: 3600
name: "Live Power"
segments:
- from: 0
color: green
- from: 1500
color: orange
- from: 2500
color: red
Apex Charts — Leistung über die Zeit
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
type: custom:apexcharts-card
header:
title: "Power (W)"
show: true
graph_span: 4h
series:
- entity: sensor.rbamp_ui1_mains_power
name: Power
stroke_width: 2
curve: smooth
Apex Charts — Energievergleich über drei Kanäle
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
type: custom:apexcharts-card
header:
title: "Channel Energy (Wh)"
show: true
graph_span: 24h
series:
- entity: sensor.rbamp_ui3_ch0_energy
name: CH0
- entity: sensor.rbamp_ui3_ch1_energy
name: CH1
- entity: sensor.rbamp_ui3_ch2_energy
name: CH2
Mini-Graph — Spannung
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
type: custom:mini-graph-card
entities:
- sensor.rbamp_ui1_mains_voltage
name: "Mains Voltage"
hours_to_show: 12
points_per_hour: 4
line_width: 2
15 · Versorgungszähler — Aggregation nach Tag / Woche / Monat
ESPHome veröffentlicht kumulative Summen in Wh. Die HA-Integration utility_meter setzt den Zähler in einstellbaren Intervallen zurück und veröffentlicht das Delta als eigenen Sensor — praktisch für Tages- oder Monatsaufschlüsselungen.
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
# configuration.yaml
utility_meter:
energy_daily:
source: sensor.rbamp_ui1_mains_energy
cycle: daily
name: "Daily Energy"
energy_monthly:
source: sensor.rbamp_ui1_mains_energy
cycle: monthly
name: "Monthly Energy"
energy_weekly:
source: sensor.rbamp_ui1_mains_energy
cycle: weekly
name: "Weekly Energy"
HA legt drei Entitäten an: sensor.energy_daily, sensor.energy_monthly, sensor.energy_weekly. Jede wird zu Beginn ihrer Periode auf 0 zurückgesetzt und akkumuliert den Zuwachs des Quellsensors total_increasing.
Abgeleiteter Sensor kWh/Tag
utility_meter liefert standardmäßig Wh. Für die Anzeige in kWh einen Sensor template ergänzen:
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
template:
- sensor:
- name: "Daily Energy kWh"
unit_of_measurement: "kWh"
state_class: total_increasing
device_class: energy
state: >
{{ (states('sensor.energy_daily') | float(0) / 1000) | round(3) }}
Sensor für Tageskosten
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
template:
- sensor:
- name: "Daily Energy Cost"
unit_of_measurement: "EUR"
icon: mdi:currency-eur
state: >
{% set kwh = states('sensor.energy_daily') | float(0) / 1000 %}
{% set rate = 0.28 %} # EUR/kWh — set your own tariff
{{ (kwh * rate) | round(2) }}
16 · Verbrauchsmessung je Last (3 Module bei 0x50 / 0x51 / 0x52)
Die Installation von drei rbAmp-Modulen in einer Verteilung ermöglicht Energiemessung pro Stromkreis ohne Smart-Panel oder zusätzliche Hardware.
Home-Assistant-YAML (nicht ESPHome) — gehört in Ihre Home-Assistant-Konfiguration, nicht in das YAML des Knotens.
# Extending the multi-module example with per-circuit utility meters
utility_meter:
kitchen_daily:
source: sensor.rbamp_multi_house_energy
cycle: daily
name: "Kitchen Circuit Daily"
solar_monthly:
source: sensor.rbamp_multi_solar_energy
cycle: monthly
name: "Solar Production Monthly"
ev_daily:
source: sensor.rbamp_multi_ev_charger_energy
cycle: daily
name: "EV Charging Daily"
Zusammen mit dem HA-Energie-Dashboard erhalten Sie monatliche Abrechnungen je Stromkreis ohne zusätzliche Berechnungen kWh × Tarif.
17 · rbAmp + ein Relais — Regelung im geschlossenen Kreis
Ein Boiler mit Relaissteuerung
# ESPHome YAML on the same ESP32 as rbAmp
switch:
- platform: gpio
pin: GPIO5
id: heater_relay
name: "Water Heater"
Mit rbAmp und einem Relais auf demselben ESP32 können Sie eine geschlossene Schleife direkt in ESPHome aufbauen (über ein Lambda oder on_value), ohne Umweg über HA:
Setzt voraus, dass Sie bereits einen Eintrag switch: mit der unten verwendeten ID haben.
sensor:
- platform: rbamp
rbamp_id: meter1
power:
name: "House Power"
on_value:
then:
- if:
condition:
lambda: 'return x > 3000.0f;'
then:
- switch.turn_off: heater_relay
else:
- switch.turn_on: heater_relay
Was es zeigt: Ein Relais wird über den Callback on_value eines rbAmp-Sensors gesteuert, ohne HA. Der Callback läuft auf dem ESP32 alle update_interval (60 s) und setzt den Relaiszustand anhand des letzten Leistungswerts. Für engere Regelung (Schleife < 60 s) setzen Sie update_interval auf 10s — das erhöht die Last des I²C-Busses proportional. Ein vollständigeres Regelbeispiel für einen Boiler finden Sie in 07_diy_integrations.md.
18 · DRDY-Integration
Der offene DRDY-Ausgang des Moduls liefert einen LOW-Impuls von ca. 10 µs alle ~100 ms, nachdem die Momentanregister aktualisiert wurden. Sie können ihn an einen GPIO des ESP32 anschließen. Die Komponente protokolliert den DRDY-Pin; das Lesen wird vom Timer gesteuert (update_interval).
rbamp:
id: meter1
address: 0x50
update_interval: 60s # energy integration still happens every 60 s
drdy_pin:
number: GPIO15
mode:
input: true
pullup: true # DRDY is open-drain; it needs a pull-up
inverted: true # the DRDY pulse is LOW; inverted=true gives a rising edge
: Auf der aktuellen Firmware protokolliert die Komponente drdy_pin in dump_config, implementiert aber keine interrupt-gesteuerten RT-Lesungen — update_interval bestimmt weiterhin die Abfragerate.
19 · Phasenbezogene Sensoren (Split-Phase- / Drehstrom-Varianten)
Bei Modulen mit mehr als einem Spannungseingang bietet die Komponente eine phasenbezogene Sensorgruppe (voltage_a/b/c, current_a/b/c, power_a/b/c, energy_a/b/c, power_factor_a/b/c, reactive_power_a/b/c, power_total, plus voltage_angle_b/c). Ein Slot veröffentlicht nur, wenn das angeschlossene Modul den entsprechenden Kanal meldet; bei einem Modul mit einer Spannung bleiben die phasenbezogenen Slots ohne Wert. Das Schema prüft, dass einzelne und phasenbezogene Gruppen nicht in einem Block sensor: gemischt werden.
sensor:
- platform: rbamp
rbamp_id: meter1
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_a:
name: "Phase A Power"
power_b:
name: "Phase B Power"
power_c:
name: "Phase C Power"
power_total:
name: "Total Power"
voltage_angle_b:
name: "Phase B Angle" # degrees vs phase A
voltage_angle_c:
name: "Phase C Angle"
phase_sequence:
name: "Phase Sequence" # 1 forward, 2 reverse, 3 abnormal
frequency:
name: "Grid Frequency"
Was es zeigt: die Gruppe phasenbezogener Felder. Das Mischen einzelner und phasenbezogener Felder in einem Block sensor: erzeugt einen Fehler zur Kompilierzeit — wählen Sie die Gruppe, die zu Ihrem Modul passt. Details stehen in 09 · API-Referenz §2.2.
20 · Migration von anderen ESPHome-Messkomponenten
Von pzem004t
Das Plattform pzem004t exportiert dieselben Feldnamen wie rbamp für die gängigen Wechselstromgrößen. Der Tausch erfolgt Block für Block mit identischen Sensornamen:
# Before (pzem004t, UART)
uart:
rx_pin: GPIO16
tx_pin: GPIO17
baud_rate: 9600
sensor:
- platform: pzem004t
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"
# After (rbamp, I²C) — the same sensor names → the same entity IDs in HA
# (replaces the block above; do not paste both)
i2c:
sda: GPIO21
scl: GPIO22
frequency: 50kHz
rbamp:
id: meter1
address: 0x50
ct_model: SCT_013_030
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"
Identische name:-Felder ergeben identische Entitäts-IDs in HA. Der Verlauf des Energie-Dashboards bleibt beim Tausch erhalten: Der Sensor total_increasing setzt dort an, wo er aufgehört hat. Entfernen Sie den Block uart:, wenn er nicht mit einer anderen Komponente geteilt wird.
Von cse7766 (Sonoff POW R2)
Dasselbe Muster. cse7766 liefert voltage, current, power, energy, power_factor, apparent_power — alle in rbamp vorhanden. Ersetzen Sie platform: cse7766 durch platform: rbamp, fügen Sie rbamp_id: meter1 hinzu, entfernen Sie uart: und ergänzen Sie i2c: sowie den Block rbamp:.
21 · STANDARD-Modul — Gesamtenergie aus Zählern im Gerät
Bei einem STANDARD-Modul akkumuliert die Komponente die eigenen Energiezähler des Moduls. Die Summen überleben Neustarts sowohl des ESP32 als auch des Moduls und bleiben monoton. Dasselbe YAML funktioniert auch mit einem BASIC-Modul, nur dass die Gesamtsummen-Schlüssel dort nie veröffentlicht werden.
rbamp:
id: meter1
address: 0x50
update_interval: 30s
bidirectional: true # per-channel energy_exported
start_current_ua: 400 # no energy counted below 400 µA per channel
sensor:
- platform: rbamp
rbamp_id: meter1
voltage:
name: "Mains Voltage"
current:
name: "Mains Current"
power:
name: "Mains Power"
energy_total:
name: "Energy Imported" # all channels, total_increasing
energy_exported_total:
name: "Energy Exported" # all channels, total_increasing
energy_net:
name: "Energy Net" # import - export, may decrease
reactive_energy:
name: "Reactive Energy Imported" # varh
reactive_energy_exported:
name: "Reactive Energy Exported"
Was es zeigt: die Gesamtsummen-Sensoren, die keine begleitende Deklaration current/voltage brauchen; start_current_ua: (0 = aus, sonst 10..2540 in Schritten von 10), damit Rauschen bei Nulllast nicht in die Import- und Exportzähler schleicht (Momentanwerte bleiben unberührt). Für das HA-Energie-Dashboard verwenden Sie energy_total als Netzbezug und energy_exported_total als Rückspeisung ins Netz.
22 · Wechsel des SCT-Nennwerts und Dienstüberschreibung
rbamp:
id: meter1
ct_model: SCT_013_010 # module was delivered with the SCT-013-030
Die Messwerte bleiben nach dem Wechsel genau: Bei Modul-Firmware bis 1.4.19 schließt die Komponente das Schreiben des Modells mit dem erforderlichen Modul-Neustart ab (im Log sichtbar) und skaliert Strom, Leistung und Energie auf den gewählten Sensor; neuere Firmware erledigt das im Modul. Ein Wert, den das Modul bereits hält, wird nie neu geschrieben, und bei einem Modul, das zusammen mit seinem eigenen eingebauten Sensor kalibriert geliefert wird (sensor_class: WIRED_CT / BUILTIN_CT), wird die Änderung mit einer Protokollzeile abgewiesen. Nur für eine bewusste erneute Anwendung einer Voreinstellung:
rbamp:
id: meter1
ct_model: SCT_013_010
ct_model_force: true # one-off service option; remove both lines afterwards
Zusammenfassung der YAML-Validierungsregeln
| Regel | Durchgesetzt durch |
|---|---|
power / energy / power_factor / reactive_power benötigen current |
Schema-Validator (_SINGLE_SLOT_DEPS) |
P/Q/PF/E für jeden Kanal erfordern voltage |
Schema-Validator |
Einzelne und phasenbezogene Gruppen werden nicht in einem sensor: gemischt |
_validate_topology_consistency |
new_address ≠ address |
_validate_new_address |
address im Bereich 0x08..0x77 |
cv.i2c_address |
update_interval Minimum 1s, erzwungen |
Schema-Validator |
latch_interval ≥ update_interval |
Schema-Validator |
ct_model: und ct_models: schließen sich gegenseitig aus |
Schema-Validator |
ct_models: hat 1..16 Einträge |
Schema-Validator |
ct_model_force: true erfordert ct_model: oder ct_models: |
Schema-Validator |
start_current_ua ist 0 oder 10..2540 in Schritten von 10 |
Schema-Validator |
CT-Modellcode ist für die festgelegte sensor_class gültig |
Schema-Validator |
Validierungsfehler werden bei esphome compile mit einer verständlichen Meldung gemeldet, die auf den betreffenden Schlüssel zeigt. Um einen Konfigurationsfehler zu finden, müssen Sie keine Hardware flashen.
Quelle und Probleme: rb-amp/rbamp-esphome · diese Seite im Repository: docs/06_examples.md (v1.9.1)