O que você vai precisar
Passo a passo
1. Faça backup antes de instalar qualquer coisa
Abra Configurações > Sistema > Backups e crie um backup completo. Zigbee2MQTT mexe com MQTT, dispositivos e entidades; se algo sair torto, restaurar backup é mais rápido do que caçar erro em três telas diferentes.
Dica: Baixe o backup para fora do Home Assistant. Backup guardado no mesmo SSD não salva se o SSD falhar.2. Conecte o coordenador Zigbee com extensor USB
Plugue o dongle Zigbee em um extensor USB curto e afaste-o do Mini PC, roteador e portas USB 3.0. Interferência em 2,4 GHz é um clássico. O extensor de R$ 20 costuma melhorar mais a rede do que trocar coordenador sem diagnóstico.
Dica: Se o dongle tiver antena externa, deixe-a vertical e longe de metal.3. Instale e configure o Mosquitto Broker
No Home Assistant, abra Configurações > Apps > Instalar app e instale Mosquitto Broker. Inicie o app e deixe iniciar no boot. Depois, vá em Dispositivos e Serviços e aceite a integração MQTT descoberta, mantendo discovery ativado.
4. Crie um usuário dedicado para MQTT
Crie um usuário no Home Assistant chamado mqtt ou zigbee_mqtt, com senha forte. Use esse usuário na configuração do Zigbee2MQTT. Separar credenciais facilita manutenção e evita usar o login pessoal em serviço de infraestrutura.
Dica: Não use senha curta porque o broker fica no coração da automação.5. Adicione o repositório oficial do Zigbee2MQTT
Na área de Apps, abra repositórios de terceiros e adicione https://github.com/zigbee2mqtt/hassio-zigbee2mqtt. Instale a versão estável do Zigbee2MQTT. A versão Edge serve para testar correções e dispositivos novos, não para primeira rede da casa.
6. Descubra o caminho serial correto do dongle
Abra Configurações > Sistema > Hardware ou use Terminal para listar /dev/serial/by-id. Copie o caminho completo do coordenador. Ele costuma parecer longo, com fabricante, chip e número serial. Esse caminho é melhor que /dev/ttyUSB0 porque não muda facilmente após reboot.
Dica: Se nada aparecer, teste outro cabo, outra porta USB e confira se o dongle está em modo coordenador, não roteador.7. Configure o Zigbee2MQTT
Na configuração do app, informe o servidor MQTT, usuário, senha e porta serial. Em instalações padrão com Mosquitto no mesmo Home Assistant, o servidor costuma ser mqtt://core-mosquitto:1883. Em serial, use o caminho /dev/serial/by-id copiado.
8. Inicie o Zigbee2MQTT e leia os logs
Clique em Iniciar e abra os logs. Se o coordenador for detectado, o serviço sobe e a interface web aparece. Se houver erro de serial, permissão ou adaptador, não force pareamento. Resolva o boot primeiro.
Dica: Log vermelho no primeiro boot não é desastre. É diagnóstico.9. Ative Permit join por tempo curto
Na interface do Zigbee2MQTT, ative Permit join por 2 ou 3 minutos. Coloque o dispositivo Zigbee em modo de pareamento. Quando ele aparecer, renomeie na hora com padrão claro, como sensorportacozinha ou tomadarepetidorsala.
10. Comece a rede por dispositivos roteadores
Antes de parear 20 sensores a bateria, pareie tomadas, módulos e interruptores alimentados pela rede elétrica. Eles atuam como roteadores Zigbee e formam malha. Depois entram sensores de porta, presença e temperatura.
Dica: Sensor a bateria não roteia. Ele é folha da rede, não poste de sinal.11. Organize grupos e nomes antes de automatizar
Depois de parear, renomeie dispositivo, entidade e friendly_name. Padronize cômodo e função. Trocar nomes depois de automações prontas dá trabalho e abre espaço para erro.
12. Desative Permit join e faça novo backup
Ao terminar os pareamentos iniciais, desative Permit join. Depois faça backup completo. A rede Zigbee já tem chaves, dispositivos e nomes; esse estado merece ser preservado.
Quem mais sofre na instalação do Zigbee2MQTT não é o dono da casa. É o sensor barato de porta que o usuário compra para testar. Ele entra em modo de pareamento, pisca três vezes, some, volta com nome esquisito e acaba culpado por uma rede que ainda nem nasceu direito. O sensor não é o problema. A ordem da instalação é.
Zigbee2MQTT é um daqueles projetos que parecem difíceis porque contam a verdade. Ele mostra coordenador, canal, linkquality, clusters, logs, conversores, firmware e rotas. O app de fabricante esconde quase tudo. Esconder é confortável até a rede falhar. Aí você quer exatamente o que o Zigbee2MQTT entrega: visibilidade.
Zigbee2MQTT começa pelo MQTT, não pelo Zigbee#
O nome entrega a arquitetura. O dispositivo fala Zigbee com o coordenador. O Zigbee2MQTT traduz eventos e comandos para MQTT. O Home Assistant lê esses tópicos e cria entidades por descoberta automática. Na prática, há três peças: coordenador Zigbee, broker MQTT e integração MQTT no Home Assistant. Quando uma falha, o conjunto parece quebrado.
Por isso Mosquitto vem antes. Instale, inicie, configure usuário e confirme que a integração MQTT aparece no Home Assistant. Só depois instale Zigbee2MQTT. Fazer o contrário é como montar interruptor antes de passar fase no quadro.
Em uma casa comum, o broker quase não pesa. Ele fica ali, discreto, recebendo mensagens de sensores e repassando comandos. Mas ele precisa ser tratado como infraestrutura. Senha boa, backup e nada de mexer sem saber por quê.
O coordenador USB precisa ficar longe do computador#
Essa etapa parece superstição até você testar. Dongle Zigbee colado em porta USB 3.0, atrás de Mini PC metálico, perto de roteador Wi-Fi, costuma dar pareamento instável, sensores sumindo e linkquality deprimente. Um extensor USB de 1 metro muda a conversa. Não é bonito. Funciona.
Zigbee opera na faixa de 2,4 GHz, a mesma região ocupada por Wi-Fi 2,4 GHz, Bluetooth e um monte de ruído doméstico. O coordenador é a antena central da sua rede. Se ele nasce espremido atrás do rack, você começa o projeto pedindo desculpa para o rádio.
Coloque o dongle afastado, vertical, sem metal ao redor e preferencialmente em uma posição mais aberta. Em apartamento pequeno, 1 metro já ajuda. Em sobrado ou casa com laje, talvez faça sentido coordenador Ethernet como SMLight SLZB-06 em ponto mais central.
A porta serial correta evita pane depois do reboot#
O erro clássico é configurar /dev/ttyUSB0. Hoje funciona. Amanhã você pluga outro adaptador USB, reinicia o servidor e o Zigbee muda de endereço. O Zigbee2MQTT não encontra o coordenador, a rede cai e a casa fica sem sensores. A solução é usar /dev/serial/by-id, que identifica o dispositivo por caminho mais estável.
Esse caminho é comprido e feio. Algo como /dev/serial/by-id/usb-ITeadSonoffZigbee3.0USBDonglePlus... Não tente embelezar. Copie inteiro. Automação boa não liga para estética de caminho de sistema.
Se o caminho não aparece, investigue antes de avançar. Pode ser cabo ruim, dongle sem firmware coordenador, porta USB com energia problemática ou VM sem passthrough correto. Parear dispositivos por cima de base instável só multiplica o prejuízo.
A primeira rede deve nascer pequena#
Não abra Permit join e saia correndo pela casa apertando botão em tudo. Comece com um dispositivo simples perto do coordenador. Uma tomada Zigbee é perfeita porque além de parear, vira roteador. Depois adicione outro roteador no cômodo vizinho. Só então entram sensores a bateria.
A enumeração certa cabe numa frase: coordenador afastado, Mosquitto estável, serial by-id, tomadas roteadoras, sensores por último e Permit join sempre fechado depois do uso. Essa ordem evita 80% das histórias de “Zigbee é instável” que aparecem em grupo.
A rede Zigbee é malha, não Wi-Fi com repetidor mágico. Dispositivos alimentados na tomada roteiam. Dispositivos a bateria dormem para economizar energia. Se você instala só sensor a bateria longe do coordenador, a rede não tem por onde passar.
Canal Zigbee e Wi-Fi merecem conversa#
Zigbee e Wi-Fi 2,4 GHz dividem espaço. Não precisa virar engenheiro de RF para montar uma casa, mas ignorar canal é pedir interferência. Muitos coordenadores usam canal Zigbee 11, 15, 20 ou 25. O ideal é afastar o Zigbee dos canais Wi-Fi mais congestionados, especialmente em apartamento com dezenas de redes vizinhas.
Minha regra prática: se a rede está estável, não mexa no canal por curiosidade. Trocar canal Zigbee depois de parear tudo pode exigir reparo ou reconfiguração de dispositivos. Canal é decisão para o começo, ou remédio para problema diagnosticado, não passatempo de domingo.
Se você tem roteador dual band, empurre celular, notebook e TV para 5 GHz sempre que possível. Deixe 2,4 GHz menos lotado para IoT. Não resolve tudo, mas reduz ruído no espaço onde Zigbee trabalha.
Nome bom evita automação quebrada#
Depois que o dispositivo entra, renomeie. Nome de fábrica como 0xa4c138d91f9c2b11 é convite para arrependimento. Use padrão com função e cômodo: sensorportaservico, tomadarepetidorcorredor, interruptorsalalustre. O friendly_name do Zigbee2MQTT deve conversar com o nome do dispositivo no Home Assistant.
Não crie automação antes de organizar nomes. Parece economia de tempo, mas cobra juros. Quando você renomeia entidade depois, precisa conferir painel, automação, script e histórico. Uma hora de organização no começo poupa três horas de caça depois.
OTA e compatibilidade são o motivo de muita gente migrar#
Zigbee2MQTT ficou famoso por aceitar uma quantidade enorme de dispositivos e por andar rápido quando aparece coisa nova no mercado. Fabricantes Tuya e derivados lançam modelos com a mesma carcaça e firmware diferente como se fosse esporte. A comunidade cria conversores, ajusta exposes e registra peculiaridades. É bagunçado, mas vivo.
Atualização OTA de firmware existe para alguns dispositivos, não para todos. Use com cuidado. Atualizar lâmpada ou tomada crítica sem ler changelog pode resolver bug ou criar outro. Eu só atualizo em massa quando há motivo claro: falha de pareamento, consumo errado, perda de conexão ou correção reconhecida.
Os logs são amigos, não punição#
A interface do Zigbee2MQTT mostra mensagens que assustam no começo. Interview failed, unsupported attribute, no converter available, route failed. Nem tudo é grave. Log é narrador da rede. Aprenda a ler antes de resetar dispositivo.
Se um sensor falha no interview, aproxime do coordenador e tente de novo. Se uma lâmpada aparece sem função, verifique se o modelo exato é suportado. Se comandos atrasam, olhe rotas e linkquality. Se tudo está ruim, volte para o básico: extensor USB, canal, roteadores alimentados e fonte do Mini PC.
Zigbee2MQTT não é obrigatório, mas é poderoso#
ZHA, a integração nativa do Home Assistant, funciona muito bem para muita gente. Se sua rede é pequena, com dispositivos comuns, e você quer menos peças para manter, ZHA pode ser escolha melhor. Zigbee2MQTT faz mais sentido quando você quer catálogo mais amplo, interface própria, logs ricos, controle fino e independência maior do ciclo de suporte do Home Assistant.
O preço dessa liberdade é manutenção. Você terá Mosquitto, Zigbee2MQTT, integração MQTT, coordenador e dispositivos. Mais peças, mais diagnóstico. Para a redação LivSmart, compensa em redes médias e grandes. Para cinco sensores em apartamento, talvez seja motor demais.
A rede boa fica invisível no uso diário#
Depois de configurado, Zigbee2MQTT deve sumir da sua cabeça. A porta abre, o sensor informa. O botão aperta, a luz responde. A tomada roteia, o corredor ganha sinal. Quando a rede só chama atenção no dia de adicionar dispositivo novo, você acertou a mão.
O melhor sinal de uma configuração madura é a falta de drama. Permit join fechado, backup feito, nomes claros, roteadores espalhados e logs sem chuva de erro. Não tem glamour. Tem casa funcionando.
Zigbee2MQTT é mais trabalhoso que um hub de fabricante, mas devolve o controle. Se você montar a base direito — MQTT antes, dongle afastado, serial by-id e malha com roteadores — ele vira uma das peças mais confiáveis do Home Assistant.