Automatisation Home Assistant MQTT : déclencheurs, templates et actions de publication

Une automatisation Home Assistant MQTT réagit aux messages d'un topic du broker et peut publier des messages en retour, ce qui vous permet d'automatiser, dans votre maison connectée, des appareils et des scripts qui n'apparaissent jamais comme entités. Dans ce tutoriel, vous allez connecter Home Assistant à un broker, écrire des automatisations avec des déclencheurs MQTT, filtrer sur des payloads JSON et des topics à wildcards, publier des commandes avec mqtt.publish, et éviter les boucles et les situations de concurrence qui piègent la plupart des utilisateurs.

Entités ou topics bruts ?

Home Assistant propose deux façons d'utiliser MQTT. La première passe par les entités : capteurs, interrupteurs et lumières MQTT définis en YAML ou créés par la découverte. Les automatisations utilisent alors des déclencheurs d'état ordinaires. La seconde est le déclencheur MQTT, qui se déclenche directement sur un message sans entité intermédiaire.

Les deux approches fonctionnent ensemble. Une configuration typique utilise des entités pour les états et des déclencheurs MQTT pour les événements. Si vous n'avez pas encore défini d'entités, commencez par Home Assistant MQTT et le guide de la découverte MQTT.

Connecter Home Assistant au broker

Ouvrez Paramètres > Appareils et services > Ajouter une intégration > MQTT et saisissez le broker. Pour un essai, vous pouvez utiliser le serveur MQTT public gratuit broker.connectmq.com, qui accepte les connexions anonymes :

Les options avancées n'apparaissent que si le Mode avancé est activé dans votre profil utilisateur. Le serveur MQTT public gratuit est partagé, lisible par tous et réservé aux tests : utilisez un préfixe unique comme connectmq/demo/k9p4z7/ et n'y envoyez jamais rien de sensible. La procédure complète de mise en production se trouve dans connecter Home Assistant à un broker MQTT externe.

Votre première automatisation Home Assistant MQTT

L'automatisation ci-dessous allume une lumière lorsqu'un bouton sans fil publie pressed. Elle utilise la syntaxe actuelle des automatisations (triggers:, trigger: mqtt, actions:).

alias: Greenhouse button turns on grow light
triggers:
  - trigger: mqtt
    topic: connectmq/demo/k9p4z7/greenhouse/button
    payload: pressed
actions:
  - action: light.turn_on
    target:
      entity_id: light.grow_light
mode: single

Testez-la depuis un terminal :

mosquitto_pub -h broker.connectmq.com -p 1883 -i btn-k9p4z7 \
  -t 'connectmq/demo/k9p4z7/greenhouse/button' -m 'pressed'

Le filtre payload compare la chaîne brute à l'identique. Si l'appareil envoie du JSON, utilisez d'abord value_template pour extraire un champ ; la valeur payload est alors comparée au résultat du template.

triggers:
  - trigger: mqtt
    topic: connectmq/demo/k9p4z7/greenhouse/button
    value_template: "{{ value_json.action }}"
    payload: double

Utiliser les données du déclencheur dans les templates

Dans l'automatisation, la variable trigger contient tout ce qui concerne le message : trigger.topic, trigger.payload, trigger.payload_json (si le payload est du JSON valide), trigger.qos et trigger.retain. Une seule automatisation devient ainsi un gestionnaire flexible.

alias: Notify on soil moisture alert
triggers:
  - trigger: mqtt
    topic: connectmq/demo/k9p4z7/garden/+/alert
conditions:
  - condition: template
    value_template: "{{ trigger.payload_json.moisture | float(100) < 25 }}"
actions:
  - action: notify.mobile_app_phone
    data:
      title: "Dry soil"
      message: >
        Bed {{ trigger.topic.split('/')[4] }} is at
        {{ trigger.payload_json.moisture }}% moisture.
mode: queued
max: 10

Le wildcard + correspond à un seul niveau : une automatisation couvre donc toutes les plates-bandes. trigger.topic.split('/')[4] extrait le nom de la plate-bande de connectmq/demo/k9p4z7/garden/<bed>/alert. Utiliser float(100) fournit une valeur par défaut sûre si le champ est absent, de sorte qu'un message mal formé ne lève pas d'erreur. mode: queued garantit que les alertes de plusieurs plates-bandes arrivant en même temps sont toutes traitées. Pour des capteurs de sol qui publient ce type de message, consultez le tutoriel capteur d'humidité du sol MQTT.

Publier en MQTT depuis les automatisations

L'action mqtt.publish envoie n'importe quel payload sur n'importe quel topic. Ici, une automatisation horaire envoie une commande d'arrosage à un contrôleur de vanne, et un changement d'état publie un résumé de statut :

alias: Morning watering command
triggers:
  - trigger: time
    at: "06:30:00"
conditions:
  - condition: numeric_state
    entity_id: sensor.rain_last_24h
    below: 2
actions:
  - action: mqtt.publish
    data:
      topic: connectmq/demo/k9p4z7/garden/valve/zone1/set
      payload: '{"state":"open","duration_s":600}'
      qos: 1
      retain: false
mode: single

alias: Publish alarm state for other systems
triggers:
  - trigger: state
    entity_id: alarm_control_panel.home
actions:
  - action: mqtt.publish
    data:
      topic: connectmq/demo/k9p4z7/home/alarm/state
      payload: "{{ trigger.to_state.state }}"
      retain: true

Deux règles empiriques. Les commandes ne doivent normalement pas être retained, sinon un appareil qui se reconnecte demain rejouera la commande d'hier. Les états que d'autres systèmes lisent au démarrage doivent être retained, afin qu'un nouvel abonné reçoive immédiatement la valeur courante. La QoS 1 vaut l'aller-retour supplémentaire pour ce type de commande, car un message perdu signifie une plate-bande qui reste sèche.

Le modèle demande et confirmation

Pour tout ce qui actionne de l'eau, du chauffage ou des portes, ne supposez pas qu'une commande publiée a abouti. Attendez la confirmation de l'appareil :

alias: Open zone 1 and verify
triggers:
  - trigger: state
    entity_id: input_boolean.water_zone1
    to: "on"
actions:
  - action: mqtt.publish
    data:
      topic: connectmq/demo/k9p4z7/garden/valve/zone1/set
      payload: open
  - wait_for_trigger:
      - trigger: mqtt
        topic: connectmq/demo/k9p4z7/garden/valve/zone1/state
        payload: open
    timeout: "00:00:15"
    continue_on_timeout: true
  - if:
      - condition: template
        value_template: "{{ wait.trigger is none }}"
    then:
      - action: notify.mobile_app_phone
        data:
          message: "Valve zone 1 did not confirm within 15 seconds."
mode: restart

wait.trigger vaut none lorsque le délai a expiré : c'est ainsi que l'automatisation sait que la vanne n'a jamais répondu.

Pièges courants

1. Boucles d'automatisation. Une automatisation qui publie sur un topic qui la déclenche aussi tournera indéfiniment. Séparez les topics de commande (/set) et les topics d'état (/state).
2. Retained messages qui déclenchent les automatisations. Lorsque Home Assistant redémarre et se réabonne, les retained messages sont de nouveau livrés et les déclencheurs MQTT se déclenchent. Ajoutez une condition comme {{ not trigger.retain }} si ce n'est pas souhaité.
3. Casse et espaces. payload: ON ne correspond ni à on ni à ON\n. Normalisez avec value_template: "{{ value | trim | lower }}".
4. Mauvais wildcard. # n'est valide qu'en dernier niveau ; + correspond à exactement un niveau.
5. Erreurs de template silencieuses. Consultez Paramètres > Système > Journaux et la trace de l'automatisation ; les traces affichent le payload du déclencheur, ce qui est le moyen le plus rapide de déboguer.

Déboguer avec une vue des topics en direct

Avant d'incriminer l'automatisation, vérifiez que le message arrive vraiment. Paramètres > Appareils et services > MQTT > Configurer propose un outil d'écoute qui s'abonne à n'importe quel topic. En dehors de Home Assistant, un explorateur MQTT de bureau ou le client web du broker montre le même trafic. Observer le côté broker est utile, car cela indique si le problème se situe dans l'appareil, la connexion au broker ou l'automatisation.

Combiner les automatisations avec des alertes côté broker

Les automatisations Home Assistant ne tournent que lorsque Home Assistant fonctionne. Si le Raspberry Pi qui l'héberge perd l'alimentation, personne n'est prévenu que la serre surchauffe. Un filet de sécurité utile consiste à ajouter un second chemin d'alerte indépendant au niveau du broker. Dans le portail ConnectMQ, vous pouvez définir des règles d'alerte à seuil sur un topic, par exemple une température supérieure à 35, et voir les alertes déclenchées dans le journal des alertes même lorsque votre serveur domestique est arrêté. Gardez la logique élaborée dans Home Assistant et réservez les règles côté broker à quelques limites critiques.

Le même raisonnement s'applique à la logique des appareils. Un contrôleur de vanne doit se refermer de lui-même après une durée maximale de fonctionnement, même si la commande de fermeture n'arrive jamais, car une automatisation qui publie open puis plante ne doit pas inonder le jardin.

Passer en production

Les automatisations qui commandent de l'eau ou du chauffage ne doivent pas dépendre du serveur MQTT public gratuit, où n'importe qui peut publier sur vos topics. Créez un broker privé, basculez l'intégration MQTT sur le port 8883 avec identifiants, et remplacez les préfixes de topics connectmq/demo/... par les vôtres, comme home/ ou site1/. Un broker MQTT managé permet aussi à des capteurs distants, à une maison de vacances ou à une seconde instance de Home Assistant de publier sur les mêmes topics sans ouvrir de ports sur votre routeur. Jeedom et Domoticz savent aussi communiquer en MQTT : ils peuvent se connecter au même broker. Pour l'architecture d'ensemble des appareils, du broker et de la logique, lisez le guide de l'automatisation IoT.

Automatisez Home Assistant avec ConnectMQ

ConnectMQ fournit un broker MQTT privé avec TLS, des identifiants générés, un explorateur de topics en direct et un client MQTT dans le navigateur, pour que vous puissiez envoyer des messages de test à vos automatisations sans quitter le navigateur. Créez un broker Serverless gratuit sur app.connectmq.com, sans carte bancaire, et pointez-y l'intégration MQTT de Home Assistant.

Questions fréquentes

Un déclencheur MQTT de Home Assistant peut-il utiliser des wildcards ?

Oui. + et # fonctionnent tous deux dans le topic du déclencheur, et trigger.topic vous indique quel topic concret a correspondu.

Comment lire un champ JSON depuis un déclencheur MQTT ?

Utilisez trigger.payload_json.field dans les templates, ou value_template: "{{ value_json.field }}" dans le déclencheur lui-même pour filtrer sur ce champ.

Pourquoi mon automatisation se déclenche-t-elle au redémarrage de Home Assistant ?

Les retained messages sont de nouveau livrés lors du réabonnement. Vérifiez trigger.retain dans une condition, ou cessez de publier ce topic avec le flag retain s'il s'agit réellement d'un événement.

Les commandes mqtt.publish doivent-elles être retained ?

Généralement non. Les commandes retained sont rejouées aux appareils lorsqu'ils se reconnectent, ce qui peut ouvrir une vanne ou commuter un relais bien après coup.