Automação MQTT no Home Assistant: Gatilhos, Templates e Ações de Publicação

Uma automação MQTT no Home Assistant reage a mensagens em um tópico do broker e pode publicar mensagens de volta, o que permite automatizar dispositivos e scripts que nunca aparecem como entidades. Neste tutorial você vai conectar o Home Assistant a um broker, escrever automações com gatilhos MQTT, filtrar por payloads JSON e tópicos com wildcard, publicar comandos com mqtt.publish e evitar os loops e condições de corrida que pegam a maioria das pessoas.

Entidades ou Tópicos Brutos?

O Home Assistant oferece duas formas de usar MQTT. A primeira são as entidades: sensores, interruptores e luzes MQTT definidos em YAML ou criados via discovery. As automações então usam gatilhos de estado comuns. A segunda é o gatilho MQTT, que dispara diretamente com uma mensagem, sem nenhuma entidade no meio.

As duas abordagens funcionam juntas. Uma configuração típica usa entidades para estados e gatilhos MQTT para eventos. Se você ainda não definiu entidades, comece com Home Assistant MQTT e o guia de MQTT discovery.

Conectando o Home Assistant ao Broker

Abra Settings > Devices & services > Add integration > MQTT e informe o broker. Para um teste, você pode usar o servidor MQTT público (gratuito) em broker.connectmq.com, que aceita conexões anônimas:

As opções avançadas só aparecem se o Advanced mode estiver ativado no seu perfil de usuário. O servidor MQTT público é compartilhado, serve para testes e protótipos e pode ser lido por qualquer pessoa, então use um prefixo único como connectmq/demo/k9p4z7/ e nunca envie nada sensível ali. O passo a passo completo de produção está em como conectar o Home Assistant a um broker MQTT externo.

Sua Primeira Automação MQTT no Home Assistant

A automação abaixo acende uma luz quando um botão sem fio publica pressed. Ela usa a sintaxe atual de automações (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

Teste a partir de um terminal:

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

O filtro payload compara a string bruta exatamente. Se o dispositivo envia JSON, use value_template para extrair um campo antes; o valor de payload passa então a ser comparado com o resultado do template.

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

Usando os Dados do Gatilho em Templates

Dentro da automação, a variável trigger carrega tudo sobre a mensagem: trigger.topic, trigger.payload, trigger.payload_json (se o payload puder ser interpretado como JSON), trigger.qos e trigger.retain. Isso transforma uma única automação em um tratador flexível.

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

O wildcard + corresponde a um nível, então uma automação cobre todos os canteiros. trigger.topic.split('/')[4] extrai o nome do canteiro de connectmq/demo/k9p4z7/garden/<bed>/alert. Usar float(100) dá um valor padrão seguro se o campo estiver ausente, de modo que uma mensagem malformada não gera erro. mode: queued garante que alertas de vários canteiros chegando ao mesmo tempo sejam todos processados. Para sensores de solo que publicam esse tipo de mensagem, veja o tutorial de sensor de umidade do solo com MQTT.

Publicando MQTT a partir de Automações

A ação mqtt.publish envia qualquer payload para qualquer tópico. Aqui, uma automação baseada em horário envia um comando de irrigação a um controlador de válvula, e uma mudança de estado publica um resumo de status:

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

Duas regras práticas. Comandos normalmente não devem ser retidos; caso contrário, um dispositivo que se reconectar amanhã vai reexecutar o comando de ontem. Estados que outros sistemas leem na inicialização devem ser retidos, para que um novo assinante receba o valor atual imediatamente. O QoS 1 compensa a viagem de ida e volta extra para comandos como esse, porque uma mensagem perdida significa um canteiro que continua seco.

Padrão de Solicitação e Confirmação

Para qualquer coisa que movimente água, calor ou portas, não presuma que um comando publicado deu certo. Espere o dispositivo confirmar:

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 é none quando o tempo limite expira, e é assim que a automação sabe que a válvula nunca respondeu.

Armadilhas Comuns

1. Loops de automação. Uma automação que publica em um tópico que também a dispara vai rodar para sempre. Mantenha os tópicos de comando (/set) e de estado (/state) separados.
2. Mensagens retidas disparando gatilhos. Quando o Home Assistant reinicia e assina novamente, as mensagens retidas são entregues outra vez e os gatilhos MQTT disparam. Adicione uma condição como {{ not trigger.retain }} se isso não for desejado.
3. Maiúsculas e espaços. payload: ON não corresponde a on nem a ON\n. Normalize com value_template: "{{ value | trim | lower }}".
4. Wildcard errado. # só é válido como último nível; + corresponde a exatamente um nível.
5. Erros silenciosos de template. Verifique Settings > System > Logs e o trace da automação; os traces mostram o payload do gatilho, que é a forma mais rápida de depurar.

Depurando com uma Visão de Tópicos ao Vivo

Antes de culpar a automação, confirme que a mensagem realmente chega. Settings > Devices & services > MQTT > Configure tem uma ferramenta de escuta que assina qualquer tópico. Fora do Home Assistant, um explorador MQTT para desktop ou o cliente web do broker mostram o mesmo tráfego. Observar o lado do broker é útil porque revela se o problema está no dispositivo, na conexão com o broker ou na automação.

Combinando Automações com Alertas no Broker

As automações do Home Assistant só rodam enquanto o Home Assistant está de pé. Se o Raspberry Pi que o hospeda perder energia, ninguém fica sabendo que a estufa está superaquecendo. Uma rede de segurança útil é um segundo caminho de alerta, independente, no broker. No portal da ConnectMQ você pode definir regras de alerta por limite em um tópico, por exemplo uma temperatura acima de 35, e ver os alertas disparados no log de alertas mesmo com o seu servidor doméstico fora do ar. Mantenha a lógica inteligente no Home Assistant e use as regras do broker apenas para alguns limites críticos.

O mesmo raciocínio vale para a lógica dos dispositivos. Um controlador de válvula deve se fechar sozinho após um tempo máximo de funcionamento, mesmo que o comando de fechar nunca chegue, porque uma automação que publica open e depois trava não pode inundar o jardim.

Indo para Produção

Automações que controlam água ou calor não devem depender do servidor MQTT público, onde qualquer pessoa pode publicar nos seus tópicos. Crie um broker privado, mude a integração MQTT para a porta 8883 com credenciais e troque os prefixos de tópico de connectmq/demo/... para os seus, como home/ ou site1/. Um broker MQTT gerenciado também permite que sensores remotos, uma casa de praia no litoral, um sítio no interior ou uma segunda instância do Home Assistant publiquem nos mesmos tópicos sem abrir portas no seu roteador. Para a arquitetura mais ampla de dispositivos, broker e lógica, leia o guia de automação com IoT.

Automatize o Home Assistant com a ConnectMQ

A ConnectMQ oferece um broker MQTT gerenciado e privado com TLS, credenciais geradas, um explorador de tópicos ao vivo e um cliente MQTT no navegador, para que você dispare mensagens de teste nas suas automações sem sair do navegador. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, e aponte a integração MQTT do Home Assistant para ele.

Perguntas frequentes

Um gatilho MQTT do Home Assistant pode usar wildcards?

Sim. Tanto + quanto # funcionam no tópico do gatilho, e trigger.topic informa qual tópico concreto correspondeu.

Como leio um campo JSON de um gatilho MQTT?

Use trigger.payload_json.field nos templates, ou value_template: "{{ value_json.field }}" no próprio gatilho para filtrar por esse campo.

Por que minha automação dispara quando o Home Assistant reinicia?

As mensagens retidas são entregues novamente ao reassinar. Verifique trigger.retain em uma condição, ou pare de publicar esse tópico com a flag retain se ele for, na verdade, um evento.

Os comandos mqtt.publish devem ser retidos?

Normalmente não. Comandos retidos são reenviados aos dispositivos quando eles se reconectam, o que pode abrir uma válvula ou acionar um relé muito tempo depois.