Zigbee2MQTT: conecte dispositivos Zigbee a qualquer broker MQTT

O Zigbee2MQTT transforma um coordenador Zigbee USB em um gateway MQTT: cada sensor, lâmpada e interruptor pareado aparece como uma mensagem JSON em um topic, e cada topic que termina em /set vira um comando. Ele não traz broker: você aponta para um no configuration.yaml, e qualquer broker MQTT compatível com o padrão funciona: um Mosquitto local, o add-on do Home Assistant ou um broker gerenciado na nuvem.

Este tutorial configura o Zigbee2MQTT (2.x) com um broker externo, explica a estrutura de topics e mostra como verificar a conexão e controlar um dispositivo pela linha de comando.

Como as peças se encaixam

Zigbee device ──radio──▶ Coordinator (USB) ──serial──▶ Zigbee2MQTT ──MQTT──▶ Broker ──▶ Home Assistant / Node-RED / your app

O Zigbee2MQTT é só mais um cliente MQTT. Isso tem duas consequências práticas: o broker pode estar em qualquer lugar acessível pela rede, e qualquer outra coisa que fale MQTT — um dashboard, um script, o cliente online — vê exatamente as mesmas mensagens que o seu software de automação.

Configuração mínima

O Zigbee2MQTT lê data/configuration.yaml. A seção MQTT é a que o conecta ao seu broker:

mqtt:
  base_topic: testmqtt/z2m          # o padrão é "zigbee2mqtt"
  server: mqtts://broker.connectmq.com:8883
  user: '!secret user'
  password: '!secret password'
  client_id: z2m-living-room
  keepalive: 60
  version: 5                        # 3, 4 (3.1.1) ou 5

serial:
  port: /dev/ttyACM0
  adapter: ember                    # zstack, ember, deconz, zigate, zboss

frontend:
  enabled: true
  port: 8080

homeassistant:
  enabled: false                    # true se o Home Assistant deve descobrir os dispositivos

advanced:
  log_level: info

user: username
password: password

Notas sobre as chaves importantes:

• server: mqtt://host:1883 para TCP sem criptografia, mqtts://host:8883 para TLS. URLs WebSocket (wss://host:8084/mqtt) também funcionam porque o Zigbee2MQTT usa MQTT.js por baixo, mas TCP é a escolha normal para um gateway.
• base_topic: a raiz de tudo que o Zigbee2MQTT publica. Mantenha o padrão zigbee2mqtt em um broker privado; em um broker de testes compartilhado use uma raiz única como a de cima para não colidir com outros usuários.
• client_id: precisa ser único no broker. Duas instâncias com o mesmo ID se derrubam em loop; veja boas práticas de client ID.
• ca, key, cert: só são necessários para uma CA privada ou TLS mútuo. Um broker com certificado publicamente confiável funciona só com mqtts://. Nunca "resolva" erros de certificado com reject_unauthorized: false em produção.
• !secret: guarda as credenciais em secret.yaml, para você compartilhar ou versionar o configuration.yaml com segurança.

Todas as opções também podem ser definidas por variáveis de ambiente, o que é prático em containers: ZIGBEE2MQTT_CONFIG_MQTT_SERVER, ZIGBEE2MQTT_CONFIG_MQTT_USER, ZIGBEE2MQTT_CONFIG_MQTT_PASSWORD e assim por diante.

Rodando com Docker

services:
  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt
    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-if00-port0:/dev/ttyACM0

Mapeie o coordenador pelo caminho /dev/serial/by-id/...: /dev/ttyUSB0 pode mudar após um reboot ou quando outro dispositivo USB é conectado. Se você roda um broker local no mesmo Compose, refira-se a ele pelo nome do serviço (mqtt://mosquitto:1883), não por localhost — dentro de um container, localhost é o próprio container. O guia do stack Docker Compose cobre essa configuração.

Inicie e acompanhe o log:

docker compose up -d
docker compose logs -f zigbee2mqtt

Uma inicialização saudável registra Connecting to MQTT server at mqtts://broker.connectmq.com:8883 seguido de Connected to MQTT server. Se aparecer MQTT error: Connection refused: Not authorized ou MQTT failed to connect, exiting..., confira primeiro as credenciais e o par porta/esquema; o guia de erros do Zigbee2MQTT explica cada mensagem.

A estrutura de topics

Dispositivos novos recebem como nome o endereço IEEE (0x00158d0001a2b3c4). Renomeie para algo significativo; uma barra no nome cria hierarquia, então living_room/ceiling vira testmqtt/z2m/living_room/ceiling. É o jeito mais fácil de ter uma árvore de topics limpa para casa inteligente.

bridge/state, bridge/info e bridge/devices são mensagens retidas, então qualquer cliente que assine depois descobre na hora se o bridge está no ar e quais dispositivos existem.

Teste cada etapa pela linha de comando

1. O bridge está conectado? Assine o estado do bridge; o valor retido chega imediatamente:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/bridge/state' -v
# testmqtt/z2m/bridge/state {"state":"online"}

2. Observe todo o tráfego enquanto aperta um botão ou abre um sensor de porta:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/#' -v

3. Pareie um dispositivo abrindo a rede por tempo limitado (o Zigbee2MQTT 2.x exige time; 0 fecha novamente):

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/z2m/bridge/request/permit_join' -m '{"time": 120}'

A resposta chega em bridge/response/permit_join, e bridge/event informa device_joined e device_interview enquanto o dispositivo é pareado.

4. Renomeie e controle:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/bridge/request/device/rename' \
  -m '{"from": "0x00158d0001a2b3c4", "to": "living_room/ceiling"}'

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/living_room/ceiling/set' \
  -m '{"state": "TOGGLE", "brightness": 180, "transition": 1}'

O novo estado da lâmpada aparece em testmqtt/z2m/living_room/ceiling em menos de um segundo. Se um comando não fizer nada, confira bridge/logging: o Zigbee2MQTT registra ali os payloads rejeitados.

Você pode fazer os mesmos passos no navegador: abra o cliente MQTT online, assine testmqtt/z2m/# e publique nos topics /set pelo painel de publicação.

Veja seus topics do Zigbee2MQTT ao vivo

Integrando com o Home Assistant

Defina homeassistant: enabled: true e o Zigbee2MQTT publica mensagens de discovery em homeassistant/.... A integração MQTT do Home Assistant precisa apontar para o mesmo broker; os dispositivos aparecem então automaticamente com todas as entidades. Se você mudou o base_topic, nada mais precisa mudar — os payloads de discovery incluem os topics de estado e de comando corretos. Veja Home Assistant e MQTT para o lado do broker.

Checklist de produção

1. Dê ao Zigbee2MQTT um usuário próprio no broker e restrinja-o a <base>/#, mais homeassistant/# se o discovery estiver ativo.
2. Use TLS (mqtts://) sempre que o broker não estiver no mesmo host.
3. Ative availability para que dispositivos offline sejam reportados em vez de ficarem desatualizados em silêncio.
4. Mantenha o permit_join fechado, exceto durante o pareamento.
5. Faça backup de todo o diretório data/: ele contém a chave da rede e o backup do coordenador, não só a configuração.

O Zigbee2MQTT é a forma mais simples de libertar dispositivos Zigbee dos hubs dos fabricantes: um bloco YAML aponta para qualquer broker e, a partir daí, cada dispositivo é só um topic. Verifique primeiro o estado do bridge, observe o tráfego enquanto pareia e controle os dispositivos com um simples mosquitto_pub antes de construir automações em cima.

Perguntas frequentes