Configurar MQTT no Home Assistant: broker, integração e discovery

O MQTT é a forma como o Home Assistant conversa com uma enorme variedade de dispositivos: Zigbee2MQTT, Tasmota, ESPHome (opcionalmente), Shelly, Frigate, OpenMQTTGateway e incontáveis sensores DIY. A configuração exige três peças — um broker, a integração MQTT no Home Assistant e, de preferência, o MQTT discovery, para que os dispositivos apareçam automaticamente. Este tutorial cobre as três e mostra como testar tudo com um cliente MQTT.

Passo 1: escolha um broker — add-on do Mosquitto ou externo

O Home Assistant não contém um broker MQTT; a integração é um cliente. Você tem duas opções principais:

Opção A: o add-on Mosquitto broker

1. Vá em Settings → Add-ons → Add-on Store, procure por Mosquitto broker e instale-o.
2. Inicie-o e ative Start on boot e Watchdog.
3. Crie um usuário dedicado do Home Assistant para os seus dispositivos (Settings → People → Users, por exemplo mqtt-user). O add-on autentica com os usuários do Home Assistant, então os dispositivos usam essas credenciais. Não reutilize sua conta de administrador.
4. O Home Assistant agora mostra uma integração MQTT descoberta em Settings → Devices & services. Clique em Configure e confirme.

Os dispositivos da sua rede se conectam ao host do Home Assistant na porta 1883 (e na 8883, se você configurar TLS nas opções do add-on).

Opção B: um broker externo

No Home Assistant Container ou Core não existe loja de add-ons, então rode o Mosquitto ao lado dele — o jeito mais fácil é o Mosquitto no Docker, ou uma instalação por pacote como descrito em como instalar o Mosquitto. Lembre que o Mosquitto 2.x precisa de um listener explícito e de autenticação antes que outros hosts possam se conectar; o gerador de mosquitto.conf produz um arquivo funcional, e como proteger o Mosquitto cobre usuários e ACLs.

Passo 2: configure a integração MQTT

Para um broker externo, adicione a integração manualmente: Settings → Devices & services → Add integration → MQTT. Informe:

• Broker — hostname ou IP (em uma rede Docker compartilhada, o nome do container, como mosquitto)
• Port — 1883, ou 8883 para TLS (veja portas MQTT)
• Username / Password — um usuário do broker criado para o Home Assistant

As opções avançadas (ative-as pelo Advanced mode no seu perfil de usuário e depois use Configure → Re-configure MQTT) permitem definir certificados TLS, o client ID, a versão do protocolo (3.1, 3.1.1 ou 5), o prefixo de discovery e as mensagens de birth e will. Os dados de conexão do broker são configurados pela interface; eles não podem mais ser definidos no configuration.yaml.

Passo 3: MQTT discovery

Com o discovery, um dispositivo se anuncia publicando uma configuração JSON em um tópico conhecido, e o Home Assistant cria a entidade automaticamente — sem YAML. O formato do tópico é:

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

• discovery_prefix — homeassistant por padrão
• component — o tipo de entidade: sensor, binary_sensor, switch, light, cover, climate e assim por diante
• node_id — agrupamento opcional, geralmente o ID do dispositivo
• object_id — um ID para esta entidade (letras, dígitos, _ e -)

Aqui está um sensor de temperatura. Publique-o em homeassistant/sensor/garage_temp/config com a flag retain, para que o Home Assistant o encontre de novo após um restart:

{
  "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"
  }
}

O unique_id torna a entidade editável pela interface, e o bloco device agrupa as entidades sob um único dispositivo. O dispositivo então publica suas leituras no tópico de estado:

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

Mensagens retidas são essenciais aqui — leia mensagens retidas (retained) no MQTT se o conceito for novo para você. Switches e lights usam também um command_topic, no qual o Home Assistant publica quando você alterna a entidade.

Passo 4: teste com um cliente MQTT

Você pode simular o dispositivo inteiro a partir de um terminal com os clientes do Mosquitto (referência completa de flags na colinha de 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}'

A entidade aparece em Settings → Devices & services → MQTT. Para acompanhar tudo o que o Home Assistant e seus dispositivos trocam, assine o prefixo de discovery:

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

A página da integração MQTT no Home Assistant também tem as ferramentas embutidas Listen to a topic e Publish a packet. E, para praticar o formato de discovery sem mexer no broker da sua casa, publique o JSON acima em um tópico de teste de um broker público pelo navegador:

Teste no cliente MQTT online

Problemas comuns

• A integração não consegue conectar — credenciais erradas, ou o broker só escuta no localhost. Confira o log do broker e o guia de erros de conexão MQTT.
• Entidade some após um restart — a configuração não foi retida, ou o dispositivo não republica quando homeassistant/status = online.
• Entidade mostra "unknown" — o value_template não corresponde ao payload, ou nada foi publicado no tópico de estado ainda.
• Remover uma entidade — publique uma mensagem retida vazia no tópico de configuração dela (-r -n).

Perguntas frequentes