Come migrare da ZHA a Zigbee2MQTT senza perdere il controllo

Prerequisiti & Hardware Necessario

• Hardware: host Home Assistant, un secondo coordinatore Zigbee compatibile con Zigbee2MQTT e prolunga USB. Un Raspberry Pi 5 è un host possibile: Raspberry Pi 5 4GB con alimentatore ufficiale.
• Software: ZHA è l’integrazione nativa attuale; Zigbee2MQTT è il nuovo gateway software e richiede un broker MQTT. Non sono due firmware del dongle e non possono usare contemporaneamente la stessa radio.
• Backup: backup completo Home Assistant, backup manuale della rete ZHA e copia della configurazione/automazioni. La migrazione fra applicazioni non è una conversione garantita di dispositivi ed entità.
• Radio: due coordinatori permettono di tenere ZHA operativo durante il passaggio; usa canali Zigbee pianificati e separati se le reti restano temporaneamente attive.

Procedura passo-passo

1. Inventaria dispositivi e automazioni. Esporta elenco di device, entity ID, aree, scene e automazioni. Annota sensori alimentati a batteria, perché richiedono spesso un’azione fisica per il pairing o il risveglio.
2. Crea i backup. In Home Assistant crea un backup completo e scaricalo fuori dall’host. Da ZHA crea anche il backup della rete dalla configurazione Zigbee. Non cancellare l’integrazione ZHA o il database prima di avere verificato i file.
3. Collega il secondo coordinatore. Usa una prolunga USB e trova il percorso stabile:

   ls -l /dev/serial/by-id/

   Non usare il coordinatore già gestito da ZHA per avviare la nuova istanza.
4. Installa e configura Zigbee2MQTT. Usa il metodo Docker/Compose già descritto, configura Mosquitto e imposta in configuration.yaml broker, serial.port, adapter e homeassistant.enabled: true. Verifica che Zigbee2MQTT parta con la nuova radio.
5. Crea una rete Zigbee2MQTT separata. Per una migrazione ZHA → Zigbee2MQTT non presumere che database e impostazioni ZHA siano riutilizzabili. Usa una nuova rete e annota canale, coordinator IEEE e credenziali MQTT.
6. Disabilita temporaneamente i nuovi pairing in ZHA. Mantieni ZHA operativo solo per il controllo dei vecchi device durante il passaggio, ma non lasciare lo stesso coordinatore collegato a due processi. Zigbee2MQTT deve avere la propria radio.
7. Ripristina ogni dispositivo secondo il produttore. Per spostare un device da una rete Zigbee a un’altra, esegui il factory reset previsto dal manuale. Un dispositivo Zigbee può appartenere a una sola rete/coordinatore alla volta.
8. Abbina un dispositivo alla volta. In Zigbee2MQTT abilita l’inclusione, resetta il dispositivo e attendi l’intervista completa. Per prima cosa abbina router alimentati, poi sensori a batteria e dispositivi difficili da raggiungere.
9. Rinomina e assegna le entità. Usa friendly name, aree e gruppi in Zigbee2MQTT/Home Assistant. Le entity ID potrebbero cambiare: aggiorna automazioni e script dopo aver verificato ogni dispositivo, non con sostituzioni globali cieche.
10. Verifica automazioni e dismetti ZHA. Testa luci, sensori, scene e notifiche per zona. Solo quando tutto funziona, rimuovi o disabilita ZHA e scollega il vecchio coordinatore; conserva backup e configurazione per un eventuale rollback.

Verifica del funzionamento

La migrazione è riuscita quando ogni dispositivo previsto compare in Zigbee2MQTT, Home Assistant riceve le entità via MQTT, automazioni e scene sono state testate e non esistono due processi che usano la stessa seriale. Verifica anche router e sensori a batteria dopo alcune ore, perché i dispositivi sleepy non comunicano continuamente.

Problemi comuni

FAQ essenziali

Posso migrare senza rifare il pairing?

Non è garantito passando da ZHA a Zigbee2MQTT. La documentazione Zigbee2MQTT indica il re-pairing come percorso necessario per migrazioni fra gateway diversi; pianificalo come requisito.

Posso tenere ZHA e Zigbee2MQTT insieme?

Sì con due coordinatori e due reti separate, ma aumenta complessità e interferenze. Non collegare la stessa radio a entrambi e pianifica canali e backup.