Premiers pas avec ESPHome

Ce qu’est ESPHome

Vous décrivez l’appareil dans un fichier YAML : quelle carte, quels capteurs sur quelles broches, comment il rejoint votre réseau. ESPHome transforme cette description en firmware, le compile et l’installe sur la carte. Home Assistant dialogue ensuite avec l’appareil par l’API native d’ESPHome, une connexion directe sur le port TCP 6053 que l’on peut chiffrer avec une clé de 32 octets.

Pour l’essentiel, il n’y a pas de code à écrire. Quand vous modifiez le YAML, vous réinstallez et l’appareil tourne avec le nouveau firmware.

Installer ESPHome

L’outil dans lequel vous travaillez s’appelle ESPHome Device Builder : un tableau de bord web qui conserve vos fichiers YAML, les compile et installe le firmware. Choisissez comment le lancer :

• Dans Home Assistant. Dans les paramètres, à la rubrique des applications (Home Assistant appelle désormais « apps » ses modules complémentaires), installez ESPHome Device Builder, démarrez-le et ouvrez son interface web. S’il n’apparaît pas, ajoutez le dépôt https://github.com/esphome/home-assistant-addon depuis le menu ⋮.
• En application de bureau. La page d’installation propose ESPHome Device Builder pour macOS (un .dmg), pour Windows et pour Linux (un .deb ou une AppImage). Sous Linux, si les ports série n’apparaissent pas, ajoutez votre utilisateur au groupe dialout.
• Dans Docker. Le même tableau de bord écoute sur le port 6052. Lancez le conteneur avec le réseau de l’hôte (--net=host) pour qu’il trouve les appareils par mDNS ; avec Docker Desktop, publiez plutôt le port 6052.
• En ligne de commande. pip install esphome (dans un environnement virtuel si possible), puis esphome run salon.yaml valide, compile, installe et affiche le journal en une seule fois.

Pour le tout premier flashage, vous pouvez aussi utiliser ESPHome Web, sur web.esphome.io, qui écrit le firmware sur la carte directement depuis le navigateur. Il faut un navigateur compatible Web Serial : Chrome, Edge et, d’après la documentation d’ESP Web Tools, Firefox ; iOS n’est pas pris en charge.

Choisir la carte

N’importe quelle carte de développement à ESP32 ou ESP8266 convient. Ces quatre-là sont courantes, peu chères et bien prises en charge ; c’est l’identifiant de la carte qui va dans le YAML.

Identifiants vérifiés avec esphome config sur ESPHome 2026.10.2. Notre comparatif ESP32 détaille les différences entre les puces.

En cas de doute, commencez par un ESP32 DevKit : c’est celui qu’utilise ce guide, et la plupart des réponses que vous trouverez en ligne partent du principe que vous en avez un.

Une première configuration, ligne par ligne

Dans le Device Builder, Create device lance un assistant qui écrit presque tout pour vous. Voici le fichier complet d’un appareil nommé salon, encore sans capteur :

esphome:
  name: salon                  # nom d’hôte : minuscules, chiffres, tirets
  friendly_name: Salon         # le nom affiché par Home Assistant

esp32:
  board: esp32dev              # votre carte
  framework:
    type: esp-idf              # par défaut depuis la 2026.1

logger:                        # journal par USB et Wi-Fi

api:                           # le lien avec Home Assistant
  encryption:
    key: !secret api_key

ota:
  - platform: esphome          # mises à jour par Wi-Fi
    encryption:                # reprend la clé de l’API

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:                          # point d’accès de secours
    password: !secret ap_password

captive_portal:                # sa page de configuration

• esphome: → name est le nom d’hôte sur votre réseau, salon.local : 31 caractères au plus, lettres minuscules, chiffres et tirets. friendly_name est le nom qu’affiche Home Assistant.
• esp32: → board indique à ESPHome la puce et la taille de la flash. Depuis ESPHome 2026.1, le framework par défaut sur l’ESP32 est ESP-IDF ; l’indiquer explicitement rend le fichier plus clair. Arduino reste pris en charge avec type: arduino.
• logger: → le journal par USB et par le réseau, par défaut au niveau DEBUG et à 115200 bauds.
• api: → l’API native qu’utilise Home Assistant, avec sa clé de chiffrement. Sans clé, la connexion n’est pas chiffrée.
• ota: → les mises à jour par Wi-Fi. Depuis ESPHome 2026.9, un encryption: vide les chiffre avec la clé de l’API.
• wifi: → votre réseau, lu dans secrets.yaml. ap: ouvre un point d’accès de secours, au nom de l’appareil, si celui-ci ne parvient pas à se connecter en 90 secondes.
• captive_portal: → une page sur ce point d’accès pour saisir de nouveaux identifiants Wi-Fi.

Les valeurs !secret viennent d’un second fichier, secrets.yaml, dans le même dossier :

wifi_ssid: "MyNetwork"
wifi_password: "MyWiFiPassword"
api_key: "…"                   # openssl rand -base64 32
ap_password: "…"

La clé de l’API se compose de 32 octets aléatoires encodés en base64 : l’assistant en génère une, tout comme la commande indiquée en commentaire. Ne publiez jamais secrets.yaml.

Un premier capteur : le BME280 en I²C

Le BME280 mesure la température, l’humidité et la pression et dialogue en I²C : deux fils de signal lui suffisent. Sur un ESP32 DevKit, les broches I²C qu’ESPHome utilise d’habitude sont GPIO21 pour SDA et GPIO22 pour SCL.

Ajoutez ceci à la fin du fichier :

i2c:
  sda: GPIO21
  scl: GPIO22
  scan: true                   # liste les adresses trouvées

sensor:
  - platform: bme280_i2c
    address: 0x76              # ou 0x77, voir le journal
    temperature:
      name: Température
    pressure:
      name: Pression
    humidity:
      name: Humidité
    update_interval: 60s

• i2c: → le bus et ses broches. scan: true, la valeur par défaut, inscrit dans le journal les adresses trouvées.
• platform: bme280_i2c → le pilote du BME280. Son adresse par défaut est 0x77 ; beaucoup de modules bon marché répondent en 0x76, comme ici. Notre page sur l’adresse du BME280 explique comment la broche SDO choisit entre les deux.
• Chaque mesure reçoit un name, qui devient une entité dans Home Assistant. update_interval: 60s lit le capteur une fois par minute.

Vous préférez cliquer ? Notre générateur produit un fichier équivalent, avec ce BME280 déjà ajouté, et crée les clés pour vous. Il met la clé de l’API directement dans le fichier plutôt que dans secrets.yaml, et ajoute des capteurs de signal Wi-Fi et de temps de fonctionnement.Ouvrir le générateur ESPHome

Un autre capteur ? Notre comparatif de capteurs met côte à côte les plus courants, du DHT22 aux SHT4x.

Le premier flashage par USB, puis par Wi-Fi

La toute première installation doit passer par un câble USB. Dans le Device Builder, cliquez sur Install dans la vignette de l’appareil et choisissez la méthode :

• Plug into this computer flashe depuis votre navigateur. Cette option utilise Web Serial, qui exige une page sécurisée : le tableau de bord ouvert en HTTPS, ou sur localhost, comme avec l’application de bureau.
• Plug into the computer running ESPHome Device Builder flashe depuis la machine qui fait tourner le tableau de bord, par exemple votre serveur Home Assistant.
• Manual download, puis Factory format, fournit un fichier .bin à écrire avec ESPHome Web : Connect, choix du port, Install.

En ligne de commande, esphome run salon.yaml demande quel port série utiliser. Si aucun port n’apparaît :

• Essayez un autre câble USB : ceux qui ne font que charger n’ont pas de fils de données.
• Installez le pilote de la puce USB-série de la carte, en général un CH34x ou un CP2102.
• Maintenez le bouton BOOT de la carte enfoncé pendant que vous la branchez, puis relâchez-le : la puce démarre alors en mode téléchargement.

Une fois l’appareil connecté à votre Wi-Fi, chaque Install suivant propose Wirelessly, et esphome run envoie le firmware par le réseau.

L’ajouter à Home Assistant

Si le mDNS fonctionne sur votre réseau, Home Assistant trouve tout seul le nouvel appareil. Allez dans Paramètres → Appareils et services : parmi les appareils Découverts, une vignette ESPHome porte son nom. Cliquez sur Configurer, saisissez la clé de chiffrement quand elle est demandée (si le Device Builder tourne en tant qu’application Home Assistant, elle est souvent préremplie) et choisissez une pièce.

Si rien n’est découvert, cliquez sur Ajouter une intégration, choisissez ESPHome et saisissez salon.local ou l’adresse IP de l’appareil. Les trois mesures du capteur apparaissent comme entités, prêtes pour le tableau de bord.

Parmi les options de l’intégration, celle qui autorise l’appareil à exécuter des actions de Home Assistant est désactivée par défaut. Ne l’activez que pour des appareils de confiance, et seulement si votre YAML en a besoin.

Lire le journal

C’est dans le journal que tout problème apparaît en premier. Dans le Device Builder, Logs le lit par USB si la carte est branchée, sinon par le réseau ; en ligne de commande, esphome logs salon.yaml. À la connexion, l’appareil affiche sa configuration, dont le balayage I²C :

[C][i2c:113]: Results from bus scan:
[C][i2c:119]: Found device at address 0x76

Le nombre qui suit i2c est le numéro de la ligne dans le code source d’ESPHome : il change d’une version à l’autre. « Found no devices » signale un problème de câblage ou d’alimentation, pas de YAML. Une mesure par minute, dans les lignes [D], veut dire que le capteur fonctionne.

Erreurs courantes

Les broches de strapping déterminent le mode de démarrage de la puce : un capteur ou une LED qui en maintient une au niveau haut ou bas peut l’empêcher de démarrer.

Sécurité

• Chiffrement de l’API. Définissez toujours une clé : sans elle, la connexion n’est ni chiffrée ni authentifiée, et n’importe quel appareil de votre réseau peut s’y connecter.
• Mises à jour chiffrées. Avec encryption: sous ota: (ESPHome 2026.9 et suivants), l’appareil n’accepte qu’un firmware chiffré avec votre clé. Les guides plus anciens utilisent password: ; ESPHome avertit désormais que cette option consomme de la flash et de la RAM, et recommande le chiffrement ; les deux ne se combinent pas.
• Un mot de passe sur le point d’accès de secours. Sa page permet à quiconque s’y connecte de modifier les paramètres Wi-Fi et d’envoyer un firmware.
• Protégez vos secrets. Ne partagez pas secrets.yaml et sauvegardez-le : sans la clé, impossible de mettre l’appareil à jour par Wi-Fi.

Le tenir à jour

ESPHome publie une nouvelle version chaque mois. Mettre à jour le Device Builder (ou pip install --upgrade esphome) ne change pas vos appareils : chacun garde le firmware avec lequel il a été compilé jusqu’à ce que vous cliquiez de nouveau sur Install. Lisez d’abord les changements incompatibles dans les notes de version, puis testez la mise à jour sur un seul appareil avant les autres.

Sur batterie : la veille profonde

Un capteur qui n’a besoin de remonter ses mesures qu’à quelques minutes d’intervalle peut dormir entre-temps avec le composant deep_sleep:, réglé par run_duration et sleep_duration. Tant qu’il dort, Home Assistant l’affiche comme indisponible, et il ne peut recevoir de mise à jour que lorsqu’il est réveillé. Carte, batterie, régulateur et consommations réelles sont traités dans notre guide pour alimenter un ESP32 sur batterie.