Home Assistant MQTT : guide de configuration complet

La prise en charge de MQTT par Home Assistant vous permet d'intégrer à votre maison connectée n'importe quel appareil qui parle MQTT : capteurs ESP32 faits maison, prises Tasmota, réseaux Zigbee2MQTT et même passerelles industrielles. Dans ce guide, vous allez configurer l'intégration Home Assistant MQTT, créer des capteurs et des interrupteurs en YAML, tout tester sur le serveur MQTT public gratuit broker.connectmq.com, puis passer à un broker ConnectMQ privé avec TLS.

Comment Home Assistant utilise MQTT

Home Assistant n'est pas un broker MQTT. Son intégration MQTT est un client qui se connecte à un broker, s'abonne aux topics d'état et publie sur les topics de commande. Les appareils sont des clients du même broker. Le broker se trouve au milieu et achemine les messages, ce qui est expliqué en détail dans le rôle d'un broker MQTT. Jeedom et Domoticz savent aussi communiquer en MQTT et peuvent se connecter au même broker.

Cela vous laisse deux choix d'hébergement :

Option	Où tourne le broker	Idéal pour	Compromis
Module complémentaire Mosquitto	Sur l'hôte Home Assistant	Une seule maison, tous les appareils sur le réseau local	Les appareils distants nécessitent une redirection de port ou un VPN ; vous gérez les sauvegardes
Broker cloud	Hébergé, accessible en TLS	Appareils sur plusieurs sites, capteurs distants, partage des données avec d'autres applications	Nécessite internet ; choisissez un fournisseur de confiance
Les deux, en pont	Mosquitto local relié en pont à un broker cloud	Résilience locale plus accès à distance	Davantage de configuration

Ce tutoriel utilise un broker cloud, car il fonctionne de la même façon que Home Assistant tourne sur un Raspberry Pi, un NUC ou une machine virtuelle. Pour le raisonnement détaillé et l'option en pont, lisez utiliser un broker MQTT externe avec Home Assistant.

Étape 1 : ajouter l'intégration MQTT

Ouvrez Paramètres > Appareils et services.
Cliquez sur Ajouter une intégration et recherchez MQTT.
Choisissez MQTT (pas un module complémentaire) et saisissez les informations du broker :
- Broker : broker.connectmq.com
- Port : 1883
- Nom d'utilisateur et mot de passe : laissez vides pour le serveur MQTT public gratuit
Validez. Home Assistant se connecte et crée l'entrée de l'intégration MQTT.

Pour définir le client ID, le TLS ou la version du protocole, activez d'abord le Mode avancé dans votre profil utilisateur. La boîte de dialogue de configuration de l'intégration affiche alors des champs supplémentaires comme le client ID, le keep alive, la validation du certificat du broker, le transport (TCP ou WebSockets) et la version du protocole MQTT. Vous en aurez besoin à l'étape 6.

Le serveur MQTT public gratuit exige un client ID non vide. Home Assistant en génère automatiquement un aléatoire lorsque le champ est laissé vide, ce qui convient pour les tests.

Étape 2 : vérifier la connexion

Ouvrez Paramètres > Appareils et services > MQTT > Configurer. Cette page contient un formulaire Publier un paquet et un formulaire Écouter un topic.

Dans Écouter un topic, saisissez connectmq/demo/ha-x7m2/# et cliquez sur Commencer l'écoute. Ensuite, depuis n'importe quel ordinateur, publiez un message de test :

mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-test-x7m2 \
  -t "connectmq/demo/ha-x7m2/test" -m "hello from the terminal"

Le message apparaît dans Home Assistant en moins d'une seconde. Si ce n'est pas le cas, vérifiez que l'hôte de Home Assistant peut joindre le port 1883 en sortie ; certains réseaux le bloquent, auquel cas utilisez le port 8883 avec TLS.

Étape 3 : créer un capteur MQTT en YAML

Supposons qu'un ESP32 publie la température et l'humidité en JSON sur connectmq/demo/ha-x7m2/livingroom/climate :

{"temperature": 22.7, "humidity": 48.1, "battery": 87}

Ajoutez ceci à configuration.yaml (ou à un fichier inclus depuis celui-ci) :

mqtt:
  sensor:
    - name: "Living Room Temperature"
      unique_id: livingroom_temperature_x7m2
      state_topic: "connectmq/demo/ha-x7m2/livingroom/climate"
      value_template: "{{ value_json.temperature }}"
      unit_of_measurement: "°C"
      device_class: temperature
      state_class: measurement
      expire_after: 600

    - name: "Living Room Humidity"
      unique_id: livingroom_humidity_x7m2
      state_topic: "connectmq/demo/ha-x7m2/livingroom/climate"
      value_template: "{{ value_json.humidity }}"
      unit_of_measurement: "%"
      device_class: humidity
      state_class: measurement
      expire_after: 600

unique_id vous permet de renommer l'entité et de l'affecter à une pièce dans l'interface. expire_after marque le capteur comme indisponible si aucun message n'arrive pendant dix minutes, ce qui vous alerte d'une pile à plat. state_class: measurement active les statistiques à long terme.

Rechargez via Outils de développement > YAML > Entités MQTT configurées manuellement, puis simulez l'appareil :

mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-test-x7m2 \
  -t "connectmq/demo/ha-x7m2/livingroom/climate" \
  -m '{"temperature": 22.7, "humidity": 48.1, "battery": 87}'

Étape 4 : créer un interrupteur MQTT

Un interrupteur a besoin d'un topic de commande sur lequel Home Assistant publie et d'un topic d'état sur lequel l'appareil rend compte :

mqtt:
  switch:
    - name: "Desk Lamp"
      unique_id: desk_lamp_x7m2
      command_topic: "connectmq/demo/ha-x7m2/desk-lamp/set"
      state_topic: "connectmq/demo/ha-x7m2/desk-lamp/state"
      availability_topic: "connectmq/demo/ha-x7m2/desk-lamp/availability"
      payload_on: "ON"
      payload_off: "OFF"
      state_on: "ON"
      state_off: "OFF"
      qos: 1
      retain: false

Placez capteurs et interrupteurs sous une seule et même clé mqtt: dans votre configuration ; YAML n'autorise pas deux fois la même clé. Si vous n'avez pas encore de matériel, jouez vous-même le rôle de l'appareil :

# jouer le rôle de l'appareil : annoncer la disponibilité et signaler l'état
mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-dev-x7m2 -r \
  -t "connectmq/demo/ha-x7m2/desk-lamp/availability" -m "online"
mosquitto_pub -h broker.connectmq.com -p 1883 -i ha-dev-x7m2 -r \
  -t "connectmq/demo/ha-x7m2/desk-lamp/state" -m "OFF"

# observer les commandes envoyées par Home Assistant quand vous basculez l'interrupteur
mosquitto_sub -h broker.connectmq.com -p 1883 -i ha-dev2-x7m2 \
  -t "connectmq/demo/ha-x7m2/desk-lamp/set" -v

Lorsque vous basculez l'interrupteur dans le tableau de bord, ON apparaît dans le terminal. Publiez ON sur le topic d'état pour confirmer, et l'interrupteur reste allumé. Sans topic d'état, Home Assistant fait fonctionner l'interrupteur en mode optimiste et suppose simplement que la commande a abouti.

Pour les lumières avec variation, utilisez la plateforme light avec schema: json ; le format de payload correspond au variateur de notre tutoriel d'éclairage intelligent MQTT.

Étape 5 : un véritable appareil

Le véritable appareil le plus rapide à mettre en place est un ESP32 exécutant un court sketch, comme dans le tutoriel ESP32 MQTT, qui publie sur le même topic climatique. Les appareils ESPHome et Tasmota peuvent aussi publier via MQTT ; consultez ESPHome MQTT. Au lieu d'écrire du YAML pour chaque entité, ces appareils peuvent s'annoncer automatiquement grâce à la découverte MQTT de Home Assistant.

Étape 6 : passer à un broker privé avec TLS

Le serveur MQTT public gratuit est parfait pour la première heure de tests, mais tout ce qui y circule est lisible par tous, et n'importe qui peut publier sur le topic de commande de votre interrupteur. Les données de votre maison ont leur place sur un broker privé. Il y a aussi une raison pratique : ce serveur public autorise 10 abonnements par client, et Home Assistant s'abonne à un topic par entité plus les topics de découverte, si bien que vous atteignez vite la limite.

Inscrivez-vous sur le portail ConnectMQ, créez un broker et copiez le nom d'utilisateur, le mot de passe et le client ID générés.
Dans Home Assistant, ouvrez Paramètres > Appareils et services > MQTT, ouvrez le menu de l'entrée et choisissez Reconfigurer (ou Configurer puis Reconfigurer MQTT, selon votre version).
Définissez le port 8883, saisissez le nom d'utilisateur et le mot de passe, renseignez le client ID délivré et réglez la validation du certificat du broker sur Auto afin que le magasin de certificats du système valide le certificat Let's Encrypt.
Remplacez vos topics connectmq/demo/ha-x7m2/... par votre propre racine, par exemple home/livingroom/climate, à la fois dans les appareils et dans le YAML.

Le client ID doit correspondre exactement à celui délivré, car ConnectMQ associe les client IDs aux identifiants. Une erreur se traduit par des lignes répétées « connection refused, not authorized » dans le journal de Home Assistant.

Liste de dépannage

L'intégration ne se connecte pas. Testez les mêmes hôte, port et identifiants avec mosquitto_sub depuis une autre machine.
L'entité affiche « inconnu ». L'appareil n'a rien publié depuis le démarrage de Home Assistant. Publiez l'état avec le flag retain.
L'entité affiche « indisponible ». Soit expire_after est écoulé, soit le topic de disponibilité indique offline.
Erreurs de template dans le journal. Le payload n'est pas le JSON attendu ; écoutez le topic et comparez.
Deux brokers se disputent un appareil. Un appareil ne peut se connecter qu'à un seul broker à la fois ; choisissez-en un, ou reliez-les en pont.
Déconnexions toutes les quelques secondes. Deux clients utilisent le même client ID et s'éjectent mutuellement.

Faites tourner Home Assistant sur ConnectMQ

Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire. Jusqu'à 25 connexions couvrent une maison typique, et l'explorateur de topics en direct de ConnectMQ vous aide à déboguer les payloads sans quitter le navigateur. Si vous vous demandez comment un broker MQTT managé se compare à un Mosquitto que vous exploitez vous-même, la comparaison ci-dessus et le guide de l'automatisation IoT vous aideront à décider.

Questions fréquentes

Home Assistant inclut-il un broker MQTT ?

Non. L'intégration MQTT est un client. Vous installez soit le module complémentaire Mosquitto, soit vous vous connectez à un broker externe comme ConnectMQ.

Puis-je utiliser YAML et la découverte en même temps ?

Oui. Les entités définies en YAML et les entités découvertes coexistent dans la même intégration, tant que leurs unique IDs diffèrent.

Quel port Home Assistant doit-il utiliser pour un broker cloud ?

Utilisez le port 8883 avec TLS. Le port 1883 transmet identifiants et données sans chiffrement et ne doit servir que pour des données de test publiques.

Pourquoi mon interrupteur se rééteint-il tout seul ?

L'appareil publie OFF sur le topic d'état, ou un retained message OFF est rejoué. Vérifiez le topic d'état avec un abonné et supprimez les retained messages obsolètes.

Intégration MQTT de Home Assistant : guide de configuration complet