Teil 2 von 4

Was man braucht, damit es läuft

Sechs YAML-Blöcke, das Web-Werkzeug „Device Builder“ und meistens Home Assistant als Zentrale. Es geht aber auch ohne.

Die Grundblöcke jeder Konfiguration

So sieht die Datei aus, die der Einrichtungsassistent von ESPHome für einen ESP32 anlegt (Namen und Schlüssel sind Platzhalter):

esphome:
  name: wohnzimmer
  friendly_name: Wohnzimmer

esp32:
  board: esp32dev
  framework:
    type: esp-idf

logger:

api:
  encryption:
    key: "BASE64-SCHLUESSEL-32-BYTE"

ota:
  - platform: esphome
    password: "OTA-PASSWORT"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "Wohnzimmer Fallback Hotspot"
    password: "zufaellig12"

captive_portal:

Was die Blöcke tun:

esphome: gibt dem Gerät einen Namen. Kleinbuchstaben, Ziffern, Bindestrich, höchstens 24 Zeichen, kein Unterstrich. friendly_name ist der Anzeigename in Home Assistant.
esp32: oder esp8266: ist der Board-Block. Er sagt ESPHome, welcher Chip auf welchem Board sitzt. Beim Pico heißt der Block rp2:.
logger: schaltet die Log-Ausgabe über USB und Netz ein. Beim Basteln ist das Log der wichtigste Freund.
api: öffnet die native Schnittstelle, über die Home Assistant das Gerät anspricht. Der Schlüssel verschlüsselt die Verbindung.
ota: erlaubt Updates über WLAN („over the air“). Seit ESPHome 2024.6 muss hier platform: esphome stehen, ältere Anleitungen ohne diese Zeile funktionieren nicht mehr.
wifi: verbindet mit dem Heimnetz. Der ap:-Teil öffnet ein Notfall-WLAN, falls das nicht klappt, und captive_portal: zeigt darin eine kleine Seite, in der man neue Zugangsdaten eintragen kann.

Alle Chips außer dem ESP32-C5 kennen nur 2,4-GHz-WLAN. Ein reines 5-GHz-Netz sieht der Chip nicht.

Danach kommen die eigentlichen Bauteile: sensor:, binary_sensor:, switch:, light:, display: und so weiter. Wie das aussieht, zeigen die Bauteilkarten.

Der ESPHome Device Builder

Das Werkzeug, in dem man Konfigurationen anlegt, prüft, kompiliert und flasht, heißt seit Juni 2026 ESPHome Device Builder (vorher „ESPHome Dashboard“). Es ist eine Webseite, die auf dem eigenen Rechner oder Server läuft. Vier Wege, sie zu bekommen:

Als Add-on in Home Assistant. Der übliche Weg, ein Klick im Add-on-Store.
Per Docker: docker run --rm --net=host -v "${PWD}":/config -it ghcr.io/esphome/esphome, danach ist die Oberfläche unter Port 6052 erreichbar.
ESPHome Desktop, eine Anwendung für Windows, macOS und Linux.
Per pip: pip install "esphome-device-builder[esphome]", oder nur die Kommandozeile mit pip install esphome.

Zum allerersten Flashen ohne eigene Installation gibt es außerdem ESPHome Web unter web.esphome.io. Das läuft komplett im Browser (Chrome, Edge oder Firefox ab 151, wegen Web Serial) und kann ein Gerät vorbereiten, Firmware installieren und Logs zeigen.

Home Assistant: meistens ja, zwingend nein

Home Assistant ist die Zentrale, die alle ESPHome-Geräte einsammelt. Es findet neue Geräte automatisch im Netz, hält eine dauerhafte Verbindung (kein Abfragen, das Gerät meldet Änderungen sofort), zeigt Updates an und erlaubt Automationen über mehrere Geräte hinweg. Wer mehr als ein Gerät hat oder Dinge miteinander verknüpfen will, kommt hier an.

Es geht aber auch ohne, und für den Unterricht ist das oft der einfachere Weg:

web_server: gibt dem Gerät eine eigene kleine Webseite. Jeder im gleichen WLAN sieht die Werte im Browser und kann Schalter bedienen. Die Standardversion 2 lädt ihr Aussehen aus dem Netz, local: true packt es in die Firmware. Auf dem ESP8266 kostet der Webserver spürbar Speicher.
mqtt: schickt die Werte an einen MQTT-Broker, den man auch mit anderen Programmen abfragen kann.
http_request: lässt das Gerät selbst Webadressen aufrufen.
Automationen wie „Taster gedrückt, LED an“ laufen ohnehin direkt auf dem Chip, dafür braucht es gar keine Zentrale.

Eine Falle für den Betrieb ohne Home Assistant: Steht api: in der Datei, aber niemand verbindet sich, startet das Gerät alle 15 Minuten neu. Entweder den Block weglassen oder reboot_timeout: 0s setzen.

Was man braucht, damit es läuft

Die Grundblöcke jeder Konfiguration

Der ESPHome Device Builder

Home Assistant: meistens ja, zwingend nein

Quellen