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

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
Hinweis

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

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

Text
[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_interval sendet 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_power in 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 entspricht mains_power ungefä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)

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)

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

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:

Text
[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.

Hinweis

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

Text
[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.

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

Text
[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:

Text
[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 config weist das Schema ab (cv.Invalid). Rutscht das YAML am Validator vorbei (manuelle Änderung / Legacy-Build), liefert die Firmware REG_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).

YAML
# 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)

Text
[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 Gesamtaufruf group=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.

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

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

YAML
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 Beispiel sensor.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 Block rbamp: gesetzt. Wenn Sie seltenere Veröffentlichungen einzelner Sensoren wünschen, fügen Sie filters: - 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. auf kWh mit multiply: 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.

Sicherheit

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

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

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

Hinweis

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:

Sicherheit

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

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

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

  1. Probe 0x50. Ist 0x50 still und antwortet 0x51 bereits, 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.

  2. Prüfen Sie, ob das Modul bereit ist, eine Provisionierung anzunehmen.

  3. Die neue Adresse in den Flash schreiben (~700 ms), ein Soft-Reset (~300 ms) und erneut auf den Wechselstromzyklus einrasten.

  4. Bestätigen Sie unter der neuen Adresse. Bei Erfolg zeigt das Protokoll Address change confirmed at 0x51 und IMPORTANT: 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):

YAML
# BEFORE (provisioning):
rbamp:
  id: meter1
  address: 0x50               # the module's current address
  new_address: 0x51           # the provisioning target
  update_interval: 60s
YAML
# 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:

  1. Ändern Sie den Wert von address: von der alten auf die neue Adresse.
  2. Löschen Sie die Zeile new_address: (nicht auskommentieren).
  3. 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.

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

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

Sicherheit

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.

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

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

  1. Einstellungen → Dashboards → Energie [Settings → Dashboards → Energy].
  2. „Verbrauch hinzufügen“ → „Netzenergie“ (oder die gewünschte Bezugsmessung) wählen [Add Consumption → Mains Energy].

  3. Wenn Sie Solar haben — „Erzeugung hinzufügen“ → Solarenergie wählen (aus meter_solar im 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.

YAML
# 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.

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

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

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

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

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

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

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

YAML
# 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.

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

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

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

YAML
# 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.

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

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

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

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

YAML
# 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"
YAML
# 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.

YAML
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

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

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