ZigDash

Migrar do ZHA para o Zigbee2MQTT

O ZHA é o Zigbee do próprio Home Assistant. O ZigDash funciona com o Zigbee2MQTT, então não consegue mostrar dispositivos que estão no ZHA. Migrar significa parear seus dispositivos de novo com o Zigbee2MQTT. Depois disso, o Home Assistant continua usando os dispositivos pela integração MQTT.

Antes de começar

Duas formas de migrar

Segundo adaptadorMesmo adaptador
CustoUm adaptador novo, cerca de 30–60 € (por exemplo um Home Assistant Connect ZBT-2, ou um SMLIGHT SLZB-06M ou SLZB-07)Grátis
Durante a migraçãoTudo continua funcionando: o ZHA fica com o adaptador antigoO Zigbee fica desligado até cada dispositivo ser pareado de novo
RitmoCômodo por cômodo, ao longo de dias se você quiserTudo de uma vez
Voltar atrásFácil: desconecte o adaptador novo; o ZHA nunca parouRestaure o backup do ZHA (veja Voltar atrás)

Segundo adaptador

  1. Configure o Zigbee2MQTT no adaptador novo (com apps ou Docker) com uma rede própria. Escolha tudo isto antes da primeira inicialização do Zigbee2MQTT, porque mudar o canal depois pode exigir parear de novo:
    • deixe a chave de rede e o PAN ID em GENERATE (o padrão);
    • escolha um canal diferente do canal do ZHA (o ⚙ › Network information do ZHA mostra qual é); o Home Assistant recomenda 15, 20 ou 25.
  2. Mantenha os dois adaptadores afastados, cada um em um cabo extensor USB.
  3. No Home Assistant OS, quando você conectar o adaptador novo, o Home Assistant pode oferecer configurá-lo para o ZHA ou o Thread. Ignore: o adaptador é para o Zigbee2MQTT.
  4. Migre um cômodo de cada vez: pareie primeiro os dispositivos ligados na tomada ou na rede elétrica (lâmpadas, tomadas inteligentes, interruptores de parede: eles são roteadores), depois os dispositivos a bateria.
  5. Quando todos os dispositivos tiverem sido migrados, desative o ZHA (veja abaixo) e guarde o adaptador antigo como reserva.

Mesmo adaptador

  1. Baixe o backup do ZHA (veja Antes de começar) logo antes de começar.
  2. Desative o ZHA: Configurações › Dispositivos e serviços › Zigbee Home Automation, o ⋮ ao lado de Zigbee Home Automation › Disable. Não Delete.
  3. Configure o Zigbee2MQTT no mesmo adaptador (com apps ou Docker), deixando a chave de rede e o PAN ID em GENERATE.
  4. Desligue os dispositivos Zigbee ligados na rede elétrica no interruptor de parede ou no disjuntor. Senão, eles continuam procurando a rede antiga.
  5. Ligue-os de novo um por um e pareie cada um assim que ele ligar. Depois pareie os dispositivos a bateria.

Seu adaptador

As páginas de adaptadores do Zigbee2MQTT têm os detalhes.

Home Assistant com apps (Home Assistant OS)

  1. Em Configurações › Apps, instale e inicie o Mosquitto broker. Em seguida, o Home Assistant oferece a integração MQTT em Configurações › Dispositivos e serviços: aceite.
  2. Adicione o repositório do Zigbee2MQTT (na loja de apps, ⋮ › Repositories: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt) e depois instale o Zigbee2MQTT.
  3. Na aba Configuration dele, defina a porta serial e o adaptador conforme seu adaptador, por exemplo:
    port: /dev/serial/by-id/usb-...
    adapter: ember
    Na forma do segundo adaptador, defina também o canal (veja acima) antes da primeira inicialização.
  4. Inicie o Zigbee2MQTT e abra a página web dele pela página do app. Depois pareie.

Home Assistant no Docker (sem apps)

Sem apps, o Mosquitto e o Zigbee2MQTT rodam em contêineres próprios, ao lado do Home Assistant. Em uma pasta nova:

1. compose.yaml (coloque o caminho do seu adaptador em devices; ls /dev/serial/by-id/ mostra qual é):

services:
  mosquitto:
    image: eclipse-mosquitto:2
    restart: unless-stopped
    ports:
      - 1883:1883
    volumes:
      - ./mosquitto/config:/mosquitto/config
      - ./mosquitto/data:/mosquitto/data
  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt
    restart: unless-stopped
    depends_on:
      - mosquitto
    ports:
      - 8080:8080
    volumes:
      - ./zigbee2mqtt:/app/data
      - /run/udev:/run/udev:ro
    environment:
      - TZ=Europe/Berlin
    devices:
      - /dev/serial/by-id/usb-...:/dev/ttyACM0

Com um adaptador de rede, deixe de fora devices e a linha do udev.

2. mosquitto/config/mosquitto.conf:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/

Crie o usuário MQTT (ele pede a senha duas vezes; o arquivo precisa pertencer ao próprio usuário do Mosquitto, senão o Mosquitto não inicia):

docker run -it --rm -v "$PWD/mosquitto/config:/mosquitto/config" eclipse-mosquitto:2 \
  sh -c "mosquitto_passwd -c /mosquitto/config/passwd zigbee && chown mosquitto:mosquitto /mosquitto/config/passwd"

3. zigbee2mqtt/configuration.yaml (as linhas do adaptador conforme seu adaptador):

homeassistant:
  enabled: true
frontend:
  enabled: true
  port: 8080
mqtt:
  server: mqtt://mosquitto:1883
  user: zigbee
  password: your-password
serial:
  port: /dev/ttyACM0          # a network adapter: tcp://IP:6638
  adapter: ember
advanced:
  network_key: GENERATE
  pan_id: GENERATE
  ext_pan_id: GENERATE
  channel: 20                 # second adapter: not ZHA's channel

4. Na forma do mesmo adaptador, o ZHA já está desativado agora (veja acima). Se o próprio contêiner do Home Assistant mapeia o adaptador, remova essa linha do arquivo compose dele ou do docker run: só um contêiner pode usar o adaptador.

5. docker compose up -d, depois abra http://the-machine:8080: a página web do Zigbee2MQTT.

6. No Home Assistant: Configurações › Dispositivos e serviços › Adicionar integração › MQTT. Broker: o endereço IP da máquina, porta 1883, usuário zigbee e a senha.

Parear os dispositivos

  1. Na página web do Zigbee2MQTT, toque em Permit join (fica aberto por cerca de quatro minutos). Para parear por um roteador perto do dispositivo, escolha esse roteador no menu do Permit join: é útil para Aqara e outros dispositivos exigentes.
  2. Coloque o dispositivo em modo de pareamento resetando-o, do jeito que o fabricante indica: um toque longo na maioria dos sensores, alguns ciclos de liga e desliga nas lâmpadas, uma sequência de acionamentos em alguns interruptores de parede.
  3. Quando ele aparecer, dê a ele um nome e um cômodo no Zigbee2MQTT. Depois, o próximo.

Primeiro os dispositivos ligados na rede elétrica, depois os dispositivos a bateria, para que a rede nova tenha rotas.

Depois da migração

Voltar atrás

Testado: em 17 de novembro de 2026, com o Home Assistant 2026.11 e um Sonoff ZBDongle-E, a rede do ZHA voltou exatamente igual (canal, PAN ID e chave de rede). Ainda não testamos com dispositivos pareados, então guarde o arquivo de backup.

Manter a rede sem parear de novo

Existe uma terceira forma: copiar a rede do ZHA para o Zigbee2MQTT, para que os dispositivos não precisem ser pareados de novo. O Zigbee2MQTT não oferece suporte a isso, um valor errado pode apagar a rede, e só vale a pena em casas grandes (digamos, com mais de 60 dispositivos). Se quiser ler sobre o assunto: a resposta do mantenedor do Zigbee2MQTT, e relatos da comunidade na discussão 24478 e na discussão 26716.

Conte para a gente como foi. Este guia é novo. Se algum passo estava errado ou faltando, escreva para [email protected] ou para a comunidade.