Come installare Zigbee2MQTT con Docker Compose

Prerequisiti & Hardware Necessario

• Hardware: host Linux con Docker Engine, un coordinatore Zigbee USB compatibile con Zigbee2MQTT e una rete locale stabile. Il coordinatore è hardware radio; Zigbee2MQTT è il software che lo controlla.
• Software: Docker Compose v2, Eclipse Mosquitto già funzionante e Home Assistant con integrazione MQTT. Zigbee2MQTT richiede un broker MQTT: non comunica direttamente con Home Assistant.
• USB: collega il dongle direttamente al server oppure usa una prolunga USB schermata per allontanarlo da USB 3 e interferenze. Non usare un hub non alimentato per un coordinatore instabile.
• Accesso: privilegi sudo, directory persistente e identificativo seriale del dongle. Per un host Raspberry Pi 5 puoi usare un Raspberry Pi 5 4GB con alimentatore ufficiale.

Procedura passo-passo

1. Identifica il coordinatore sul sistema host.

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

   Usa il percorso completo /dev/serial/by-id/..., non un nome volatile come /dev/ttyUSB0 o /dev/ttyACM0.

2. Crea la directory dati.

   sudo install -d -m 0755 /opt/zigbee2mqtt/data
   cd /opt/zigbee2mqtt

3. Crea /opt/zigbee2mqtt/compose.yaml. Sostituisci il percorso del device e l’IP/hostname MQTT:

   services:
     zigbee2mqtt:
       container_name: zigbee2mqtt
       image: ghcr.io/koenkk/zigbee2mqtt:latest
       restart: unless-stopped
       volumes:
         - /opt/zigbee2mqtt/data:/app/data
         - /run/udev:/run/udev:ro
       ports:
         - "8080:8080"
       environment:
         TZ: Europe/Rome
       devices:
         - /dev/serial/by-id/USB_COORDINATORE_REALE:/dev/ttyACM0

   Il percorso a sinistra è quello dell’host; /dev/ttyACM0 è il nome interno al container.

4. Configura Zigbee2MQTT. In /opt/zigbee2mqtt/data/configuration.yaml inserisci valori coerenti con il broker e il firmware del coordinatore:

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

   adapter: zstack è solo un esempio: usa ember, deconz, zigate, zboss o altro valore previsto dal tuo coordinatore e firmware.

5. Avvia il container.

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

6. Completa la configurazione dal frontend. Apri http://IP_DEL_SERVER:8080. Se l’onboarding richiede dati mancanti, conferma broker MQTT, porta, utente, password e porta seriale. Non cambiare il canale Zigbee dopo aver associato dispositivi senza pianificare la rete.
7. Configura MQTT in Home Assistant. Vai in Impostazioni → Dispositivi e servizi → Aggiungi integrazione → MQTT e usa lo stesso broker, porta e credenziali. Con homeassistant.enabled: true, Zigbee2MQTT pubblica discovery e Home Assistant può creare automaticamente dispositivi ed entità.
8. Abbina un dispositivo Zigbee di prova. Apri il frontend Zigbee2MQTT, abilita temporaneamente l’inclusione, metti un sensore in pairing e poi disabilita l’inclusione. Verifica che il device compaia sia in Zigbee2MQTT sia in Home Assistant.
9. Aggiorna con cautela. Esegui un backup di /opt/zigbee2mqtt/data, quindi

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

   Non cancellare la directory dati: contiene rete, pairing e configurazione.

Verifica del funzionamento

La configurazione è corretta quando il container è Up, il log mostra il coordinatore aperto senza errori seriali, il frontend risponde sulla porta 8080 e un dispositivo abbinato viene pubblicato su MQTT e scoperto da Home Assistant. Riavvia il server e verifica che Zigbee2MQTT torni attivo con la stessa rete e gli stessi dispositivi.

Problemi comuni

FAQ essenziali

Posso usare Zigbee2MQTT e ZHA insieme?

Sì solo con coordinatori separati e reti Zigbee indipendenti. Non collegare lo stesso coordinatore a ZHA e Zigbee2MQTT contemporaneamente.

Devo usare il tag latest?

È semplice ma segue gli aggiornamenti. Per produzione, esegui backup e valuta un tag di versione specifico dopo aver controllato compatibilità di coordinatore, firmware e Home Assistant.