Passare da ZHA a Zigbee2MQTT
ZHA è lo Zigbee integrato in Home Assistant. ZigDash funziona con Zigbee2MQTT, quindi non può mostrare i dispositivi che sono in ZHA. Passare significa associare di nuovo i tuoi dispositivi con Zigbee2MQTT. Home Assistant continua poi a usarli, tramite la sua integrazione MQTT.
Prima di iniziare
- Quale installazione? Se il menu Impostazioni di Home Assistant mostra Apps (Componenti aggiuntivi nelle versioni precedenti), hai Home Assistant OS: vedi con app. Altrimenti Home Assistant gira in Docker (Container): vedi Docker.
- Quale adattatore? Apri Impostazioni › Dispositivi e servizi › Zigbee Home Automation. Sotto Hubs l'adattatore compare con il suo modello, per esempio SONOFF ZBDongle-E. Poi guarda il tuo adattatore.
- Fai il backup di ZHA. In quella pagina tocca il ⚙ accanto a Zigbee Home Automation, poi Download backup. Conserva il file. Nella stessa pagina, Network information mostra il canale, il tipo di radio e la porta seriale.
- Cosa cambia in Home Assistant. I tuoi dispositivi tornano come nuovi dispositivi MQTT, con nuovi ID entità. Automazioni, script e plance che li usano vanno collegati a quelli nuovi, e la loro cronologia riparte da zero. Gruppi e binding creati in ZHA vanno rifatti in Zigbee2MQTT.
- Tempo. Ogni dispositivo va resettato e associato di nuovo, uno alla volta. Non abbiamo ancora tempi affidabili; prevedi una serata per una casa piccola e di più per una grande.
Due modi per passare
| Secondo adattatore | Stesso adattatore | |
|---|---|---|
| Costo | Un nuovo adattatore, circa 30–60 € (per esempio un Home Assistant Connect ZBT-2, oppure uno SMLIGHT SLZB-06M o SLZB-07) | Gratis |
| Durante il passaggio | Tutto continua a funzionare: ZHA tiene il vecchio adattatore | Lo Zigbee resta spento finché ogni dispositivo non è associato di nuovo |
| Ritmo | Stanza per stanza, anche in più giorni se vuoi | Tutto in una volta |
| Tornare indietro | Facile: scollega il nuovo adattatore, ZHA non si è mai fermato | Ripristina il backup di ZHA (vedi Tornare indietro) |
Secondo adattatore
- Configura Zigbee2MQTT sul nuovo adattatore (con app o Docker) con una rete tutta sua. Scegli tutto questo prima del primo avvio di Zigbee2MQTT, perché cambiare il canale dopo può voler dire associare di nuovo:
- lascia la chiave di rete e il PAN ID su
GENERATE(il valore predefinito); - scegli un canale diverso da quello di ZHA (lo mostra il ⚙ di ZHA › Network information); Home Assistant consiglia 15, 20 o 25.
- lascia la chiave di rete e il PAN ID su
- Tieni i due adattatori lontani tra loro, ognuno su una prolunga USB.
- Su Home Assistant OS, quando colleghi il nuovo adattatore, Home Assistant potrebbe proporti di configurarlo per ZHA o Thread. Ignora la proposta: l'adattatore è per Zigbee2MQTT.
- Sposta una stanza alla volta: associa prima i dispositivi alimentati a rete (lampadine, prese, interruttori da incasso: fanno da router), poi quelli a batteria.
- Quando hai spostato tutti i dispositivi, disabilita ZHA (vedi sotto) e tieni il vecchio adattatore come scorta.
Stesso adattatore
- Scarica il backup di ZHA (vedi Prima di iniziare), subito prima di cominciare.
- Disabilita ZHA: Impostazioni › Dispositivi e servizi › Zigbee Home Automation, il ⋮ accanto a Zigbee Home Automation › Disabilita. Non Elimina.
- Configura Zigbee2MQTT sullo stesso adattatore (con app o Docker), lasciando la chiave di rete e il PAN ID su
GENERATE. - Spegni i dispositivi Zigbee alimentati a rete dall'interruttore a muro o dal quadro elettrico. Altrimenti continuano a cercare la vecchia rete.
- Riaccendili uno alla volta e associa ciascuno appena si accende. Poi associa i dispositivi a batteria.
Il tuo adattatore
- Silicon Labs (Home Assistant Connect ZBT-1 e ZBT-2, Home Assistant Yellow, Sonoff ZBDongle-E, SMLIGHT SLZB-06M e SLZB-07):
adapter: ember. Lo ZBT-2 richiede anchebaudrate: 460800; lo ZBDongle-E richiedertscts: false; lo SLZB-06M richiede il firmware 20240510 o successivo. - Texas Instruments (Sonoff ZBDongle-P, SMLIGHT SLZB-06 e SLZB-06P7):
adapter: zstack. - ConBee o RaspBee:
adapter: deconz. - CC2531 o ZiGate: troppo vecchi o non più mantenuti per una buona rete Zigbee2MQTT. Usa il modo del secondo adattatore, con un adattatore nuovo.
- Un adattatore di rete (SMLIGHT SLZB-06, SLZB-06M, SLZB-07, MR series): ZHA lo mostra come
socket://IP:6638; in Zigbee2MQTT ètcp://IP:6638, e Docker non ha bisogno della riga USB. - Multiprotocollo (ZBT-1 o Yellow con Zigbee e Thread insieme; lo dice la pagina dell'hardware in Home Assistant): Zigbee2MQTT non può usare un firmware multiprotocollo. Per il modo dello stesso adattatore, disattiva il multiprotocollo mentre sei ancora su ZHA, con la procedura di Home Assistant (ZBT-1, Yellow). I dispositivi Thread che lo usavano smettono di funzionare finché un altro border router Thread non li prende in carico. Per il modo del secondo adattatore, lascialo com'è e compra il nuovo adattatore in versione solo Zigbee.
Le pagine sugli adattatori di Zigbee2MQTT hanno i dettagli.
Home Assistant con app (Home Assistant OS)
- In Impostazioni › Apps, installa e avvia Mosquitto broker. Home Assistant ti proporrà l'integrazione MQTT in Impostazioni › Dispositivi e servizi: accettala.
- Aggiungi il repository di Zigbee2MQTT (nello store delle app, ⋮ › Repository:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt), poi installa Zigbee2MQTT. - Nella sua scheda Configurazione, imposta la porta seriale e l'adattatore secondo il tuo adattatore, per esempio:
Per il modo del secondo adattatore, imposta anche il canale (vedi sopra) prima del primo avvio.port: /dev/serial/by-id/usb-... adapter: ember - Avvia Zigbee2MQTT e apri la sua pagina web dalla pagina dell'app. Poi associa.
Home Assistant in Docker (senza app)
Senza app, Mosquitto e Zigbee2MQTT girano nei loro container, accanto a Home Assistant. In una nuova cartella:
1. compose.yaml (metti il percorso del tuo adattatore in devices; ls /dev/serial/by-id/ te lo mostra):
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
Con un adattatore di rete, togli devices e la riga udev.
2. mosquitto/config/mosquitto.conf:
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
Crea l'utente MQTT (chiede la password due volte; il file deve appartenere all'utente di Mosquitto, altrimenti Mosquitto non si avvia):
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 (le righe dell'adattatore indicate in Il tuo adattatore):
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. Per il modo dello stesso adattatore, ZHA ora è disabilitato (vedi sopra). Se il container di Home Assistant mappa l'adattatore, togli quella riga dal suo file compose o dal suo docker run: un solo container alla volta può usare l'adattatore.
5. docker compose up -d, poi apri http://the-machine:8080: è la pagina web di Zigbee2MQTT.
6. In Home Assistant: Impostazioni › Dispositivi e servizi › Aggiungi integrazione › MQTT. Broker: l'indirizzo IP della macchina, porta 1883, utente zigbee e la password.
Associare i dispositivi
- Nella pagina web di Zigbee2MQTT tocca Permit join (resta aperto per circa quattro minuti). Per associare tramite un router vicino al dispositivo, scegli quel router nel menu di Permit join: utile per Aqara e altri dispositivi difficili.
- Metti il dispositivo in modalità di associazione come indica il produttore: una pressione lunga per la maggior parte dei sensori, alcuni cicli acceso/spento per le lampadine, una serie di scatti dell'interruttore per alcuni interruttori da incasso.
- Quando compare, dagli il suo nome e la sua stanza in Zigbee2MQTT. Poi passa al successivo.
Prima i dispositivi alimentati a rete, poi quelli a batteria, così la nuova rete ha dei percorsi.
Dopo il passaggio
- ZigDash: aprilo e tocca Trova la mia configurazione. Trova Mosquitto sulla tua rete; accedi con l'utente MQTT. Oppure scegli Home Assistant e accedi: ora funziona anche così, perché Home Assistant ha l'integrazione MQTT.
- Nomi e stanze: in ZigDash, Impostazioni › Importa da Home Assistant porta i nomi e le stanze che hai dato ai nuovi dispositivi in Home Assistant.
- Home Assistant: collega automazioni, script e plance ai nuovi dispositivi. Quando sei sicuro, elimina l'integrazione ZHA.
Tornare indietro
- Secondo adattatore: ferma Zigbee2MQTT e scollega il nuovo adattatore. ZHA non si è mai fermato. I dispositivi che hai già spostato vanno associati di nuovo a ZHA.
- Stesso adattatore: ferma Zigbee2MQTT, poi nella pagina di ZHA tocca Abilita. ZHA dice "Network settings do not match most recent backup" (le impostazioni di rete non corrispondono all'ultimo backup), perché ora l'adattatore contiene la rete di Zigbee2MQTT. Apri Impostazioni › Riparazioni › "Zigbee network settings have changed" (le impostazioni della rete Zigbee sono cambiate) e scegli Restore backup (recommended). La rete di ZHA torna com'era. I dispositivi che avevi associato a Zigbee2MQTT vanno associati di nuovo a ZHA. Se non compare nessuna riparazione, usa ⚙ › Migrate adapter con il backup che hai scaricato.
Tenere la rete senza associare di nuovo
Esiste un terzo modo: copiare la rete di ZHA in Zigbee2MQTT, così i dispositivi non vanno associati di nuovo. Zigbee2MQTT non lo supporta, un valore sbagliato può cancellare la rete, e ha senso solo per case grandi (diciamo oltre 60 dispositivi). Se vuoi approfondire: la risposta del maintainer di Zigbee2MQTT, e le esperienze della community nella discussione 24478 e nella discussione 26716.