Automatizaciones MQTT en Home Assistant: triggers, plantillas y acciones de publicación

Una automatización MQTT de Home Assistant reacciona a los mensajes de un topic del broker y puede publicar mensajes de vuelta, lo que te permite automatizar dispositivos y scripts que nunca aparecen como entidades. En este tutorial conectarás Home Assistant a un broker, escribirás automatizaciones con triggers MQTT, filtrarás por payloads JSON y topics con wildcards, publicarás comandos con mqtt.publish y evitarás los bucles y las condiciones de carrera en los que cae la mayoría.

¿Entidades o topics en bruto?

Home Assistant ofrece dos formas de usar MQTT. La primera son las entidades: sensores, interruptores y luces MQTT definidos en YAML o creados mediante discovery. Las automatizaciones usan entonces triggers de estado normales. La segunda es el trigger MQTT, que se dispara directamente con un mensaje sin ninguna entidad de por medio.

Ambos enfoques funcionan juntos. Una configuración típica usa entidades para los estados y triggers MQTT para los eventos. Si todavía no has definido entidades, empieza por Home Assistant MQTT y la guía de MQTT discovery.

Conectar Home Assistant al broker

Abre Ajustes > Dispositivos y servicios > Añadir integración > MQTT e introduce el broker. Para una prueba puedes usar el servidor MQTT público gratuito en broker.connectmq.com, que acepta conexiones anónimas y está pensado para pruebas y prototipos, no para producción:

Las opciones avanzadas solo aparecen si el Modo avanzado está activado en tu perfil de usuario. El área pública de pruebas es compartida y cualquiera puede leerla, así que usa un prefijo único como connectmq/demo/k9p4z7/ y nunca envíes nada sensible allí. La guía completa de producción está en cómo conectar Home Assistant a un broker MQTT externo.

Tu primera automatización MQTT en Home Assistant

La siguiente automatización enciende una luz cuando un botón inalámbrico publica pressed. Usa la sintaxis actual de automatizaciones (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

Pruébala desde un terminal:

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

El filtro payload compara la cadena en bruto de forma exacta. Si el dispositivo envía JSON, usa value_template para extraer antes un campo; el valor de payload se compara entonces con el resultado de la plantilla.

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

Usar los datos del trigger en plantillas

Dentro de la automatización, la variable trigger contiene toda la información del mensaje: trigger.topic, trigger.payload, trigger.payload_json (si el payload se interpreta como JSON), trigger.qos y trigger.retain. Esto convierte una sola automatización en un manejador 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

El wildcard + coincide con un nivel, así que una sola automatización cubre todos los bancales. trigger.topic.split('/')[4] extrae el nombre del bancal de connectmq/demo/k9p4z7/garden/<bed>/alert. Usar float(100) da un valor por defecto seguro si falta el campo, de modo que un mensaje mal formado no provoca un error. mode: queued garantiza que se procesen todas las alertas de varios bancales que lleguen a la vez. Para sensores de suelo que publican este tipo de mensaje, consulta el tutorial de sensor de humedad del suelo con MQTT.

Publicar MQTT desde automatizaciones

La acción mqtt.publish envía cualquier payload a cualquier topic. Aquí, una automatización basada en la hora envía un comando de riego a un controlador de válvulas y un cambio de estado publica un resumen del estado:

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

Dos reglas prácticas. Normalmente los comandos no deben ser retenidos; de lo contrario, un dispositivo que se reconecte mañana volverá a ejecutar el comando de ayer. Los estados que otros sistemas leen al arrancar sí deben ser retenidos, para que un nuevo suscriptor reciba el valor actual de inmediato. QoS 1 compensa el viaje de ida y vuelta adicional en comandos como este, porque un mensaje perdido significa un bancal que se queda seco.

Patrón de petición y confirmación

Para todo lo que mueva agua, calor o puertas, no des por hecho que un comando publicado ha tenido éxito. Espera a que el dispositivo lo confirme:

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 vale none cuando ha expirado el tiempo de espera, y así es como la automatización sabe que la válvula nunca respondió.

Errores habituales

1. Bucles de automatización. Una automatización que publica en un topic que también la dispara se ejecutará indefinidamente. Mantén separados los topics de comandos (/set) y los de estado (/state).
2. Mensajes retenidos que disparan triggers. Cuando Home Assistant se reinicia y vuelve a suscribirse, los mensajes retenidos se entregan de nuevo y los triggers MQTT se disparan. Añade una condición como {{ not trigger.retain }} si no lo quieres.
3. Mayúsculas y espacios. payload: ON no coincide con on ni con ON\n. Normaliza con value_template: "{{ value | trim | lower }}".
4. Wildcard incorrecto. # solo es válido como último nivel; + coincide exactamente con un nivel.
5. Errores de plantilla silenciosos. Revisa Ajustes > Sistema > Registros y la traza de la automatización; las trazas muestran el payload del trigger, que es la forma más rápida de depurar.

Depurar con una vista de topics en vivo

Antes de culpar a la automatización, confirma que el mensaje llega realmente. Ajustes > Dispositivos y servicios > MQTT > Configurar tiene una herramienta de escucha que se suscribe a cualquier topic. Fuera de Home Assistant, un explorador MQTT de escritorio o el cliente web del broker muestran el mismo tráfico. Observar el lado del broker es útil porque te dice si el problema está en el dispositivo, en la conexión con el broker o en la automatización.

Combinar automatizaciones con alertas en el broker

Las automatizaciones de Home Assistant solo se ejecutan mientras Home Assistant está en marcha. Si la Raspberry Pi que lo aloja se queda sin alimentación, nadie se entera de que el invernadero se está sobrecalentando. Una red de seguridad útil es una segunda vía de alertas, independiente, en el broker. En el portal de ConnectMQ puedes definir reglas de alerta por umbral sobre un topic, por ejemplo una temperatura superior a 35, y ver las alertas disparadas en el registro de alertas aunque tu servidor doméstico esté caído. Mantén la lógica inteligente en Home Assistant y usa las reglas del broker solo para unos pocos límites críticos.

El mismo razonamiento se aplica a la lógica del dispositivo. Un controlador de válvulas debería cerrarse solo tras un tiempo máximo de funcionamiento aunque nunca llegue el comando de cierre, porque una automatización que publica open y luego falla no debe inundar el jardín.

Pasar a producción

Las automatizaciones que controlan agua o calor no deberían depender de un área pública de pruebas en la que cualquiera puede publicar en tus topics. Crea un broker privado, cambia la integración MQTT al puerto 8883 con credenciales y cambia los prefijos de topic de connectmq/demo/... a los tuyos, como home/ o site1/. Un broker MQTT gestionado también permite que sensores remotos, una casa de vacaciones o una segunda instancia de Home Assistant publiquen en los mismos topics sin abrir puertos en tu router. Para la arquitectura general de dispositivos, broker y lógica, lee la guía de automatización IoT.

Automatiza Home Assistant con ConnectMQ

ConnectMQ ofrece un broker MQTT privado con TLS, credenciales generadas, un explorador de topics en vivo y un cliente MQTT en el navegador, para que puedas lanzar mensajes de prueba a tus automatizaciones sin salir del navegador. Crea un broker Serverless gratuito en app.connectmq.com, sin tarjeta de crédito, y apunta a él la integración MQTT de Home Assistant.

Preguntas frecuentes

¿Un trigger MQTT de Home Assistant puede usar wildcards?

Sí. Tanto + como # funcionan en el topic del trigger, y trigger.topic te indica qué topic concreto coincidió.

¿Cómo leo un campo JSON desde un trigger MQTT?

Usa trigger.payload_json.field en las plantillas, o value_template: "{{ value_json.field }}" en el propio trigger para filtrar por ese campo.

¿Por qué mi automatización se dispara cuando Home Assistant se reinicia?

Los mensajes retenidos se vuelven a entregar al suscribirse de nuevo. Comprueba trigger.retain en una condición, o deja de publicar ese topic con el flag retain si en realidad es un evento.

¿Los comandos de mqtt.publish deben ser retenidos?

Normalmente no. Los comandos retenidos se vuelven a enviar a los dispositivos cuando se reconectan, lo que puede abrir una válvula o activar un relé mucho después de lo previsto.