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

Prerequisiti & Hardware Necessario

• Hardware: SONOFF Zigbee 3.0 USB Dongle Plus (ZBDongle-E) con firmware coordinator EmberZNet compatibile, host Linux con Docker e prolunga USB schermata. Il dongle è hardware; Zigbee2MQTT è software.
• Software: Docker Engine, Docker Compose v2, Zigbee2MQTT e broker MQTT Mosquitto. Il ZBDongle-E non va configurato con zstack: usa l’adapter ember.
• Rete: broker MQTT raggiungibile in LAN, Home Assistant con integrazione MQTT e nessun altro servizio che usi il dongle. Il firmware multiprotocollo non è il percorso supportato per questa configurazione Zigbee2MQTT.
• Host: Raspberry Pi 5 con alimentazione adeguata, ad esempio Raspberry Pi 5 4GB con alimentatore ufficiale, oppure mini PC/VM Linux con USB passthrough.

Procedura passo-passo

1. Collega il dongle in modalità USB. Usa una prolunga USB schermata, lontano da USB 3 e SSD NVMe. Non collegare lo stesso ZBDongle-E contemporaneamente a ZHA e Zigbee2MQTT.
2. Identifica il percorso persistente.

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

   Copia il percorso completo del SONOFF e non usare direttamente /dev/ttyUSB0 o /dev/ttyACM0 sul sistema host.

3. Verifica firmware e modello. Controlla l’etichetta ZBDongle-E e usa un firmware coordinator EmberZNet compatibile con la release di Zigbee2MQTT. Non aggiornare il firmware senza un backup e senza verificare la procedura del produttore/firmware builder.
4. Configura il mapping Docker. Nel servizio Zigbee2MQTT sostituisci il percorso a sinistra:

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

5. Imposta configuration.yaml. 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: ember

   Il valore moderno è ember; ezsp è deprecato nella documentazione Zigbee2MQTT. Non sostituirlo con zstack.

6. Avvia Zigbee2MQTT e leggi il log.

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

   Il log deve mostrare l’avvio dell’Ember adapter senza errori NCP/EZSP.
7. Controlla il frontend. Apri http://IP_DEL_SERVER:8080 e verifica broker MQTT, credenziali, porta seriale e adapter. Se la configurazione iniziale si ripresenta dopo ogni riavvio, il file dati non è persistente o non è scrivibile.
8. Abbina un dispositivo di prova. Abilita l’inclusione, metti un sensore in pairing vicino al coordinatore e poi disabilita l’inclusione. Allontana il sensore dopo il primo abbinamento e controlla i messaggi ricevuti.
9. Collega Home Assistant. In Impostazioni → Dispositivi e servizi → Aggiungi integrazione → MQTT inserisci lo stesso broker. Con homeassistant.enabled: true, la discovery Zigbee2MQTT crea automaticamente dispositivi ed entità.
10. Esegui backup prima di aggiornare. Conserva /opt/zigbee2mqtt/data, inclusi database e backup coordinator. Aggiorna l’immagine solo dopo aver verificato compatibilità fra firmware EmberZNet e Zigbee2MQTT.

Verifica del funzionamento

La guida è completata quando il log mostra l’Ember adapter attivo, il frontend risponde, MQTT riceve i topic zigbee2mqtt/... e Home Assistant scopre il dispositivo abbinato. Riavvia il container e controlla che il percorso /dev/serial/by-id resti uguale e la rete conservi il pairing.

Problemi comuni

FAQ essenziali

Posso usare il firmware multiprotocollo con Zigbee2MQTT?

La documentazione Zigbee2MQTT indica il firmware multiprotocollo come non supportato per EmberZNet in questo scenario. Usa un firmware coordinator Zigbee dedicato e una rete per coordinatore.

Devo rifare il pairing passando da ZBDongle-P a ZBDongle-E?

La sostituzione del coordinatore può richiedere il ripristino di un backup compatibile o il re-pairing. Esegui un backup e verifica la procedura di migrazione prima di spegnere la rete attuale.