Intégration domotique ESPHome, gratuite et open source

Pilotez vos appareils ESPHome (ESP32/ESP8266) en local, via l'API native.

• Publiée par William-De71
• Appareils
• Version 1.2.0
• Nécessite Gladys >=5.1.0
• ★ 0

Voir sur GitHubToutes les intégrations externes

Cette intégration permet de piloter vos appareils ESPHome (ESP32, ESP8266) depuis Gladys Assistant, directement sur votre réseau local, via l'API native ESPHome. Aucun cloud, aucun broker MQTT, aucun Home Assistant nécessaire.

Fonctionnalités

Contrairement à un appareil du commerce, un nœud ESPHome expose exactement ce que vous avez déclaré dans son fichier YAML. L'intégration s'adapte donc à ce que chaque nœud annonce :

Composant ESPHome	Ce que vous obtenez dans Gladys
sensor	Capteur numérique (température, humidité, puissance, batterie...)
binary_sensor	Capteur binaire (mouvement, ouverture, présence, fuite, fumée...)
text_sensor	Capteur texte (lecture seule)
text	Texte modifiable : envoyer un message au nœud (écran)
switch	Interrupteur (on/off)
light	Lampe : on/off, luminosité, couleur, température de couleur
cover	Volet ou rideau : ouvrir, fermer, arrêter, position
fan	Ventilateur : on/off et vitesse
lock	Serrure : verrouiller / déverrouiller
siren	Sirène : marche / arrêt
valve	Vanne : ouverte / fermée
button	Bouton poussoir
number	Réglage numérique modifiable (curseur)
climate	Thermostat : consigne (une seule) et température mesurée
event	Aucune fonctionnalité : le déclencheur de scène « Événement ESPHome »

Les types qui n'ont pas d'équivalent dans Gladys (media_player, camera, select, date...) sont simplement ignorés lors de la découverte. Un capteur energy (en kWh ou en Wh) est un index cumulé : Gladys en calcule la consommation et son coût.

Les états arrivent en temps réel

ESPHome pousse ses changements d'état : l'intégration garde une connexion ouverte vers chaque nœud, et Gladys reçoit la nouvelle valeur à l'instant où elle change. Il n'y a pas d'intervalle d'interrogation à régler. Un appareil que vous ajoutez reçoit aussitôt les valeurs déjà remontées par son nœud, et une mesure qui ne change pas n'est pas renvoyée (elle est rafraîchie une fois par heure).

Prérequis

• Gladys 5.1.0 ou plus récent.

• Un ou plusieurs appareils sous ESPHome 2025.10 ou plus récent.

• L'API native activée dans votre YAML (c'est le cas par défaut) :

  api:
    encryption:
      key: 'votre_clé_base64'

• Gladys et vos nœuds ESPHome doivent être sur le même réseau local.

Configuration

1. La clé de chiffrement

Ouvrez l'écran de configuration de l'intégration et collez, dans Clé de chiffrement, la clé déclarée sous api: encryption: key: dans votre YAML.

Si tous vos nœuds partagent la même clé (le cas le plus courant quand on utilise un !secret commun), c'est la seule chose à renseigner.

Si vos nœuds n'ont pas de chiffrement du tout (api: sans bloc encryption), laissez ce champ vide.

2. Les nœuds ayant une clé différente

Si certains nœuds ont leur propre clé, remplissez Clés par nœud, une ligne par nœud :

salon|kBv1s2f3G4h5J6k7L8m9N0p1Q2r3S4t5U6v7W8x9Y0=
cuisine|9xQm4Zt6R8s0T2u4V6w8X0y2Z4a6B8c0D2e4F6g8H0=

Le nom du nœud est celui déclaré dans esphome: name:. Ces clés sont prioritaires sur la clé par défaut.

3. Découvrez vos appareils

Allez dans l'écran Découverte et lancez un scan. Les nœuds ESPHome présents sur votre réseau y apparaissent avec toutes leurs entités. Ajoutez ceux que vous voulez : aucune adresse IP à saisir.

La découverte utilise le mDNS (le protocole par lequel ESPHome s'annonce sur le réseau). C'est Gladys qui effectue la capture, car l'intégration tourne dans un conteneur qui ne reçoit pas ce type de trafic.

4. Si un nœud n'est pas trouvé

Certains réseaux bloquent le mDNS (VLAN séparés, Wi-Fi avec isolation des clients, routeur filtrant le multicast). Dans ce cas, renseignez le nœud à la main dans Nœuds ajoutés à la main, une adresse par ligne :

salon.local
192.168.1.42
192.168.1.43:6054

Le port est facultatif (6053 par défaut). Une fois connecté, le nœud annonce lui-même son vrai nom : un nœud ajouté par son adresse IP apparaîtra bien sous son nom ESPHome, et il continuera de fonctionner même si son adresse IP change ensuite.

Si ce nœud a une clé de chiffrement qui lui est propre, indiquez-la dans Clés par nœud en utilisant la même adresse que celle saisie ici, et non son nom ESPHome :

192.168.1.42|kBv1s2f3G4h5J6k7L8m9N0p1Q2r3S4t5U6v7W8x9Y0=

La raison est simple : son nom n'est connu qu'une fois la connexion établie, et la connexion a justement besoin de la clé. Cela ne concerne pas les nœuds trouvés par le scan, ni ceux qui utilisent la clé par défaut.

Actions disponibles

• Tester la connexion : relance une découverte complète et vous indique combien de nœuds ont répondu et combien de fonctionnalités sont disponibles.
• Reconnecter les nœuds : ferme toutes les connexions et les rouvre. Utile après avoir reflashé un nœud ou changé une clé.

Scènes

Déclencheurs

• Événement ESPHome : une entité event d'un nœud s'est déclenchée — un bouton cliqué une ou deux fois ou maintenu, une sonnette, un code de télécommande reçu. Filtres : le nœud (esphome: name:), l'entité (son name:) et le type d'événement (un de ses event_types) ; laissez un filtre vide pour tout accepter. Variables : node, entity, entity_id, event_type.
• Nœud ESPHome hors ligne : un nœud est resté déconnecté pendant une minute. Un redémarrage ou une mise à jour OTA terminés dans la minute ne déclenchent rien. Variables : node, address.
• Nœud ESPHome de retour en ligne : un nœud signalé hors ligne est de nouveau connecté. Variables : node, address, offline_minutes.

Une entité événement, déclenchée par un bouton qui distingue simple et double clic :

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 }

Action « Exécuter une action ESPHome »

Exécute une action déclarée sous api: actions: dans le YAML d'un nœud : jouer une mélodie, afficher un message, lancer un script.

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

• Nœud : le nom ESPHome du nœud, ou le nom de son appareil dans Gladys.
• Action : play_rtttl.
• Arguments : un objet JSON avec une entrée par variable, par exemple {"song_str": "two_short:d=4,o=5,b=100:16e6,16e6"}. Les variables de scène sont acceptées. Laissez vide pour une action sans variables.

Un argument manquant, inconnu ou du mauvais type fait échouer l'action avec un message clair, tout comme un nom d'action que le nœud ne déclare pas (le message liste celles qu'il déclare). Les sorties node et action sont disponibles pour les actions suivantes de la scène. Pendant les deux secondes qui suivent cette action, les événements de ce nœud ne démarrent aucune scène : une action qui déclenche un événement ne peut pas boucler sur la scène qui l'a appelée.

Comprendre les capteurs : l'importance de device_class

Gladys a besoin de savoir ce que mesure un capteur pour l'afficher correctement (icône, unité, graphique). ESPHome transmet cette information via device_class.

Avec un device_class, votre capteur arrive typé :

sensor:
  - platform: dht
    temperature:
      name: 'Température salon'
      device_class: temperature # -> capteur de température dans Gladys
    humidity:
      name: 'Humidité salon'
      device_class: humidity # -> capteur d'humidité dans Gladys

Sans device_class, le capteur apparaît quand même, mais dans la catégorie générique « Inconnu ». Il fonctionne, il est historisé, mais il n'aura ni icône ni catégorie spécifique. Si un de vos capteurs s'affiche ainsi, ajoutez le device_class correspondant dans votre YAML et relancez une découverte.

Deux familles de capteurs échappent à cette règle, parce qu'ESPHome ne leur donne jamais de device_class — le vocabulaire de Home Assistant n'a pas de mot pour ce qu'elles mesurent. L'intégration les reconnaît à la forme de leur déclaration :

Déclaration ESPHome	Catégorie Gladys
unit_of_measurement: "°"	Angle
aucune unité et accuracy_decimals: 0	Compteur entier

C'est le cas typique des capteurs mmWave (ld2410, ld2450…) : leurs compteurs de cibles (Moving / Still / Presence Target Count) arrivent en Compteur, et leurs angles de cible (Target-1 Angle) en Angle. Un firmware qui déclare explicitement state_class: measurement_angle, total ou total_increasing est classé sur cette déclaration en priorité.

Les device_class reconnus incluent : temperature, humidity, pressure, illuminance, battery, signal_strength, carbon_dioxide, pm25, pm10, power, energy, voltage, current, distance, moisture, speed, duration, et pour les capteurs binaires : motion, occupancy, door, window, smoke, gas, moisture, vibration, tamper, battery, lock.

Résolution de problèmes

Aucun nœud n'est trouvé lors du scan Vérifiez que vos nœuds sont allumés et connectés au Wi-Fi. Si votre réseau bloque le mDNS, ajoutez-les à la main (voir plus haut).

Un nœud est trouvé mais n'apparaît pas dans la liste C'est presque toujours une clé de chiffrement qui ne correspond pas. Le nœud est visible sur le réseau, mais refuse la connexion. Vérifiez la clé dans son YAML, et utilisez Clés par nœud si elle diffère de la clé par défaut.

Un nœud disparaît puis revient C'est normal après un redémarrage du nœud (mise à jour OTA, coupure de courant). L'intégration se reconnecte automatiquement, avec un délai croissant pour ne pas saturer le réseau.

Un appareil s'affiche comme « injoignable » La connexion vers ce nœud est tombée : nœud éteint, hors de portée Wi-Fi, ou en cours de redémarrage. L'intégration retente automatiquement. Sachez aussi qu'un nœud ESPHome n'accepte qu'un nombre limité de clients API simultanés : si le même nœud est déjà connecté à un Home Assistant ou à une console de logs ESPHome ouverte, il peut refuser une connexion de plus. Fermez les clients inutiles et utilisez l'action Reconnecter les nœuds.

Un thermostat n'affiche que la température mesurée, sans consigne C'est un thermostat à deux consignes (heat_cool, une basse et une haute). Gladys ne gère qu'une consigne par thermostat : plutôt que d'afficher un curseur qui resterait à 0 et ne piloterait rien, l'intégration ne publie que la température mesurée.

L'action « Exécuter une action ESPHome » échoue Le nœud doit être connecté, le nom de l'action doit être celui écrit après action: dans le YAML, et les arguments doivent correspondre à ses variables: (noms et types). Le message d'erreur de la scène indique lequel est en cause.

Une entité n'apparaît pas du tout Son type n'a pas d'équivalent dans Gladys (voir le tableau des fonctionnalités), ou elle est marquée internal: true dans votre YAML — auquel cas ESPHome ne l'expose pas du tout sur son API.

Paramètres de configuration

Voici les paramètres demandés par ESPHome dans son écran de configuration dans Gladys.

Paramètre	Type	Obligatoire	Description
Pour commencer	section	Non	Cette intégration communique avec vos nœuds ESPHome sur votre réseau local, via leur API native (port 6053). Collez votre clé de chiffrement ci-dessous, puis allez dans l'écran Découverte et lancez un scan : les nœuds trouvés sur votre réseau y apparaissent avec toutes leurs entités, prêts à être ajoutés. Aucune adresse IP à saisir.
Clé de chiffrement	secret	Non	La clé base64 déclarée sous api: encryption: key: dans votre YAML ESPHome. Utilisée pour tous les nœuds n'ayant pas de clé spécifique ci-dessous. À laisser vide uniquement si vos nœuds n'ont pas de chiffrement.
Nœuds avec une clé différente	section	Non	Ne remplissez les deux champs ci-dessous que si certains nœuds ne partagent pas la clé ci-dessus, ou si un nœud n'est pas trouvé par le scan réseau (autre VLAN, mDNS filtré par votre routeur).
Clés par nœud	secret	Non	Un nœud par ligne, sous la forme nœud|clé. Le nom du nœud est celui de votre YAML ESPHome (esphome: name:), ou son adresse. Ces clés sont prioritaires sur la clé ci-dessus.
Nœuds ajoutés à la main	string	Non	Une adresse par ligne (salon.local, 192.168.1.42, ou 192.168.1.42:6053), pour les nœuds que le scan réseau ne trouve pas. Les nœuds trouvés par le scan n'ont rien à faire ici.
Durée de la découverte (s)	number	Non	Durée pendant laquelle le scan mDNS écoute les nœuds ESPHome sur le réseau.
Délai d'attente de connexion (s)	number	Non	Temps d'attente pour qu'un nœud réponde avant de l'abandonner.

Comment installer ESPHome dans Gladys

1. Dans Gladys, ouvrez Intégrations : ESPHome apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/william-de71/gladys-esphome:1.2.0), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration).
3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/William-De71/gladys-esphome.

ESPHome nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.

Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.

À propos des intégrations externes

ESPHome est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par William-De71, et non par l'équipe cœur de Gladys.

• Parcourir toutes les intégrations externes
• Découvrir les intégrations natives intégrées à Gladys
• Créer et publier votre propre intégration externe
• Code source sur GitHub — source de cette documentation

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂