Configurer MQTT dans Home Assistant : broker, intégration et découverte

MQTT est le moyen par lequel Home Assistant dialogue avec une très large gamme d’appareils : Zigbee2MQTT, Tasmota, ESPHome (en option), Shelly, Frigate, OpenMQTTGateway et d’innombrables capteurs faits maison. La mise en place repose sur trois éléments — un broker, l’intégration MQTT de Home Assistant et, idéalement, la découverte MQTT (MQTT discovery) pour que les appareils apparaissent automatiquement. Ce tutoriel couvre les trois et montre comment tester la configuration avec un client MQTT.

Étape 1 : choisir un broker — add-on Mosquitto ou broker externe

Home Assistant ne contient pas lui-même de broker MQTT ; l’intégration est un client. Vous avez deux options principales :

Option A : l’add-on Mosquitto broker

1. Allez dans Paramètres → Modules complémentaires → Boutique des modules complémentaires, cherchez Mosquitto broker et installez-le.
2. Démarrez-le et activez Démarrage au boot (Start on boot) ainsi que Watchdog.
3. Créez un utilisateur Home Assistant dédié à vos appareils (Paramètres → Personnes → Utilisateurs, par ex. mqtt-user). L’add-on authentifie les clients avec les utilisateurs Home Assistant : les appareils utilisent donc ces identifiants. Ne réutilisez pas votre compte administrateur.
4. Home Assistant affiche alors une intégration MQTT découverte dans Paramètres → Appareils et services. Cliquez sur Configurer et confirmez.

Les appareils de votre réseau se connectent à l’hôte Home Assistant sur le port 1883 (et 8883 si vous configurez TLS dans les options de l’add-on).

Option B : un broker externe

Sur Home Assistant Container ou Core, il n’y a pas de boutique de modules complémentaires : faites donc tourner Mosquitto à côté — le plus simple est Mosquitto dans Docker, ou une installation par paquet comme décrit dans comment installer Mosquitto. N’oubliez pas que Mosquitto 2.x exige un listener explicite et une authentification avant que d’autres hôtes puissent se connecter ; le générateur de mosquitto.conf produit un fichier fonctionnel, et sécuriser Mosquitto couvre les utilisateurs et les ACL.

Étape 2 : configurer l’intégration MQTT

Pour un broker externe, ajoutez l’intégration manuellement : Paramètres → Appareils et services → Ajouter une intégration → MQTT. Renseignez :

• Broker — nom d’hôte ou IP (dans un réseau Docker partagé, le nom du conteneur, comme mosquitto)
• Port — 1883, ou 8883 pour TLS (voir les ports MQTT)
• Nom d’utilisateur / mot de passe — un utilisateur du broker créé pour Home Assistant

Les options avancées (activez le mode avancé dans votre profil utilisateur, puis Configurer → Reconfigurer MQTT) permettent de définir les certificats TLS, le client ID, la version du protocole (3.1, 3.1.1 ou 5), le préfixe de découverte ainsi que les messages de naissance (birth) et de testament (will). Les paramètres de connexion au broker se configurent dans l’interface ; ils ne peuvent plus être définis dans configuration.yaml.

Étape 3 : la découverte MQTT

Avec la découverte, un appareil s’annonce en publiant une configuration JSON sur un topic bien connu, et Home Assistant crée l’entité automatiquement — sans YAML. Le format du topic est :

<discovery_prefix>/<component>/[<node_id>/]<object_id>/config

• discovery_prefix — homeassistant par défaut
• component — le type d’entité : sensor, binary_sensor, switch, light, cover, climate, etc.
• node_id — regroupement facultatif, généralement l’ID de l’appareil
• object_id — un identifiant pour cette entité (lettres, chiffres, _ et -)

Voici un capteur de température. Publiez-le sur homeassistant/sensor/garage_temp/config avec le flag retain, pour que Home Assistant le retrouve après un redémarrage :

{
  "name": "Garage temperature",
  "unique_id": "garage_env_temp",
  "state_topic": "garage/env/state",
  "value_template": "{{ value_json.temperature }}",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "state_class": "measurement",
  "device": {
    "identifiers": ["garage_env_01"],
    "name": "Garage environment sensor",
    "manufacturer": "DIY",
    "model": "ESP32 + BME280"
  }
}

unique_id rend l’entité modifiable dans l’interface, et le bloc device regroupe les entités sous un même appareil. L’appareil publie ensuite ses mesures sur le topic d’état :

{ "temperature": 21.4, "humidity": 48 }

Les messages retenus sont essentiels ici — lisez les messages retenus MQTT si la notion est nouvelle pour vous. Les interrupteurs et les lumières utilisent en plus un command_topic sur lequel Home Assistant publie lorsque vous basculez l’entité.

Étape 4 : tester avec un client MQTT

Vous pouvez simuler tout l’appareil depuis un terminal avec les clients Mosquitto (référence complète des options dans l’aide-mémoire mosquitto_pub/sub) :

BROKER=homeassistant.local
AUTH="-u mqtt-user -P your-password"

mosquitto_pub -h $BROKER $AUTH -r -t 'homeassistant/sensor/garage_temp/config' -m '{
  "name": "Garage temperature",
  "unique_id": "garage_env_temp",
  "state_topic": "garage/env/state",
  "value_template": "{{ value_json.temperature }}",
  "unit_of_measurement": "°C",
  "device_class": "temperature",
  "device": { "identifiers": ["garage_env_01"], "name": "Garage environment sensor" }
}'

mosquitto_pub -h $BROKER $AUTH -t 'garage/env/state' -m '{"temperature": 21.4, "humidity": 48}'

L’entité apparaît dans Paramètres → Appareils et services → MQTT. Pour observer tout ce qu’échangent Home Assistant et vos appareils, abonnez-vous au préfixe de découverte :

mosquitto_sub -h homeassistant.local -u mqtt-user -P your-password -t 'homeassistant/#' -v

La page de l’intégration MQTT dans Home Assistant propose aussi des outils intégrés pour écouter un topic et publier un paquet. Et pour vous exercer au format de découverte sans toucher à votre broker domestique, publiez le JSON ci-dessus sur un topic de test d’un broker public, dans le navigateur :

Essayez-le dans le client MQTT en ligne

Problèmes courants

• L’intégration ne parvient pas à se connecter — identifiants erronés, ou le broker n’écoute que sur localhost. Consultez le journal du broker et le guide des erreurs de connexion MQTT.
• Entité absente après un redémarrage — la configuration n’était pas retenue, ou l’appareil ne republie pas lorsque homeassistant/status = online.
• L’entité affiche « inconnu » — le value_template ne correspond pas au payload, ou rien n’a encore été publié sur le topic d’état.
• Supprimer une entité — publiez un message retenu vide sur son topic de configuration (-r -n).

Questions fréquentes