Guide de configuration MQTT dans ESPHome : discovery, birth/will et brokers externes

ESPHome parle MQTT avec un seul bloc YAML. Ajoutez mqtt: avec l'adresse d'un broker et chaque capteur, interrupteur et lumière de l'appareil publie son état et accepte des commandes sur des topics prévisibles, sans écrire de C++. Cela fonctionne avec Home Assistant via MQTT discovery, et tout aussi bien sans Home Assistant, pour alimenter Node-RED, Grafana ou votre propre backend depuis n'importe quel broker.

Ce guide couvre une configuration complète avec un broker externe, l'organisation des topics générée par ESPHome, le discovery, les messages birth et will, TLS, les abonnements personnalisés et la vérification de chaque élément depuis le navigateur.

Une configuration minimale qui fonctionne

esphome:
  name: livingroom

esp32:
  board: esp32dev
  framework:
    type: esp-idf

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

logger:

ota:
  - platform: esphome
    password: !secret ota_password

mqtt:
  broker: broker.connectmq.com
  port: 1883
  username: !secret mqtt_user
  password: !secret mqtt_password
  client_id: esphome-livingroom
  topic_prefix: testmqtt/esphome/livingroom
  discovery: false

sensor:
  - platform: wifi_signal
    name: "WiFi Signal"
    update_interval: 30s
  - platform: uptime
    name: "Uptime"

switch:
  - platform: gpio
    pin: GPIO2
    name: "Relay"
    id: relay

wifi_ssid: "your-ssid"
wifi_password: "your-wifi-password"
ota_password: "change-me"
mqtt_user: "username"
mqtt_password: "password"

Flashez-la avec esphome run livingroom.yaml. Dans le log, vous devriez voir Connecting to MQTT... suivi de MQTT Connected!.

Trois réglages méritent d'être définis explicitement plutôt que de se fier aux valeurs par défaut :

• topic_prefix vaut par défaut le nom du nœud (livingroom). Sur un broker partagé, cela entre en collision avec le salon de tout le monde. Un préfixe unique comme testmqtt/esphome/livingroom garde vos topics à vous.
• client_id doit être unique par appareil. Deux appareils avec le même ID se déconnectent mutuellement en boucle. Si vous l'omettez, ESPHome en génère un à partir du nom et de l'adresse MAC, ce qui convient très bien ; ne copiez simplement jamais un ID fixe d'un fichier YAML à l'autre.
• discovery: false pendant vos tests sur un broker public ou partagé, pour ne pas publier de messages de configuration Home Assistant dans un espace de noms que d'autres lisent. Activez-le quand vous utilisez votre propre broker.

Les topics générés par ESPHome

Chaque entité reçoit un topic d'état, et les entités pilotables un topic de commande. L'object ID est le nom de l'entité en minuscules, espaces remplacés par des underscores :

Vous pouvez redéfinir chacun d'eux par entité avec state_topic: et command_topic: lorsqu'il faut respecter une conception de topics existante. L'option log_topic: contrôle le topic de débogage ; réglez-la sur null pour cesser de publier les logs en MQTT, ce qui économise de la bande passante sur les appareils chargés.

Messages birth, will et shutdown

ESPHome envoie un message birth après la connexion et enregistre un Last Will auprès du broker. Par défaut, les deux vont sur <topic_prefix>/status, en retained, avec les payloads online et offline. C'est ce qu'utilise Home Assistant pour la disponibilité des entités. Vous pouvez les personnaliser :

mqtt:
  # ...
  birth_message:
    topic: testmqtt/esphome/livingroom/availability
    payload: "connected"
    retain: true
  will_message:
    topic: testmqtt/esphome/livingroom/availability
    payload: "lost"
    retain: true
  shutdown_message:
    topic: testmqtt/esphome/livingroom/availability
    payload: "shutdown"
    retain: true
  keepalive: 30s

Le will est publié par le broker, pas par l'appareil, environ 1,5 × keepalive après que l'appareil est devenu silencieux. Le message shutdown est envoyé par l'appareil lui-même avant un redémarrage planifié ou une mise à jour OTA : vous distinguez ainsi « redémarrage volontaire » et « coupure de courant ». Les délais sont expliqués dans MQTT Last Will, et le flag retained dans messages retenus.

Discovery Home Assistant

Avec discovery: true (la valeur par défaut), ESPHome publie un message de configuration retained par entité sous <discovery_prefix>/<component>/<node>/<object_id>/config. L'intégration MQTT de Home Assistant s'abonne à ce préfixe et crée automatiquement les entités.

mqtt:
  broker: broker.connectmq.com
  port: 1883
  username: !secret mqtt_user
  password: !secret mqtt_password
  discovery: true
  discovery_prefix: homeassistant
  discovery_retain: true

À savoir :

• Le préfixe doit correspondre. Home Assistant écoute sur homeassistant, sauf si vous l'avez changé dans les options de l'intégration MQTT. Si vous en modifiez un, modifiez les deux.
• Les messages de discovery sont retained. Si vous renommez ou supprimez une entité, l'ancienne configuration reste sur le broker. Effacez-la en publiant un message retained vide sur l'ancien topic de configuration.
• Un seul broker pour les deux. Home Assistant doit se connecter au même broker que l'appareil. Pour le côté Home Assistant, lisez Home Assistant MQTT.

S'abonner et publier depuis le YAML

ESPHome peut réagir à n'importe quel topic, pas seulement à ses propres topics de commande, et publier des messages arbitraires :

mqtt:
  # ...
  on_message:
    - topic: testmqtt/esphome/livingroom/cmd/toggle
      qos: 1
      then:
        - switch.toggle: relay
  on_json_message:
    topic: testmqtt/esphome/livingroom/cmd/json
    then:
      - if:
          condition:
            lambda: 'return x["relay"] == "on";'
          then:
            - switch.turn_on: relay
          else:
            - switch.turn_off: relay

interval:
  - interval: 60s
    then:
      - mqtt.publish:
          topic: testmqtt/esphome/livingroom/heartbeat
          payload: "alive"
          qos: 0
          retain: false

on_json_message analyse le payload avec ArduinoJson et l'expose sous le nom x. Gardez des payloads compacts : des messages très volumineux peuvent dépasser le buffer du client sur les cartes à mémoire limitée.

Utiliser TLS avec un broker externe

Sur ESP32, ajoutez le certificat de la CA du broker et passez au port 8883 :

mqtt:
  broker: broker.connectmq.com
  port: 8883
  username: !secret mqtt_user
  password: !secret mqtt_password
  certificate_authority: |
    -----BEGIN CERTIFICATE-----
    ... root CA of your broker's certificate chain ...
    -----END CERTIFICATE-----

Utilisez la CA racine de la chaîne présentée par le broker, pas le certificat du serveur lui-même. Le framework ESP-IDF est le choix recommandé pour MQTT sur TLS sur ESP32. La prise en charge sur ESP8266 est bien plus limitée (empreintes uniquement avec le framework Arduino) : pour les appareils où TLS est critique, choisissez un ESP32, ou gardez les ESP8266 sur un réseau local de confiance. Notre guide TLS pour ESP32 explique comment extraire le bon certificat avec openssl s_client.

Tester chaque élément depuis le navigateur

1. Ouvrez le client MQTT en ligne, connectez-vous à broker.connectmq.com sur le port 8084 (chemin /mqtt) et abonnez-vous à testmqtt/esphome/livingroom/#.
2. Vous devriez voir status = online (retained) et les états wifi_signal et uptime toutes les 30 secondes.
3. Publiez ON sur testmqtt/esphome/livingroom/switch/relay/command. Le relais bascule et switch/relay/state indique ON.
4. Publiez n'importe quoi sur testmqtt/esphome/livingroom/cmd/toggle pour tester on_message.
5. Coupez l'alimentation de la carte. Après environ 1,5 × keepalive, le will passe status à offline. Si vous la redémarrez plutôt depuis le dashboard, vous verrez d'abord le message shutdown.

Observer votre nœud ESPHome dans le client en ligne

Si une entité n'apparaît pas sur le topic attendu, collez le topic et votre filtre dans le topic matcher pour repérer une faute de frappe dans le préfixe.

Aide-mémoire de dépannage

Pour un diagnostic pas à pas, lisez ESPHome MQTT ne se connecte pas.

Configurer ESPHome pour MQTT est surtout une affaire de nommage : un préfixe de topic et un client ID uniques, le discovery activé seulement là où vit Home Assistant, et des topics de disponibilité fiables. Une fois cela en place, vérifiez l'état, les commandes et le will depuis le client en ligne : le même YAML passera de votre broker de test à la production en changeant un nom d'hôte et un secret.

Questions fréquentes