Home Assistant com Broker MQTT Externo: Conecte-se a um Broker na Nuvem via TLS

Usar o Home Assistant com um broker MQTT externo coloca o broker fora da sua casa, para que dispositivos em uma casa de praia, em uma oficina ou no apartamento de um parente conversem com o mesmo Home Assistant sem redirecionamento de portas nem VPN. Neste guia você vai conectar o Home Assistant a um broker na nuvem via TLS, organizar tópicos para vários locais e, como alternativa, fazer bridge do add-on Mosquitto local com a nuvem para que os dispositivos locais continuem funcionando quando a internet cair.

Por que Usar um Broker Externo

O add-on Mosquitto é a escolha padrão por um bom motivo: é local, rápido e simples. Ele fica inconveniente quando os dispositivos não estão na LAN da sua casa:

• Um sensor em um segundo imóvel precisa alcançar a sua rede doméstica, o que significa redirecionamento de portas, DNS dinâmico e expor um broker à internet, ou rodar uma VPN em hardware alimentado por bateria.
• Várias instâncias do Home Assistant (a sua, a dos seus pais) não conseguem compartilhar facilmente um mesmo conjunto de dispositivos.
• Outros aplicativos, como uma stack Grafana em um servidor ou um app móvel, precisam de um caminho próprio de entrada.

Um broker externo inverte a direção. Todo cliente, inclusive o Home Assistant, se conecta de saída ao mesmo broker MQTT na nuvem. Nada fica escutando dentro da sua casa, e todos os locais são iguais.

Escolha a conexão direta se a maioria dos dispositivos for remota ou se você preza pela simplicidade. Escolha a bridge se automações locais críticas (iluminação, aquecimento) dependerem de dispositivos MQTT dentro de casa.

Opção 1: Conectar o Home Assistant Diretamente ao Broker na Nuvem

Crie o broker e as credenciais

Cadastre-se no portal da ConnectMQ, crie um broker e anote o usuário, a senha e o client ID gerados. Crie credenciais separadas para o Home Assistant e para cada dispositivo remoto, assim você pode revogar uma sem mexer nas outras.

Antes de mexer no Home Assistant, teste as credenciais a partir de um computador:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u YOUR_USERNAME -P YOUR_PASSWORD -i YOUR_CLIENT_ID \
  -t "sites/#" -v

No macOS com Homebrew, substitua --capath /etc/ssl/certs por --cafile apontando para um bundle de CAs, por exemplo $(brew --prefix)/etc/ca-certificates/cert.pem. Se esse comando conectar e ficar aguardando em silêncio, as credenciais e o caminho TLS estão corretos.

Configure a integração

1. No seu perfil de usuário do Home Assistant, ative o Advanced mode. Sem ele, as opções de client ID e TLS ficam ocultas.
2. Vá em Settings > Devices & services > Add integration > MQTT (ou reconfigure sua entrada MQTT existente).
3. Informe:
   • Broker: broker.connectmq.com
   • Porta: 8883
   • Usuário / Senha: as credenciais do Home Assistant
   • Client ID: o client ID emitido, exatamente
   • Validação do certificado do broker: Auto
   • Transporte: TCP
   • Protocolo MQTT: 5 (ou 3.1.1; ambos são suportados)
4. Envie e verifique se a integração aparece como conectada.

A validação Auto usa o repositório de CAs do sistema, que confia no certificado Let's Encrypt apresentado pelo broker. Nunca escolha Off para uma conexão pela internet. Se a sua rede bloquear a porta 8883 de saída, mude o transporte para WebSockets com a porta 8084 e o caminho /mqtt; ele trafega como HTTPS, o que a maioria dos firewalls permite. Mais detalhes em MQTT sobre WebSocket.

Um dispositivo remoto

Um ESP32 remoto publica no mesmo broker com suas próprias credenciais:

#include <WiFi.h>
#include <WiFiClientSecure.h>
#include <PubSubClient.h>

WiFiClientSecure net;
PubSubClient mqtt(net);

void setup() {
  WiFi.begin("CABIN_WIFI", "CABIN_WIFI_PASSWORD");
  while (WiFi.status() != WL_CONNECTED) delay(250);
  net.setCACert(ISRG_ROOT_X1);   // raiz Let's Encrypt, string PEM definida em outro lugar
  mqtt.setServer("broker.connectmq.com", 8883);
}

void loop() {
  if (!mqtt.connected()) {
    if (mqtt.connect("YOUR_CLIENT_ID", "YOUR_USERNAME", "YOUR_PASSWORD",
                     "sites/cabin/boiler-room/availability", 1, true, "offline")) {
      mqtt.publish("sites/cabin/boiler-room/availability", "online", true);
    } else {
      delay(5000);
      return;
    }
  }
  mqtt.loop();
  static unsigned long last = 0;
  if (millis() - last > 60000) {
    last = millis();
    mqtt.publish("sites/cabin/boiler-room/climate", "{\"temperature\":6.4,\"humidity\":71}");
  }
}

O tutorial de ESP32 com MQTT mostra como embutir o certificado raiz. No Home Assistant, defina o sensor em YAML ou deixe o dispositivo se anunciar por meio do MQTT discovery do Home Assistant.

Design de Tópicos para Vários Locais

Com muitos locais em um único broker, coloque o local primeiro:

sites/<site>/<room>/<device>/<measurement-or-command>
sites/home/livingroom/climate
sites/cabin/boiler-room/climate
sites/cabin/boiler-room/availability
sites/workshop/compressor/power

Vantagens: um wildcard por local (sites/cabin/#), regras de bridge simples e propriedade clara no explorador de tópicos da ConnectMQ. Mantenha as configurações de discovery sob o prefixo padrão homeassistant/ e, se duas instâncias do Home Assistant compartilharem o broker, dê a cada uma o seu próprio prefixo de discovery para que uma não capture as entidades da outra.

Opção 2: Bridge do Add-on Mosquitto com a Nuvem

Uma bridge é uma conexão do seu Mosquitto local com o broker externo que encaminha tópicos selecionados em uma ou nas duas direções. O Home Assistant e os dispositivos locais continuam falando com o broker local, de modo que as automações sobrevivem a quedas de internet, enquanto os locais remotos aparecem pela bridge.

1. Na configuração do add-on Mosquitto, habilite a configuração personalizada:

customize:
  active: true
  folder: mosquitto

2. Crie /share/mosquitto/bridge.conf (por exemplo com o add-on File editor ou Samba):

connection connectmq
address broker.connectmq.com:8883
bridge_protocol_version mqttv311
remote_clientid YOUR_CLIENT_ID
remote_username YOUR_USERNAME
remote_password YOUR_PASSWORD
bridge_capath /etc/ssl/certs
bridge_insecure false
cleansession true
try_private false
notifications false
restart_timeout 10 60

# dados da casa local sobem, locais remotos descem
topic sites/home/# out 1
topic sites/cabin/# in 1
topic sites/workshop/# in 1

3. Reinicie o add-on e verifique no log uma linha informando que a bridge conectou.

try_private false é recomendado quando o lado remoto não é outra instância do Mosquitto. Se o add-on não encontrar o diretório de CAs na sua versão, baixe o PEM do ISRG Root X1 para /share/mosquitto/ e use bridge_cafile /share/mosquitto/isrgrootx1.pem no lugar. Nunca faça bridge de # nas duas direções; isso cria loops e duplicatas.

A bridge é um recurso padrão do Mosquitto que atua como um cliente MQTT comum do broker na nuvem, por isso funciona com qualquer broker MQTT gerenciado que aceite TLS e credenciais.

Monitorando a Conexão

Quando o Home Assistant passa a depender de um broker externo, torne os problemas de conexão visíveis. Dê a cada dispositivo remoto um tópico de disponibilidade com uma mensagem online retida e um last will offline, e use-o nas definições das entidades para que sensores remotos fiquem indisponíveis em vez de exibir valores desatualizados. Uma automação simples no Home Assistant que avisa quando a entidade de disponibilidade de um local remoto fica indisponível por dez minutos detecta quedas de energia e falhas de roteador no segundo imóvel. No lado do broker, o explorador de tópicos em tempo real mostra se um local continua publicando, e regras de alerta por limite podem vigiar valores críticos, como uma temperatura com risco de geada no chalé.

Checklist de Segurança

1. TLS em toda conexão pela internet (8883 ou 8084), nunca 1883 sem criptografia com credenciais reais.
2. Um conjunto de credenciais por local ou dispositivo; revogue em vez de trocar tudo.
3. Os client IDs precisam corresponder às credenciais emitidas; a ConnectMQ os vincula e bloqueia IPs após tentativas de login malsucedidas repetidas.
4. Não publique estados de fechaduras, códigos de alarme ou dados de presença no servidor MQTT público (gratuito) nem em outro broker aberto: ele serve para testes e protótipos; mantenha esses dados no seu broker privado.
5. Mantenha os tópicos de comando restritos e faça os dispositivos aceitarem apenas valores conhecidos.

Os princípios gerais estão em boas práticas de segurança MQTT.

Solução de Problemas

Conecte o Home Assistant à ConnectMQ

Crie um broker no plano Serverless (Free) em app.connectmq.com, sem cartão de crédito. O plano Serverless (Free) suporta até 25 conexões, o suficiente para o Home Assistant, uma bridge e um conjunto de dispositivos remotos, e você pode fazer upgrade depois sem mudar os tópicos. A ConnectMQ opera o broker, renova os certificados e isola o seu tráfego. Para mais projetos, veja o guia de automação com IoT e a configuração básica de MQTT no Home Assistant.

Perguntas frequentes

Minhas automações vão parar se a internet cair?

Com uma conexão direta à nuvem, as entidades MQTT param de atualizar até a conexão voltar. Se automações locais dependerem de dispositivos MQTT, use a bridge do Mosquitto para que o tráfego local nunca saia de casa.

Preciso abrir portas no meu roteador?

Não. O Home Assistant, a bridge e os dispositivos remotos se conectam todos de saída ao broker externo, então nenhuma porta de entrada é necessária.

Duas instâncias do Home Assistant podem compartilhar um broker externo?

Sim. Dê a cada instância suas próprias credenciais e seu próprio prefixo de discovery, e organize os tópicos por local para que cada instância assine apenas o que precisa.

Qual porta devo usar se a 8883 estiver bloqueada?

Use WebSocket seguro na porta 8084 com o caminho /mqtt, que o Home Assistant suporta pela opção de transporte WebSockets.