ESPHome

ESPHome wird fuer eigene ESP-basierte Sensoren genutzt, bei denen die Firmware und die eigentliche Messlogik als YAML im ESPHome Device Builder gepflegt werden. Home Assistant bindet die fertigen Geraete nativ ueber die ESPHome- Integration ein.

Betriebsmodell

Baustein	Rolle
ESPHome Device Builder	Firmware bauen, YAML-Konfiguration pflegen, OTA-Updates
Home Assistant Integration esphome	Native Einbindung der geflashten Geraete
Energie-Dashboard	Nutzung der stabilen Energie- und Leistungssensoren

Der ESPHome Device Builder laeuft als HAOS-Add-on. Im Live-System ist Version 2026.6.3 installiert; ein Update auf 2026.6.4 ist verfuegbar.

Eingebundene ESPHome-Geraete

Aus Home Assistant sind aktuell drei ESPHome-Config-Entries geladen:

Geraet	Status	Zweck
Gas-SmartMeterReader	geladen	Gaszaehler auslesen
Strom-SMR	geladen	Stromzaehler / Smart-Meter-Reader
Test-D1-Mini	geladen	Test-/Entwicklungsgeraet, keine dokumentierte Nutzfunktion

Alle drei Eintraege wurden per Zeroconf erkannt. Die ESPHome-Optionen sind bei allen gleich gesetzt:

Option	Wert	Bedeutung
allow_service_calls	false	Keine ESPHome-Service-Calls aus HA erlauben
subscribe_logs	false	Keine Live-Logs dauerhaft abonnieren

Gas-SmartMeterReader

Der Gas-SmartMeterReader erfasst den Gaszaehler und stellt den Zaehlerstand in Home Assistant bereit.

Hardware und Anschluss

Punkt	Wert
Board	Wemos D1 Mini / ESP8266
Funktion	Impulse des Gaszaehlers ueber Reed-Kontakt zaehlen
Reed-Signal	GPIO5 / D1
Reed-GND	GND
Status-LED	GPIO2 / D4, invertiert
Eingang	INPUT_PULLUP
Entprellung	delayed_on: 100ms

Der Reed-Kontakt zieht das Signal gegen Masse. Bei erkanntem Impuls wird der globale Zaehler total_pulses erhoeht. Die interne LED dient als einfache lokale Impulsanzeige.

Firmware-Logik

Baustein	Konfiguration
restore_from_flash	aktiv
flash_write_interval	5min
Zaehlerwert	globaler Integer total_pulses, mit Restore
Startwert	manuell gesetzter Impulsstand
Umrechnung	total_pulses * 0.01
Einheit	m3
ESPHome-Updateintervall	60s

Ein Impuls entspricht 0.01 m3. Der ESPHome-Sensor ist als device_class: gas und state_class: total_increasing definiert und damit fuer Langzeitstatistik und Energiedashboard geeignet.

Die Firmware stellt ausserdem einen ESPHome-API-Service update_counter_pulses bereit. Damit kann der Impulszaehler aus Home Assistant gezielt auf einen neuen Wert gesetzt werden, zum Beispiel nach Zaehlerwechsel, Fehlzaehlung oder manuellem Abgleich.

Entity	Plattform	Bedeutung
sensor.gas_smartmeterreader_gasverbrauch	ESPHome	Gasverbrauch / Zaehlerstand in m3
sensor.gas_smartmeterreader_uptime	ESPHome	Laufzeit des ESPHome-Geraets
sensor.gas_smartmeterreader_wifi_signal	ESPHome	WLAN-Signalstaerke
sensor.gasverbrauch_in_kwh	Template	Umrechnung des Gasverbrauchs in kWh

Die kWh-Umrechnung ist kein ESPHome-Sensor, sondern ein Home-Assistant- Template auf demselben Geraet. Der Umrechnungsfaktor wird ueber input_number.gas_brennwert gepflegt.

Sicherheitsnotiz

Die Firmware nutzt ESPHome-API-Verschluesselung und OTA-Passwort ueber Secrets. Ein Fallback-Access-Point ist konfiguriert. Das Fallback-AP-Passwort gehoert nicht in die Dokumentation und sollte rotiert werden, wenn die YAML ausserhalb des ESPHome Device Builders geteilt wurde.

Strom-SMR

Strom-SMR ist der ESPHome-basierte Smart-Meter-Reader fuer den Hauptstrom- zaehler.

Hardware und Schnittstelle

Punkt	Wert
Board	ESP32-C3 DevKitM-1
Framework	ESP-IDF
Zaehlerprotokoll	SML
UART-RX	GPIO5
Baudrate	9600
Datenformat	8 Datenbits, keine Paritaet, 1 Stopbit
RX-Puffer	4096

Der Stromzaehler wird per UART/SML gelesen. ESPHome nutzt dafuer einen uart-Bus my_uart und eine SML-Instanz my_sm.

Firmware-Logik

Punkt	Wert
Logger-Level	WARN
api.connection Logs	ERROR
sml Logs	ERROR
API-Reboot-Timeout	0s
WLAN-Reboot-Timeout	0s
WLAN Power Save	none
Fallback-AP	nicht konfiguriert
Captive Portal	nicht konfiguriert

Der deaktivierte Reboot-Timeout ist fuer dieses Geraet relevant: Der Smart- Meter-Reader soll nicht nur wegen kurzzeitiger API- oder WLAN-Probleme neu starten und dadurch Messdaten oder Verfuegbarkeit verlieren.

Entity	Plattform	Bedeutung
sensor.strom_smr_e_in	ESPHome	Kumulierte Netzbezugsenergie
sensor.strom_smr_e_out	ESPHome	Kumulierte Netzeinspeisung
sensor.strom_smr_p_in	ESPHome	Aktuelle Bezugsleistung

Diese Sensoren sind die relevanten stabilen Messpunkte fuer Energieauswertung und HA-Energiedashboard.

SML-OBIS-Zuordnung

ESPHome-Sensor	OBIS-Code	Einheit	Filter	Bedeutung
E_in	1-0:1.8.0	kWh	multiply: 0.0001, throttle: 10s	Netzbezug kumuliert
E_out	1-0:2.8.0	kWh	multiply: 0.0001, throttle: 10s	Einspeisung kumuliert
P_in	1-0:16.7.0	W	throttle: 5s	Momentane Leistung

E_in und E_out sind als total_increasing konfiguriert. P_in ist ein laufender Messwert mit state_class: measurement.

Sicherheitsnotiz

Die Strom-SMR-YAML enthaelt API-Encryption-Key und OTA-Passwort. Diese Werte duerfen nicht ins Repo. Fuer die dauerhafte Pflege sollten sie in ESPHome- Secrets ausgelagert und nach dem Teilen der Konfiguration rotiert werden.

Test-D1-Mini

Test-D1-Mini ist als ESPHome-Integration geladen, liefert in der aktuell gelesenen Registry aber keine dokumentierten Nutzsensoren. Das Geraet ist daher als Test- oder Entwicklungsgeraet zu behandeln, bis eine produktive Funktion festgelegt ist.

Zugriff auf die YAML-Konfigurationen

Die eigentlichen ESPHome-YAML-Dateien konnten ueber den MCP-Zugriff nicht direkt ausgelesen werden. Die Konfigurationen fuer Gas-SmartMeterReader und Strom-SMR wurden manuell bereitgestellt und in dieser Seite bereinigt dokumentiert.

• Der ESPHome Device Builder ist gestartet und per Ingress erreichbar.
• Die direkte Add-on-API /devices liefert ohne freigegebenen Host-Port 6052 einen 403 Forbidden.
• Der Add-on-Port 6052/tcp ist aktuell nicht auf den Host gemappt.

Wenn die Firmware-YAMLs vollstaendig dokumentiert werden sollen, gibt es zwei saubere Wege:

1. In Home Assistant beim Add-on ESPHome Device Builder den Port 6052/tcp temporaer auf einen Host-Port mappen und das Add-on neu starten.
2. Die ESPHome-Konfigurationsdateien aus dem Add-on-Ordner oder Backup separat bereitstellen.

Fuer weitere ESPHome-Geraete werden weiterhin die jeweiligen YAML-Dateien benoetigt. Erst damit lassen sich Pinbelegung, UART/SML-Konfiguration, Filter, Pulse-Counter, Substitutions und OTA/API-Parameter belastbar dokumentieren.

Restore-Relevanz

Fuer einen Wiederaufbau sind wichtig:

• ESPHome Device Builder installieren.
• YAML-Dateien der Geraete wiederherstellen.
• Secrets fuer WLAN/API/OTA wieder bereitstellen.
• Geraete per USB oder OTA flashen.
• Home Assistant ESPHome-Integration pruefen.
• Energie- und Template-Sensoren im Energiedashboard wieder zuordnen.