Come configurare SONOFF Zigbee 3.0 USB Dongle Plus (ZBDongle-P) con Zigbee2MQTT

Prerequisiti & Hardware Necessario

• Hardware: SONOFF Zigbee 3.0 USB Dongle Plus (ZBDongle-P) con firmware coordinator compatibile, server Linux con Docker e prolunga USB schermata. Il dongle è l’hardware radio; Zigbee2MQTT è il software che lo controlla.
• Software: Docker Engine, Docker Compose v2, Zigbee2MQTT e broker MQTT Mosquitto già attivo. Il modello ZBDongle-P usa lo stack TI zStack; non applicare la configurazione ember tipica del ZBDongle-E.
• Rete: broker MQTT raggiungibile, porta 1883 nella LAN e Home Assistant con integrazione MQTT. Non avviare ZHA sullo stesso dongle.
• Host: Raspberry Pi 5 con alimentatore adeguato, ad esempio Raspberry Pi 5 4GB con alimentatore ufficiale, oppure mini PC/VM Linux con passthrough USB.

Procedura passo-passo

1. Collega il dongle lontano da USB 3. Inserisci il SONOFF ZBDongle-P in una prolunga USB schermata e non direttamente accanto alle porte USB 3 o al disco NVMe. Non collegarlo a due host contemporaneamente.
2. Identifica il percorso persistente.

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

   Copia il percorso completo che punta al dongle SONOFF. Usa /dev/serial/by-id/..., non /dev/ttyUSB0, perché il nome numerico può cambiare.

3. Verifica che nessun altro stack usi il coordinatore. Arresta ZHA, un secondo Zigbee2MQTT o qualunque servizio che abbia aperto la seriale. Un coordinatore Zigbee non può essere gestito contemporaneamente da due applicazioni.
4. Configura il mapping Docker. Nel servizio Zigbee2MQTT mantieni il mapping seguente sostituendo il percorso a sinistra:

   devices:
     - /dev/serial/by-id/SONOFF_ZBDONGLE_P_REALE:/dev/ttyUSB0

   Verifica che il device interno corrisponda a quello indicato in configuration.yaml.
5. Imposta il file Zigbee2MQTT. In /opt/zigbee2mqtt/data/configuration.yaml usa:

   mqtt:
     server: mqtt://IP_O_HOSTNAME_MOSQUITTO:1883
     user: zigbee2mqtt
     password: PASSWORD_MQTT
     base_topic: zigbee2mqtt
   homeassistant:
     enabled: true
   frontend:
     enabled: true
   serial:
     port: /dev/ttyUSB0
     adapter: zstack

   zstack è il valore per il Dongle-P con firmware TI compatibile. Non cambiare a ember senza cambiare anche hardware/firmware e verificare la documentazione del modello.

6. Avvia Zigbee2MQTT.

   cd /opt/zigbee2mqtt
   docker compose config
   docker compose up -d zigbee2mqtt
   docker compose logs --tail=100 zigbee2mqtt

   Il log deve indicare l’apertura del coordinatore senza errori seriali.
7. Apri il frontend. Visita http://IP_DEL_SERVER:8080 e controlla in Settings → MQTT che broker, utente e topic siano corretti. In Settings → Advanced verifica il tipo adapter solo se richiesto dalla tua versione.
8. Metti in pairing un solo dispositivo. Abilita l’inclusione dal frontend, porta un sensore vicino al dongle per il primo abbinamento e poi disabilita l’inclusione. Allontana il sensore e verifica il routing della rete.
9. Collega Home Assistant via MQTT. Vai in Impostazioni → Dispositivi e servizi → Aggiungi integrazione → MQTT. Con discovery attiva in Zigbee2MQTT, il dispositivo dovrebbe comparire senza configurare manualmente ogni entità.
10. Esegui un backup prima degli aggiornamenti. Conserva /opt/zigbee2mqtt/data, in particolare database, configurazione e backup coordinator. Aggiorna solo dopo aver verificato compatibilità del firmware del dongle con la release Zigbee2MQTT.

Verifica del funzionamento

La configurazione è corretta quando il log mostra il SONOFF ZBDongle-P aperto con adapter zstack, il frontend risponde, il broker MQTT riceve i topic zigbee2mqtt/... e Home Assistant scopre il dispositivo. Riavvia il container e verifica che il percorso /dev/serial/by-id resti identico e che la rete Zigbee conservi i dispositivi.

Problemi comuni

FAQ essenziali

SONOFF ZBDongle-P e ZBDongle-E sono intercambiabili?

No. Sono modelli hardware differenti e possono richiedere stack e firmware differenti: ZBDongle-P normalmente usa zStack, mentre ZBDongle-E usa Ember/EZSP. Controlla sempre l’etichetta e il firmware installato.

Posso spostare il dongle su un altro server senza rifare il pairing?

Sì, se trasferisci la configurazione e il database Zigbee2MQTT, mantieni la stessa rete e usi un coordinatore compatibile. Crea prima un backup e non avviare contemporaneamente le due istanze.