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

05 · Schnellstart — von null bis Home Assistant

Etwa 5 Minuten praktische Arbeit plus Kompilier- und Flash-Zeit (die allererste Kompilierung lädt außerdem die Toolchain des ESP32 herunter, bei langsamer Verbindung bis zu ca. 15 Minuten) — damit führen Sie von einem nackten ESP32 und einem rbAmp-Modul zu Live-Sensoren in Home Assistant.

Was Sie benötigen

Hardware

  • ESP32-Board — jedes Board mit zwei freien I²C-Pins funktioniert. Die Beispiele verwenden GPIO21 (SDA) und GPIO22 (SCL) — die Standardwerte des DevKitC. Weicht Ihr Board ab, passen Sie die Pin-Nummern im YAML an.
  • rbAmp-Modul — jede SKU UI oder I. Für einen ersten Lauf ist UI1 am einfachsten: eine Spannungs- und eine Stromleitung, die wenigsten Drähte.
  • 5-V-Versorgung für rbAmp — das Modul läuft mit 4.5..5.5 V. Die USB-Versorgung des ESP32 funktioniert, wenn das Board die 5-V-Schiene herausführt.
  • CT-Zange — eine geteilte SCT-013-Stromzange, die in die CT-Buchse des Moduls gesteckt wird. Den Nennwert lesen Sie vom Aufkleber ab (z. B. SCT-013-030 = 30 A); Sie brauchen ihn für ct_model: unten.
  • Verdrahtung (Niederspannungsseite): VCC → +5 V, GND → GND, SDA → GPIO21, SCL → GPIO22. Externe Pull-up-Widerstände sind für ein einzelnes Modul nicht nötig (die eingebauten 4.7 kΩ sind bereits auf der Platine). Den vollständigen Schaltplan finden Sie unter 04_hardware.md.
  • Verdrahtung (Netzseite): Netz L und N gehen an die Klemmen L/N des Moduls (für die Spannungsmessung), und die CT-Klemme wird nur um den L-Leiter gelegt, wobei der Pfeil zur Last zeigt. Siehe 04_hardware.md und 03_sensor_selection.md.
DANGER

die L/N-Klemmen führen Netzspannung. Vor dem Anschluss den Stromkreis spannungsfrei schalten und sichern; Netzverdrahtung und Arbeiten im Schaltschrank nur durch eine Elektrofachkraft; nur EINEN Leiter (L) umklammern und die CT-Klemme nie an einem Leiter belassen, wenn die CT-Buchse nicht eingesteckt ist.

  • USB-Kabel vom ESP32 zum Rechner zum Flashen.

Software

Voraussetzung Hinweis
ESPHome ≥ 2025.3.0 Die Komponente verwendet die moderne Syntax ota: (Plattformliste) und das Objekt-ID-Hashing von ESPHome 2025.x. Geprüft bis ESPHome 2026.5 und neuer.
Python 3.11..3.13 für die CLI Die interne PlatformIO-Schicht von ESPHome (penv) akzeptiert Python 3.14 nicht. Verwenden Sie das HA-Add-on, gilt dieser Punkt nicht.
Home Assistant Jede aktuelle Version. Die automatische Erkennung funktioniert über mDNS (Avahi / Bonjour).

Zwei Kompilierwege:

  1. HA-ESPHome-Add-on (für die meisten Anwender empfohlen) — das YAML in das Konfigurationsverzeichnis des Add-ons legen und auf Kompilieren klicken. Keine lokale Python-Umgebung nötig.
  2. Lokale CLI-venv — für Entwicklung und CI. Installation mit pip install esphome in einer venv mit Python 3.11–3.13.

Einrichten einer venv (nur CLI-Pfad)

Shell
# Windows PowerShell — adjust the Python path to your 3.11 / 3.13
& "C:\Python311\python.exe" -m venv .venv-esphome
.\.venv-esphome\Scripts\Activate.ps1
pip install esphome
esphome version          # should print 2025.3.0 or newer

Unter Linux / macOS:

Shell
python3.11 -m venv .venv-esphome
source .venv-esphome/bin/activate
pip install esphome
esphome version

Schritt 1 — Komponente finden

Für den Block external_components gibt es zwei Formen — wählen Sie je nach Umgebung.

Form A — github (Standard, funktioniert im HA-Add-on)

YAML
external_components:
  - source: github://rb-amp/rbamp-esphome@v1.9.0   # pin a release tag
    components: [rbamp]
    refresh: 1d   # 1 day for production. If you track @main during
                  # development, change this to `0s`, otherwise ESPHome will
                  # cache the copy and ignore new commits.

Diese Form ist die einzige, die im HA-ESPHome-Add-on funktioniert (das Add-on hat keinen Shell-Zugriff auf Nachbarverzeichnisse). Sie ist auch für die CLI praktisch: Nichts muss lokal geklont werden.

Form B — lokaler Pfad (für die Entwicklung)

Wenn Sie rb-amp/rbamp-esphome geklont haben und direkt mit den Quellen der Komponente arbeiten, verweisen Sie ESPHome auf einen lokalen Pfad:

YAML
external_components:
  - source:
      type: local
      path: /absolute/path/to/rbamp-esphome/components
    components: [rbamp]

In example/ui1.yaml ist der Block bereits für einen relativen Pfad (../components) konfiguriert, der funktioniert, wenn Sie esphome compile aus dem Verzeichnis example/ ausführen:

Shell
cd rbamp-esphome/example
esphome compile ui1.yaml
Sicherheit

⚠ Ein lokaler Pfad funktioniert im HA-Add-on nicht — das Add-on hält das YAML in /config/esphome/ und hat keinen Shell-Zugriff auf das übrige Dateisystem. Add-on-Nutzer wählen Form A.

Schritt 2 — YAML erstellen

Kopieren Sie example/ui1.yaml als Ausgangspunkt (es verwendet den lokalen Pfad Form B; die folgende Auflistung nutzt Form A, damit sie auch im Add-on funktioniert). Öffnen Sie die Datei in einem beliebigen Editor und tragen Sie Ihre WLAN-Zugangsdaten und den Gerätenamen ein. Die vollständige Datei mit zeilenweisen Kommentaren steht unten.

Regel: power, energy, power_factor, reactive_power und apparent_power benötigen voltage UND current, deklariert im selben Block sensor: (fügen Sie internal: true zu einem Sensor hinzu, den Sie nicht als Home-Assistant-Entität möchten); andernfalls bricht esphome config mit „power requires current to also be declared“ ab. Dasselbe gilt für die nummerierten Kanalsensoren (power_1 braucht current_1 und voltage).

YAML
esphome:
  name: rbamp-ui1          # node name — sets the mDNS hostname (rbamp-ui1.local)

esp32:
  board: esp32dev           # your board (e.g. nodemcu-32s, lolin_d32)
  framework:
    type: arduino           # arduino or esp-idf — both work with the component

logger:
  level: DEBUG              # DEBUG shows I²C reads; after the first run you can use INFO

wifi:
  ssid: !secret wifi_ssid   # see secrets.yaml below
  password: !secret wifi_password
  ap:
    ssid: "rbAmp UI1 Fallback"    # fallback AP if the connection fails
    password: !secret ap_password

captive_portal:             # config page on the fallback AP

api:                        # Home Assistant native API on port 6053
  # encryption:
  #   key: "BASE64_KEY"     # optional — see 08_has_integrations.md

ota:
  - platform: esphome       # over-the-air updates

i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz          # IMPORTANT: 100 kHz causes intermittent NACKs from the module;
                            # 50 kHz reduces them ~5-10x (see 10 · troubleshooting → NACK-discipline)
  scan: true                # logs every I²C address found at boot

external_components:
  - source: github://rb-amp/rbamp-esphome@v1.9.0   # works in the HA Add-on and the CLI
    components: [rbamp]
    # Working from a local clone instead? Use Form B above.

rbamp:
  id: meter1
  address: 0x50             # factory default address
  update_interval: 60s      # how often to close the period and publish sensors
                            # minimum 1 s (v1.3); below this → cv.Invalid
  ct_model: SCT_013_030     # CT clamp model — change it to match yours
                            # (SCT_013_005 / _010 / _020 / _030 / _050 / _060 / _100)

sensor:
  - platform: rbamp
    rbamp_id: meter1
    voltage:
      name: "Mains Voltage"  # entity ID in HA: sensor.rbamp_ui1_mains_voltage
    current:
      name: "Mains Current"
    power:
      name: "Mains Power"
    energy:
      name: "Mains Energy"   # state_class: total_increasing — ready for the Energy dashboard
    frequency:
      name: "Mains Frequency"
    power_factor:
      name: "Mains Power Factor"
Hinweis

Der Schlüssel ct_model: lädt die Werkskoeffizienten für das gewählte Zangenmodell. Wenn Sie keine SCT-013-030 haben, ändern Sie ihn auf das Modell, das Sie haben. Zur Wahl siehe 03_sensor_selection.md.

secrets.yaml

Legen Sie secrets.yaml im selben Verzeichnis wie das YAML an (sie ist standardmäßig über einen Eintrag .gitignore in example/.gitignore von der Versionsverwaltung ausgeschlossen, damit Zugangsdaten nicht in einen Commit gelangen):

YAML
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"

Schritt 3 — Kompilierung

Shell
# from the example/ directory with the venv active
esphome compile ui1.yaml

Was passiert:

  1. ESPHome entpackt external_components und lädt das Python-Paket rbamp aus ../components.
  2. PlatformIO lädt die ESP32-Plattform beim ersten Lauf herunter (ca. 1–2 GB, danach im Cache). Dies ist der langsamste Schritt — bei langsamer Verbindung bis zu 15 Minuten.
  3. Die C++-Komponente kompiliert und bindet. Ein erfolgreicher Abschluss sieht so aus:
Text
SUCCESS Took 58.71 seconds
Wrote .esphome/build/rbamp-ui1/.pioenvs/rbamp-ui1/firmware.factory.bin

Bricht der Build mit Error: Failed to install Python dependencies ab, läuft der Host höchstwahrscheinlich mit Python 3.14. Verwenden Sie das HA-Add-on oder eine venv mit 3.11 / 3.13 (siehe „Was Sie brauchen“). Das ist eine Inkompatibilität zwischen dem Resolver uv von PlatformIO und bestimmten CPU-Modellen, kein Fehler der Komponente.

Schritt 4 — Erster Flash

esphome upload flasht die Binärdatei über USB. Finden Sie zuerst den richtigen Port:

  • Windows: Geräte-Manager → Anschlüsse (COM und LPT). Meist COM3–COM9.
  • Linux / macOS: ls /dev/tty* — meist /dev/ttyUSB0 oder /dev/ttyACM0.
Shell
esphome upload --device COM6 ui1.yaml             # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml     # Linux

Für den Weg über das HA-Add-on:

  1. Öffnen Sie Home Assistant → Einstellungen → Add-ons → ESPHome [Home Assistant → Settings → Add-ons → ESPHome].
  2. Öffnen Sie die Web-Oberfläche des ESPHome-Add-ons.
  3. Suchen Sie Ihr Gerät (oder klicken Sie auf „New Device“) → Install → An diesen Rechner anschließen.

Das Flash-Werkzeug (darin esptool.py) startet den ESP32 nach dem Schreiben automatisch neu. Die gesamte Flash-Zeit beträgt meist 30–60 Sekunden.

Schritt 5 — Was im Startprotokoll zu erwarten ist

Hängen Sie esphome logs an, um den Start in Echtzeit zu verfolgen:

Shell
esphome logs ui1.yaml --device COM6

Ein gesunder erster Start erzeugt ungefähr diese Zeilen (Werte und Zeiten sind Richtwerte):

Text
[D][i2c]: Found i2c device at address 0x50
[C][rbamp]: Setting up rbAmp at 0x50 ...
[C][rbamp]:   Firmware version: 0x04
[C][rbamp]:   Variant:         UI1
[C][rbamp]:   UID:             0x1A2B3C4D5E6F708192A3
[C][rbamp]:   sensor_class:    matches → skipped (nothing to write)
[C][rbamp]:   ct_model[0]:     matches → skipped (nothing to write)
[C][rbamp]: rbAmp:
[C][rbamp]:   Address: 0x50
[C][rbamp]:   Firmware version: 1.3
[C][rbamp]:   Topology: SINGLE, channels: 1, voltage: yes
[C][rbamp]:   Bidirectional: NO
[C][rbamp]:   Wh persistence: NVS every 300s
[C][component]: Setup rbamp took 67ms

Die Zeile i2c: scan: true erscheint vor den Komponentenzeilen und bestätigt, dass das Modul physisch am Bus sichtbar ist. Fehlt Found i2c device at address 0x50, siehe den Abschnitt „Was tun, wenn“ weiter unten.

Innerhalb eines update_interval (standardmäßig 60 s) erscheinen Sensorveröffentlichungen — warten Sie etwa 60 s oder setzen Sie beim Testen update_interval: 5s:

Text
[D][sensor]: 'Mains Voltage': Sending state 226.70 V
[D][sensor]: 'Mains Current': Sending state 0.755 A
[D][sensor]: 'Mains Power': Sending state 92.80 W
[D][sensor]: 'Mains Power Factor': Sending state 0.542
[D][sensor]: 'Mains Frequency': Sending state 50.0 Hz
[D][sensor]: 'Mains Energy': Sending state 0.026 Wh

Referenzwerte am Prüfstand mit einer UI1-SKU und induktiver Last: U ≈ 225 V, I ≈ 0.78 A, P ≈ 110 W, PF ≈ 0.62. Die genauen Werte hängen von der angeschlossenen Last ab.

Schritt 6 — Erkennung in Home Assistant

mDNS (automatisch)

HA findet ESPHome-Knoten mit konfiguriertem Block api: selbstständig im selben lokalen Netzwerksegment. Innerhalb von 30–60 Sekunden nach dem ersten Start des ESP32:

  1. HA zeigt eine Benachrichtigung: Neue Geräte gefunden.
  2. Einstellungen (Settings) → Geräte & Dienste (Devices & Services) → ESPHome (oder klicken Sie auf die Benachrichtigung).
  3. Wählen Sie den neuen Knoten (z. B. rbamp-ui1).
  4. Geben Sie die lokale IP des Geräts ein (in den Logs sichtbar als [I][wifi]: IP: 192.168.0.xxx), falls HA es nicht selbst gefunden hat.
  5. Add.

Alle Sensor-Entitäten werden sofort registriert. Die Entitäts-ID folgt dem Muster sensor._ (Leerzeichen durch Unterstriche ersetzt, alles klein geschrieben). Für das obige YAML: sensor.rbamp_ui1_mains_voltage, sensor.rbamp_ui1_mains_energy usw.

Manuelles Hinzufügen (falls mDNS blockiert ist)

Einstellungen → Geräte & Dienste → Integration hinzufügen → ESPHome → IP-Adresse und API-Port (6053). Ist unter api: encryption: key: ein Schlüssel gesetzt, geben Sie ihn bei der Abfrage ein.

Energie-Dashboard

Der Sensor energy ist bereits für HA Energy konfiguriert:

  • device_class: energy
  • state_class: total_increasing
  • unit_of_measurement: Wh

Einstellungen (Settings) → Dashboards → Energie (Energy) → Verbrauch hinzufügen (Add Consumption) → „Mains Energy“ auswählen. HA beginnt sofort, den kumulierten Verbrauch zu erfassen.

Schritt 7 — Skalierung auf eine Flotte (kanonische Installation mit mehreren Modulen)

Ein einzelnes UI1 am Netz liefert Gesamthaus-Summen. Für eine Aufschlüsselung nach Teilzweigen (Boiler, Klimaanlage, E-Auto) fügen Sie I2/I3-Module an demselben I²C-Bus hinzu. Das ist die 80-%-kanonische Installation (siehe 01_overview.md).

Minimale YAML-Erweiterung

YAML
i2c:
  sda: GPIO21
  scl: GPIO22
  frequency: 50kHz
  scan: true

# external_components: ... as in Step 1

rbamp:
  - id: mains_meter
    address: 0x50
    sensor_class: SCT_013
    ct_model: SCT_013_030
    fleet_gc_enable: true       # NEW v1.3 — capability-gated GC snapshot
    group_id: 1                  # cluster id

  - id: boiler_meter             # I2 sub-meter, address 0x51 after provisioning
    address: 0x51
    sensor_class: SCT_013
    ct_models: [SCT_013_020, SCT_013_010]   # 20A boiler + 10A washing machine
    fleet_gc_enable: true
    group_id: 1                  # same group → synchronized snapshots

  - id: panel_meter              # I3 sub-meter, address 0x52
    address: 0x52
    sensor_class: SCT_013
    ct_models: [SCT_013_005, SCT_013_030, SCT_013_020]   # mixed CT sizes
    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" }
    energy:  { name: "Mains Energy" }
  - platform: rbamp
    rbamp_id: boiler_meter
    current:   { name: "Boiler Current" }       # SCT_013_020 channel 0
    current_1: { name: "Washer Current" }       # SCT_013_010 channel 1
  - platform: rbamp
    rbamp_id: panel_meter
    current:   { name: "Lighting Current" }     # SCT_013_005 channel 0
    current_1: { name: "Appliances Current" }   # SCT_013_030 channel 1
    current_2: { name: "Sub-panel Current" }    # SCT_013_020 channel 2

Was vor dem ersten Start zu tun ist

  1. Adressprovisionierung — alle Module werden ab Werk auf 0x50 ausgeliefert. Das sequenzielle Verfahren (immer nur ein Neumodul am Bus) steht in 04_hardware.md Zwei-Phasen-Adress-Commit.

  2. Pull-ups — folgen Sie der Pull-up-Tabelle in 04_hardware.md Bus mit mehreren Modulen. Bei 3 Modulen: die Lötbrücken für Pull-ups auf allen durchtrennen und ein externes Paar von 2.7–3.3 kΩ (SDA und SCL gegen 3.3 V) am ESP32 ergänzen.

  3. Externe 5-V-Versorgung — 3 Module × ~15 mA = ~45 mA + ESP32 ~200 mA. Die USB-VBUS-Leitung reicht meist für die Inbetriebnahme; für einen Produktionsbetrieb verwenden Sie ein eigenes 5-V-Schaltnetzteil.

Was nach dem Start im Protokoll zu erwarten ist

Text
[D][i2c]: Found i2c device at address 0x50
[D][i2c]: Found i2c device at address 0x51
[D][i2c]: Found i2c device at address 0x52
[C][rbamp]: rbAmp 0x50: variant=UI1, fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x51: variant=I2,  fleet_gc=on, group=1
[C][rbamp]: rbAmp 0x52: variant=I3,  fleet_gc=on, group=1
[I][rbamp]: GC latch enabled fleet-wide: 3 modules in group 1

Synchronisationsprüfung

Mit UI1@0x50 + I2@0x51 + I3@0x52 und fleet_gc_enable: true:

Text
[D][rbamp]: GC frame emit: group=1, tick=42, all 3 modules ACK'd
[D][rbamp]: check_sync(tick=42) → 3/3 in_sync   ; fleet in sync

Siehe 09_api_reference.md Abschnitt Flotte für programmatisches Senden und Prüfung der Synchronisation über die native API-Dienste.

Was tun, wenn

Symptom Wahrscheinliche Ursache Was zu tun ist
Found i2c device at address 0x50 fehlt Modul nicht bestromt oder falsch verdrahtet, falsche GPIO-Pins Prüfen Sie VCC (sollte 4.5–5.0 V betragen), GND, SDA / SCL; stellen Sie sicher, dass die Pull-up-Brücken am Modul intakt sind
Probe failed at 0x50 in den Protokollen Das Modul ist im Scan sichtbar, antwortet aber nicht auf Registerlesungen Prüfen Sie frequency: 50kHz im YAML; stellen Sie sicher, dass das Modul nicht mitten in einem Flash-Schreibvorgang steckt (~700 ms)
Sensoren liefern 0 oder NaN Das Modul startet noch; in den ersten ~250 ms nach dem Einschalten lesen die Register 0 Auf den ersten Zyklus update_interval warten; die Komponente überspringt die Lesung, bis das Statusregister bereit ist
HA findet das Gerät nicht mDNS vom Router / VLAN blockiert; Block api: fehlt api: hinzufügen; manuelles Hinzufügen per IP versuchen
Warnung update() took 406ms Die Komponente ist vom Burst-Lesepfad v1.3 auf Einzelregisterlesungen zurückgefallen (4 Transaktionen × 9 Floats bei 50 kHz) Kein Problem; prüfen Sie, ob die Firmware-Version 0x04 ist und die Pull-ups am Bus der Tabelle in 04_hardware.md folgen (auf saubere 3.3 V hochgezogen) — ein gesunder v1.3-Zyklus bleibt unter 30 ms
Fällt in den AP-Modus zurück Falsche SSID / falsches Passwort; AP außer Reichweite Prüfen Sie secrets.yaml; rücken Sie näher an den AP; 2.4 GHz vs. 5 GHz

Bei Problemen, die nicht auf dieser Liste stehen, siehe 10_troubleshooting.md.

Was als Nächstes kommt


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