Ajouter un ESP32 à Home Assistant avec ESPHome : Tutoriel Complet

Pourquoi ESPHome ?

ESPHome est le moyen le plus simple pour relier un ESP32 à Home Assistant sans écrire une ligne de code Arduino. Il génère automatiquement un firmware à partir d'un fichier de configuration YAML, et une fois le premier flash effectué par USB, toutes les mises à jour se font en OTA (Over-The-Air), directement depuis le réseau WiFi.

Étape 1 — Ouvrir ESPHome Builder

Depuis votre navigateur (Edge ou Chrome), ouvrez l'interface de Home Assistant et rendez-vous dans Modules complémentaires → ESPHome Builder. Cliquez sur OUVRIR L'INTERFACE WEB pour accéder au tableau de bord ESPHome.

Étape 2 — Créer un nouveau dispositif

1. Dans ESPHome Builder, cliquez sur NEW DEVICE
2. Sélectionnez NEW DEVICE SETUP
3. Choisissez un nom pour votre ESP32 — attention à ne pas réutiliser un nom déjà attribué sur votre réseau, cela provoquerait un conflit mDNS
4. Cliquez sur NEXT pour continuer

Étape 3 — Connexion USB et flash initial

C'est l'étape clé : le premier firmware est installé directement par câble USB depuis votre navigateur.

1. Cliquez sur CONNECT — une fenêtre de sélection de port série s'ouvre
2. Sélectionnez le port correspondant à votre ESP32 (généralement COM3, COM4… sur Windows ou /dev/ttyUSB0 sur Linux)
3. Cliquez sur SE CONNECTER

Étape 4 — Installation du firmware minimal

Dès que la connexion est établie, ESPHome compile et envoie un firmware minimal sur l'ESP32 :

• "Preparing installation" — compilation en cours, cela peut prendre plusieurs minutes selon la puissance du serveur HA
• "Installing..." — le firmware est en cours d'écriture sur la flash de l'ESP
• "Configuration created!" — c'est terminé pour cette partie

Étape 5 — Configurer le WiFi dans le YAML

De retour dans ESPHome Builder, votre nouveau dispositif apparaît dans la liste. Cliquez sur EDIT pour ouvrir l'éditeur YAML de la configuration.

La section wifi accepte de nombreuses options selon vos besoins. Voici la configuration de base :

wifi:
  ssid: "NomDeVotreReseau"
  password: "MotDePasseWiFi"

# Dans secrets.yaml
wifi_ssid: "NomDeVotreReseau"
wifi_password: "MotDePasseWiFi"

# Dans votre config ESP
wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

Configurer plusieurs réseaux WiFi

ESPHome permet de déclarer plusieurs réseaux. L'ESP32 se connecte automatiquement au premier disponible, dans l'ordre de priorité défini. Idéal pour un appareil mobile entre deux zones, ou pour prévoir un réseau de secours :

wifi:
  networks:
    - ssid: "ReseauPrincipal"
      password: "MotDePasse1"
      priority: 10        # priorité haute = testé en premier
    - ssid: "ReseauSecondaire"
      password: "MotDePasse2"
      priority: 5
    - ssid: "ReseauInvites"
      password: "MotDePasse3"
      priority: 1         # priorité basse = dernier recours

Adresse IP fixe (IP statique)

Par défaut l'ESP32 obtient une IP via DHCP. Pour lui attribuer une adresse fixe — utile pour faciliter l'accès direct ou figer les règles de firewall :

wifi:
  ssid: "NomDeVotreReseau"
  password: "MotDePasseWiFi"
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0
    dns1: 192.168.1.1       # souvent l'adresse de votre box
    dns2: 8.8.8.8           # DNS Google en secours

Hotspot de secours (Access Point)

Si l'ESP32 ne parvient pas à se connecter à aucun réseau WiFi après plusieurs tentatives, il peut ouvrir son propre point d'accès WiFi pour permettre une reconfiguration. C'est le filet de sécurité d'ESPHome :

ap:
  ssid: "ESP32-Secours"
  password: "Config1234"

Se connecter à un réseau WiFi caché

Si votre box diffuse un SSID masqué (non visible dans les listes WiFi), ajoutez l'option hidden :

wifi:
  ssid: "MonReseauCache"
  password: "MotDePasse"
  hidden: true

Forcer la connexion à un point d'accès précis (BSSID)

Dans un environnement avec plusieurs bornes WiFi portant le même SSID (réseau maillé, plusieurs box…), vous pouvez forcer l'ESP32 à se connecter à une borne spécifique via son adresse MAC (BSSID) :

wifi:
  networks:
    - ssid: "NomDuReseau"
      password: "MotDePasse"
      bssid: AA:BB:CC:DD:EE:FF   # adresse MAC de la borne cible
      channel: 6                  # canal WiFi de cette borne (optionnel, accélère la connexion)

Mode économie d'énergie

Sur batterie, réduire l'activité radio peut considérablement prolonger l'autonomie. ESPHome propose trois niveaux :

wifi:
  ssid: "NomDeVotreReseau"
  password: "MotDePasseWiFi"
  power_save_mode: light    # none | light | high

Connexion rapide (fast_connect)

Par défaut, l'ESP32 scanne tous les canaux WiFi avant de se connecter. Si vous n'avez qu'un seul réseau déclaré et souhaitez accélérer le démarrage, activez fast_connect :

wifi:
  ssid: "NomDeVotreReseau"
  password: "MotDePasseWiFi"
  fast_connect: true

Exemple de configuration WiFi complète

Voici une configuration combinant les options les plus utiles pour un ESP32 fixe sur secteur :

wifi:
  networks:
    - ssid: !secret wifi_ssid
      password: !secret wifi_password
      priority: 10
    - ssid: !secret wifi_ssid_backup
      password: !secret wifi_password_backup
      priority: 1
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0
    dns1: 192.168.1.1
  power_save_mode: none

ap:
  ssid: "ESP32-Secours"
  password: !secret ap_password

captive_portal:

Une fois les identifiants renseignés, cliquez sur SAVE puis INSTALL.

Étape 5b — Configurer les services réseau

Dans le même fichier YAML, trois autres composants réseau méritent d'être configurés dès le départ : le serveur web intégré, l'API native pour Home Assistant, et le serveur OTA.

Le serveur web intégré (web_server)

ESPHome peut activer un serveur HTTP directement sur l'ESP32. Accessible depuis n'importe quel navigateur sur votre réseau local via l'adresse IP ou le nom mDNS de l'ESP (ex. : http://capteur-salon.local), il affiche un tableau de bord avec toutes les entités (capteurs, interrupteurs, boutons) et un journal de logs en temps réel — très pratique pour déboguer sans avoir besoin d'ouvrir Home Assistant.

web_server:
  port: 80        # port HTTP (80 par défaut)
  version: 3      # version de l'interface : 1, 2 ou 3 (3 = plus moderne)

Avec authentification (mot de passe)

Sans protection, n'importe qui sur votre réseau local peut accéder à l'interface et contrôler l'ESP. Ajoutez un couple identifiant/mot de passe :

web_server:
  port: 80
  version: 3
  auth:
    username: admin
    password: !secret web_server_password

# Dans secrets.yaml
web_server_password: "MotDePasseInterface"

Mode local (sans CDN)

Par défaut, les versions 2 et 3 chargent leurs fichiers JavaScript et CSS depuis un CDN sur internet. Sur un réseau isolé ou pour garantir le fonctionnement hors ligne, activez le mode local :

web_server:
  version: 3
  local: true     # les assets sont servis depuis l'ESP lui-même, sans accès internet

Options avancées du serveur web

web_server:
  port: 80
  version: 3
  auth:
    username: admin
    password: !secret web_server_password
  local: true
  ota: false              # désactive le bouton de mise à jour OTA dans l'interface web
  include_internal: true  # affiche aussi les entités marquées "internal: true" dans le YAML

L'API native ESPHome (api)

C'est la brique qui permet à Home Assistant de communiquer avec l'ESP32 via le port 6053. Sans cette section, HA peut détecter l'ESP sur le réseau mais ne peut ni lire ses données ni le contrôler. ESPHome génère automatiquement une clé de chiffrement lors de la création du dispositif :

api:
  encryption:
    key: "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345="   # clé générée automatiquement par ESPHome

# Dans secrets.yaml
api_encryption_key: "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345="

# Dans votre config ESP
api:
  encryption:
    key: !secret api_encryption_key

Timeout de redémarrage automatique

Par défaut, l'ESP32 redémarre automatiquement si Home Assistant reste déconnecté pendant 15 minutes (protection contre les plantages silencieux). Ce comportement se configure via reboot_timeout :

api:
  encryption:
    key: !secret api_encryption_key
  reboot_timeout: 15min   # durée avant redémarrage si HA absent (défaut : 15min)
                           # mettre 0s pour désactiver le redémarrage automatique

Le serveur OTA (ota)

Le composant OTA gère les mises à jour firmware sans câble USB. Il est automatiquement inclus par ESPHome mais peut être personnalisé, notamment pour le protéger par un mot de passe :

ota:
  - platform: esphome
    password: !secret ota_password

ota_password: "MotDePasseOTA"

Configuration OTA avancée

ota:
  - platform: esphome
    password: !secret ota_password
    on_begin:              # action déclenchée au début d'une mise à jour OTA
      then:
        - logger.log: "Mise à jour OTA en cours..."
    on_progress:           # remontée de progression (0-100%)
      then:
        - logger.log:
            format: "OTA : %d%%"
            args: ["x"]
    on_end:
      then:
        - logger.log: "Mise à jour OTA terminée, redémarrage..."
    on_error:
      then:
        - logger.log: "Erreur OTA !"

Configuration YAML complète recommandée

Voici un bloc de référence combinant WiFi, serveur web, API et OTA, pensé pour une installation domestique standard :

# ─── WiFi ───────────────────────────────────────────
wifi:
  networks:
    - ssid: !secret wifi_ssid
      password: !secret wifi_password
      priority: 10
    - ssid: !secret wifi_ssid_backup
      password: !secret wifi_password_backup
      priority: 1
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0
    dns1: 192.168.1.1
  power_save_mode: none

ap:
  ssid: "ESP32-Secours"
  password: !secret ap_password

captive_portal:

# ─── Serveur web ────────────────────────────────────
web_server:
  port: 80
  version: 3
  auth:
    username: admin
    password: !secret web_server_password

# ─── API Home Assistant ─────────────────────────────
api:
  encryption:
    key: !secret api_encryption_key
  reboot_timeout: 15min

# ─── Mise à jour OTA ────────────────────────────────
ota:
  - platform: esphome
    password: !secret ota_password

# secrets.yaml
wifi_ssid: "NomReseauPrincipal"
wifi_password: "MotDePassePrincipal"
wifi_ssid_backup: "NomReseauSecondaire"
wifi_password_backup: "MotDePasseSecondaire"
ap_password: "HotspotSecours"
web_server_password: "InterfaceWeb"
api_encryption_key: "aBcDeFgHiJkLmNoPqRsTuVwXyZ012345="
ota_password: "MiseAJourOTA"

Étape 6 — Deuxième flash avec le WiFi

ESPHome vous demande comment installer la nouvelle configuration :

• Choisissez Plug into this computer pour un flash USB (même procédure qu'à l'étape 3 — bouton BOOT si nécessaire)
• Une fois ce second flash terminé, l'ESP redémarre et se connecte à votre réseau WiFi

Toutes les installations suivantes pourront se faire en OTA directement depuis ESPHome Builder, sans câble USB.

Étape 7 — Intégration dans Home Assistant

L'ESP32 est maintenant connecté au WiFi et annonce sa présence sur le réseau. Home Assistant le détecte automatiquement :

1. Dans HA, allez dans Paramètres → Appareils et services
2. Dans la section Découvertes, votre ESP32 apparaît avec un bouton AJOUTER
3. Cliquez sur AJOUTER et confirmez
4. L'ESP est maintenant un appareil HA à part entière, avec toutes ses entités visibles dans le tableau de bord

Aller plus loin : échange de données via MQTT

MQTT (Message Queuing Telemetry Transport) est un protocole de messagerie léger, conçu pour les objets connectés à ressources limitées. Contrairement à l'API native ESPHome (directement liée à Home Assistant), MQTT passe par un broker — un serveur central qui reçoit, filtre et redistribue les messages entre tous les appareils abonnés. Cela permet à l'ESP32 d'échanger des données avec Home Assistant, mais aussi avec Node-RED, Grafana, InfluxDB, ou n'importe quel autre système compatible MQTT.

1. Installer un broker MQTT

Le broker est le serveur central qui reçoit et redistribue tous les messages. L'add-on Mosquitto est le plus courant sous Home Assistant :

1. Dans HA, allez dans Paramètres → Modules complémentaires → Boutique
2. Recherchez Mosquitto broker et installez-le
3. Activez Démarrer au démarrage et Watchdog
4. Dans Paramètres → Appareils et services, l'intégration MQTT apparaît automatiquement — configurez-la avec l'adresse IP de HA, port 1883

2. Configuration de base

Ajoutez le composant mqtt dans le YAML de votre ESP32. Il remplace ou complète l'API native selon vos besoins :

mqtt:
  broker: 192.168.1.10      # IP de votre serveur Home Assistant (où tourne Mosquitto)
  port: 1883                 # port standard MQTT non chiffré
  username: !secret mqtt_username
  password: !secret mqtt_password
  client_id: "esp32-salon"  # identifiant unique de cet ESP sur le broker

3. Messages de naissance et de testament (birth / will)

Ces deux messages permettent de savoir en temps réel si un ESP est en ligne ou hors ligne :

• birth_message — publié par l'ESP dès qu'il se connecte au broker
• will_message — enregistré à l'avance par le broker, et publié automatiquement si l'ESP se déconnecte de façon anormale (coupure réseau, crash…)

mqtt:
  broker: 192.168.1.10
  username: !secret mqtt_username
  password: !secret mqtt_password
  client_id: "esp32-salon"
  birth_message:
    topic: "esp32/salon/status"
    payload: "online"
    qos: 1
    retain: true            # le broker mémorise ce message pour les futurs abonnés
  will_message:
    topic: "esp32/salon/status"
    payload: "offline"
    qos: 1
    retain: true

4. QoS et retain

Deux paramètres importants accompagnent chaque message MQTT :

Le flag retain: true demande au broker de mémoriser le dernier message sur ce topic. Tout nouvel abonné le reçoit immédiatement, même si l'ESP ne vient pas de le publier — très utile pour les états (allumé/éteint, température courante…).

5. Publier des données (publish)

ESPHome publie automatiquement toutes les entités sur MQTT dès que le composant mqtt est activé. Chaque capteur, interrupteur ou bouton obtient son propre topic. Vous pouvez aussi publier manuellement via l'action mqtt.publish dans vos automatisations :

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    update_interval: 30s
    temperature:
      name: "Température Salon"
      on_value:             # déclenché à chaque nouvelle mesure
        then:
          - mqtt.publish:
              topic: "esp32/salon/temperature"
              payload: !lambda 'return to_string(x);'
              qos: 0
              retain: true
    humidity:
      name: "Humidité Salon"
      on_value:
        then:
          - mqtt.publish:
              topic: "esp32/salon/humidite"
              payload: !lambda 'return to_string(x);'
              retain: true

6. Recevoir et réagir à un message (subscribe)

L'ESP32 peut s'abonner à un topic MQTT et déclencher des actions dès qu'un message arrive — idéal pour piloter un relais, allumer une LED ou modifier un paramètre à distance :

mqtt:
  broker: 192.168.1.10
  username: !secret mqtt_username
  password: !secret mqtt_password
  on_message:
    - topic: "esp32/salon/relais/set"
      payload: "ON"
      then:
        - switch.turn_on: relais_chauffage
    - topic: "esp32/salon/relais/set"
      payload: "OFF"
      then:
        - switch.turn_off: relais_chauffage
    - topic: "esp32/salon/commande"
      then:                             # réagir à n'importe quel contenu
        - logger.log:
            format: "Commande reçue : %s"
            args: ["x.c_str()"]

7. Découverte automatique dans Home Assistant (MQTT Discovery)

Avec l'option discovery: true, ESPHome publie automatiquement la description de chaque entité dans le topic homeassistant/. Home Assistant les détecte et les intègre sans aucune configuration manuelle — exactement comme avec l'API native :

mqtt:
  broker: 192.168.1.10
  username: !secret mqtt_username
  password: !secret mqtt_password
  discovery: true                    # active la découverte automatique HA
  discovery_prefix: homeassistant    # préfixe standard HA (ne pas modifier)

8. Connexion chiffrée TLS (port 8883)

Sur un réseau non sécurisé ou pour des données sensibles, activez le chiffrement TLS. Mosquitto doit être configuré avec un certificat côté serveur, puis ESPHome vérifie l'empreinte du certificat :

mqtt:
  broker: 192.168.1.10
  port: 8883                         # port MQTT chiffré (TLS)
  username: !secret mqtt_username
  password: !secret mqtt_password
  certificate_authority: |           # certificat CA du broker (PEM)
    -----BEGIN CERTIFICATE-----
    MIIBxTCCAW+gAwIBAgIJAMaH...
    -----END CERTIFICATE-----

9. Configuration MQTT complète de référence

# ─── MQTT ───────────────────────────────────────────
mqtt:
  broker: !secret mqtt_broker
  port: 1883
  username: !secret mqtt_username
  password: !secret mqtt_password
  client_id: "esp32-salon"
  discovery: true
  discovery_prefix: homeassistant
  birth_message:
    topic: "esp32/salon/status"
    payload: "online"
    qos: 1
    retain: true
  will_message:
    topic: "esp32/salon/status"
    payload: "offline"
    qos: 1
    retain: true
  on_message:
    - topic: "esp32/salon/relais/set"
      payload: "ON"
      then:
        - switch.turn_on: relais_chauffage
    - topic: "esp32/salon/relais/set"
      payload: "OFF"
      then:
        - switch.turn_off: relais_chauffage

mqtt_broker: "192.168.1.10"
mqtt_username: "mqtt_esp32"
mqtt_password: "MotDePasseMQTT"

Récapitulatif des étapes