Zigbee2MQTT con Docker: installazione e collegamento a Home Assistant

di Chiara Bellini redattrice IA 17 ottobre 2026, 15:32

Illustrazione 3D di una persona al computer che configura hub e sensori domotici wireless. — Immagine generata con IA

Sensori di temperatura, contatti sulle finestre e lampadine Zigbee possono passare tutti da una sola chiavetta USB, collegata a un computer che resta acceso in casa. Zigbee2MQTT fa da ponte: riceve i dati dei dispositivi, li consegna a un broker MQTT e da lì li legge Home Assistant. Questa guida porta Zigbee2MQTT in un container Docker su Linux, con Mosquitto protetto da password, fino al primo sensore abbinato e al collegamento con Home Assistant. Si passa da Docker perché è la strada raccomandata nella pagina sull’installazione nativa. I comandi sono quelli della documentazione ufficiale, in fondo.

Cosa serve

L’hardware necessario è elencato nella pagina Getting started di Zigbee2MQTT. Per la strada con Docker si aggiunge qualche requisito:

Un adattatore Zigbee, cioè l’interfaccia fra il computer e la rete radio Zigbee. Si collega via USB, via GPIO oppure da remoto, via Wi-Fi o Ethernet. Zigbee2MQTT raccomanda gli adattatori zStack ed EmberZNet e consiglia di leggere la pagina del proprio modello prima di installare, perché alcuni modelli richiedono parametri aggiuntivi.
Un computer sempre acceso, per esempio un Raspberry Pi o un Intel NUC. La pagina usata qui per installare Docker Engine è scritta per Ubuntu: non copre Raspberry Pi OS né Debian. Zigbee2MQTT funziona anche su Windows e macOS, ma questa guida segue Linux.
Ubuntu a 64 bit: versioni 26.10, 26.04 LTS, 24.04 LTS o 22.04 LTS, su architetture x86_64 (amd64), armhf, arm64, s390x e ppc64le. Le derivate come Linux Mint non sono supportate ufficialmente, anche se secondo Docker possono funzionare. L’immagine di Zigbee2MQTT esiste per linux/386, linux/amd64, linux/arm/v6, linux/arm/v7, linux/arm64 e linux/riscv64.
Mosquitto già installato sullo stesso computer: è il broker MQTT raccomandato da Zigbee2MQTT, anche se altri dovrebbero funzionare. Le pagine consultate non ne spiegano l’installazione; la pagina Getting started rimanda a un tutorial per Raspberry Pi.
Almeno un dispositivo Zigbee da abbinare.

Trovare il percorso stabile della chiavetta Zigbee

Collegate la chiavetta, se potete con una prolunga USB: la documentazione la indica come il primo rimedio per portata e stabilità della rete, perché riduce le interferenze. Poi bisogna scoprire con che nome la vede Linux. La pagina Docker di Zigbee2MQTT chiede di usare sempre il percorso sotto /dev/serial/by-id/, non un nome generico come /dev/ttyACM0.

ls -l /dev/serial/by-id

Questo è l’esempio riportato nella pagina sulle impostazioni dell’adattatore:

lrwxrwxrwx. 1 root root 13 Oct 19 19 :26 usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00 - > .. / .. /ttyACM0

Vi serve il nome del collegamento dopo by-id/, la parte che comincia con usb-. Il percorso completo è /dev/serial/by-id/ seguito da quel nome. Il CC2531 dell’esempio serve solo a mostrare com’è fatto il percorso: nella vostra uscita comparirà il vostro adattatore. Annotatelo, va nel file di Compose.

Installare Docker Engine e il plugin Compose su Ubuntu

Se Docker è già installato potete saltare questa sezione. Altrimenti si usa il repository apt ufficiale descritto nella pagina di installazione di Docker Engine, che porta con sé anche il plugin Compose. Prima Docker chiede di rimuovere i pacchetti non ufficiali che possono andare in conflitto: docker.io, docker-compose, docker-compose-v2, docker-doc, docker-buildx, podman-docker e, se presenti, containerd e runc. Il comando è nella sezione «Uninstall old versions» della stessa pagina.

Un avviso sul firewall. Se lo gestite con ufw o firewalld, le porte dei container esposte da Docker scavalcano le vostre regole, quindi anche la porta 8080 dell’interfaccia web. Chi raggiunge l’interfaccia ha il controllo completo di Zigbee2MQTT, e la password di Mosquitto non la protegge: tenetela dentro la rete di casa e non esponetela su Internet senza autenticazione e cifratura. Docker inoltre è compatibile solo con iptables-nft e iptables-legacy; le regole create con nft non sono supportate. Se il computer protegge anche altri servizi, leggete prima la sezione «Firewall limitations» della pagina Docker.

Si comincia aggiornando l’elenco dei pacchetti e installando certificati e curl:

sudo apt update

sudo apt install ca-certificates curl

I tre comandi successivi creano la cartella delle chiavi, scaricano da download.docker.com la chiave GPG ufficiale di Docker e la rendono leggibile. Il file scaricato è una chiave, non uno script, e non viene eseguito; il chmod tocca solo quel file.

sudo install -m 0755 -d /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc

sudo chmod a+r /etc/apt/keyrings/docker.asc

Ora va aggiunto il repository. Nella pagina di Docker, subito dopo questi comandi, c’è un blocco che con sudo tee crea il file /etc/apt/sources.list.d/docker.sources: contiene le righe Types, URIs, Suites, Components, Architectures e Signed-By e ricava da solo versione di Ubuntu e architettura. Copiatelo così com’è nel terminale, poi aggiornate di nuovo l’elenco dei pacchetti:

sudo apt update

Installate i pacchetti di Docker, Compose compreso:

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Per la verifica c’è l’immagine di prova hello-world: il comando la scarica e la avvia in un container, che stampa un messaggio di conferma e si chiude. Se il messaggio compare, Docker Engine funziona.

sudo docker run hello-world

Creare l’utente di Zigbee2MQTT in Mosquitto

Zigbee2MQTT pubblica i dati dei sensori sul broker, e da lì li leggono gli altri programmi, Home Assistant compreso. La documentazione di Mosquitto sui metodi di autenticazione spiega che da Mosquitto 2.0 bisogna scegliere in modo esplicito come autenticare i client, altrimenti non possono collegarsi; nelle versioni precedenti i client entravano senza credenziali. Il manuale di mosquitto.conf aggiunge un dettaglio che qui conta: se nel file non è definito nessun listener, le connessioni sono ammesse solo dalla macchina locale. Il container di Zigbee2MQTT, per Mosquitto, non è la macchina locale: per questo serve un listener esplicito.

Il metodo più diretto è un file di password, creato con mosquitto_passwd, che chiede di digitare la password. Attenzione all’opzione -c: se il file esiste già lo sovrascrive, e gli utenti che conteneva si perdono. Usatela solo la prima volta; per aggiungere utenti a un file esistente si usa lo stesso comando senza -c. Al posto di <password file> mettete il percorso del file (Mosquitto suggerisce /etc/mosquitto/password_file), al posto di <username> il nome dell’utente, per esempio zigbee2mqtt.

mosquitto_passwd -c <password file> <username>

Poi in mosquitto.conf aggiungete il listener sulla porta 1883 e, dopo, l’opzione che indica il file delle password:

listener 1883
password_file /etc/mosquitto/password_file

Il file delle password deve essere leggibile dall’utente con cui gira Mosquitto, che su Linux di solito è mosquitto. Salvato il file, riavviate Mosquitto perché carichi il nuovo listener. Se più avanti cambiate solo il file delle password, a Mosquitto basta un segnale SIGHUP per rileggerlo.

La connessione sulla porta 1883 così configurata non è cifrata, e il manuale di Mosquitto raccomanda la cifratura di rete quando si usano le password, perché altrimenti possono essere intercettate. Mosquitto consiglia inoltre un controllo su chi può leggere quali topic: questa guida lo lascia fuori.

Scrivere il docker-compose.yml e avviare Zigbee2MQTT

Create una cartella dedicata e, al suo interno, un file docker-compose.yml basato sull’esempio della pagina Docker di Zigbee2MQTT. Sotto services: va un servizio zigbee2mqtt con queste voci:

container_name: zigbee2mqtt e image: ghcr.io/koenkk/zigbee2mqtt: il nome del container e l’immagine ufficiale.
restart: unless-stopped: il container parte all’accensione e si riavvia dopo un crash.
Sotto volumes:, le righe ./data:/app/data e /run/udev:/run/udev:ro. La prima è la cartella dove Zigbee2MQTT salva la configurazione, la seconda serve a rilevare l’adattatore in automatico.
Sotto ports:, la riga 8080:8080 per l’interfaccia web.
Sotto environment:, la riga TZ=Europe/Rome per il fuso orario (l’esempio ufficiale usa Berlino).
Sotto devices:, il vostro percorso by-id seguito da :/dev/ttyACM0. Prima dei due punti c’è il percorso sul computer, dopo quello che la chiavetta avrà dentro il container.

Dopo l’installazione il gruppo docker esiste ma è vuoto: se non avete seguito i passaggi post-installazione per Linux linkati dalla pagina di Docker, i comandi Docker vanno lanciati con sudo davanti, come per hello-world. Dalla cartella che contiene il file, avviate il container:

docker compose up -d zigbee2mqtt

Windows e macOS: cosa dicono le pagine consultate

La pagina Docker di Zigbee2MQTT descrive il passaggio della chiavetta al container solo da un computer Linux. Per Windows la documentazione di Zigbee2MQTT prevede l’installazione nativa, e la pagina sulle impostazioni dell’adattatore rimanda a istruzioni dedicate per trovare la porta. Per macOS le pagine consultate non danno una procedura dedicata.

Configurare Zigbee2MQTT dall’onboarding sulla porta 8080

Al primo avvio non esiste ancora un configuration.yaml, quindi Zigbee2MQTT apre una configurazione guidata sulla porta 8080. Di norma la pagina risponde all’indirizzo dell’interfaccia web, http://localhost:8080, ma con alcune configurazioni cambia.

La procedura cerca da sola i dispositivi seriali e quelli annunciati via mDNS; ricaricando la pagina la ricerca riparte. Se la chiavetta non compare, scrivete a mano percorso e tipo. Con il file di Compose di questa guida, dentro il container la chiavetta sta su /dev/ttyACM0. I tipi più comuni sono zstack, ember e deconz, più zigate e zboss: quello giusto è indicato nella pagina del vostro adattatore.

Nella stessa procedura vanno inseriti i dati del broker MQTT: l’indirizzo, l’utente e la password creati prima. Se Mosquitto gira sullo stesso computer, la pagina Docker suggerisce di raggiungerlo dal container con l’IP del bridge docker0, cioè mqtt://172.17.0.1.

Attenzione: data/configuration.yaml contiene le credenziali MQTT e la chiave della rete Zigbee. La pagina sulla sicurezza dell’installazione chiede di limitarne lettura e scrittura all’utente che esegue Zigbee2MQTT. Con il container di questa guida, dalla cartella di Compose usate sudo chmod 600 data/configuration.yaml: il comando cambia i permessi solo di quel file. Proteggete anche l’accesso alla cartella data, che contiene configurazione, stato della rete e dati dei dispositivi.

Se la configurazione non supera la validazione, la pagina mostra i dettagli dell’errore. Se invece Zigbee2MQTT non riesce a partire, per esempio per un percorso dell’adattatore sbagliato, l’onboarding ricomincia all’avvio successivo. Finita la procedura, Zigbee2MQTT parte. Controllate che in data/configuration.yaml il blocco frontend abbia enabled: true: il pulsante per abbinare i sensori sta lì, e secondo l’elenco delle impostazioni il frontend parte disattivato e la modifica richiede un riavvio.

Abbinare il primo sensore

La rete resta aperta 254 secondi, quindi conviene avere sotto mano le istruzioni del sensore prima di aprirla. Seguendo la pagina sull’ingresso dei dispositivi, la sequenza è questa:

Cercate il sensore nell’elenco dei dispositivi supportati (Supported devices) e cliccate sul numero di modello. Se la pagina ha istruzioni di abbinamento, tenetele aperte.
Nell’interfaccia web premete Permit join (All), in alto a destra nella barra di navigazione. Da quel momento la rete accetta nuovi dispositivi per 254 secondi.
Mettete il sensore in abbinamento seguendo le sue istruzioni. Se non ce ne sono, probabilmente basta riportarlo alle impostazioni di fabbrica.
Guardate il log. Quando compare una riga simile a questa, il dispositivo è abbinato e potete comandarlo dall’interfaccia e via MQTT:

Zigbee2MQTT:info 2019-11-09T12:19:56: Successfully interviewed '0x00158d0001dc126a', device has successfully been paired

Con lo stesso pulsante potete chiudere la rete prima che scada il tempo. La freccia accanto a Permit join (All) permette di scegliere da quale nodo far entrare il dispositivo, il coordinatore o un router. La documentazione la indica per i dispositivi che faticano a scegliere il router, come gli Aqara, ma precisa che non garantisce che quel router venga scelto né che resti quello nel tempo.

Aggiornare Zigbee2MQTT con Compose

Per passare all’ultima immagine, dalla cartella del file di Compose scaricate la nuova versione e riavviate il servizio:

docker compose pull zigbee2mqtt

docker compose up -d zigbee2mqtt

Se togliete zigbee2mqtt dai comandi, Compose scarica le immagini nuove di tutti i servizi del file e riavvia solo quelli aggiornati.

Collegare Zigbee2MQTT a Home Assistant

La pagina sull’integrazione con Home Assistant indica il discovery MQTT come il modo più semplice per collegare i due programmi: è Zigbee2MQTT ad aggiungere da sé i dispositivi a Home Assistant. Servono due passaggi:

Nel configuration.yaml di Zigbee2MQTT, che con Docker sta nella cartella data accanto al file di Compose, impostate homeassistant: e, sotto, enabled: true. Conservate le altre impostazioni e, se il blocco homeassistant esiste già, modificate quello. L’opzione ha effetto solo dopo un riavvio di Zigbee2MQTT.
In Home Assistant attivate l’integrazione MQTT.

Il discovery collega Zigbee2MQTT anche al registro dei dispositivi di Home Assistant: potete cambiare entity_id e friendly_name dall’interfaccia web senza riavviare Home Assistant, e vedere quali entità appartengono a ciascun dispositivo.

Se qualcosa va storto

«USB adapter discovery error (No valid USB adapter found)»: Zigbee2MQTT non ha rilevato l’adattatore da solo. Aprite data/configuration.yaml e compilate la sezione serial. Con il docker-compose.yml di questa guida, in port va /dev/ttyACM0, il percorso dopo i due punti nella voce devices, non il percorso by-id. In adapter va il tipo del vostro adattatore.
L’adattatore continua a non comunicare: controllate che sia in modalità USB. Alcuni modelli, come ZigStar, partono in modalità rete e non comunicano via USB finché non vengono passati in modalità USB.
L’onboarding resta su una pagina di errore: il processo rimane attivo finché non premete Close nella pagina o non lo chiudete a mano. Per rifare l’onboarding più avanti c’è la variabile d’ambiente Z2M_ONBOARD_FORCE_RUN=1.
Raspberry Pi 1 o Zero: per un bug, Docker sceglie l’architettura sbagliata. Prima di avviare il container la pagina Docker di Zigbee2MQTT indica di scaricare l’immagine giusta con docker pull ghcr.io/koenkk/zigbee2mqtt --platform linux/arm/v6.
Timeout, abbinamenti che non riescono, dispositivi che spariscono dalla rete: la prima cosa da fare è usare la prolunga USB. Per gli altri problemi di abbinamento la documentazione rimanda alle sue FAQ.

Documentazione di riferimento

Pagine consultate il 17 ottobre 2026: