ESPHome und Home Assistant: Eigene Sensoren bauen, ohne zu programmieren

ESPHome verwandelt Mikrocontroller per YAML-Datei in Smart-Home-Geräte, die Home Assistant selbstständig einbindet, ganz ohne C++ (Stand: November 2026). Die erste Installation muss laut der ESPHome-Einsteigeranleitung per USB-Kabel laufen, erst danach gehen Updates drahtlos. Laut Home Assistant nutzen 27,4 Prozent der aktiven Installationen die ESPHome-Integration.

Was braucht ESPHome, damit der erste Sensor läuft?

Wer mit ESPHome Sensoren bauen will, braucht laut der Einsteigeranleitung auf esphome.io einen Mikrocontroller, ein USB-Kabel und eine installierte ESPHome-Software. Ein Mikrocontroller ist ein winziger Chip mit Prozessor und Anschlusspins, wie er in vielen Steckdosen und Sensoren steckt. Ihr Gerät beschreiben Sie in einer Konfiguration. Das sind eine oder mehrere YAML-Dateien, die auflisten, welche Hardware am Chip hängt. (YAML ist ein Textformat, in dem Einrückungen die Struktur festlegen.) Die Software liest diese Beschreibung und baut daraus eine passende Firmware. Alles, was Sie definieren, erscheint automatisch in Home Assistant.

Die Weboberfläche dafür heißt Device Builder. Dort legen Sie Konfigurationen an, bearbeiten und installieren sie. Wer stattdessen das Kommandozeilenwerkzeug installiert hat, nutzt dieselbe YAML. Fehlt Ihnen Home Assistant noch, hilft die Anleitung zum Home Assistant installieren.

Die Tabelle nennt die Mikrocontroller-Familien, die laut Home-Assistant-Dokumentation mit ESPHome laufen.

Die Geräte-Datenbank des Projekts bildet laut Home Assistant nur einen Teil des Möglichen ab. Weitere Geräte und Zubehör funktionieren, stehen dort aber nicht drin. Das Projekt wird offenbar eifrig gepflegt: Die GitHub-Seite zeigt 19.635 Commits (gespeicherte Änderungsschritte), 12,0k Sterne und 5,8k Forks (Kopien des Projekts). Für ein Bastelprojekt ist das eine ordentliche Hausnummer.

Kabel zuerst, Funk später: So bekommt der Chip seine erste Firmware

Die erste Installation eines ESPHome-Geräts muss laut Einsteigeranleitung per USB-Kabel passieren, jedes spätere Update läuft drahtlos. Drahtlos heißt hier „over the air“, kurz OTA. Im Device Builder gehen Sie so vor:

1. Schließen Sie den Mikrocontroller per USB-Kabel an, bis Ihr Rechner ihn erkennt.
2. Öffnen Sie den Device Builder und klicken Sie bei leerer Geräteliste auf „Create device“.
3. Wählen Sie im Assistenten „New Device Setup“, wenn Sie unsicher sind.
4. Tragen Sie Ihre WLAN-Zugangsdaten ein, sonst erreicht das Gerät weder Ihr Netz noch Home Assistant.
5. Fügen Sie über „Edit“ die gewünschte Hardware in die YAML ein und klicken Sie auf „Save“.
6. Klicken Sie auf „Install“, damit die Firmware kompiliert und auf das Gerät geladen wird.
7. Bestätigen Sie in Home Assistant das automatisch entdeckte Gerät.

Klingt einfach, ist es aber nicht immer. Die Anleitung nennt diese erste Installation den meist hakeligsten Teil des ganzen Vorgangs, zumindest bis Sie sie einige Male gemacht haben.

Tipp: Speichern verändert das Gerät nicht, erst ein Klick auf „Install“ schickt die neue Konfiguration auf den Chip.

Der Assistent bietet drei Wege. „New Device Setup“ führt durch Plattform, Board und WLAN. „Import from File“ lädt eine vorhandene .yaml- oder .yml-Datei hoch, etwa für Backups. „Empty Configuration“ startet leer, für alle, die selbst schreiben oder eine Vorlage von devices.esphome.io einfügen. Unter Home Assistant liegen die Dateien im Ordner /config/esphome/, etwa als living-room.yaml.

Wer lieber im Terminal arbeitet, findet für jeden Schritt einen Befehl, die YAML bleibt identisch. Die Tabelle ordnet jede Aktion dem passenden Kommando zu.

Der Befehl run prüft die Konfiguration, kompiliert und lädt hoch. Auch hier braucht der erste Lauf das USB-Kabel. Dabei entsteht ein Ordner mit dem erzeugten PlatformIO-Projekt, in dem Sie nach Belieben stöbern dürfen.

Aus YAML wird Hardware: Switch und Binärsensor im Detail

Ein GPIO-Switch und ein Binärsensor sind die beiden Beispiele, mit denen die ESPHome-Anleitung das erste Gerät ausstattet. GPIO steht für einen frei nutzbaren Anschlusspin des Chips. Ein Switch schaltet etwas, ein Binärsensor meldet einen von zwei Zuständen.

Dieses Bild wurde mit KI generiertProviderhiggsfieldModellgpt_image_2_5 flare high 1k 16:9Promptcinematic photo with dramatic lighting, close-up of a NodeMCU-style microcontroller board on a dark workbench, wired with jumper cables to a small relay module and a magnetic window contact sensor. In the blurred background a monitor glows with a YAML configuration file in a code editor, showing indented text lines. Low-key lighting with a cool blue key light and a warm orange rim light, shallow depth of field, reflective metal pins in sharp focus, no people, no hands, no readable numbers. No watermark, no signature.

So sieht der Schalter aus:

switch:
  - platform: gpio
    name: "Living Room Dehumidifier"
    pin: GPIOXX

Ersetzen Sie GPIOXX durch den Pin, an dem Ihre Hardware tatsächlich hängt. Der Schalter kann einen Entfeuchter, eine Lampe oder einen Lüfter steuern. Der Name ist frei wählbar. Auf einem NodeMCU-Board dürfen Sie D1 statt der rohen GPIO-Nummer schreiben, die Software übersetzt die Pin-Namen.

Der Binärsensor meldet, ob ein Pin auf high oder low liegt:

binary_sensor:
  - platform: gpio
    name: "Living Room Window"
    pin:
      number: GPIOXX
      inverted: true
      mode:
        input: true
        pullup: true

Beachten Sie, dass pin hier ein Block statt eines einzelnen Werts ist. Fast jeder Pin akzeptiert diese lange Form mit Optionen für Invertierung und Pin-Modus. Alle Optionen stehen im Pin Schema der Dokumentation.

Die Namen in Home Assistant setzt das System aus friendly_name und Komponentenname zusammen. Laut Home-Assistant-Dokumentation zur Integration entsteht bei friendly_name „Living room desk“ und dem Sensor „Temperature“ die Entität „Living room desk Temperature“. Eine Entität ist ein einzelner Baustein in Home Assistant, etwa ein Sensor oder Schalter. Ihre ID lautet sensor.living_room_desk_temperature. Fehlt friendly_name, steht der Gerätename davor. Sonderzeichen wandelt Home Assistant in die nächsten ASCII-Zeichen um.

Home Assistant fragt Werte nicht ständig ab. Es hält eine dauerhafte Verbindung zum Gerät und bekommt Änderungen laut Dokumentation sofort gemeldet. Für schnelle Automationen ist das ein Segen. Wie Sie daraus Regeln bauen, zeigt der Home-Assistant-Einsteiger-Guide.

Wenn der Chip schweigt: Typische Fehler bei ESPHome und ihre Auswege

Die Dokumentationen von ESPHome und Home Assistant nennen mehrere Fehlerquellen ausdrücklich: fehlende WLAN-Daten, nicht installierte Änderungen und Geräte, die Home Assistant nicht findet. Ohne WLAN-Zugangsdaten erreicht das Gerät das Netz nicht und nimmt keine drahtlosen Updates an. Änderungen, die Sie nur gespeichert haben, landen nie auf dem Chip. Die kurze Version der Fehlersuche: mit „Validate“ prüfen, Logs lesen, neu installieren. „Validate“ steckt im Überlaufmenü (⋮) der Gerätekarte und prüft, ohne etwas zu bauen.

Die Logs öffnen Sie über das Dokumentsymbol an der Gerätekarte. Sie laufen per USB-Seriell oder übers Netzwerk. Laut Home Assistant zeigen sie unter anderem den WLAN-Status, Fehler und Debug-Meldungen. Sollen sie auch ohne Ihr Zutun ankommen, aktivieren Sie in den Optionen der Integration „Subscribe to logs from the device“. Dann erscheinen sie unter dem Logger homeassistant.components.esphome.

Tipp: Versuchen Sie bei Kompilierfehlern zuerst „Clean build files“, das ist laut Anleitung jederzeit gefahrlos.

Home Assistant entdeckt das Gerät automatisch, sofern Ihr Netz mDNS zulässt. (mDNS ist ein Verfahren, mit dem Geräte im lokalen Netz ihren Namen ankündigen.) Klappt das nicht, richten Sie es von Hand ein: unter „Settings > Devices & services“ auf „Add Integration“ klicken, „ESPHome“ wählen und den Hostnamen eingeben. Er leitet sich vom Gerätenamen ab, ein Gerät namens living-room-lamp antwortet unter living-room-lamp.local. Die IP-Adresse geht ebenfalls.

Die Tabelle zeigt die Felder, die Home Assistant bei der manuellen Einrichtung abfragt.

Wo ESPHome an Grenzen stößt: Namen, Vertrauen und Handarbeit

Jedes ESPHome-Gerät braucht laut Home Assistant einen eindeutigen Namen, sonst drohen Verbindungsprobleme, fehlgeschlagene Erkennung und unerwartetes Verhalten. Der Name steckt in den mDNS-Ankündigungen und verknüpft das Gerät mit dem Device Builder. Fällt mDNS aus, zählt er auch für die DHCP-Erkennung.

Beim Hardwaretausch hilft die Namenskonflikt-Auflösung. Sie startet laut Dokumentation nur, wenn das neue Gerät ESPHome 2025.4.0 oder neuer nutzt, denselben Namen trägt und das alte Gerät offline ist. Dann haben Sie zwei Optionen. „Migrate“ überträgt Einstellungen, Entitätsnamen und Verlauf auf das neue Gerät und passt bei gleicher YAML. „Overwrite“ löscht all das und ist bei einem völlig anderen Gerät die sicherere Wahl.

Auch das Vertrauen hat Grenzen. Die Option „Allow the device to perform Home Assistant actions“ ist standardmäßig aus. Aktivieren Sie sie laut Dokumentation nur, wenn Sie dem Gerät trauen.

Das Verkabeln nimmt Ihnen die Software nicht ab. Die Anleitung lässt GPIOXX bewusst offen, denn Sie müssen wissen, wo Ihre Hardware angeschlossen ist. Ein Bastelprojekt bleibt es, im Ernst. Wie viel Sie dabei selbst in die Hand nehmen sollten, beschreibt unser Beitrag Smart Home DIY.

Ein Gerät kann auch als Proxy dienen. Es fängt ein Signal dort auf, wo es steht, und reicht es übers Netz an Home Assistant weiter. Die Tabelle nennt die vier Proxy-Arten laut Home-Assistant-Dokumentation.

Die jeweilige Integration in Home Assistant richten Sie danach trotzdem selbst ein, etwa den geteilten seriellen Port. Beim Bluetooth-Proxy ist der Scan-Modus „Auto“ voreingestellt. Er spart laut Home Assistant etwa 95 bis 96 Prozent des scanbedingten Batterieverbrauchs der Bluetooth-Geräte in der Umgebung. Wie weit sich das treiben lässt, zeigt die Home Assistant Community: Dort standen am 29. und 30. Oktober 2026 Themen zu einer Tesla Wall Connector Gen 3 über RS485, zu einem Engelmann-Sensostar-Wärmezähler und zu einer Intergas-Xtend-Wärmepumpe mit mehr als 66 Sensoren.

Als nächsten Schritt durchsuchen Sie die Components-Seite auf esphome.io nach Ihrer Hardware. Offen bleibt das Ende der Passwort-Option: Die Home-Assistant-Dokumentation nennt dafür nur ein künftiges Release ohne Termin.