Fabriquer ses propres capteurs avec ESPHome

Un capteur de température du commerce coûte entre 15 et 40 euros, dépend souvent d'une application de la marque et mesure ce que le fabricant a décidé. Avec une petite carte électronique à quelques euros, un module capteur et ESPHome, vous fabriquez le vôtre : il parle directement à Home Assistant, sans nuage, et vous décidez de ce qu'il mesure et à quelle fréquence.

Le mot « fabriquer » fait peur à tort. Il n'y a ici ni fer à souder, ni calcul électronique : quatre fils à enficher, un fichier texte à écrire, et un câble USB. La difficulté est ailleurs : comprendre le fichier de configuration, réussir le premier transfert sur la carte, et savoir ce qui se passe quand ça ne marche pas. C'est ce que ce guide détaille.

Il suppose une installation de Home Assistant qui fonctionne : sinon, commencez par Premiers pas avec Home Assistant.

Sécurité : alimentation par USB uniquement. Tout ce guide fonctionne en 5 volts, par un câble USB branché sur un chargeur de téléphone ou un ordinateur. Aucune étape ne touche au 230 V. Les montages qui se branchent sur le secteur (relais, modules encastrés dans un interrupteur, prise démontée) sont volontairement hors sujet : une erreur sur le 230 V ne grille pas une carte à 5 euros, elle électrocute ou met le feu. Ne vous y lancez pas à partir d'un tutoriel trouvé en ligne.

Vérifié sur la documentation officielle d'ESPHome et de Home Assistant en octobre 2026. L'interface évolue chaque mois : les écrans sont décrits par leur fonction, les noms entre guillemets sont ceux de l'interface anglaise.

Ce qu'est ESPHome, en une image

Pensez à une imprimante : vous ne programmez pas l'imprimante, vous lui envoyez un document qu'elle sait lire. ESPHome fonctionne pareil : vous décrivez votre capteur dans un fichier texte (« voici ma carte, voici mon Wi-Fi, il y a un capteur de température branché sur telles broches »), ESPHome transforme cette description en programme, puis l'envoie sur la carte. Vous n'écrivez aucune ligne de code au sens programmation : seulement une description, au format YAML.

Trois éléments, à ne pas confondre :

• la carte ESP32 : un petit circuit avec un processeur et du Wi-Fi intégré, de la taille d'une clé USB. C'est elle qui lit le capteur et envoie les mesures ;
• ESPHome Device Builder : le tableau de bord, dans Home Assistant, où l'on écrit les fichiers et d'où l'on envoie le programme sur la carte. C'est une App (ex-module complémentaire) ;
• l'intégration ESPHome : la partie de Home Assistant qui reçoit les mesures de la carte et les transforme en entités, comme pour n'importe quel appareil.

Le trajet complet, du capteur jusqu'à l'écran :

flowchart LR
    S["Module AHT20<br/>température et humidité"] -->|"4 fils, bus I2C"| E["Carte ESP32<br/>programme ESPHome"]
    E -->|"Wi-Fi, connexion chiffrée"| I["Intégration ESPHome<br/>dans Home Assistant"]
    I --> T["Entités et tableau de bord"]
    D["ESPHome Device Builder<br/>(App dans Home Assistant)"] -->|"1re fois : câble USB<br/>ensuite : par le Wi-Fi (OTA)"| E

Ce qu'il faut acheter

Pour un premier capteur, environ 10 à 15 euros :

Deux pièges à l'achat :

• beaucoup de modules sont vendus broches livrées à part, à souder soi-même. Vérifiez la mention « soudé » (« pre-soldered headers ») dans la fiche, ou les photos ;
• le vieux DHT22, très présent dans les tutoriels, fonctionne aussi, mais il est moins précis et plus capricieux. Pour un premier montage, l'AHT20 évite des heures de doute.

Les autres familles de cartes (ESP32-C3, ESP32-S3, ESP8266) fonctionnent avec ESPHome, mais leurs broches diffèrent : si vous en prenez une, adaptez le fichier en conséquence.

Étape 1 : installer ESPHome Device Builder

ESPHome Device Builder s'installe comme une App, depuis la rubrique Apps des paramètres. La procédure (boutique d'Apps, démarrage automatique, lecture du journal) est détaillée dans Étendre Home Assistant : intégrations, Apps et Marketplace : cherchez « ESPHome Device Builder » dans la boutique, installez, démarrez, et activez l'affichage dans la barre latérale.

Rappel de ce guide : les Apps n'existent que sur Home Assistant OS. En conteneur, ESPHome Device Builder se fait tourner dans un conteneur à part ; le reste de ce guide est identique.

Étape 2 : brancher le capteur

Débranchez la carte de tout câble USB avant de câbler. Le module AHT20 a quatre broches, à relier à la carte avec les câbles Dupont :

GPIO21 et GPIO22 sont les broches I2C par défaut de l'ESP32 classique. I2C est un petit bus à deux fils (données et horloge) sur lequel plusieurs capteurs peuvent partager les mêmes broches : c'est ce qui rend le montage si simple.

Branchez le VCC du capteur sur 3V3, pas sur la broche 5 V ou VIN de la carte. Inverser VCC et GND peut détruire le module : vérifiez deux fois avant de brancher l'USB.

Étape 3 : créer l'appareil dans Device Builder

Ouvrez ESPHome Device Builder depuis la barre latérale, puis :

1. Utilisez le bouton de création d'un appareil (« Create device »).
2. Choisissez l'assistant de configuration (« New Device Setup »). Il demande un nom (par exemple capteur-salon, en minuscules et tirets : il servira d'adresse réseau), le type de carte (ESP32) et vos identifiants Wi-Fi.
3. Enregistrez. L'appareil apparaît comme une carte dans le tableau de bord de Device Builder.

L'assistant a écrit un fichier de base. Les identifiants Wi-Fi n'y figurent pas en clair : ils sont rangés dans un fichier de secrets (secrets.yaml), que Device Builder permet d'éditer, et le fichier de l'appareil y fait référence avec !secret.

Étape 4 : le fichier de configuration, ligne par ligne

Ouvrez l'édition de l'appareil. Complétez le fichier généré pour qu'il ressemble à ceci. Gardez la clé de chiffrement et les mots de passe que l'assistant a générés : ne recopiez pas ceux d'un exemple.

esphome:
  name: capteur-salon
  friendly_name: Capteur salon

esp32:
  board: esp32dev

logger:

api:
  encryption:
    key: "la-cle-generee-par-l-assistant"

ota:
  - platform: esphome

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  ap:
    ssid: "Capteur-Salon secours"
    password: "le-mot-de-passe-genere"

captive_portal:

i2c:
  sda: GPIO21
  scl: GPIO22

sensor:
  - platform: aht10
    variant: AHT20
    temperature:
      name: "Température"
    humidity:
      name: "Humidité"
    update_interval: 60s

Ce que dit chaque bloc :

• esphome : l'identité de l'appareil. name est son nom technique sur le réseau (capteur-salon.local), friendly_name le nom affiché dans Home Assistant.
• esp32 : le type de carte. esp32dev désigne la DevKit classique. Une erreur ici fait échouer le transfert.
• logger : active le journal de la carte. C'est lui que vous lirez quand quelque chose ne marche pas.
• api : la connexion avec Home Assistant. La clé de chiffrement garantit que seul votre Home Assistant peut parler à la carte : Home Assistant vous la demandera lors de l'ajout.
• ota : autorise les mises à jour par le réseau (« over the air »). Sans ce bloc, chaque modification demanderait de reprendre le câble USB.
• wifi : votre réseau, par les secrets. Le sous-bloc ap crée un point d'accès de secours : si la carte ne trouve plus votre Wi-Fi (mot de passe changé, box remplacée), elle ouvre son propre réseau.
• captive_portal : sur ce réseau de secours, une page s'ouvre pour saisir les nouveaux identifiants Wi-Fi. Avec ap, c'est ce qui évite de devoir rebrancher la carte sur un ordinateur.
• i2c : le bus à deux fils, sur les broches câblées à l'étape 2. Au démarrage, ESPHome cherche les capteurs présents sur ce bus et l'écrit dans le journal : pratique pour vérifier le câblage.
• sensor : le capteur lui-même. La plateforme s'appelle aht10, même pour un AHT20 : c'est variant: AHT20 qui fait la différence. update_interval: 60s envoie une mesure par minute, largement assez pour une pièce.

Le YAML est sensible à l'indentation : deux espaces par niveau, jamais de tabulation. Device Builder signale une erreur de structure avant même de compiler.

Étape 5 : le premier transfert, par USB

La toute première fois, la carte est vide : elle ne connaît pas votre Wi-Fi, donc le programme doit passer par le câble USB. C'est l'étape la plus délicate, et une seule fois par carte.

Branchez la carte sur l'ordinateur, puis, depuis la carte de l'appareil dans Device Builder, utilisez le bouton d'installation (« Install »). Il propose plusieurs méthodes ; deux conviennent ici :

• le branchement sur l'ordinateur que vous utilisez, directement depuis le navigateur. Cette méthode exige que Home Assistant soit ouvert en HTTPS : si vous y accédez par une adresse locale en http://, elle ne fonctionnera pas ;
• le téléchargement du programme compilé, puis son envoi avec ESPHome Web (web.esphome.io), la page officielle qui transfère un programme sur une carte depuis le navigateur. C'est la voie la plus sûre pour un premier essai.

Dans les deux cas :

• utilisez Chrome ou Edge sur ordinateur : le transfert par USB depuis une page web repose sur une fonction (WebSerial) que Firefox et Safari n'offrent pas ;
• la première compilation est longue (plusieurs minutes) : Device Builder télécharge les outils nécessaires. Les suivantes sont bien plus rapides ;
• si la carte n'apparaît pas dans la liste des ports, c'est presque toujours le câble (charge seule) ou le pilote de la puce USB de la carte (CH340 ou CP2102, indiqués sur la puce elle-même) à installer sur l'ordinateur ;
• si le transfert refuse de démarrer, maintenez le bouton BOOT de la carte enfoncé au moment où la connexion commence, puis relâchez.

Une fois le transfert terminé, la carte redémarre, se connecte à votre Wi-Fi, et la carte de l'appareil dans Device Builder passe en ligne (« Online »). Vous pouvez la débrancher de l'ordinateur et la brancher sur un simple chargeur USB.

Étape 6 : l'ajouter à Home Assistant

Dans la plupart des cas, Home Assistant découvre la carte tout seul : une notification signale un appareil ESPHome découvert, dans la rubrique des appareils et services des paramètres. Utilisez le bouton de configuration proposé, saisissez la clé de chiffrement si elle est demandée (c'est celle du bloc api), et rattachez l'appareil à sa pièce.

Si rien n'est découvert, ajoutez-le à la main : bouton d'ajout d'une intégration, choisissez ESPHome, puis saisissez l'adresse capteur-salon.local ou l'adresse IP de la carte (visible dans le journal de Device Builder et dans l'interface de votre box). La découverte automatique dépend d'un mécanisme réseau (mDNS) que certains routeurs ou réseaux invités bloquent.

L'appareil apparaît avec deux entités, Température et Humidité, préfixées du nom affiché : « Capteur salon Température ». Vous pouvez les placer sur un tableau de bord (voir Construire un tableau de bord Home Assistant sur mesure) et les utiliser dans des automatisations comme n'importe quel capteur.

Une option des réglages de l'intégration autorise la carte à déclencher des actions dans Home Assistant. Elle est désactivée par défaut : laissez-la ainsi, un capteur qui mesure n'en a pas besoin.

Étape 7 : modifier et mettre à jour sans débrancher

À partir de maintenant, le câble USB ne sert plus. Chaque modification suit le même chemin :

1. modifiez le fichier dans Device Builder et enregistrez (cela ne change encore rien sur la carte) ;
2. utilisez Install, et choisissez cette fois l'envoi sans fil : Device Builder compile, puis transfère le programme par le Wi-Fi ;
3. la carte redémarre avec la nouvelle version, en une dizaine de secondes d'absence dans Home Assistant.

Par exemple, si la carte réchauffe le capteur et que la mesure est trop haute d'un degré par rapport à un thermomètre de référence, ajoutez une correction sous temperature :

    temperature:
      name: "Température"
      filters:
        - offset: -1.0

Device Builder signale aussi quand une nouvelle version d'ESPHome est disponible pour vos appareils. Comme pour Home Assistant : une mise à jour à la fois, et lisez les notes de version, qui annoncent les changements de syntaxe.

Cas concret

Julien veut surveiller l'humidité de sa salle de bains pour déclencher l'aération. Il monte un ESP32 et un AHT20, crée l'appareil capteur-sdb, et lance l'installation depuis Device Builder. La compilation réussit, mais l'option de branchement direct reste inutilisable.

1. Diagnostic : il accède à Home Assistant par http://192.168.1.20:8123. Pas de HTTPS, donc pas de transfert USB depuis le navigateur par cette voie.
2. Il choisit le téléchargement du programme, ouvre web.esphome.io dans Edge, connecte la carte : aucun port n'apparaît.
3. Il remplace le câble, qui venait d'une lampe de bureau : c'était un câble de charge seule. Le port apparaît, le transfert passe.
4. La carte passe en ligne, Home Assistant la découvre. Mais le journal indique que le capteur n'est pas trouvé sur le bus I2C.
5. Il revérifie le câblage : SDA et SCL étaient inversés. Une fois corrigé, la mesure arrive.
6. Les mesures suivantes partiront de la même façon, et la prochaine modification passera par le Wi-Fi.

Placé dans la salle de bains, le boîtier reste branché sur un chargeur USB hors de portée des projections d'eau, loin de la douche : c'est aussi pour cela qu'on reste en 5 V.

Erreurs fréquentes

• Câble USB de charge seule : la carte s'allume, mais aucun port n'apparaît sur l'ordinateur. C'est la panne numéro un du premier transfert.
• Tenter le transfert depuis Firefox, ou depuis Home Assistant ouvert en http:// : téléchargez le programme et utilisez ESPHome Web dans Chrome ou Edge.
• SDA et SCL inversés, ou VCC sur la mauvaise broche : la carte fonctionne, le capteur n'apparaît pas. Le journal au démarrage dit ce qu'il trouve sur le bus I2C.
• Oublier variant: AHT20 : la plateforme aht10 suppose par défaut un AHT10, et la lecture échoue.
• Recopier la clé de chiffrement d'un tutoriel au lieu de garder celle générée par l'assistant : la clé protège la connexion, elle doit être unique.
• Supprimer le bloc ota en « nettoyant » le fichier : la mise à jour suivante exige de nouveau le câble.
• Coller le capteur contre la carte : l'ESP32 chauffe légèrement et fausse la température. Éloignez le module de quelques centimètres avec les fils.
• Vouloir piloter un appareil sur secteur avec un relais acheté à côté : c'est du 230 V, hors du périmètre de ce guide.

À retenir

• ESPHome transforme une description YAML en programme pour une carte ESP32 : on décrit, on ne programme pas.
• ESPHome Device Builder est une App ; l'intégration ESPHome reçoit les mesures. Les deux sont nécessaires.
• Le premier transfert se fait par USB, depuis Chrome ou Edge, avec un câble de données. Tous les suivants passent par le Wi-Fi grâce au bloc ota.
• Le bloc api et sa clé de chiffrement relient la carte à Home Assistant, qui la découvre généralement tout seul.
• 5 V par USB uniquement : aucune manipulation sur le 230 V.

Mini-exercice

Sur votre capteur en service :

1. Ouvrez le journal de l'appareil dans Device Builder et retrouvez la ligne où ESPHome liste ce qu'il a trouvé sur le bus I2C au démarrage. Notez l'adresse du capteur.
2. Passez update_interval de 60s à 30s, enregistrez, et installez sans fil. Vérifiez dans l'historique de l'entité que les mesures arrivent deux fois plus souvent.
3. Remettez 60s : une pièce d'habitation n'a pas besoin de plus, et chaque mesure de trop alourdit l'historique de Home Assistant.

Si les trois étapes passent sans toucher au câble USB, votre capteur est autonome : la prochaine fois, ajouter un second capteur sur le même bus I2C ne demandera que quelques lignes et une mise à jour sans fil.