Home Assistant MQTT: Guia Completo de Configuração

O suporte a MQTT do Home Assistant permite trazer para a sua casa inteligente qualquer dispositivo que fale MQTT: sensores ESP32 caseiros, tomadas Tasmota, redes Zigbee2MQTT e até gateways industriais. Neste guia você vai configurar a integração MQTT do Home Assistant, criar sensores e interruptores em YAML, testar tudo com o servidor MQTT público (gratuito) em broker.connectmq.com e, em seguida, migrar para um broker privado da ConnectMQ com TLS.

Como o Home Assistant usa o MQTT

O Home Assistant não é um broker MQTT. Sua integração MQTT é um cliente que se conecta a um broker, assina tópicos de estado e publica em tópicos de comando. Os dispositivos são clientes do mesmo broker. O broker fica no meio e roteia as mensagens, como explicamos em detalhes em o que faz um broker MQTT.

Isso oferece duas opções de hospedagem:

Opção	Onde o broker roda	Indicado para	Contrapartidas
Add-on Mosquitto	No próprio host do Home Assistant	Uma única casa, todos os dispositivos na LAN	Dispositivos remotos exigem redirecionamento de porta ou VPN; você cuida dos backups
Broker na nuvem	Hospedado, acessado via TLS	Dispositivos em vários locais, sensores remotos, compartilhamento de dados com outros apps	Exige internet; escolha um provedor confiável
Ambos, em bridge	Mosquitto local em bridge com um broker na nuvem	Resiliência local e acesso remoto	Mais configuração

Este tutorial usa um broker na nuvem porque ele funciona da mesma forma, seja o Home Assistant rodando em um Raspberry Pi, um NUC ou uma máquina virtual. Se quiser entender o raciocínio completo e a opção com bridge, leia como usar um broker MQTT externo com o Home Assistant.

Passo 1: Adicione a integração MQTT

Abra Settings > Devices & services.
Clique em Add integration e pesquise por MQTT.
Escolha MQTT (não um add-on) e informe os dados do broker:
- Broker: broker.connectmq.com
- Porta: 1883
- Usuário e senha: deixe em branco para o broker público de testes
Envie. O Home Assistant se conecta e cria a entrada da integração MQTT.

Para definir o client ID, o TLS ou a versão do protocolo, ative primeiro o Advanced mode no seu perfil de usuário. A caixa de configuração da integração passa a mostrar campos extras, como client ID, keep alive, validação do certificado do broker, transporte (TCP ou WebSockets) e versão do protocolo MQTT. Você vai precisar deles no Passo 6.

O servidor MQTT público exige um client ID não vazio. O Home Assistant gera um aleatório automaticamente quando o campo fica em branco, o que é suficiente para testes.

Passo 2: Verifique a conexão

Abra Settings > Devices & services > MQTT > Configure. Essa página tem um formulário Publish a packet e outro Listen to a topic.

Em Listen to a topic, digite connectmq/demo/ha-x7m2/# e clique em Start listening. Depois, de qualquer computador, publique uma mensagem de teste:

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

A mensagem aparece no Home Assistant em menos de um segundo. Se não aparecer, verifique se o host do Home Assistant consegue acessar a porta 1883 de saída; algumas redes a bloqueiam e, nesse caso, use a 8883 com TLS.

Passo 3: Crie um sensor MQTT em YAML

Suponha que um ESP32 publique temperatura e umidade em JSON no tópico connectmq/demo/ha-x7m2/livingroom/climate:

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

Adicione isto ao configuration.yaml (ou a um arquivo incluído a partir dele):

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

O unique_id permite renomear a entidade e atribuí-la a uma área pela interface. O expire_after marca o sensor como indisponível se nenhuma mensagem chegar em dez minutos, e é assim que você percebe uma bateria descarregada. O state_class: measurement habilita as estatísticas de longo prazo.

Recarregue em Developer tools > YAML > Manually configured MQTT entities e então simule o dispositivo:

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}'

Passo 4: Crie um interruptor MQTT

Um interruptor precisa de um tópico de comando, no qual o Home Assistant publica, e de um tópico de estado, no qual o dispositivo informa sua situação:

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

Coloque sensores e interruptores sob uma única chave mqtt: na sua configuração; o YAML não permite repetir a chave. Se ainda não tiver hardware, faça você mesmo o papel do dispositivo:

# atue como o dispositivo: anuncie a disponibilidade e informe o estado
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"

# observe os comandos que o Home Assistant envia ao acionar o interruptor
mosquitto_sub -h broker.connectmq.com -p 1883 -i ha-dev2-x7m2 \
  -t "connectmq/demo/ha-x7m2/desk-lamp/set" -v

Ao alternar o interruptor no painel, ON aparece no terminal. Publique ON no tópico de estado para confirmar, e o interruptor permanece ligado. Sem um tópico de estado, o Home Assistant opera o interruptor em modo otimista e simplesmente presume que o comando funcionou.

Para lâmpadas com brilho ajustável, use a plataforma light com schema: json; o formato do payload é o mesmo do dimmer do nosso tutorial de iluminação inteligente com MQTT.

Passo 5: Um dispositivo real

O dispositivo real mais rápido de montar é um ESP32 rodando um sketch curto, como no tutorial de ESP32 com MQTT, publicando no mesmo tópico de clima. Dispositivos ESPHome e Tasmota também podem publicar via MQTT; veja ESPHome MQTT. Em vez de escrever YAML para cada entidade, esses dispositivos podem se anunciar automaticamente por meio do MQTT discovery do Home Assistant.

Passo 6: Migre para um broker privado com TLS

O servidor MQTT público é perfeito para a primeira hora, mas tudo o que passa por ele pode ser lido por qualquer pessoa, e qualquer um pode publicar no tópico de comando do seu interruptor. Os dados da sua casa devem ficar em um broker privado. Há também um motivo prático: o servidor MQTT público permite 10 assinaturas por cliente, e o Home Assistant assina um tópico por entidade, além dos tópicos de discovery, então você atinge o limite rapidamente.

Cadastre-se no portal da ConnectMQ, crie um broker e copie o usuário, a senha e o client ID gerados.
No Home Assistant, abra Settings > Devices & services > MQTT, abra o menu da entrada e escolha Reconfigure (ou Configure e depois Re-configure MQTT, dependendo da versão).
Defina a porta 8883, informe usuário e senha, defina o client ID com o valor emitido e ajuste a validação do certificado do broker para Auto, para que o repositório de CAs do sistema valide o certificado Let's Encrypt.
Troque seus tópicos de connectmq/demo/ha-x7m2/... para uma raiz própria, por exemplo home/livingroom/climate, tanto nos dispositivos quanto no YAML.

O client ID precisa coincidir exatamente com o emitido, porque a ConnectMQ vincula os client IDs às credenciais. Uma divergência aparece como linhas repetidas de "connection refused, not authorized" no log do Home Assistant.

Checklist de solução de problemas

A integração não conecta. Teste o mesmo host, porta e credenciais com mosquitto_sub a partir de outra máquina.
A entidade aparece como unknown. O dispositivo não publicou nada desde que o Home Assistant iniciou. Publique o estado com a flag retain.
A entidade aparece como unavailable. Ou o expire_after expirou, ou o tópico de disponibilidade informa offline.
Erros de template no log. O payload não é o JSON esperado; escute o tópico e compare.
Dois brokers disputam o mesmo dispositivo. Um dispositivo só se conecta a um broker por vez; escolha um ou faça uma bridge entre eles.
Desconexões a cada poucos segundos. Dois clientes usam o mesmo client ID e derrubam um ao outro.

Rode o Home Assistant na ConnectMQ

Crie um broker no plano Serverless (Free) em app.connectmq.com, sem cartão de crédito. Até 25 conexões atendem uma casa típica, e o explorador de tópicos ao vivo da ConnectMQ ajuda você a depurar payloads sem sair do navegador. Se estiver em dúvida sobre como um broker MQTT gerenciado se compara a rodar o Mosquitto por conta própria, a comparação acima e o guia de automação IoT vão ajudar você a decidir.

Perguntas frequentes

O Home Assistant inclui um broker MQTT?

Não. A integração MQTT é um cliente. Você instala o add-on Mosquitto ou se conecta a um broker externo, como a ConnectMQ.

Posso usar YAML e discovery ao mesmo tempo?

Sim. Entidades definidas em YAML e entidades descobertas convivem na mesma integração, desde que seus unique IDs sejam diferentes.

Qual porta o Home Assistant deve usar com um broker na nuvem?

Use a 8883 com TLS. A porta 1883 envia credenciais e dados sem criptografia e só deve ser usada para dados públicos de teste.

Por que meu interruptor desliga sozinho?

O dispositivo publica OFF no tópico de estado, ou uma mensagem OFF retida está sendo reenviada. Verifique o tópico de estado com um assinante e limpe mensagens retidas obsoletas.

Integração MQTT no Home Assistant: Guia Completo de Configuração