Zigbee2MQTT com Broker na Nuvem: Controle Dispositivos Zigbee de Qualquer Lugar via TLS

Usar o Zigbee2MQTT com um broker na nuvem permite ler sensores e acionar dispositivos Zigbee de qualquer lugar, sem redirecionamento de portas nem VPN na rede de casa. Neste guia você vai apontar uma instalação existente do Zigbee2MQTT para um broker protegido por TLS na porta 8883, testar primeiro no servidor MQTT público e depois migrar para credenciais privadas no uso diário.

Por que usar um broker na nuvem com o Zigbee2MQTT?

A maioria das instalações do Zigbee2MQTT conversa com um contêiner Mosquitto no mesmo Raspberry Pi. Isso funciona bem até você querer que algo fora de casa veja os dados: um app no celular usando dados móveis, um painel no escritório, um segundo local, como uma casa de veraneio, ou um serviço de backend que registra o consumo de energia. Expor um broker local à internet significa redirecionamento de portas, DNS dinâmico e certificados, e cada um desses itens é uma nova chance de errar.

Um broker na nuvem inverte o sentido da conexão. O Zigbee2MQTT abre uma conexão TLS de saída até o broker, exatamente como um navegador abrindo um site, então nada precisa mudar no seu roteador. Qualquer cliente autorizado, em qualquer lugar, pode então assinar os mesmos tópicos. Se o papel do broker nesse cenário é novo para você, a explicação curta sobre o que faz um broker MQTT é uma boa introdução.

A contrapartida é clara: os estados dos seus dispositivos passam agora por um serviço na internet, então criptografia e credenciais privadas não são opcionais. O restante deste guia as trata como padrão.

O que você precisa

• Uma instalação funcional do Zigbee2MQTT (1.x ou 2.x) com um coordenador pareado. Se estiver começando do zero, siga primeiro o guia de configuração do Zigbee2MQTT e volte aqui.
• Acesso ao configuration.yaml do Zigbee2MQTT (na pasta data ou na página de configuração do add-on no Home Assistant).
• Para testes: nada mais, porque o servidor MQTT público aceita conexões anônimas.
• Para produção: um broker com usuário, senha e client ID próprios, por exemplo um broker ConnectMQ criado pelo portal.

Passo 1: Teste no servidor MQTT público

Antes de mexer com credenciais, comprove que o Zigbee2MQTT consegue acessar a internet e publicar via TLS. O servidor MQTT público (gratuito) em broker.connectmq.com aceita clientes anônimos com qualquer client ID único e não vazio. Tudo o que é publicado ali pode ser lido por qualquer pessoa, então use um prefixo de tópico aleatório e apenas dispositivos de teste inofensivos, nunca dados de produção.

Edite a seção mqtt do configuration.yaml:

mqtt:
  base_topic: connectmq/demo/z2m-7f3k9q/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  client_id: z2m-7f3k9q
  version: 5
  keepalive: 60
  reject_unauthorized: true

Algumas observações sobre esses valores:

• mqtts:// e a porta 8883 ativam o TLS. O broker usa um certificado Let's Encrypt, no qual o Node.js já confia, então você não precisa de uma entrada ca.
• O base_topic com o seu ID aleatório mantém suas mensagens separadas das de todo mundo. O Zigbee2MQTT acrescenta o friendly name do dispositivo e sufixos como /set, então o tópico completo aqui tem seis níveis, dentro do limite de oito do servidor MQTT público.
• version: 5 seleciona o MQTT 5. A versão 4 (MQTT 3.1.1) também funciona.
• reject_unauthorized: true é o padrão; mantenha-o ativado. Desativá-lo aceita qualquer certificado e anula o propósito do TLS.

Reinicie o Zigbee2MQTT e procure no log uma linha semelhante a Connected to MQTT server. Depois, assine de qualquer máquina:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i watcher-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/#' -v

Você deve ver bridge/state, bridge/info, bridge/devices e um tópico por dispositivo. Acione uma lâmpada do outro lado:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -i sender-7f3k9q -t 'connectmq/demo/z2m-7f3k9q/zigbee2mqtt/living_lamp/set' \
  -m '{"state":"TOGGLE"}'

No Windows ou no macOS, substitua --capath /etc/ssl/certs por --cafile apontando para um pacote de CAs que contenha o ISRG Root X1.

Limites do servidor MQTT público a considerar

A área pública permite 64 KB por mensagem e 10 mensagens por segundo por cliente. Uma rede Zigbee grande pode atingir os dois: bridge/devices lista cada dispositivo com sua definição completa e pode passar de 64 KB em uma malha grande, e uma rajada de relatórios de sensores pode exceder o limite de taxa. Em um teste com poucos dispositivos isso não é problema, mas é mais um motivo para migrar para um broker privado na instalação definitiva.

Passo 2: Migre para um broker privado na nuvem

Quando o teste funcionar, crie um broker privado. Na ConnectMQ você escolhe um plano, cria um broker e recebe usuário, senha e client ID gerados. Os client IDs são vinculados às credenciais emitidas, então use exatamente o client ID do portal.

Mantenha os segredos fora do arquivo principal com a sintaxe !secret do Zigbee2MQTT. Crie um secret.yaml ao lado do configuration.yaml:

mqtt_user: YOUR_USERNAME
mqtt_password: YOUR_PASSWORD
mqtt_client_id: YOUR_CLIENT_ID

E referencie-o:

mqtt:
  base_topic: home/zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  user: '!secret mqtt_user'
  password: '!secret mqtt_password'
  client_id: '!secret mqtt_client_id'
  version: 5
  keepalive: 60
  reject_unauthorized: true
  include_device_information: false

frontend:
  enabled: true
  port: 8080

advanced:
  last_seen: ISO_8601

Substitua o host pelo exibido para o seu broker no portal, se for diferente. Reinicie e confirme a conexão no log e no explorador de tópicos ao vivo do portal, onde home/zigbee2mqtt/bridge/state deve aparecer assim que o Zigbee2MQTT iniciar.

O last_seen adiciona um timestamp a cada mensagem de dispositivo, o que facilita muito identificar um sensor que ficou mudo quando você olha os dados remotamente. Deixe include_device_information desativado, a menos que algum consumidor precise dele, porque ele adiciona um bloco de metadados a cada payload.

Passo 3: Controle dispositivos Zigbee remotamente

Com o Zigbee2MQTT em um broker na nuvem, qualquer cliente MQTT com credenciais pode agir sobre seus dispositivos. O contrato de tópicos é o mesmo de um broker local:

O tópico bridge/state é retido e definido como Last Will, para que um painel remoto consiga distinguir "a lâmpada está desligada" de "o gateway Zigbee inteiro está offline". Use isso na sua interface em vez de confiar para sempre no último estado do dispositivo.

Um controlador remoto mínimo em Python, usando paho-mqtt 2.x, fica assim:

import json
import paho.mqtt.client as mqtt

BASE = "home/zigbee2mqtt"

def on_connect(client, userdata, flags, reason_code, properties):
    print("connected:", reason_code)
    client.subscribe(f"{BASE}/bridge/state")
    client.subscribe(f"{BASE}/living_lamp")
    client.publish(f"{BASE}/living_lamp/set", json.dumps({"state": "ON", "brightness": 120}))

def on_message(client, userdata, msg):
    print(msg.topic, msg.payload.decode())

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2, client_id="YOUR_CLIENT_ID")
client.username_pw_set("YOUR_USERNAME", "YOUR_PASSWORD")
client.tls_set()
client.on_connect = on_connect
client.on_message = on_message
client.connect("broker.connectmq.com", 8883, keepalive=60)
client.loop_forever()

Observe que este script precisa do seu próprio client ID. Rodá-lo com o mesmo ID do Zigbee2MQTT desconectaria o gateway toda vez que o script se conectasse, porque um broker permite apenas uma sessão por client ID. Dê a cada aplicação suas próprias credenciais.

Home Assistant e outros consumidores

Se o Home Assistant precisar descobrir os dispositivos Zigbee, ative homeassistant: enabled: true no Zigbee2MQTT e aponte a integração MQTT do Home Assistant para o mesmo broker e credenciais. A versão passo a passo, incluindo as configurações de TLS na interface do Home Assistant, está no guia sobre como usar o Home Assistant com um broker MQTT externo. As mensagens de discovery são retidas, então chegam mesmo que o Home Assistant inicie depois do Zigbee2MQTT.

Outros sistemas se integram da mesma forma: Node-RED, Telegraf ou um pequeno script se conecta como cliente MQTT, assina home/zigbee2mqtt/# e grava no armazenamento que você usa. O broker em si apenas roteia mensagens, o que mantém a arquitetura simples e substituível.

Checklist de solução de problemas

1. Connection refused: Not authorized - verifique usuário e senha, e se o client_id coincide exatamente com o emitido para essas credenciais.
2. O gateway reconecta a cada poucos segundos - outro cliente está usando o mesmo client ID. Procure nos seus scripts, fluxos do Node-RED e contêineres antigos.
3. self signed certificate ou unable to verify - você está atrás de um proxy que intercepta TLS ou o relógio do sistema está errado. Corrija o relógio (comum em um Pi sem sincronização de horário) antes de qualquer outra coisa.
4. Nada chega ao assinante - confirme que o base_topic está escrito de forma idêntica nos dois lados; tópicos MQTT diferenciam maiúsculas de minúsculas.
5. bridge/devices ausente no servidor MQTT público - a mensagem provavelmente é maior que o limite público de 64 KB. Teste com menos dispositivos ou migre para um broker privado, onde o plano Free permite 256 KB.
6. Limite de conexões atingido - cada instância do Zigbee2MQTT, painel e script conta como uma conexão. O plano Free permite até 25.

Para uma revisão mais ampla de TLS, credenciais e projeto de tópicos, veja o guia de boas práticas de segurança MQTT.

Escolhendo um broker MQTT gerenciado para o Zigbee2MQTT

O Zigbee2MQTT não exige muito de um broker: MQTT 3.1.1 ou 5, TLS, mensagens retidas e Last Will. O que importa mais em uma instalação remota é que o broker seja acessível, criptografado e isolado de outros clientes. Um broker MQTT gerenciado como a ConnectMQ cuida de certificados, disponibilidade e atualizações, para que o seu Raspberry Pi só precise rodar o Zigbee2MQTT. Os brokers Serverless gratuitos suportam QoS 0 e 1, o que cobre a publicação padrão em QoS 0 do Zigbee2MQTT sem alterações. Para uma visão mais ampla das opções de hospedagem, leia o guia de broker MQTT na nuvem e, para mais projetos de automação sobre o mesmo broker, explore o guia de automação IoT.

Coloque sua rede Zigbee na ConnectMQ

Crie um broker Serverless gratuito em app.connectmq.com (sem cartão de crédito), cole as credenciais geradas no secret.yaml e veja seus dispositivos Zigbee aparecerem no explorador de tópicos ao vivo em até um minuto após reiniciar o Zigbee2MQTT.

Perguntas frequentes

O Zigbee2MQTT pode se conectar a um broker na nuvem via TLS?

Sim. Defina server como mqtts://host:8883 na seção mqtt do configuration.yaml. Para brokers que usam certificados publicamente confiáveis, como os do Let's Encrypt, nenhum arquivo de CA extra é necessário.

É seguro usar um servidor MQTT público com o Zigbee2MQTT?

Apenas para testes curtos com dispositivos inofensivos. Qualquer pessoa pode ler e publicar em tópicos de um servidor MQTT público, então uma fechadura ou um alarme nunca devem ser conectados assim; use credenciais privadas para qualquer coisa real.

Ainda preciso de um broker Mosquitto local?

Não. O Zigbee2MQTT pode publicar diretamente no broker na nuvem. Algumas pessoas mantêm um broker local para automações apenas locais, que precisam funcionar durante uma queda de internet, o que é uma escolha de projeto válida.

Por que meu gateway Zigbee2MQTT desconecta quando abro outro app?

O outro app quase certamente está usando o mesmo client ID. Um broker mantém uma sessão por client ID e derruba a conexão mais antiga, então dê a cada cliente seu próprio ID e suas próprias credenciais.