ESPHome Smart-Home-Integration, kostenlos und Open Source

Steuern Sie Ihre ESPHome-Geräte (ESP32/ESP8266) lokal über die native API.

• Veröffentlicht von William-De71
• Geräte
• Version 1.2.1
• Erfordert Gladys >=5.1.0
• ★ 0

Auf GitHub ansehenAlle Integrationen

Mit dieser Integration steuern Sie Ihre ESPHome-Geräte (ESP32, ESP8266) aus Gladys Assistant heraus, direkt in Ihrem lokalen Netzwerk, über die native API von ESPHome. Keine Cloud, kein MQTT-Broker, kein Home Assistant nötig.

Funktionen

Anders als ein Gerät von der Stange stellt ein ESPHome-Knoten genau das bereit, was Sie in seiner YAML-Datei angegeben haben. Die Integration richtet sich daher nach dem, was jeder Knoten meldet:

ESPHome-Komponente	Was Sie in Gladys erhalten
sensor	Numerischer Sensor (Temperatur, Luftfeuchtigkeit, Leistung, …)
binary_sensor	Binärsensor (Bewegung, Öffnung, Anwesenheit, Leck, Rauch, …)
text_sensor	Textsensor (nur lesend)
text	Beschreibbarer Text: eine Nachricht an den Knoten (Display)
switch	Schalter (ein/aus)
light	Lampe: ein/aus, Helligkeit, Farbe, Farbtemperatur
cover	Rollladen oder Vorhang: öffnen, schließen, stoppen, Position
fan	Ventilator: ein/aus und Geschwindigkeit
lock	Schloss: verriegeln / entriegeln
siren	Sirene: ein / aus
valve	Ventil: offen / geschlossen
button	Taster
number	Beschreibbarer Zahlenwert (Schieberegler)
climate	Thermostat: Sollwert (ein einzelner) und gemessene Temperatur
event	Keine Funktion: der Szenen-Auslöser „ESPHome-Ereignis“

Typen ohne Entsprechung in Gladys (media_player, camera, select, date, …) werden bei der Suche einfach ausgelassen. Ein energy-Sensor (in kWh oder Wh) ist ein kumulativer Zählerstand: Gladys berechnet daraus den Verbrauch und seine Kosten.

Zustände kommen in Echtzeit an

ESPHome sendet seine Zustandsänderungen von selbst: Die Integration hält zu jedem Knoten eine Verbindung offen, und Gladys erhält den neuen Wert in dem Moment, in dem er sich ändert. Es gibt kein Abfrageintervall einzustellen. Ein hinzugefügtes Gerät erhält sofort die Werte, die sein Knoten bereits gemeldet hat, und ein unveränderter Messwert wird nicht erneut gesendet (er wird einmal pro Stunde aufgefrischt).

Voraussetzungen

• Gladys 5.1.0 oder neuer.

• Ein oder mehrere Geräte mit ESPHome 2025.10 oder neuer.

• Die native API in Ihrer YAML aktiviert (das ist standardmäßig der Fall):

  api:
    encryption:
      key: 'ihr_base64_schluessel'

• Gladys und Ihre ESPHome-Knoten müssen sich im selben lokalen Netzwerk befinden.

Einrichtung

1. Der Verschlüsselungsschlüssel

Öffnen Sie den Konfigurationsbildschirm der Integration und fügen Sie unter Verschlüsselungsschlüssel den Schlüssel ein, der in Ihrer YAML unter api: encryption: key: steht.

Wenn alle Ihre Knoten denselben Schlüssel verwenden (der Normalfall bei einem gemeinsamen !secret), ist das die einzige Angabe.

Haben Ihre Knoten gar keine Verschlüsselung (api: ohne encryption-Block), lassen Sie dieses Feld leer.

2. Knoten mit einem anderen Schlüssel

Haben einige Knoten einen eigenen Schlüssel, füllen Sie Schlüssel pro Knoten aus, ein Knoten pro Zeile:

wohnzimmer|kBv1s2f3G4h5J6k7L8m9N0p1Q2r3S4t5U6v7W8x9Y0=
kueche|9xQm4Zt6R8s0T2u4V6w8X0y2Z4a6B8c0D2e4F6g8H0=

Der Knotenname ist der unter esphome: name: angegebene. Diese Schlüssel haben Vorrang vor dem Standardschlüssel.

3. Geräte entdecken

Öffnen Sie den Bildschirm Entdecken und starten Sie eine Suche. Die ESPHome-Knoten in Ihrem Netzwerk erscheinen dort mit all ihren Entitäten. Fügen Sie die gewünschten hinzu: keine IP-Adresse einzugeben.

Die Suche nutzt mDNS (das Protokoll, mit dem sich ESPHome im Netzwerk ankündigt). Gladys übernimmt den Mitschnitt selbst, denn die Integration läuft in einem Container, der solchen Verkehr nie empfängt.

4. Wenn ein Knoten nicht gefunden wird

Manche Netzwerke blockieren mDNS (getrennte VLANs, WLAN mit Client-Isolation, ein Router, der Multicast filtert). Tragen Sie den Knoten dann unter Manuell hinzugefügte Knoten ein, eine Adresse pro Zeile:

wohnzimmer.local
192.168.1.42
192.168.1.43:6054

Der Port ist optional (standardmäßig 6053). Sobald er verbunden ist, meldet der Knoten selbst seinen echten Namen: Ein per IP-Adresse hinzugefügter Knoten erscheint trotzdem unter seinem ESPHome-Namen und funktioniert weiter, auch wenn sich seine IP-Adresse später ändert.

Hat dieser Knoten einen eigenen Verschlüsselungsschlüssel, tragen Sie ihn unter Schlüssel pro Knoten mit derselben Adresse ein, die Sie hier angegeben haben, nicht mit seinem ESPHome-Namen:

192.168.1.42|kBv1s2f3G4h5J6k7L8m9N0p1Q2r3S4t5U6v7W8x9Y0=

Der Grund ist einfach: Sein Name ist erst nach erfolgreicher Verbindung bekannt, und genau diese Verbindung braucht den Schlüssel. Das betrifft weder die von der Suche gefundenen Knoten noch jene, die den Standardschlüssel verwenden.

Verfügbare Aktionen

• Verbindung testen: startet eine vollständige Suche und zeigt an, wie viele Knoten geantwortet haben und wie viele Funktionen verfügbar sind.
• Knoten neu verbinden: schließt alle Verbindungen und öffnet sie neu. Nützlich, nachdem ein Knoten neu geflasht oder ein Schlüssel geändert wurde.

Szenen

Auslöser

• ESPHome-Ereignis: Eine event-Entität eines Knotens hat ausgelöst — eine Taste einmal, zweimal oder lange gedrückt, eine Türklingel, ein empfangener Fernbedienungscode. Filter: der Knoten (esphome: name:), die Entität (ihr name:) und der Ereignistyp (einer ihrer event_types); lassen Sie einen Filter leer, um alles zu akzeptieren. Variablen: node, entity, entity_id, event_type.
• ESPHome-Knoten offline: Ein Knoten war eine Minute lang getrennt. Ein Neustart oder ein OTA-Update, das innerhalb der Minute abgeschlossen ist, löst nichts aus. Variablen: node, address.
• ESPHome-Knoten wieder online: Ein als offline gemeldeter Knoten ist wieder verbunden. Variablen: node, address, offline_minutes.

Eine Ereignis-Entität, ausgelöst von einer Taste, die Einfach- und Doppelklick unterscheidet:

event:
  - platform: template
    name: 'Button'
    id: button_event
    event_types: [single, double]

binary_sensor:
  - platform: gpio
    pin: GPIO0
    on_multi_click:
      - timing:
          [ON for at most 0.5s, OFF for at most 0.3s, ON for at most 0.5s, OFF for at least 0.2s]
        then:
          - event.trigger: { id: button_event, event_type: double }
      - timing: [ON for at most 0.5s, OFF for at least 0.4s]
        then:
          - event.trigger: { id: button_event, event_type: single }

Aktion „ESPHome-Aktion ausführen“

Führt eine Aktion aus, die in der YAML eines Knotens unter api: actions: angegeben ist: eine Melodie abspielen, eine Nachricht anzeigen, ein Skript starten.

api:
  actions:
    - action: play_rtttl
      variables:
        song_str: string
      then:
        - rtttl.play:
            rtttl: !lambda 'return song_str;'

• Knoten: der ESPHome-Name des Knotens oder der Name seines Geräts in Gladys.
• Aktion: play_rtttl.
• Argumente: ein JSON-Objekt mit einem Eintrag pro Variable, zum Beispiel {"song_str": "two_short:d=4,o=5,b=100:16e6,16e6"}. Szenenvariablen sind erlaubt. Leer lassen für eine Aktion ohne Variablen.

Ein fehlendes, unbekanntes oder falsch typisiertes Argument lässt die Aktion mit einer klaren Meldung fehlschlagen, ebenso ein Aktionsname, den der Knoten nicht angibt (die Meldung listet die angegebenen auf). Die Ausgaben node und action stehen den folgenden Aktionen der Szene zur Verfügung. Zwei Sekunden lang nach dieser Aktion starten die Ereignisse dieses Knotens keine Szene: Eine Aktion, die ein Ereignis auslöst, kann nicht in einer Schleife auf die Szene zurückwirken, die sie aufgerufen hat.

Sensoren verstehen: warum device_class wichtig ist

Gladys muss wissen, was ein Sensor misst, um ihn richtig darzustellen (Symbol, Einheit, Diagramm). ESPHome übermittelt diese Information über device_class.

Mit einer device_class kommt Ihr Sensor typisiert an:

sensor:
  - platform: dht
    temperature:
      name: 'Temperatur Wohnzimmer'
      device_class: temperature # -> Temperatursensor in Gladys
    humidity:
      name: 'Luftfeuchtigkeit Wohnzimmer'
      device_class: humidity # -> Luftfeuchtigkeitssensor in Gladys

Ohne device_class erscheint der Sensor trotzdem, allerdings in der allgemeinen Kategorie „Unbekannt“. Er funktioniert und sein Verlauf wird gespeichert, aber er bekommt weder ein eigenes Symbol noch eine eigene Kategorie. Erscheint einer Ihrer Sensoren so, ergänzen Sie die passende device_class in Ihrer YAML und starten Sie die Suche erneut.

Zwei Sensorfamilien sind von dieser Regel ausgenommen, weil ESPHome ihnen nie eine device_class gibt — das Vokabular von Home Assistant hat kein Wort für das, was sie messen. Die Integration erkennt sie an der Form ihrer Deklaration:

ESPHome-Deklaration	Gladys-Kategorie
unit_of_measurement: "°"	Winkel
keine Einheit und accuracy_decimals: 0	Zähler

Das ist der typische Fall bei mmWave-Sensoren (ld2410, ld2450, …): Ihre Zielzähler (Moving / Still / Presence Target Count) landen unter Zähler, ihre Zielwinkel (Target-1 Angle) unter Winkel. Eine Firmware, die ausdrücklich state_class: measurement_angle, total oder total_increasing angibt, wird vorrangig nach dieser Angabe eingeordnet.

Zu den erkannten device_class-Werten gehören: temperature, humidity, pressure, illuminance, battery, signal_strength, carbon_dioxide, pm25, pm10, power, energy, voltage, current, distance, moisture, speed, duration und für Binärsensoren: motion, occupancy, door, window, smoke, gas, moisture, vibration, tamper, battery, lock.

Fehlerbehebung

Die Suche findet keinen Knoten Prüfen Sie, ob Ihre Knoten eingeschaltet und mit dem WLAN verbunden sind. Blockiert Ihr Netzwerk mDNS, fügen Sie sie manuell hinzu (siehe oben).

Ein Knoten wird gefunden, erscheint aber nicht in der Liste Das ist fast immer ein Verschlüsselungsschlüssel, der nicht passt. Der Knoten ist im Netzwerk sichtbar, lehnt die Verbindung aber ab. Prüfen Sie den Schlüssel in seiner YAML und verwenden Sie Schlüssel pro Knoten, wenn er vom Standardschlüssel abweicht.

Ein Knoten verschwindet und kommt wieder Das ist nach einem Neustart des Knotens normal (OTA-Update, Stromausfall). Die Integration verbindet sich von selbst neu, mit wachsender Wartezeit, um das Netzwerk nie zu überlasten.

Ein Gerät wird als „nicht erreichbar“ angezeigt Die Verbindung zu diesem Knoten ist abgebrochen: Knoten ausgeschaltet, außer WLAN-Reichweite oder im Neustart. Die Integration versucht es automatisch erneut. Beachten Sie außerdem, dass ein ESPHome-Knoten nur eine begrenzte Zahl gleichzeitiger API-Clients akzeptiert: Ist derselbe Knoten bereits mit einem Home Assistant oder einer geöffneten ESPHome-Log-Konsole verbunden, kann er eine weitere Verbindung ablehnen. Schließen Sie nicht benötigte Clients und verwenden Sie die Aktion Knoten neu verbinden.

Ein Thermostat zeigt nur die gemessene Temperatur, ohne Sollwert Es handelt sich um ein Thermostat mit zwei Sollwerten (heat_cool, ein unterer und ein oberer). Gladys verwaltet einen Sollwert pro Thermostat: Statt eines Schiebereglers, der auf 0 stünde und nichts steuern würde, veröffentlicht die Integration nur die gemessene Temperatur.

Die Aktion „ESPHome-Aktion ausführen“ schlägt fehl Der Knoten muss verbunden sein, der Aktionsname muss der in der YAML nach action: angegebene sein, und die Argumente müssen zu ihren variables: passen (Namen und Typen). Die Fehlermeldung der Szene nennt, was nicht stimmt.

Eine Entität erscheint überhaupt nicht Ihr Typ hat keine Entsprechung in Gladys (siehe Funktionstabelle), oder sie ist in Ihrer YAML als internal: true markiert — dann stellt ESPHome sie gar nicht über seine API bereit.

Konfigurationseinstellungen

Diese Einstellungen fragt ESPHome in seinem Konfigurationsbildschirm in Gladys ab.

Einstellung	Typ	Pflichtfeld	Beschreibung
Erste Schritte	section	Nein	Diese Integration spricht über die native API (Port 6053) mit Ihren ESPHome-Knoten in Ihrem lokalen Netzwerk. Fügen Sie unten Ihren Verschlüsselungsschlüssel ein, öffnen Sie dann den Bildschirm „Entdecken“ und starten Sie eine Suche: Die in Ihrem Netzwerk gefundenen Knoten erscheinen dort mit all ihren Entitäten und können hinzugefügt werden. Keine IP-Adresse einzugeben.
Verschlüsselungsschlüssel	secret	Nein	Der Base64-Schlüssel, der in Ihrer ESPHome-YAML unter api: encryption: key: angegeben ist. Er gilt für jeden Knoten ohne eigenen Schlüssel weiter unten. Nur leer lassen, wenn Ihre Knoten keine Verschlüsselung haben.
Knoten mit einem anderen Schlüssel	section	Nein	Füllen Sie die beiden Felder unten nur aus, wenn einige Knoten den obigen Schlüssel nicht teilen oder ein Knoten von der Netzwerksuche nicht gefunden wird (anderes VLAN, mDNS vom Router gefiltert).
Schlüssel pro Knoten	secret	Nein	Ein Knoten pro Zeile, im Format knoten|schlüssel. Der Knotenname ist der aus Ihrer ESPHome-YAML (esphome: name:) oder seine Adresse. Diese Schlüssel haben Vorrang vor dem obigen Schlüssel.
Manuell hinzugefügte Knoten	string	Nein	Eine Adresse pro Zeile (wohnzimmer.local, 192.168.1.42 oder 192.168.1.42:6053) für die Knoten, die die Netzwerksuche nicht findet. Von der Suche gefundene Knoten brauchen hier nichts.
Dauer der Suche (s)	number	Nein	Wie lange die mDNS-Suche im Netzwerk nach ESPHome-Knoten lauscht.
Verbindungs-Timeout (s)	number	Nein	Wie lange auf die Antwort eines Knotens gewartet wird, bevor aufgegeben wird.

So installierst du ESPHome in Gladys

1. Öffne in Gladys Integrationen: ESPHome erscheint im Katalog neben den nativen Integrationen, mit einem Community-Badge.
2. Klicke auf Installieren. Gladys lädt das Docker-Image (ghcr.io/william-de71/gladys-esphome:1.2.1) herunter, startet es in einer vom Kern isolierten Sandbox und erzeugt die Oberfläche der Integration (Geräte, Erkennung und Konfiguration).
3. Öffne den Bildschirm Konfiguration der Integration, fülle die Einstellungen aus und speichere.
4. Du kannst sie auch direkt über die URL ihres Repositorys installieren: https://github.com/William-De71/gladys-esphome.

ESPHome benötigt Gladys >=5.1.0. Der Katalog in Gladys wird stündlich aktualisiert, eine neue Version ist also spätestens eine Stunde nach ihrer Veröffentlichung verfügbar.

Du nutzt Gladys noch nicht? Es ist kostenlos und Open Source: folge der Installationsanleitung, um loszulegen.

Über externe Integrationen

ESPHome ist eine externe Integration: eine Community-Integration, die als Docker-Container verpackt und auf GitHub veröffentlicht wird. Gladys installiert sie mit einem Klick und führt sie in einer vom Kern isolierten Sandbox aus. Sie wird von William-De71 veröffentlicht und gepflegt, nicht vom Gladys-Kernteam.

• Alle Integrationen durchsuchen, native und aus der Community
• Deine eigene externe Integration bauen und veröffentlichen
• Quellcode auf GitHub — Quelle dieser Dokumentation

Abonniere den Newsletter von Gladys Assistant

Ein paar E-Mails im Monat zu neuen Releases und Neuigkeiten aus dem Projekt. Verschickt von Pierre-Gilles Leymarie, dem Gründer des Projekts. Jederzeit abbestellbar 🙂