ESPHome

ESPHome wird für 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 Geräte nativ über 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 Geräte
Energie-Dashboard	Nutzung der stabilen Energie- und Leistungssensoren

Der ESPHome Device Builder läuft als HAOS-Add-on. Im Live-System ist Version 2026.6.3 installiert; ein Update auf 2026.6.4 ist verfügbar.

Eingebundene ESPHome-Geräte

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

Gerät	Status	Zweck
Gas-SmartMeterReader	geladen	Gaszähler auslesen
Strom-SMR	geladen	Stromzähler / Smart-Meter-Reader
Test-D1-Mini	geladen	Test-/Entwicklungsgerät, keine dokumentierte Nutzfunktion

Alle drei Einträge 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 Gaszähler und stellt den Zählerstand in Home Assistant bereit.

Hardware und Anschluss

Punkt	Wert
Board	Wemos D1 Mini / ESP8266
Funktion	Impulse des Gaszählers über Reed-Kontakt zählen
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 Zähler total_pulses erhöht. Die interne LED dient als einfache lokale Impulsanzeige.

Firmware-Logik

Baustein	Konfiguration
restore_from_flash	aktiv
flash_write_interval	5min
Zählerwert	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 für Langzeitstatistik und Energiedashboard geeignet.

Die Firmware stellt außerdem einen ESPHome-API-Service update_counter_pulses bereit. Damit kann der Impulszähler aus Home Assistant gezielt auf einen neuen Wert gesetzt werden, zum Beispiel nach Zählerwechsel, Fehlzählung oder manuellem Abgleich.

Entity	Plattform	Bedeutung
sensor.gas_smartmeterreader_gasverbrauch	ESPHome	Gasverbrauch / Zählerstand in m3
sensor.gas_smartmeterreader_uptime	ESPHome	Laufzeit des ESPHome-Geräts
sensor.gas_smartmeterreader_wifi_signal	ESPHome	WLAN-Signalstärke
sensor.gasverbrauch_in_kwh	Template	Umrechnung des Gasverbrauchs in kWh

Die kWh-Umrechnung ist kein ESPHome-Sensor, sondern ein Home-Assistant- Template auf demselben Gerät. Der Umrechnungsfaktor wird über input_number.gas_brennwert gepflegt.

Sicherheitsnotiz

Die Firmware nutzt ESPHome-API-Verschlüsselung und OTA-Passwort über Secrets. Ein Fallback-Access-Point ist konfiguriert. Das Fallback-AP-Passwort gehört 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 für den Hauptstrom- zähler.

Hardware und Schnittstelle

Punkt	Wert
Board	ESP32-C3 DevKitM-1
Framework	ESP-IDF
Zählerprotokoll	SML
UART-RX	GPIO5
Baudrate	9600
Datenformat	8 Datenbits, keine Parität, 1 Stopbit
RX-Puffer	4096

Der Stromzähler wird per UART/SML gelesen. ESPHome nutzt dafür 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 für dieses Gerät relevant: Der Smart- Meter-Reader soll nicht nur wegen kurzzeitiger API- oder WLAN-Probleme neu starten und dadurch Messdaten oder Verfügbarkeit 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 für 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 enthält API-Encryption-Key und OTA-Passwort. Diese Werte dürfen nicht ins Repo. Für 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 Gerät ist daher als Test- oder Entwicklungsgerät zu behandeln, bis eine produktive Funktion festgelegt ist.

Zugriff auf die YAML-Konfigurationen

Die eigentlichen ESPHome-YAML-Dateien konnten über den MCP-Zugriff nicht direkt ausgelesen werden. Die Konfigurationen für 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 vollständig dokumentiert werden sollen, gibt es zwei saubere Wege:

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

Für weitere ESPHome-Geräte werden weiterhin die jeweiligen YAML-Dateien benötigt. Erst damit lassen sich Pinbelegung, UART/SML-Konfiguration, Filter, Pulse-Counter, Substitutions und OTA/API-Parameter belastbar dokumentieren.

Restore-Relevanz

Für einen Wiederaufbau sind wichtig:

• ESPHome Device Builder installieren.
• YAML-Dateien der Geräte wiederherstellen.
• Secrets für WLAN/API/OTA wieder bereitstellen.
• Geräte per USB oder OTA flashen.
• Home Assistant ESPHome-Integration prüfen.
• Energie- und Template-Sensoren im Energiedashboard wieder zuordnen.