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) undGPIO22(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ürct_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.
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:
- 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.
- Lokale CLI-venv — für Entwicklung und CI. Installation mit
pip install esphomein einer venv mit Python 3.11–3.13.
Einrichten einer venv (nur CLI-Pfad)
# 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:
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)
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:
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:
cd rbamp-esphome/example
esphome compile ui1.yaml
⚠ 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).
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"
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):
wifi_ssid: "YourNetworkName"
wifi_password: "YourPassword"
ap_password: "rbamprbamp"
Schritt 3 — Kompilierung
# from the example/ directory with the venv active
esphome compile ui1.yaml
Was passiert:
- ESPHome entpackt
external_componentsund lädt das Python-Paketrbampaus../components. - 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.
- Die C++-Komponente kompiliert und bindet. Ein erfolgreicher Abschluss sieht so aus:
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/ttyUSB0oder/dev/ttyACM0.
esphome upload --device COM6 ui1.yaml # Windows
esphome upload --device /dev/ttyUSB0 ui1.yaml # Linux
Für den Weg über das HA-Add-on:
- Öffnen Sie Home Assistant → Einstellungen → Add-ons → ESPHome [Home Assistant → Settings → Add-ons → ESPHome].
- Öffnen Sie die Web-Oberfläche des ESPHome-Add-ons.
- 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
4.7 CT-Modell-Verifikationsspiegel (0x51..0x53) (API-Referenz) · 8.10 Rücklesen des CT-Modell-Verifikationsspiegels (Plausibilität nach der Zuordnung) (API-Referenz)
Hängen Sie esphome logs an, um den Start in Echtzeit zu verfolgen:
esphome logs ui1.yaml --device COM6
Ein gesunder erster Start erzeugt ungefähr diese Zeilen (Werte und Zeiten sind Richtwerte):
[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:
[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:
- HA zeigt eine Benachrichtigung: Neue Geräte gefunden.
- Einstellungen (Settings) → Geräte & Dienste (Devices & Services) → ESPHome (oder klicken Sie auf die Benachrichtigung).
- Wählen Sie den neuen Knoten (z. B.
rbamp-ui1). - 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. - 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: energystate_class: total_increasingunit_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
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
-
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.
-
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.
-
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
[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
6.3 GC-Broadcast-Snapshot — optionale Fleet-Synchronisation (api-reference) · 8.4 GC-Broadcast-Snapshot + Witness-Fallback (api-reference)
Mit UI1@0x50 + I2@0x51 + I3@0x52 und fleet_gc_enable: true:
[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
- Dreikanal-Aufbau: 06_examples.md — UI3-YAML mit drei unabhängigen Stromkanälen und allen abgeleiteten Größen.
- Mehrere Module an einem Bus: 06_examples.md — der Abschnitt zu Mehrmodul-Installationen.
- Vertiefung zu HA Energy: 08_has_integrations.md.
- DIY-Integrationen (Grafana, MQTT, Automationen): 07_diy_integrations.md.
- Vollständige Konfigurationsreferenz: 09_api_reference.md.
- Diagnose von Problemen bei Ihrem ersten Lauf mit rbAmp: 10_troubleshooting.md.
Quelle und Probleme: rb-amp/rbamp-esphome · diese Seite im Repository: docs/05_quickstart.md (v1.9.1)