Mit ESPHome ist es denkbar einfach einen Mikrocontroller für die Verwendung in HomeAssistant zu programmieren. Mein erster Einsatzzweck für einen selbst programmierten Mikrocontroller war das Erfassen des Wasserdurchflusses und der Temperaturwerte meiner Heizung, siehe: ESP32 programmieren, Arduino - Voraussetzungen installieren.

(Bild eines ESP32-Mikrocontrollers an einem USB-Ladekabel)

auf amazon.de:

AZDelivery ESP32 NodeMCU Module WLAN WiF...

Verfügbarkeit: Jetzt
Preis: 10,99 €
zum Stand: 17.11.2024 15:54 Details

[Produktpreise und Verfügbarkeit gelten zum angegebenen Datum/Uhrzeit und können sich ändern. Für den Kauf dieses Produkts gelten alle zum Zeitpunkt des Kaufs auf amazon.de angezeigten Preis- und Verfügbarkeitsinformationen.]

Obwohl ich den Mikrocontroller, nicht zuletzt dank zahlreicher Beispiele in Arduino, relativ schnell programmieren konnte, ist die Umsetzung mit ESPHome noch einfacher. Der Programmcode mit ähnlicher Funktionalität in ESPHome besitzt, im Verglich zu meiner Arduino-Version, ca. die Hälfte Zeilen und ist zudem wesentlich verständlicher und stabiler als meine Arduino-Version. Ein Grund warum ich meinen funktionierenden Mikrocontroller mit ESPHome neu programmiert habe, war, dass ich den ESP hin und wieder neu starten musste, damit dieser die Verbindung zum MQTT-Broker erneut aufbaute.

Für Änderungen am Programmcode oder für das Debugging musste ich mit Arduino entweder einen Laptop im Heizraum anstecken oder bei gröberen Änderungen den Mikrocontroller ausbauen und diesen an einem gemütlicheren Ort programmieren: Dann mehr oder weniger blind ohne Sensoren, da diese ja im Heizraum verbaut sind. Grund genug um ESPHome zu testen.

Was ist ESPHome?

ESPHome ist eine schlanke Weboberfläche mit dessen Hilfe Mikrocontroller, wie der ESP8266 oder ESP32 programmiert und einfach in Home Assistant eingebunden werden können. Programmiert wird in ESPHome, im Gegensatz zu Arduino, primär nicht mit C, sondern in YAML-Dateien. ESPHome wandelt den YAML-Code in C um, kompiliert diesen und spielt das fertige Programm auf den Mikrocontroller. Das fertige Beispielprogramm kümmert sich um die WLAN-Verbindung und um die Möglichkeit sich selbst upzudaten. Zudem liefert es die Basis für die Kommunikation mit Home Assistant.

OTA-Update

Mit ESPHome können die Geräte per WLAN programmiert und die Konsolen-Ausgabe angezeigt werden: OTA-Update, also Over-the-Air-Update. Wurde der ESP mit dem Basiscode bespielt, kann das Gerät somit schon mal an seinem Einsatzort verbaut und verkabelt werden und später über WLAN von einem beliebigen Browser mit der notwendigen Software versorgt werden.

ESPHome in Docker inkl https

Ich betreibe Home Assistent in Docker, daher ist der AddOn Store nicht verfügbar. ESPHome kann über einen zusätzlichen Docker Container hinzugefügt werden.

docker-compose.yml

Um ESPHome mittels docker compose zu starten, kann das offizielle Docker ESPHome-Image verwendet werden. Das Image kann mit einer simplen docker-compose.yml Datei heruntergeladen, erstellt und gestartet werden. Die Datei kann mit einem beliebigen Texteditor wie folgt befüllt und dann angepasst werden:

Dateiname: docker-compose.yml, Inhalt:

services:
  esphome:
    container_name: esphome
    image: esphome/esphome
    privileged: true
    environment:
        - USERNAME=admin
        - PASSWORD=???
        - ESPHOME_DASHBOARD_USE_PING=true
   #Für einen direkten Zugriff, ohne Internet. Aufruf: http://localhost:6052 oder http://ServerIP:6052
    ports:
      - 6052:6052
    dns: 
      - 192.168.1.1
    volumes:
      - ./esphome:/config:rw
   #Labels für ReverseProxy, siehe: https://www.libe.net/traefik
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.esphome.rule=Host(`esphome.domain.tld`)"      
      - "traefik.http.routers.esphome.entrypoints=web"
      - "traefik.http.routers.esphome.entrypoints=websecure"
      - "traefik.http.routers.esphome.tls.certresolver=myresolver"      
      - "traefik.http.services.esphome.loadbalancer.server.port=6052"
    restart: always

#Ohne dem Einsatz eines Reverse Proxy (https://www.libe.net/traefik) fehlt voraussichtlich das Netzwerk webproxy 
#und die folgenden Zeilen können entfernt oder auskommentiert werden. Alternativ kann das Netzwerk mit "docker network create webproxy" erstellt werden
networks:
  default:
    name: webproxy
    external: true

Für einen direkten Zugriff über die IP-Adresse oder localhost - auch ohne Reverse Proxy, DNS oder öffentlicher IP - beinhaltet die Konfiguration "ports: - 6052:6052", wodurch der Aufruf auch über localhost:6052 erfolgen kann. Für den Einsatz ohne Reverse-Proxy kann der Bereich network: .. entfernt werden.

Damit der Internetzugriff über den Traefik Reverse Proxy funktioniert, muss in den Labels die Domäne mit den zuvor erstellten DNS-Einträgen ersetzt werden (im Beispiel: esphome.domain.tld). Das Beispiel verwendet Docker Bind-Mounts und keine Volumes für das permanente Speichern der Daten. Siehe: Docker Daten speichern: Docker Volumes vs. Host-Ordner. Für eine funktionierende Namensauflösung von ESPHome zu den Mikrocontrollern habe ich auch noch meinen Router als DNS-Server hinzugefügt, siehe: offline.

Container starten

Der Start erfolgt aus dem Ordner der docker-compose.yml-Datei mit dem Befehl "docker compose up“:

docker compose up -d

Inbetriebnahme / erster Aufruf der Weboberfläche

Beim Aufruf der angegebenen Domain (https://wp.domain.tld) meldet sich ESPHome mit einer Login-Maske. Der Benutzername und das Passwort können in der docker-compose.yml-Datei vorgegeben und geändert werden.

Beim Klick auf "NEW DEVICE" können neue Mikrocontroller angelegt werden:

Die Verbindung zum Mikrocontroller muss dabei initial über ein Kabel erfolgen. In meinem Fall habe ich den Mikrocontroller an einem Rechner mit USB angeschlossen, was mir das Verbinden über den Browser mittels des UART Bridge Controller ermöglicht (Plug into this computer). Da die Verbindung zum Mikrocontroller über den Browser erfolgt, spielt es bei dieser Variante auch keine Rolle, wenn der ESPHome-Server auf einem anderen Gerät läuft:

HA-Integration

Damit die Mikrocontroller als Geräte in Home Assistant auftauchen, benötigen wir die ESPHome-Integration:

Für die Verbindung habe ich zunächst die IP-Adresse meines ersten Mikrocontrollers verwendet:

Zurück zu ESPHome, kann darin ein API-Key (Encryption key) ausgelesen werden:

Der Encryption key wird für die Verbindung in Home Assistant benötigt:

Hier ein Blick auf meinen eingebundenen Mikrocontroller und dessen zur Verfügung gestellten Sensoren:

ESP-Home als Menüpunkt in der Home-Assistant Sidebar

Damit sich ESPHome in die Home Assistant-Gui integriert, kann das Webservice in der configuration.yaml-Datei als panel_iframe angelegt werden:

Folgende Zeilen zu Beginn der configuration.yaml fügen ESPHome als neuen Menüpunkt hinzu:

panel_iframe:
  esphome:
    title: "ESPHome"
    url: "https://esphome.domain.tld/"
    icon: mdi:docker

Die "url:" muss hier natürlich mit der zuvor konfigurierten URL ersetzt werden.

Troubleshooting

Mein erster Versuch endete mit folgendem Fehler: "Please upgrade to the PlatformIO Core 6"

Ich habe ESPHome schon vor einiger Zeit getestet und dabei einen Docker-Container gestartet. Beim erneuten Versuch ESPHome zu verwenden, konnte ich den ESP32 fürs Erste nicht programmieren, da der Container offensichtlich zu alt war: Ein "docker-compose pull" konnte das Problem beheben, indem eine neue Version von ESPHome heruntergeladen wurde.

Configuration created but unable to detect the device on the network

Ursprünglich wollte ich den ESP auf ein verstecktes WLAN verbinden, was aber nicht funktionierte. Die Lösung war ein sichtbares WLAN für die Verbindung zu verwenden.

Offline

Obwohl der Controller einwandfrei funktionierte, wurde dieser dennoch als "OFFLINE" angezeigt:

Der ESPHome Docker-Container versucht den Controller offensichtlich mit dessen Namen heating.local aufzurufen. Damit er das kann, habe ich den DNS-Namen des ESP32 am Router hinterlegt und die IP-Adresse meines Routers in der docker-compose.yml-Datei hinzugefügt (dns:...).

Fazit

Speziellen Projekten oder der Einsatz einer günstigen DIY-Hardware steht mit ESPHome nichts im Weg. Die zahlreichen Beispiele auf der ESPHome-Seite erleichtern die Programmierung und Einbindung in Home Assistant. Für die Anbindung eines Ultraschall-Durchflussmessers habe ich ein Beispiel auf folgender Seite abgelegt:  ESP32 Flowmeter - RS485 Modbus. Wie DS18B20-Temperatursensoren ausgelesen werden können, ist auf dieser Seite zu finden:  DS18B20 - Temperatur-Sensoren in ESP-Home.  Die Steuerung meiner Heizung habe ich hier dokumentiert: Heizung mit Home Assistant steuern.