community italiana di domotica personale
 
Troubleshooting ZigBee2MQTT: perché “non parte” e come risolvere

Troubleshooting ZigBee2MQTT: perché “non parte” e come risolvere

ZigBee2MQTT logoZigBee2MQTT è possibilmente il miglior BRIDGE/Gateway ZigBee in circolazione, affermazione comprovata anche da considerazioni e valutazioni specifiche.

Purtroppo, di contro talvolta risulta anche il più ostico da implementare, spece per i novellini della domotica DIY: data la vastita di parametri e delle configurazioni che è in grado di accettare, è altrettanto ampio il margine di rischio di fallire la prima configurazione e avvio.

Le nostre guide per l’implementazione sono:

Questa breve guida, invece, illustra i più classici errori che vengono effettuati dagli utenti, basandoci sull’esperienza della nostra chat e forum.

Broker MQTT

Che si implementi come add-on di Home Assistant OS o come container Docker su Mini PC o su Raspberry (o in altre modalità), in linea di massima la configurazione specifica di ZigBee2MQTT non differisce.

Il primo errore è quello di non disporre di un Broker MQTT correttamente installato e funzionante, oppure disporne ma averlo mal configurato sulla configurazione Zigbee2MQTT.

La porzione di configurazione yaml di ZigBee2MQTT è indicata come:

mqtt:
  # MQTT base topic per i messaggi di zigbee2mqtt
  base_topic: zigbee2mqtt
  # MQTT server - URL (indirizzo LAN)
  server: 'mqtt://IP_DEL_BROKER_MQTT'
  # MQTT server - Parametri di autenticazione (decommentare e popolare correttamente se si utilizzano credenziali per la connessione al broker MQTT
  user: NOME_UTENTE
  password: PASSWORD
  include_device_information: true

Se i log di ZigBee2MQTT (consultabili presso l’add-on se si usa Home Assistant OS/Supervised, in altri in console se si usa Docker o altro) riportano un errore di connessone verso il broker, del tipo:

Zigbee2MQTT:info  1980-01-01 08:00:34: Zigbee: disabling joining new devices.
Zigbee2MQTT:info  1980-01-01 08:00:34: Connecting to MQTT server at mqtt://XXX.XXX.XXX.XXX:1883
Zigbee2MQTT:error 1980-01-01 08:00:35: MQTT error: XXXXXXXXXXXXXXXXXXXX
Zigbee2MQTT:error 1980-01-01 08:00:35: MQTT failed to connect, exiting...

assicurarsi che:

  • se si opera su Home Assistant OS/Supervised, che le funzionalità MQTT siano attive su Home Assistant;
  • che il broker MQTT Eclipse Mosquitto (o quel che si sia scelto) sia in esecuzione;
  • in caso si usi Docker, di non aver indicato erroneamente 127.0.0.1 come IP alla voce server, bensì l’IP LAN dell’host ospitante;
  • username e password siano corretti.

Smarcando questi punti, la configurazione sarà dunque corretta e ZigBee2MQTT, su questo fronte, non dovrebbe più avere problemi.

Coordinator

il secondo scoglio, spesso quello principale, è quello legato al coordinator, ovvero “l’antenna” che il software utilizzerà per gestire la rete mesh ZigBee, definita nella sezione:

serial:

della configurazione di ZigBee2MQTT.

I coordinator sono sostanzialmente di due tipologie:

  • direttamente connessi all’host che ospita ZigBee2MQTT, solitamente via USB;
  • connessi via rete LAN/Wi-Fi.

I primi sono quelli solitamente più adottati. Ce ne sono alcuni che, malgrado siano fisicamente connessi via USB, tramite un firmware specifico (RCP) gli permettano l’uso contemporaneo con ZigBee e Thread, e vadano quindi collegati (per la parte ZigBee) a ZigBee2MQTT tramite un software intermedio, chiamato Silicon Labs Multiprotocol. Agli occhi di ZigBee2MQTT, questa connessione avviene quindi tramite LAN/Wi-Fi, sebbene in loopback sull’host stesso.

Ora: quando nei log si ricontra un errore del tipo:

Zigbee2MQTT:info  1980-01-08 08:00:53: Starting Zigbee2MQTT version X.XX.X (commit #unknown)
Zigbee2MQTT:info  1980-01-08 08:00:53: Starting zigbee-herdsman (X.XX.X)
Zigbee2MQTT:error 1980-01-08 08:01:38: Error while starting zigbee-herdsman
Zigbee2MQTT:error 1980-01-08 08:01:38: Failed to start zigbee
Zigbee2MQTT:error 1980-01-08 08:01:38: Check https://www.zigbee2mqtt.io/guide/installation/20_zigbee2mqtt-fails-to-start.html for possible solutions
Zigbee2MQTT:error 1980-01-08 08:01:38: Exiting...
Zigbee2MQTT:error 1980-01-08 08:01:38: Error: Failure to connect 

99 volte su 100 il problema sta nella cattiva configurazione del coordinator.

Le cose da verificare sono:

  • di non avere un altro BRIDGE/Gateway in esecuzione (eg. ZHA) e che usi il coordinator scelto;
  • sul mio coordinator USB ho installato un filrmware NCP (con quindi connessione diretta via USB) o RCP? In questo secondo caso, ho provveduto a configurare PRIMA e in modo corretto il software Silicon Labs Multiprotocol? Vedi guida ad hoc. Di fabbrica, i coordinator che prevedono questa opzione arrivano sempre già programmati NCP;
  • in caso di firmware NCP (o comunque in presenza di un coordinator “standard”, senza possibilità di firmware RCP), ho identificato il percorso corretto (eg. /dev/ttyACM0)?
  • se sto usando Proxmox per eseguire Home Assistant OS (sigh), ho “passato” correttamente la chiavetta USB alla macchina virtuale che ospita Home Assistant OS?
  • se sto usando Docker, lanciando il container ho “passato” la chiavetta USB a ZigBee2MQTT, mappandolo in modo corretto?
  • se stai usando Home Assistant OS su host dedicato (Mini PC, Raspebrry o altro che sia), hai verificato nella lista hardware che la chiavetta USB sia vista correttamente, e il suo indirizzo sia riportato correttamente nella configurazione di ZigBee2MTT (vedi guida).

Al netto di aver “passato” l’hardware ai contesti operativio dove gira ZigBee2MQTT, la configurazione di quest’ultimo varia in funzione delle tipologie di coordinator in uso:

I campi da personalizzare sono, principalmente:
  • "homeassistant";
  • "server";
  • "user" e "password";
  • "serial".
Il campo homeassistant nella configurazione proposta è impostato a true. Tale impostazione fa sì che - laddove lato Home Assistant l'integrazione MQTT abbia attiva "l'auto identificazione" (autodiscovery), questo fa sì che ogni qual volta venga associato un nuovo componente a ZigBee2MQTT automaticamente vengano create le relative entità lato Home Assistant. Se si adotta ZigBee2MQTT per usarlo con Home Assistant, il nostro consiglio è di lasciare inizialmente tale campo a false, così da concedere all'utente la possibilità di di definire eventualmente la proprie entità a mano (in ottica di "pulizia" e di maggiore versatilità). Diversamente, lasciare true.  Nel campo "server" va indicato il nostro broker MQTT: se si usa un proprio broker presente sulla rete, sarà ovviamente necessario indicare in questo campo l'indirizzo IP corretto; diversamente, se si è seguita la nostra guida per installare Mosquitto Broker, allora sarà necessario indicare semplicemente "mqtt://core-mosquitto" su Home Assistant Core/Supervised o "mqtt://ip-del-broker-mqtt" sulle altre installazioni (eg. su Docker). Nei campi "user" e "password", invece, è necessario indicare le credenziali d'accesso al broker MQTT, indipendentemente da dove esso sia in esecuzione. Infine, nel campo "port" indicare la porta precedentemente identificata. In ultimo, si noti il campo finale, "frontend", presso il quale è indicata al porta TCP/IP (tipicamente la 8080) presso la quale risponderà l'interfaccia web di gestione di ZigBee2MQTT.

PORTE COORDINATOR

La porzione in rosso nella configurazione di cui sopra (campo "serial") è particolarmente critica, perché prevede configurazioni specifiche in base al coordinator in uso. Se si sbaglia tale configurazione, il BRIDGE/Gateway non partirà. Vediamo alcune configurazione specifiche:

Phoscon ConBee o RaspBee

Se si utilizza un'antenna ConBee II, ConBee III o RaspBee II, aggiungere questa porzione:
serial:
  port: /dev/ttyXXX
  adapter: deconz
dove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente.

Sonoff ZBDongle-P

Se invece si usa la ITEAD Sonoff ZigBee 3.0 USB Dongle v1 (ZBDongle-P)  con firmware di fabbrica o Koenkk, aggiungere questa:
serial:
  port: /dev/ttyXXX
dove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente.

Sonoff ZBDongle-E con firmware NCP

Se invece si usa la ITEAD Sonoff ZigBee 3.0 USB Dongle Plus v2 (ZBDongle-E)  con firmware NCP (di fabbrica), aggiungere questa:
serial:
  port: /dev/ttyXXX
  adapter: ember 
dove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente.

Sonoff ZBDongle-E con firmware RCP

Se invece si utilizza il firmware MultiPan RCP per l'uso contemporaneo anche dello standard Thread (comunque non consigliato per questioni di stabilità), la configurazione cambia; l'abbiamo spiegata qui.

Sonoff ZigBee Bridge Pro (ZB Bridge-P)

Dopo aver provveduto alla configurazione del firmware Tastmota sul coordinator, la configurazione è la seguente:
port:
 tcp://indirizzo_ip_tasmota:8888
dove indirizzo_ip_tasmota va sostituito con l'indirizzo IP assegnato (staticamente) al coordinator dotato di firmware Tasmota.

Z-Wave.Me Z-Station con firmware NCP

Se invece si usa la Z-Station di Z-Wave.ME con firmware NCP (di fabbrica), aggiungere questa:
serial:
  port: /dev/ttyXXX
  adapter: ember 
dove /dev/ttXXX va sostituito con la porta logica assegnata al coordinator e individuata precedentemente.

Z-Wave.Me Z-Station con firmware RCP

Se invece si utilizza il firmware MultiPan RCP per l'uso contemporaneo anche dello standard Thread (comunque non consigliato per questioni di stabilità), la configurazione cambia; l'abbiamo spiegata qui.

Altro

Ulteriori dettagli relativi alle configurazioni (queste o altre possibili) sono forniti qui.
 

Infine

ZigBee2MQTT riporta un esteso articolo sulle più comuni cause di malfunzionamento. Se il presente vademecum non vi ha aiutati, provate a consultare anche quello (in inglese).

Alle brutte, c’è la nostra chat e il nostro forum.

Questa pagina è redatta, manutenuta e aggiornata dallo staff di inDomus, un gruppo di persone molto diverse tra loro che trovi, per domande e supporto, sul forum e sulla chat del sito. Alcuni link sono taggati in qualità di affiliati Amazon e riceviamo un compenso dagli acquisti idonei, utile al sostenimento del sito, ma le nostre recensioni sono tutte indipendenti e non sponsorizzate. Se ti sei perso, a tua disposizione c'è la mappa.