ESPHome für Einsteiger: der erste Sensor mit ESP32
ESPHome für Einsteiger: ESP32 im Browser flashen, BME280 für Temperatur, Feuchte und Luftdruck per YAML einbinden und in Home Assistant anzeigen.
Von Nathan Base
ESPHome macht aus einem Mikrocontroller für wenige Euro einen Sensor, der seine Werte direkt an Home Assistant meldet, ohne Cloud und ohne dass Du eine Zeile C++ schreibst. Du beschreibst in einer kurzen YAML-Datei, welcher Sensor an welchen Pins hängt, ESPHome baut daraus die Firmware und spielt sie auf. Viele Anleitungen setzen genau dieses Grundprinzip voraus. Hier fangen wir bei null an und bauen einen Klimasensor, der Temperatur, Luftfeuchtigkeit und Luftdruck misst.
Die Anleitung gilt für ESPHome 2026.10 und Home Assistant ab 2026.2, in dem Add-ons „Apps“ heißen. Die YAML-Konfiguration unten folgt der Vorlage, die der Assistent von ESPHome selbst erzeugt, und der offiziellen Dokumentation auf esphome.io, mit der ich auch die Klickwege im Device Builder abgeglichen habe.
Was Du brauchst
Die Einkaufsliste ist kurz:
- ein ESP32-Entwicklungsboard (Affiliate Link), am einfachsten ein „ESP32 DevKit“ mit USB-C,
- ein BME280-Sensormodul (Affiliate Link) für I2C,
- vier Steckkabel (female auf female), falls das Sensormodul Stiftleisten hat,
- ein USB-Kabel, das Daten überträgt, nicht nur Strom.
Achte beim Sensor auf das „E“: Der äußerlich identische BMP280 misst keine Luftfeuchtigkeit und wird in ESPHome anders eingebunden. Händler verwechseln die beiden gern. Dazu kommt ein laufendes Home Assistant und ein Rechner mit Chrome oder Edge, denn nur diese Browser können über USB mit dem ESP32 sprechen.
So funktioniert ESPHome
Das Prinzip ist immer dasselbe, egal ob Du einen Temperatursensor, ein Relais oder einen Präsenzmelder baust:
- Du schreibst eine YAML-Datei, die das Gerät beschreibt.
- Der ESPHome Device Builder übersetzt sie in eine Firmware.
- Die erste Firmware kommt per USB auf den ESP32, alle weiteren per WLAN.
- Home Assistant findet das Gerät im Netzwerk und legt die Sensoren automatisch an.
Der ESP32 spricht dabei direkt mit Home Assistant über dessen API, es gibt keinen Umweg über MQTT oder eine Hersteller-Cloud.
Schritt 1: Den Sensor verkabeln
Der BME280 kommuniziert über I2C, einen Bus mit zwei Datenleitungen. Verbinde die vier Pins so:
| BME280 | ESP32 |
|---|---|
| VIN (oder VCC) | 3V3 |
| GND | GND |
| SDA | GPIO21 |
| SCL | GPIO22 |
GPIO21 und GPIO22 sind auf den meisten ESP32-Boards die üblichen I2C-Pins, die Beschriftung steht auf der Platine. Schließ den Sensor an 3V3 an, nicht an 5V. Viele Module haben zwar einen Spannungsregler, aber mit 3,3 Volt bist Du bei jedem Modell auf der sicheren Seite. Hat Dein Modul zusätzlich die Pins CSB und SDO, lass sie für den Anfang frei.
Schritt 2: Den ESPHome Device Builder installieren
In Home Assistant öffnest Du Einstellungen > Apps und klickst unten rechts auf die Schaltfläche zum Installieren einer App. Such nach ESPHome Device Builder, klick darauf, dann auf Installieren und danach auf Starten. Schalte In Seitenleiste anzeigen ein, dann erreichst Du den Device Builder künftig mit einem Klick. Öffne ihn über Web-UI öffnen.
Die App gibt es nur, wenn Home Assistant als Home Assistant OS läuft, also etwa auf einem Raspberry Pi oder dem Home Assistant Green. Bei einer Installation in Docker kannst Du ESPHome als eigenen Container betreiben, der Rest der Anleitung ist dann identisch.
Schritt 3: Das Gerät anlegen und zum ersten Mal flashen
Klick im Device Builder unten rechts auf Create device und wähle New Device Setup. Der Assistent fragt nach einem Namen, etwa Wetterstation, und nach Deinen WLAN-Zugangsdaten. Als Plattform wählst Du ESP32. Die Zugangsdaten landen in einer separaten Datei secrets.yaml, damit sie nicht in jeder Gerätekonfiguration stehen.
Jetzt kommt die erste Installation. Schließ den ESP32 per USB an den Rechner an, an dem Du gerade sitzt, und wähle im Installationsdialog die Option, über diesen Computer zu installieren. Chrome zeigt eine Liste der seriellen Geräte. Wähle den Eintrag des ESP32, er heißt meist CP2102 oder USB Serial, und klicke auf Verbinden.
Der Device Builder kompiliert nun die Firmware. Das dauert beim ersten Mal einige Minuten, weil die Werkzeuge für den ESP32 heruntergeladen werden. Danach wird die Firmware übertragen, und im Log erscheint, dass sich der ESP32 mit Deinem WLAN verbunden hat. Ab jetzt steht das Gerät im Device Builder als Online.
Bleibt die Liste im Browser leer oder bricht das Übertragen ab, liegt es fast immer an Kabel oder Treiber, dazu unten mehr.
Schritt 4: Den BME280 in die YAML-Datei eintragen
Klick beim neuen Gerät auf Edit. Der Assistent hat bereits eine Grundkonfiguration angelegt. Ergänze am Ende die Abschnitte i2c und sensor, sodass die Datei so aussieht:
esphome:
name: wetterstation
friendly_name: Wetterstation
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: "DEIN-SCHLUESSEL-AUS-DEM-ASSISTENTEN"
ota:
- platform: esphome
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
ap:
ssid: "Wetterstation Fallback Hotspot"
password: "DEIN-FALLBACK-PASSWORT"
captive_portal:
i2c:
sda: GPIO21
scl: GPIO22
scan: true
sensor:
- platform: bme280_i2c
address: 0x76
update_interval: 60s
temperature:
name: "Temperatur"
humidity:
name: "Luftfeuchtigkeit"
pressure:
name: "Luftdruck"Die Werte für key und das Fallback-Passwort übernimmst Du unverändert aus Deiner Datei, die Platzhalter oben stehen nur für die vom Assistenten erzeugten Zufallswerte. Hat der Assistent im Abschnitt ota zusätzliche Zeilen angelegt, etwa zur Verschlüsselung, lässt Du sie ebenfalls stehen. Zeile für Zeile bedeutet das Folgende.
esphome legt den technischen Namen fest, unter dem das Gerät im Netzwerk als wetterstation.local erscheint, und friendly_name den Anzeigenamen in Home Assistant. esp32 beschreibt das Board, esp-idf ist das von Espressif gepflegte Framework, das ESPHome heute standardmäßig verwendet.
logger schaltet die Logausgabe ein, die Du im Device Builder unter Logs siehst. api ist die verschlüsselte Verbindung zu Home Assistant, ota erlaubt Updates per WLAN. Der Block ap zusammen mit captive_portal öffnet einen eigenen Hotspot, falls der ESP32 Dein WLAN nicht findet, etwa nach einem Passwortwechsel. Über diesen Hotspot trägst Du dann neue Zugangsdaten ein, ohne das Gerät wieder per USB anschließen zu müssen.
i2c sagt ESPHome, an welchen Pins der Bus hängt. scan: true lässt den ESP32 beim Start nach angeschlossenen Geräten suchen und das Ergebnis ins Log schreiben, was bei der Fehlersuche enorm hilft.
Unter sensor steht der eigentliche Sensor. bme280_i2c ist die Plattform für den BME280 am I2C-Bus. address ist die Busadresse des Moduls: Die meisten günstigen Breakout-Boards nutzen 0x76, manche 0x77, was zugleich der Standardwert von ESPHome ist. update_interval: 60s misst einmal pro Minute, das ist für ein Raumklima völlig ausreichend. Die drei Unterpunkte legen jeweils eine Entität mit dem angegebenen Namen an. Alle Optionen beschreibt die offizielle ESPHome-Doku zum BME280.
Klick oben rechts auf Save und dann auf Install. Weil die Grundfirmware bereits läuft, wählst Du jetzt Wirelessly. Die neue Firmware geht per WLAN auf den ESP32, das USB-Kabel brauchst Du ab hier nur noch zur Stromversorgung.
Schritt 5: Prüfen, ob der Sensor antwortet
Nach dem Neustart zeigt der Device Builder das Log des Geräts. Kurz nach dem Start sucht der ESP32 den I2C-Bus ab. Findet er den Sensor, steht dort:
Found device at address 0x76Einige Sekunden später erscheinen im Log die ersten Messwerte für Temperatur, Luftfeuchtigkeit und Luftdruck. Steht dort stattdessen Found device at address 0x77, trägst Du in der YAML address: 0x77 ein und installierst erneut.
Schritt 6: In Home Assistant einbinden
Home Assistant entdeckt das neue Gerät von selbst. Öffne Einstellungen > Geräte & Dienste, dort steht unter Entdeckt ein Eintrag ESPHome mit dem Namen Wetterstation. Klick auf Hinzufügen und bestätige. Weil die App und Home Assistant den Verschlüsselungsschlüssel kennen, musst Du ihn in der Regel nicht eintippen. Fragt Home Assistant doch danach, kopierst Du den Wert hinter key: aus der YAML-Datei.
Danach hat das Gerät drei Entitäten für Temperatur, Luftfeuchtigkeit und Luftdruck, die Du wie jeden anderen Sensor in Dashboards, Automationen und der Verlaufsansicht nutzt. Erscheint das Gerät nicht unter Entdeckt, fügst Du es über Integration hinzufügen > ESPHome manuell hinzu und gibst als Host wetterstation.local oder die IP-Adresse aus dem Log ein.
Updates und Änderungen per WLAN
Jede Änderung an der YAML wirkt erst, wenn Du Install und danach Wirelessly wählst. Speichern allein ändert auf dem Gerät nichts. Bringt eine neue ESPHome-Version Verbesserungen, zeigt Home Assistant für das Gerät ein Firmware-Update an, und im Device Builder kannst Du mehrere Geräte markieren und gemeinsam aktualisieren.
Wenn es nicht klappt
- Der Browser findet keinen seriellen Anschluss. Probier zuerst ein anderes USB-Kabel, viele mitgelieferte Kabel sind reine Ladekabel. Hilft das nicht, fehlt der Treiber für den USB-Chip des Boards. Welcher Chip verbaut ist, steht meist neben der USB-Buchse: Für CP2102 gibt es den Treiber bei Silicon Labs, für CH340 beim Hersteller WCH.
- Das Übertragen bricht bei „Connecting“ ab. Halte die Taste
BOOTauf dem Board gedrückt, während die Verbindung aufgebaut wird, und lass sie los, sobald der Fortschrittsbalken läuft. Manche Boards gehen nur so in den Flash-Modus. - Im Log steht
Found no devices. Der ESP32 sieht am I2C-Bus nichts. Prüfe die Verkabelung, vor allem ob SDA und SCL vertauscht sind, und ob der Sensor an 3V3 und GND hängt. - Im Log steht
Wrong chip ID. Du hast vermutlich einen BMP280 erwischt. Ersetze dannbme280_i2cdurchbmp280_i2cund lösche den Blockhumidity, denn dieser Chip misst keine Feuchte. - Die Temperatur ist ein bis zwei Grad zu hoch. Der ESP32 erwärmt sich im Betrieb und heizt einen direkt daneben sitzenden Sensor mit. Setz den Sensor mit ein paar Zentimetern Kabel ab und gleiche einen verbleibenden Unterschied zu einem Referenzthermometer mit einem Filter aus:
temperature:
name: "Temperatur"
filters:
- offset: -1.0Wie es weitergeht
Mit diesem Ablauf aus Verkabeln, YAML, Flashen und Einbinden baust Du jedes weitere ESPHome-Gerät. Als Nächstes bietet sich ein mmWave-Präsenzmelder mit LD2410 und ESPHome an, der zuverlässiger als ein Bewegungsmelder erkennt, ob jemand im Raum ist. Hast Du Bluetooth-Thermometer im Haus, die zu weit von Home Assistant entfernt sind, macht ein zweiter ESP32 als ESP32 Bluetooth Proxy für Home Assistant sie erreichbar. Und für die Luftqualität gibt es den Feinstaubsensor mit PMS7003 und ESPHome.
Weiterlesen.
-
Raspberry Pi & LinuxESP32 Bluetooth Proxy für Home Assistant einrichten
Mit einem ESP32 und ESPHome baust Du einen Bluetooth-Proxy, der BLE-Sensoren per WLAN an Home Assistant weiterreicht. Für mehr Reichweite.
Nathan Base -
Raspberry Pi & LinuxmmWave-Präsenzmelder mit LD2410 und ESPHome bauen
Präsenzmelder für Home Assistant selbst bauen: ESP32 und LD2410 mit ESPHome, damit das Licht anbleibt, solange jemand still im Raum sitzt.
Nathan Base -
Raspberry Pi & LinuxFeinstaubsensor selbst bauen: PMS7003 mit ESPHome
Feinstaubsensor selbst bauen: PMS7003 und Wemos D1 mini mit ESPHome flashen und in Home Assistant einbinden. Mit geprüfter Konfiguration für 2026.
Nathan Base -
Raspberry Pi & LinuxHome Assistant: Automation löst nicht aus, Fehlersuche
Deine Home-Assistant-Automation tut nichts? Mit Traces findest Du die Ursache: Trigger, Bedingung, Modus Einzeln, nicht verfügbare Entität oder Zeitzone.
Nathan Base -
Raspberry Pi & LinuxSwitchBot Meter Pro CO2 in Home Assistant einbinden
SwitchBot Meter Pro CO2 einrichten und per Bluetooth lokal in Home Assistant einbinden, ohne Hub und ohne Cloud. Mit ESP32-Proxy und Tipp zum Dauerbetrieb.
Nathan Base -
Raspberry Pi & LinuxHome Assistant: Melden, wenn ein Sensor keine Daten mehr schickt
Leere Batterie oder Funkloch: Ein Template-Sensor in Home Assistant erkennt Sensoren, die seit Stunden schweigen, und eine Automation meldet sie.
Nathan Base