ZigDash

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

Due modi per passare

Secondo adattatoreStesso adattatore
CostoUn nuovo adattatore, circa 30–60 € (per esempio un Home Assistant Connect ZBT-2, oppure uno SMLIGHT SLZB-06M o SLZB-07)Gratis
Durante il passaggioTutto continua a funzionare: ZHA tiene il vecchio adattatoreLo Zigbee resta spento finché ogni dispositivo non è associato di nuovo
RitmoStanza per stanza, anche in più giorni se vuoiTutto in una volta
Tornare indietroFacile: scollega il nuovo adattatore, ZHA non si è mai fermatoRipristina il backup di ZHA (vedi Tornare indietro)

Secondo adattatore

  1. 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.
  2. Tieni i due adattatori lontani tra loro, ognuno su una prolunga USB.
  3. 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.
  4. Sposta una stanza alla volta: associa prima i dispositivi alimentati a rete (lampadine, prese, interruttori da incasso: fanno da router), poi quelli a batteria.
  5. Quando hai spostato tutti i dispositivi, disabilita ZHA (vedi sotto) e tieni il vecchio adattatore come scorta.

Stesso adattatore

  1. Scarica il backup di ZHA (vedi Prima di iniziare), subito prima di cominciare.
  2. Disabilita ZHA: Impostazioni › Dispositivi e servizi › Zigbee Home Automation, il ⋮ accanto a Zigbee Home Automation › Disabilita. Non Elimina.
  3. Configura Zigbee2MQTT sullo stesso adattatore (con app o Docker), lasciando la chiave di rete e il PAN ID su GENERATE.
  4. Spegni i dispositivi Zigbee alimentati a rete dall'interruttore a muro o dal quadro elettrico. Altrimenti continuano a cercare la vecchia rete.
  5. Riaccendili uno alla volta e associa ciascuno appena si accende. Poi associa i dispositivi a batteria.

Il tuo adattatore

Le pagine sugli adattatori di Zigbee2MQTT hanno i dettagli.

Home Assistant con app (Home Assistant OS)

  1. In Impostazioni › Apps, installa e avvia Mosquitto broker. Home Assistant ti proporrà l'integrazione MQTT in Impostazioni › Dispositivi e servizi: accettala.
  2. Aggiungi il repository di Zigbee2MQTT (nello store delle app, ⋮ › Repository: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt), poi installa Zigbee2MQTT.
  3. Nella sua scheda Configurazione, imposta la porta seriale e l'adattatore secondo il tuo adattatore, per esempio:
    port: /dev/serial/by-id/usb-...
    adapter: ember
    Per il modo del secondo adattatore, imposta anche il canale (vedi sopra) prima del primo avvio.
  4. 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

  1. 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.
  2. 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.
  3. 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

Tornare indietro

Provato: il 17 novembre 2026, con Home Assistant 2026.11 e un Sonoff ZBDongle-E, la rete di ZHA è tornata identica (canale, PAN ID e chiave di rete). Non l'abbiamo ancora verificato con dispositivi associati, quindi conserva il file di backup.

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.

Facci sapere com'è andata. Questa guida è nuova. Se un passaggio era sbagliato o mancava, scrivi a [email protected] o alla community.