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
- Qual instalação você tem? Se o menu Configurações do Home Assistant mostra Apps (Add-ons em versões mais antigas), você tem o Home Assistant OS: veja com apps. Se não mostra, o Home Assistant roda no Docker (Container): veja Docker.
- Qual adaptador você tem? Abra Configurações › Dispositivos e serviços › Zigbee Home Automation. Em Hubs, o adaptador aparece pelo modelo, por exemplo SONOFF ZBDongle-E. Depois veja seu adaptador.
- Faça backup do ZHA. Nessa página, toque no ⚙ ao lado de Zigbee Home Automation e depois em Download backup. Guarde o arquivo. Na mesma página, Network information mostra o canal, o tipo de rádio e a porta serial.
- O que muda no Home Assistant. Seus dispositivos voltam como novos dispositivos MQTT, com novos IDs de entidade. Automações, scripts e painéis que usam esses dispositivos precisam ser apontados para os novos, e o histórico deles começa do zero. Grupos e vínculos (bindings) feitos no ZHA são refeitos no Zigbee2MQTT.
- Tempo. Cada dispositivo é resetado e pareado de novo, um por um. Ainda não temos tempos confiáveis; reserve uma noite para uma casa pequena e mais para uma grande.
Duas formas de migrar
| Segundo adaptador | Mesmo adaptador | |
|---|---|---|
| Custo | Um 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ção | Tudo continua funcionando: o ZHA fica com o adaptador antigo | O Zigbee fica desligado até cada dispositivo ser pareado de novo |
| Ritmo | Cômodo por cômodo, ao longo de dias se você quiser | Tudo de uma vez |
| Voltar atrás | Fácil: desconecte o adaptador novo; o ZHA nunca parou | Restaure o backup do ZHA (veja Voltar atrás) |
Segundo adaptador
- 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.
- deixe a chave de rede e o PAN ID em
- Mantenha os dois adaptadores afastados, cada um em um cabo extensor USB.
- 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.
- 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.
- Quando todos os dispositivos tiverem sido migrados, desative o ZHA (veja abaixo) e guarde o adaptador antigo como reserva.
Mesmo adaptador
- Baixe o backup do ZHA (veja Antes de começar) logo antes de começar.
- Desative o ZHA: Configurações › Dispositivos e serviços › Zigbee Home Automation, o ⋮ ao lado de Zigbee Home Automation › Disable. Não Delete.
- Configure o Zigbee2MQTT no mesmo adaptador (com apps ou Docker), deixando a chave de rede e o PAN ID em
GENERATE. - Desligue os dispositivos Zigbee ligados na rede elétrica no interruptor de parede ou no disjuntor. Senão, eles continuam procurando a rede antiga.
- Ligue-os de novo um por um e pareie cada um assim que ele ligar. Depois pareie os dispositivos a bateria.
Seu adaptador
- Silicon Labs (Home Assistant Connect ZBT-1 e ZBT-2, Home Assistant Yellow, Sonoff ZBDongle-E, SMLIGHT SLZB-06M e SLZB-07):
adapter: ember. O ZBT-2 também precisa debaudrate: 460800; o ZBDongle-E precisa dertscts: false; o SLZB-06M precisa do firmware 20240510 ou mais recente. - Texas Instruments (Sonoff ZBDongle-P, SMLIGHT SLZB-06 e SLZB-06P7):
adapter: zstack. - ConBee ou RaspBee:
adapter: deconz. - CC2531 ou ZiGate: antigos demais ou sem manutenção para uma boa rede Zigbee2MQTT. Use a forma do segundo adaptador, com um adaptador novo.
- Um adaptador de rede (SMLIGHT SLZB-06, SLZB-06M, SLZB-07, série MR): o ZHA mostra como
socket://IP:6638; no Zigbee2MQTT ficatcp://IP:6638, e o Docker não precisa da linha de USB. - Multiprotocolo (ZBT-1 ou Yellow rodando Zigbee e Thread juntos; a página do hardware no Home Assistant informa isso): o Zigbee2MQTT não consegue usar firmware multiprotocolo. Na forma do mesmo adaptador, desative o multiprotocolo ainda no ZHA, com o procedimento do próprio Home Assistant (ZBT-1, Yellow). Os dispositivos Thread que usavam o adaptador param de funcionar até outro roteador de borda Thread assumir. Na forma do segundo adaptador, não mexa nele e compre o adaptador novo só para Zigbee.
As páginas de adaptadores do Zigbee2MQTT têm os detalhes.
Home Assistant com apps (Home Assistant OS)
- 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.
- Adicione o repositório do Zigbee2MQTT (na loja de apps, ⋮ › Repositories:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt) e depois instale o Zigbee2MQTT. - Na aba Configuration dele, defina a porta serial e o adaptador conforme seu adaptador, por exemplo:
Na forma do segundo adaptador, defina também o canal (veja acima) antes da primeira inicialização.port: /dev/serial/by-id/usb-... adapter: ember - 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
- 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.
- 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.
- 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
- ZigDash: abra o aplicativo e toque em Encontrar minha instalação. Ele encontra o Mosquitto na sua rede; entre com o usuário MQTT. Ou escolha Home Assistant e faça login: agora isso também funciona, porque o Home Assistant tem a integração MQTT.
- Nomes e cômodos: no ZigDash, Configurações › Importar do Home Assistant traz os nomes e cômodos que você deu aos dispositivos novos no Home Assistant.
- Home Assistant: aponte automações, scripts e painéis para os dispositivos novos. Quando tiver certeza, exclua a integração ZHA.
Voltar atrás
- Segundo adaptador: pare o Zigbee2MQTT e desconecte o adaptador novo. O ZHA nunca parou. Os dispositivos que você já migrou precisam ser pareados de novo com o ZHA.
- Mesmo adaptador: pare o Zigbee2MQTT e, na página do ZHA, toque em Enable. O ZHA diz "Network settings do not match most recent backup" (as configurações de rede não batem com o backup mais recente), porque agora o adaptador guarda a rede do Zigbee2MQTT. Abra Configurações › Reparos › "Zigbee network settings have changed" (as configurações da rede Zigbee mudaram) e escolha Restore backup (recommended). A rede do ZHA volta como estava. Os dispositivos que você tinha pareado com o Zigbee2MQTT precisam ser pareados de novo com o ZHA. Se nenhum reparo aparecer, use ⚙ › Migrate adapter com o backup que você baixou.
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.