Guia de Configuração do Zigbee2MQTT: do Coordenador ao Painel

Uma configuração do Zigbee2MQTT permite usar sensores, lâmpadas e interruptores Zigbee de várias marcas sem os hubs ou nuvens dos fabricantes, e expõe cada dispositivo como tópicos MQTT simples. Neste guia você vai escolher um coordenador, rodar o Zigbee2MQTT no Docker, conectá-lo a um broker, parear e renomear dispositivos, controlá-los pela linha de comando e acompanhar seus estados em um painel. Tudo é testado primeiro no servidor MQTT público (gratuito), com um base topic exclusivo.

Como o Zigbee2MQTT se encaixa

O Zigbee2MQTT é uma bridge. De um lado, ele controla um coordenador Zigbee (um pendrive USB ou um adaptador de rede) que forma a sua malha Zigbee. Do outro, é um cliente MQTT que publica o estado de cada dispositivo em JSON e escuta comandos. Qualquer coisa que fale MQTT, como Home Assistant, Node-RED, um script Python ou um app de celular, pode então usar esses dispositivos.

[Zigbee devices] ~~radio~~ [Coordinator] --USB/TCP-- [Zigbee2MQTT] --MQTT-- [Broker] -- [Dashboards, automations]

O broker fica no meio e é a única coisa à qual todos os consumidores se conectam. Se quiser relembrar o que faz um broker MQTT, vale uma leitura rápida antes de começar.

Escolhendo um coordenador

O coordenador determina qual valor de adapter você usa. Opções populares e bem suportadas:

Duas dicas práticas fazem muita diferença. Use um cabo extensor USB de cerca de meio metro para afastar o pendrive das portas USB 3 e dos SSDs, cuja interferência pode degradar muito o alcance do Zigbee. E adicione logo no início alguns roteadores alimentados pela rede elétrica (tomadas ou lâmpadas inteligentes), porque dispositivos a bateria não roteiam e uma malha só com dispositivos finais é frágil.

Instalando o Zigbee2MQTT com Docker

Encontre o caminho estável do seu adaptador, que não muda entre reinicializações:

ls -l /dev/serial/by-id/

Crie uma pasta com um docker-compose.yml:

services:
  zigbee2mqtt:
    container_name: zigbee2mqtt
    image: ghcr.io/koenkk/zigbee2mqtt:latest
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - /run/udev:/run/udev:ro
    ports:
      - "8080:8080"
    environment:
      - TZ=Europe/Berlin
    devices:
      - /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXX-if00-port0:/dev/ttyACM0

Substitua o caminho do dispositivo pelo do seu sistema e defina o seu fuso horário. Em uma instalação de longa duração, fixe a imagem em uma tag de versão específica em vez de latest, para que as atualizações aconteçam quando você decidir.

O arquivo de configuração do Zigbee2MQTT

Crie data/configuration.yaml antes da primeira inicialização. Escolha um segmento aleatório para o base topic, porque o servidor MQTT público é compartilhado e pode ser lido por qualquer pessoa:

homeassistant:
  enabled: false
frontend:
  enabled: true
  port: 8080
mqtt:
  base_topic: connectmq/demo/z7q4/z2m
  server: mqtt://broker.connectmq.com:1883
  client_id: z2m-z7q4-bridge
serial:
  port: /dev/ttyACM0
  adapter: zstack
availability:
  enabled: true
advanced:
  log_level: info
  channel: 25
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE

Pontos-chave:

• base_topic é o prefixo de tudo o que o Zigbee2MQTT publica. Aqui ele tem quatro níveis, deixando folga dentro do limite de 8 níveis de tópico do servidor MQTT público.
• client_id precisa ser único e não vazio no broker.
• channel não pode ser alterado depois sem parear de novo todos os dispositivos. Os canais 15, 20 e 25 evitam a sobreposição mais comum com o Wi-Fi; verifique quais canais Wi-Fi estão ocupados perto de você.
• GENERATE faz o Zigbee2MQTT criar uma chave de rede e IDs aleatórios na primeira inicialização e gravá-los de volta no arquivo. Depois disso, faça backup de configuration.yaml e coordinator_backup.json da pasta de dados.
• availability publica {"state":"online"} ou offline por dispositivo, o que é muito útil em painéis.

Inicie e acompanhe o log:

docker compose up -d
docker compose logs -f zigbee2mqtt

Você deve ver a versão do firmware do coordenador e, em seguida, uma linha confirmando a conexão com o broker MQTT. Se você iniciar sem um arquivo de configuração, as versões recentes abrem uma página de onboarding na porta 8080, onde é possível informar os mesmos valores em um formulário.

Pareando e nomeando dispositivos

Abra o frontend em http://<host>:8080 e clique em Permit join (All), ou habilite a entrada na rede via MQTT por até 254 segundos:

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/bridge/request/permit_join" -m '{"time": 254}'

Coloque o dispositivo em modo de pareamento (normalmente um toque longo no botão ou uma sequência de liga/desliga no caso das lâmpadas). Ele aparece com um endereço IEEE como 0x00158d0001abcd12. Renomeie-o logo para algo significativo, porque o nome vira o seu tópico:

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/bridge/request/device/rename" \
  -m '{"from": "0x00158d0001abcd12", "to": "living_room_lamp"}'

Encerre a entrada na rede com {"time": 0} quando terminar. Deixar a rede aberta convida dispositivos dos vizinhos a entrar por acidente.

Use sublinhados em vez de barras nos friendly names enquanto testa no servidor MQTT público. Um nome como living_room/lamp é permitido e cria hierarquias mais bonitas, mas cada barra adiciona um nível de tópico, e bridge/request/device/rename já usa todos os 8 níveis com este base topic.

Lendo e controlando dispositivos via MQTT

Assine tudo sob o base topic:

mosquitto_sub -h broker.connectmq.com -p 1883 -i z2m-watch-z7q4 -t "connectmq/demo/z7q4/z2m/#" -v

Um sensor de temperatura publica em connectmq/demo/z7q4/z2m/hallway_sensor:

{"battery": 97, "humidity": 48.2, "linkquality": 116, "temperature": 21.4, "voltage": 2995}

Controle uma lâmpada publicando no seu tópico set:

mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
  -t "connectmq/demo/z7q4/z2m/living_room_lamp/set" \
  -m '{"state": "ON", "brightness": 180, "color_temp": 370, "transition": 2}'

Para pedir o estado atual de um dispositivo, publique {"state": ""} no seu tópico get. Os tópicos dos dispositivos carregam o estado completo, então um painel precisa de apenas uma assinatura por dispositivo.

Do MQTT ao painel

Como o Zigbee2MQTT fala MQTT puro, você tem várias opções de painel:

1. O frontend do Zigbee2MQTT para gerenciamento: lista de dispositivos, mapa da rede, atualizações OTA e logs.
2. Home Assistant pela integração MQTT. Defina homeassistant.enabled: true e o Zigbee2MQTT publica mensagens de discovery para que as entidades apareçam automaticamente; o guia de Home Assistant com MQTT cobre esse lado.
3. Node-RED Dashboard, assinando os tópicos dos dispositivos com um nó mqtt in e um nó JSON.
4. Um painel no navegador usando MQTT sobre WebSocket, conectando-se a wss://broker.connectmq.com:8084/mqtt.

Para verificações rápidas sem construir nada, o explorador de tópicos ao vivo do portal da ConnectMQ mostra cada tópico do Zigbee2MQTT à medida que é atualizado, o que é útil durante o pareamento e a renomeação.

Solução de problemas na configuração do Zigbee2MQTT

O servidor MQTT público também limita cada cliente a 10 mensagens por segundo, o que uma pequena rede de teste respeita com folga, mas uma rede grande na inicialização pode ultrapassar. É mais um motivo pelo qual a área pública serve apenas para testes e protótipos, nunca para produção; o artigo sobre o servidor MQTT público (gratuito) lista todos os seus limites.

Migrando para um broker privado

O Zigbee2MQTT controla fechaduras, luzes e alarmes, então a produção exige credenciais e TLS. Com um broker MQTT gerenciado como a ConnectMQ, você cria um broker no portal, copia o usuário, a senha e o client ID gerados e altera apenas o bloco mqtt:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtts://broker.connectmq.com:8883
  user: YOUR_USERNAME
  password: YOUR_PASSWORD
  client_id: YOUR_CLIENT_ID
  version: 5

O certificado Let's Encrypt é validado pelo pacote de CAs do sistema dentro do contêiner, então nenhum arquivo de certificado extra é necessário. O plano gratuito Serverless permite mensagens de até 256 KB, o suficiente para os payloads típicos da bridge, e os planos pagos elevam isso para 1 MB. O guia de Zigbee2MQTT com broker na nuvem se aprofunda em acesso remoto e instalações com vários locais, e o guia de automação IoT mostra onde o Zigbee se encaixa em um sistema maior de casa ou edifício.

Rode o Zigbee2MQTT na ConnectMQ

A ConnectMQ oferece à sua bridge Zigbee2MQTT um broker MQTT gerenciado e privado com TLS, Secure WebSocket para painéis no navegador e um portal para acompanhar ao vivo cada tópico de dispositivo. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, e aponte o seu mqtt.server para ele.

Perguntas frequentes

Qual coordenador é o melhor para uma nova configuração do Zigbee2MQTT?

Um pendrive baseado no Texas Instruments CC2652P com o adapter zstack ou um pendrive Silicon Labs EFR32MG21 com o adapter ember são as escolhas mais comuns e bem suportadas. Adaptadores de rede são úteis quando o servidor fica longe dos dispositivos.

Posso mudar o canal Zigbee depois?

Tecnicamente sim, mas a maioria dos dispositivos precisará ser pareada de novo. Escolha o canal com cuidado antes de parear qualquer coisa.

O Zigbee2MQTT precisa do Home Assistant?

Não. O Zigbee2MQTT só precisa de um broker MQTT. O Home Assistant é um consumidor opcional entre muitos, ao lado de Node-RED, scripts e painéis.

É seguro rodar o Zigbee2MQTT no servidor MQTT público?

Apenas para testes. Qualquer pessoa pode ler e publicar em tópicos públicos, inclusive nos seus tópicos set; por isso, use um broker privado com credenciais e TLS para dispositivos reais.