Come usare Zigbee2MQTT con chiavetta USB: guida al setup

Per usare Zigbee2MQTT servono quattro elementi: un adattatore Zigbee collegato via USB, un host che esegue il software, un broker MQTT che smista i messaggi e i dispositivi Zigbee da abbinare alla rete. Secondo Zigbee2MQTT (2026), per l’adattatore sono consigliati i firmware zStack, EmberZNet e deCONZ, mentre come host sono indicati Raspberry Pi, Intel NUC o un computer con Linux, Windows o macOS. Ogni componente svolge un ruolo distinto, e conoscere questa suddivisione aiuta a capire dove si trova un problema di connessione.

Componenti necessari e ruolo di ciascuno

Requisiti dell’host

L’host deve poter ospitare Zigbee2MQTT e collegarsi fisicamente all’adattatore. Sono indicati come esempi Raspberry Pi e Intel NUC, oltre a sistemi Linux, Windows e macOS. Per i requisiti hardware minimi (memoria, processore, spazio su disco), consultare la documentazione ufficiale di Zigbee2MQTT.

Collegamento dell’adattatore all’host

Al primo avvio, in assenza del file configuration.yaml, Zigbee2MQTT apre una pagina di onboarding su http://localhost:8080, dove si imposta il tipo di adattatore e la porta seriale. Gli adattatori Wi-Fi possono essere meno stabili: se non è possibile usare un adattatore USB o UART locale, Zigbee2MQTT (2026) raccomanda un adattatore remoto collegato via Ethernet cablato.

Installazione del broker Mosquitto

Mosquitto è il broker consigliato da Zigbee2MQTT (2026). Va installato sullo stesso host, o su un’altra macchina raggiungibile in rete, e poi indicato nella configurazione di Zigbee2MQTT. Per l’installazione e la configurazione, consultare la documentazione di Mosquitto e della propria distribuzione.

Quale chiavetta USB Zigbee scegliere

Per scegliere un adattatore Zigbee bisogna controllare tre elementi: il chip, il firmware coordinator supportato e il tipo di collegamento all’host. Secondo Zigbee2MQTT (2026), gli stack consigliati sono zStack ed EmberZNet, e, per i chip CC2652 e CC1352, il suffisso determina la potenza massima di trasmissione. Un adattatore deve avere il firmware coordinator prima dell’uso, quindi il chip e lo stack vanno verificati prima dell’acquisto.

Chip CC2652 e CC1352: differenze di potenza

I chip CC2652 e CC1352 con suffisso P integrano un amplificatore di potenza. Le versioni R e RB non ne hanno uno.

Un valore più alto in dBm indica una potenza di uscita maggiore. La potenza non si traduce in una portata fissa in metri, perché la copertura reale dipende dagli ostacoli e dall’ambiente della casa.

Stack firmware supportati

Secondo Zigbee2MQTT (2026), lo stack zStack (Texas Instruments) ed EmberZNet (Silicon Labs) sono quelli consigliati. Anche lo stack deCONZ è tra i firmware consigliati, ma non supporta il backup del coordinatore: se si vuole questa funzione, conviene scegliere zStack o EmberZNet.

Se il sistema non rileva l’adattatore, può essere necessario un driver USB-UART VCP, secondo quanto indicato da Zigbee2MQTT (2026).

Adattatori USB, Wi-Fi ed Ethernet a confronto

Un adattatore Ethernet cablato remoto va posizionato lontano dall’host, nella zona della casa dove serve la copertura Zigbee, e collegato alla rete tramite cavo.

Il firmware coordinator è già installato?

Prima di configurare Zigbee2MQTT, occorre capire se la chiavetta USB è già programmata con il firmware coordinator. Un adattatore deve avere questo firmware prima dell’uso: alcuni modelli arrivano preflashati di fabbrica, altri richiedono un flashing manuale. Il firmware determina lo stack Zigbee che gestisce la rete, quindi la scelta va fatta in base a supporto e manutenzione.

Adattatori con firmware preflashato di fabbrica

Verificare se il firmware è presente è il primo passo: l’adattatore con firmware già caricato si collega e viene riconosciuto dal sistema senza ulteriori operazioni. Le informazioni sul firmware installato si trovano nelle istruzioni o nella scheda tecnica del produttore; in caso di dubbio, conviene consultare la documentazione del prodotto specifico (Zigbee2MQTT, 2026).

Confronto tra zStack, EmberZNet e deCONZ

Zigbee2MQTT indica tre firmware consigliati, con caratteristiche diverse:

ZiGate non mantenuto e ZBOSS sperimentale

Non tutti i firmware sono adatti a un uso continuativo. Zigbee2MQTT segnala che ZiGate non è più mantenuto, quindi gli adattatori con questo firmware non dovrebbero essere scelti per una nuova installazione. Il firmware ZBOSS è sperimentale e va trattato come opzione per test, non per una casa in funzione h24 (Zigbee2MQTT, 2026).

Come collegare la chiavetta e trovare la porta

Zigbee2MQTT comunica con l’adattatore attraverso una porta seriale: il sistema host deve riconoscere la chiavetta come porta seriale virtuale, e il software deve puntare a quella porta. Il collegamento fisico è immediato, ma il nome assegnato dal sistema può cambiare dopo un riavvio o una riconnessione, quindi conviene annotare la porta fin dall’inizio.

Collegamento diretto o tramite prolunga USB

Collega l’adattatore a una porta USB dell’host oppure usa una prolunga USB. Secondo Zigbee2MQTT (2026), una prolunga USB può migliorare portata e stabilità. In pratica, la prolunga permette di spostare la chiavetta dal retro dell’host verso una posizione più centrale rispetto ai dispositivi Zigbee da controllare, senza modificare la configurazione del software.

Individuare la porta seriale sull’host

Un metodo pratico consiste nel confrontare l’elenco delle porte prima e dopo il collegamento: la voce nuova dovrebbe corrispondere all’adattatore, da verificare con dmesg subito dopo il collegamento.

I nomi della tabella sono esempi tipici: il numero o il suffisso reale dipende dal sistema e dal chip dell’adattatore.

Nomi di porta su Linux

Su Linux, nomi come /dev/ttyUSB0 possono cambiare dopo un riavvio o una riconnessione, per esempio se si collegano altre periferiche seriali; un consiglio da fonti secondarie non verificate (IOTstack) è usare il percorso /dev/serial/by-id/. Il comando dmesg mostra la porta assegnata subito dopo il collegamento, e questa è la verifica da ripetere dopo ogni riavvio.

Come configurare Zigbee2MQTT al primo avvio

Quando Zigbee2MQTT si avvia senza un file configuration.yaml, mostra una pagina di onboarding all’indirizzo predefinito http://localhost:8080, raggiungibile dal browser della macchina che esegue il servizio. Da questa pagina si impostano due parametri hardware: il tipo di adattatore e la porta seriale a cui è collegata la chiavetta. Secondo la documentazione di Zigbee2MQTT (2026), è il metodo previsto per la configurazione iniziale.

Scegliere il tipo di adattatore

Il tipo selezionato deve corrispondere al firmware coordinator caricato sulla chiavetta. Alcuni adattatori sono già preflashati, mentre altri devono essere flashati prima dell’uso. I firmware citati nella documentazione sono:

zStack, EmberZNet e deCONZ sono i firmware consigliati.

Impostare la porta seriale

Nel campo della porta seriale si inserisce il percorso con cui il sistema operativo identifica la chiavetta. Il valore va scritto esattamente come rilevato sul sistema host e controllato prima di salvare la configurazione.

Come abbinare i dispositivi Zigbee?

L’abbinamento si svolge in due fasi: prima si verifica nell’elenco dei dispositivi supportati come entrare in modalità di abbinamento sul modello specifico, poi si attiva quella modalità sul dispositivo mentre Zigbee2MQTT è in ascolto.

Consultare l’elenco dei dispositivi supportati

Prima di iniziare, cerca il modello esatto del dispositivo, indicato di solito sull’etichetta o sulla confezione, nell’elenco ufficiale di Zigbee2MQTT. Ogni scheda descrive la procedura di abbinamento per quel modello. Un prodotto con lo stesso nome commerciale ma una revisione hardware diversa può avere una procedura differente, quindi conviene confrontare la sigla e non soltanto il marchio.

Attivare la modalità di abbinamento sul dispositivo

La modalità di abbinamento (in inglese pairing mode) è lo stato in cui il dispositivo cerca una rete Zigbee a cui unirsi. Il metodo di attivazione dipende dal produttore: di norma si tiene premuto un pulsante o si ripete un’accensione e spegnimento della luce, come indicato nelle istruzioni del modello.

Se l’elenco non riporta una procedura per quel modello, Zigbee2MQTT (2026) indica che spesso funziona un reset di fabbrica. Il reset cancella eventuali abbinamenti precedenti, quindi conviene eseguirlo anche per dispositivi già usati con un altro hub.

Verificare l’abbinamento nel log

Mentre il dispositivo è in modalità di abbinamento, Zigbee2MQTT deve essere in funzione e l’adattatore deve essere attivo. L’abbinamento riuscito compare nel log del servizio.

Cosa fare se la chiavetta non viene rilevata?

Se il sistema operativo non vede la chiavetta, il problema può dipendere da driver, porta o permessi, prima ancora che da Zigbee2MQTT. Zigbee2MQTT segnala che, quando il sistema non rileva l’adattatore, può servire un driver USB-UART VCP (Zigbee2MQTT, 2026). Conviene quindi verificare in quest’ordine: driver, nome della porta, permessi di accesso.

Installare il driver USB-UART VCP

Il driver VCP (Virtual COM Port) fa comparire il chip USB-UART della chiavetta come porta seriale virtuale. Il procedimento generale è:

1. Scollegare la chiavetta e individuare il chip USB-UART (spesso indicato sulla scheda o nella scheda tecnica del prodotto).
2. Scaricare il driver VCP dal sito del produttore del chip, non da repository di terze parti.
3. Installare il driver, riavviare il sistema e ricollegare la chiavetta.
4. Controllare che compaia una nuova porta seriale nel sistema (vedi sezione successiva).

Su Linux conviene verificare con il comando dmesg subito dopo il collegamento se il dispositivo viene riconosciuto, prima di installare altro.

Verificare il nome della porta nel sistema

Zigbee2MQTT richiede la porta seriale corretta durante l’onboarding. Il nome cambia in base al sistema:

Permessi di accesso alla porta seriale su Linux

Anche con la porta visibile, il processo di Zigbee2MQTT può non avere il permesso di aprirla. Il controllo è questo:

• Eseguire ls -l /dev/ttyUSB0 (o il nome trovato) e leggere il gruppo proprietario della porta.
• Verificare che l’utente che avvia Zigbee2MQTT appartenga a quel gruppo con il comando groups.
• Se manca, aggiungere l’utente al gruppo: su molte distribuzioni Debian e Ubuntu il gruppo è dialout, quindi sudo usermod -aG dialout $USER.
• Disconnettersi e riaccedere, perché la nuova appartenenza al gruppo vale solo dalla sessione successiva.

Come fare il backup della rete Zigbee?

Il backup del coordinatore è la copia di sicurezza dello stato della rete Zigbee: chiavi, identificativi e dispositivi abbinati. Con Zigbee2MQTT, questa operazione produce un file coordinator_backup.json, generato dal coordinatore stesso. Il file serve a ripristinare la rete se la chiavetta si guasta o viene sostituita, ma funziona solo con alcuni tipi di adattatore.

File coordinator_backup.json generato dal coordinatore

Il file coordinator_backup.json viene creato dal coordinatore Zigbee. Va conservato in un luogo separato dal sistema host, perché contiene le informazioni necessarie a ricostruire la rete. Il backup va rifatto dopo modifiche rilevanti alla rete, come l’aggiunta o la rimozione di molti dispositivi, così da avere una copia aggiornata.

Adattatori compatibili: solo zStack ed EmberZNet

Solo gli adattatori con firmware zStack (Texas Instruments) ed EmberZNet (Silicon Labs) supportano il backup del coordinatore.

Riabbinamento dei dispositivi dopo cambio adattatore

Cambiare adattatore può richiedere di riabbinare tutti i dispositivi Zigbee. Il ripristino del file coordinator_backup.json riduce questa necessità solo quando il nuovo adattatore è dello stesso tipo supportato. Per riabbinare un dispositivo, consultare le istruzioni nell’elenco dei dispositivi supportati di Zigbee2MQTT; in mancanza, spesso funziona un reset di fabbrica. L’abbinamento riuscito compare nel log di Zigbee2MQTT.

Letture correlate

• Hub Zigbee compatibile con Apple Home: come funziona il bridge
• Border router Thread per Matter: cos’è e come funziona
• Hub Matter Thread: quale scegliere nel 2026 per la tua casa smart