ESPHome MQTT : utiliser MQTT à la place de l'API native

La prise en charge de MQTT dans ESPHome permet à un ESP32 ou un ESP8266 configuré en YAML de publier l'état de ses capteurs et de recevoir des commandes via n'importe quel broker standard, au lieu de l'API native de Home Assistant. Dans ce tutoriel, vous allez configurer le composant mqtt:, comprendre les topics générés par ESPHome, ajouter TLS et identifiants pour la production, et réagir aux messages entrants directement sur l'appareil.

API native ou MQTT : quand changer

L'API native d'ESPHome est une liaison point à point efficace et chiffrée entre un appareil et Home Assistant. Elle est excellente tant que Home Assistant est le seul à dialoguer avec l'appareil. Elle devient limitante dès qu'un autre logiciel a besoin des mêmes données : un flux Node-RED, un enregistreur Python, une chaîne Grafana via Telegraf, ou un second site qui ne peut pas atteindre votre réseau local.

MQTT résout ce problème en plaçant un broker au milieu. L'appareil publie une seule fois et un nombre quelconque d'abonnés reçoivent la mesure. Rien ne change sur l'appareil lorsque vous ajoutez un nouveau consommateur, et les appareils situés derrière un NAT peuvent tout de même joindre un broker sur Internet. Si le modèle publication/abonnement est nouveau pour vous, la présentation de ce que fait un broker MQTT constitue une bonne introduction. Home Assistant n'est d'ailleurs pas seul dans la maison connectée : Jeedom et Domoticz savent aussi communiquer en MQTT.

Vous pouvez utiliser les deux simultanément, mais si plus rien ne se sert de l'API native, supprimez le bloc api: pour que l'appareil n'y consacre pas de mémoire.

Une configuration ESPHome MQTT minimale

L'exemple ci-dessous est une configuration complète pour un ESP32 équipé d'un capteur DHT22 et d'un relais. Il se connecte au serveur MQTT public gratuit, réservé aux tests, ce qui vous permet de voir des messages en quelques minutes. Remplacez a7k2q9 par votre propre chaîne aléatoire pour que vos topics n'entrent pas en collision avec ceux d'autres utilisateurs.

esphome:
  name: greenhouse-node
  friendly_name: Greenhouse Node

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

logger:
  level: INFO

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

ota:
  - platform: esphome
    password: !secret ota_password

mqtt:
  broker: broker.connectmq.com
  port: 1883
  client_id: esphome-greenhouse-a7k2q9
  topic_prefix: connectmq/demo/a7k2q9/greenhouse
  discovery: false
  log_topic: null
  birth_message:
    topic: connectmq/demo/a7k2q9/greenhouse/status
    payload: online
    retain: true
  will_message:
    topic: connectmq/demo/a7k2q9/greenhouse/status
    payload: offline
    retain: true

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    update_interval: 30s
    temperature:
      name: "Air Temperature"
      id: air_temp
    humidity:
      name: "Air Humidity"
      id: air_hum

switch:
  - platform: gpio
    pin: GPIO26
    name: "Vent Fan"
    id: vent_fan

Flashez-la avec esphome run greenhouse-node.yaml. Une fois l'appareil en ligne, abonnez-vous depuis votre ordinateur :

mosquitto_sub -h broker.connectmq.com -p 1883 -i sub-a7k2q9 \
  -t 'connectmq/demo/a7k2q9/greenhouse/#' -v

Vous devriez voir le statut online retenu et un message d'état toutes les 30 secondes pour chaque capteur.

Les paramètres à bien comprendre

• client_id : il doit être non vide et unique sur le broker. Si deux appareils partagent un même ID, le broker déconnecte l'ancienne session chaque fois que la nouvelle se connecte, et les deux appareils oscillent sans cesse.
• topic_prefix : par défaut, le nom du nœud. Le définir explicitement vous donne une hiérarchie prévisible et garde l'espace de test public bien rangé.
• discovery : réglez-le sur false sauf si Home Assistant consomme ce broker. La découverte publie des messages de configuration retenus sous homeassistant/, qui seraient visibles par tout le monde sur un broker public partagé.
• log_topic : ESPHome recopie par défaut ses journaux sur <prefix>/debug. Le régler sur null évite qu'un appareil bavard épuise les limites de débit.

Les topics publiés par ESPHome

ESPHome construit les topics à partir du préfixe, du type de composant et d'un identifiant d'objet dérivé du nom de l'entité (en minuscules, les espaces devenant des tirets bas).

Les états sont de simples chaînes : 23.4 pour un capteur, ON ou OFF pour un interrupteur. Pour allumer le ventilateur depuis la ligne de commande :

mosquitto_pub -h broker.connectmq.com -p 1883 -i pub-a7k2q9 \
  -t 'connectmq/demo/a7k2q9/greenhouse/switch/vent_fan/command' -m 'ON'

L'appareil exécute la commande puis publie le nouvel état sur le topic state correspondant, de sorte que les tableaux de bord reflètent toujours ce qui s'est réellement produit plutôt que ce qui a été demandé.

Si une autre organisation des topics est nécessaire, chaque composant accepte des surcharges state_topic et command_topic. C'est utile lorsque vous disposez déjà d'une structure comme celle décrite dans le guide sur la structure des topics MQTT pour la maison connectée.

sensor:
  - platform: dht
    pin: GPIO4
    model: DHT22
    temperature:
      name: "Air Temperature"
      state_topic: connectmq/demo/a7k2q9/site1/greenhouse/temperature

Réagir aux messages MQTT sur l'appareil

Le composant MQTT ne sert pas qu'en sortie. Vous pouvez déclencher des automatisations depuis n'importe quel topic avec on_message ou on_json_message, et publier des payloads arbitraires avec les actions mqtt.publish et mqtt.publish_json.

mqtt:
  # ... paramètres de connexion ci-dessus ...
  on_message:
    - topic: connectmq/demo/a7k2q9/greenhouse/mode
      payload: "night"
      then:
        - switch.turn_off: vent_fan
  on_json_message:
    topic: connectmq/demo/a7k2q9/greenhouse/setpoint
    then:
      - lambda: |-
          if (x.containsKey("max_temp")) {
            id(max_temp) = x["max_temp"];
          }

globals:
  - id: max_temp
    type: float
    restore_value: true
    initial_value: '28.0'

interval:
  - interval: 60s
    then:
      - if:
          condition:
            lambda: 'return id(air_temp).state > id(max_temp);'
          then:
            - switch.turn_on: vent_fan
            - mqtt.publish_json:
                topic: connectmq/demo/a7k2q9/greenhouse/event
                payload: |-
                  root["event"] = "overheat";
                  root["temp"] = id(air_temp).state;

Une règle de sécurité simple reste ainsi sur l'appareil lui-même, ce qui permet au ventilateur de tourner même en cas de panne réseau, tandis que la consigne peut être modifiée à distance en publiant {"max_temp": 30}.

Configuration de production : TLS et identifiants

L'espace de test public convient aux expérimentations, mais chaque topic y est lisible par n'importe qui. Pour une installation réelle, créez un broker privé et utilisez les identifiants générés. Sur ESP32 avec le framework ESP-IDF, ESPHome prend en charge le TLS si vous fournissez le certificat de l'autorité qui a signé le certificat du broker. ConnectMQ utilise un certificat Let's Encrypt : l'autorité est donc ISRG Root X1.

mqtt:
  broker: broker.connectmq.com
  port: 8883
  client_id: YOUR_CLIENT_ID
  username: YOUR_USERNAME
  password: !secret mqtt_password
  topic_prefix: site1/greenhouse
  discovery: false
  log_topic: null
  certificate_authority: |
    -----BEGIN CERTIFICATE-----
    (paste the ISRG Root X1 certificate here)
    -----END CERTIFICATE-----
  birth_message:
    topic: site1/greenhouse/status
    payload: online
    retain: true
  will_message:
    topic: site1/greenhouse/status
    payload: offline
    retain: true

Conservez le mot de passe dans secrets.yaml plutôt que dans le fichier principal pour qu'il ne se retrouve pas dans votre gestionnaire de versions. Comme le client ID est lié aux identifiants attribués sur ConnectMQ, copiez-le exactement depuis le portail.

Les cartes ESP8266 disposent de beaucoup moins de RAM, et la validation complète des certificats y est juste. Si vous devez utiliser TLS sur un ESP8266, consultez la documentation actuelle d'ESPHome pour connaître les options prises en charge, ou passez le projet sur un ESP32, qui gère TLS sans difficulté.

Alimenter Home Assistant et d'autres outils

Une fois l'appareil sur un broker, Home Assistant devient un consommateur parmi d'autres. Pointez son intégration MQTT vers le même broker (le guide broker MQTT externe pour Home Assistant détaille la marche à suivre) et réglez discovery: true sur l'appareil pour que les entités apparaissent automatiquement. Les détails de la découverte, y compris les payloads de configuration retenus, sont expliqués dans la découverte MQTT de Home Assistant.

Dans le même temps, un flux Node-RED peut s'abonner à site1/+/sensor/+/state pour journaliser chaque capteur, et un script Python peut archiver les mesures dans une base de données. Aucun d'eux n'a besoin de connaître l'adresse IP de l'appareil.

Dépannage d'ESPHome MQTT

1. L'appareil se connecte puis se déconnecte toutes les quelques secondes. C'est presque toujours un client ID en double. Vérifiez qu'aucun autre appareil ni aucun script de test oublié n'utilise le même ID.
2. Aucun message n'apparaît. Vérifiez que l'abonnement correspond exactement au préfixe, casse comprise. Abonnez-vous à connectmq/demo/a7k2q9/# pour voir tout ce qui se trouve sous votre branche.
3. La négociation TLS échoue. Vérifiez que l'appareil est à l'heure (TLS en a besoin ; ESPHome se synchronise via SNTP), que vous avez collé le bloc PEM complet et que vous utilisez le port 8883.
4. Des messages sont perdus sur le broker public. L'espace de test autorise 10 messages par seconde et par client, et 64 Ko par message. Des journaux sur le topic de débogage ou des intervalles de mise à jour très courts peuvent dépasser ces limites.
5. Les commandes sont ignorées. Publiez sur le topic command, pas sur le topic state, et utilisez ON ou OFF en majuscules pour les interrupteurs.

Observer l'arborescence des topics dans un explorateur en direct rend la plupart de ces problèmes évidents en quelques secondes ; c'est pourquoi il vaut la peine d'ouvrir l'explorateur de topics du portail ou l'application ConnectMQ Desktop pendant le flashage.

Passer à l'échelle au-delà de quelques nœuds

Un simple Raspberry Pi qui fait tourner un broker fonctionne jusqu'au jour où il ne fonctionne plus : pannes de carte SD, coupures de courant et redirection de ports pour l'accès distant deviennent alors votre problème. Passer à un broker MQTT managé supprime cette maintenance et offre à chaque nœud ESPHome un point de terminaison TLS stable, accessible depuis n'importe quel réseau. La vision d'ensemble pour combiner appareils, brokers et logique d'automatisation est présentée dans le guide d'automatisation IoT.

Connectez vos appareils ESPHome à ConnectMQ

ConnectMQ vous fournit un broker privé avec TLS sur le port 8883, un nom d'utilisateur, un mot de passe et un client ID générés, ainsi qu'un explorateur de topics en direct pour voir vos nœuds ESPHome remonter leurs données. Créez gratuitement un broker Serverless sur app.connectmq.com, sans carte bancaire, collez les identifiants dans secrets.yaml et flashez.

Questions fréquentes

Puis-je utiliser ESPHome MQTT et l'API native en même temps ?

Oui. Les deux composants peuvent être activés ensemble, ce qui est pratique pendant une migration. Supprimez api: dès que plus rien n'en dépend pour économiser de la mémoire.

ESPHome MQTT fonctionne-t-il sans Home Assistant ?

Oui. Avec discovery: false, l'appareil se contente de publier ses états et d'écouter les commandes, et n'importe quel client MQTT peut les utiliser.

Pourquoi mon appareil ESPHome se reconnecte-t-il sans cesse au broker ?

La cause la plus fréquente est que deux clients utilisent le même client ID. Attribuez à chaque appareil un client_id unique, ou utilisez exactement l'ID fourni avec les identifiants de votre broker.

Quel niveau de QoS ESPHome utilise-t-il ?

Les messages d'état utilisent le QoS 0 par défaut. Vous pouvez définir qos par composant ou dans birth_message et will_message si vous avez besoin de garanties de livraison, comme expliqué dans le guide sur les niveaux de QoS MQTT.