Integrare componenti Zigbee a Home Assistant via zigbee2mqtt (parte 2)

8 minuti di lettura
SCOPI DELLA GUIDA:
  • Integrare un componente ZigBee con Home Assistant utilizzando il BRIDGE/Gateway software zigbee2mqtt
  • Livello di difficoltà: medio
CONCETTI AFFRONTATI:
  • Utilizzo e configurazione software
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
  • Il computer sul quale risiede Home Assistant
  • il componente ZigBee da integrare
GUIDA maggiormente indicatA per:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere progettata ed effettuata da personale qualificato;
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno puro scopo didattico);
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere garanzia, omologazioni e certificazioni di qualità.
Revisione guida: 1.1

Abstract

Il protocollo ZigBee.

Come sappiamo l’iteroperabilità tra componenti basati su questo protocollo ma di diverse tipologie e diversi produttori è spesso – anzi, quasi sempre – un problema. Esistono infatti interessantissimi componenti ma di linee molto diverse tra loro e, non potendo pensare di acquistare un BRIDGE/Gateway per ciascuna delle linee prodotti, spesso ci si trova davanti alla scelta di doversi “accontentare” di una linea prodotti rinunciando magari ad altri singoli componenti che ci interesserebbe introdurre in domotica.

Altro prodotto di questa situazione è, spesso, l’impossibilità di integrare il BRIDGE/Gateway (e quindi i componenti ZigBee ad esso collegati) col proprio HUB personale, come nel caso di quello della linea LUMI Aqara – non fosse che, per fortuna, i componenti (validissimi) di questa linea sono gestibili anche dal gateway Xiaomi Mijia, il quale è integrabile con Home Assistant. Quando dei componenti ZigBee non sono altrimenti controllabili se non col “proprio” gateway (magari non integrabile col nostro Home Assistant), in sostanza diventano inutili, se non nell’ambito del proprio ecosistema e della propria app mobile.

Per salvare capra e cavoli esiste un’ottima soluzione, ovvero quella di implementare presso la nostra domotica un BRIDGE/Gateway ZigBee↔︎TCP/IP avulso dalle logiche dei singoli produttori: la risposta è data dalla sinergia di zigbee2mqtt (componente software) il dongle USB CC2531 (componente hardware), un’accoppiata che permette di censire il più alto numero di componenti ZigBee possibile scavalcando i problemi di cui sopra. Ovviamente, tale BRIDGE/Gateway “standard” è pienamente integrabile con Home Assistant.

In questa guida vedremo quali siano i passi per integrare un componente ZigBee su Home Assistant utilizzando appunto zigbee2mqtt quale BRIDGE/Gateway, il quale si intende già installato e configurato.

N.b. Questa guida, “parte 2“, serve per capire come integrare i componenti ZigBee a Home Assistant. La “parte 1” illustra invece come installare e configurare zigbee2mqtt (conditio sine qua non per procedere con la presente). Tale “guida parte 1” è disponibile per gli utenti che abbiano Home Assistant installato come applicativo su Raspbian oppure che utilizzino la distribuzione HASSIO.

N.b. Alternativa al binomio zigbee2mqtt+CC2531 è l’adozione di deCONZ+ConBee/RaspBee, non oggetto di questa specifica guida.

Si parte

Come funziona

Prima di proseguire, porsi la domanda: conosco MQTT? Se la risposta sì, bene, altrimenti provvedere a un approfondimento su questo protocollo. La guida dà per scontato che, quando si fa riferimento a comandi e telemetrie MQTT, si sappia di che si sta parlando, almeno a grandi linee.

Dunque, come funziona zigbee2mqtt, e perché ci consente di integrare componenti ZigBee?
Arrivati sin qui dovrebbe già essere chiaro, ma qualora non lo fosse, repetita iuvant.

zigbee2mqtt permette, tramite l’antenna CC2531, di fare da ponte tra il protocollo ZigBee e il protocollo MQTT; quest’ultimo è ben compreso e gestito da Home Assistant, il quale riesce così ad integrare eventuali componenti ZigBee compatibili con zigbee2mqtt. Questo “fare ponte” significa “tradurre” il protocollo ZigBee in messaggi MQTT, da e per il componente.

Il processo server di zigbee2mqtt è esso stesso un client MQTT pertanto, per comandarne i comportamenti suoi e dei componenti ZigBee ad esso connessi, va da sé che si si usino messaggi MQTT.

Quando si collega un componente ZigBee a zigbee2mqtt (procedura di pairing), esso ne registra – per così dire – l’identità univoca, generando così un set di telemetrie e di comandi MQTT da e per il componente. Da qui in poi il suo mestiere sarà finito. Quando arriverà una telemetria via ZigBee dal componente (per esempio, una temperatura da un sensore termico), pubblicherà sul broker MQTT il messaggio di telemetria, ovviamente “battezzato” col “nome” del componente che l’ha generata. Dato che zigbee2mqtt avrà anche sottoscritto sul broker i topic di comando per quel componente, se si pubblicherà un comando MQTT sul broker zigbee2mqtt lo riceverà e lo girerà al componente via zigbee. E via così.

Dunque, è chiaro come zigbee2mqtt non si colleghi direttamente a Home Assistant, ma si limiti a “parlare” con il broker MQTT.

Home Assistant, dal canto suo, è anch’esso connesso al broker MQTT: se l’autodiscovery è attiva (cosa che consigliamo di attivare nella “parte 1” della guida), alla prima pubblicazione sul broker da parte di zigbee2mqtt della disponibilità di un nuovo componete ZigBee tramite esso censito (comunicato con uno speciale messaggio MQTT di “presentazione”, per così dire), Home Assistant provvede a creare automaticamente delle entità le quali, ovviamente, riceveranno stati e invieranno comandi tramite MQTT nella logica sopra descritta.

zigbee2mqtt architecture

Pairing

Il pairing, ovvero l’associazione di un dispositivo ZigBee con zigbee2mqtt, avviene impostando quest’ultimo in questa modalità specifica. Per farlo è possibile perseguire due strade:

  • impostarla “fissa”, in modo che il BRIDGE/Gateway sia sempre in ascolto di nuovi componenti (fortemente sconsigliata);
  • attivarla temporaneamente:
    • vi comando manuale;
    • via interfaccia.
PAIRING FISSO

Per far sì che zigbee2mqtt sia perennemente attivo nella modalità pairing (ma lo sconsigliamo fortemente per una questione di performance e corretto funzonamento) è necessario:

  • su Home Assistant installato come applicativo su Rasbian, modificare il file “opt/zigbee2mqtt/data/configuration.yaml” impostando a “true” il campo “permit_join” e riavviando poi il servizio (comando da terminale “sudo systemctl restart zigbee2mqtt“);
  • su HASSIO, modificare la configurazione dell’add-on (stoppandolo, prima) impostando a “true” il campo “permit_join” (e poi salvare e riavviare l’add-on).

A questo punto (dopo il riavvio del servizio/dell’add-on) sarà sufficiente premere il pulsante di pairing posto sul compnente ZigBee da integrare (far riferimento alla documentazione ufficiare del componente stesso per scoprire come attivare la modalità di pairing) e attendere qualche secondo. Il componente, se compatibile con zigbee2mqtt, verrà integrato al BRIDGE/Gateway.

PAIRING TEMPORANEO

Per attivare temporaneamente la modalità di pairing lato zigbee2mqtt è necessario pubblicare uno specifico comando MQTT su broker. Tale comando è solitamente:

zigbee2mqtt/bridge/config/permit_join true

mentre quello per interrompere la modalità di pairing:

zigbee2mqtt/bridge/config/permit_join false

Per inviare tale comando MQTT è possibile:

  • farlo manualmente via client MQTT;
  • inviarlo automaticamente via interfaccia Home Assistant.

Per farlo manualmente è possibile utilizzare un qualsiasi client MQTT connesso al broker oppure il client Home Assistant presso la sua interfaccia (“Strumenti per gli sviluppatori” > “MQTT“).

Se invece si è seguita alla lettera la “parte 1” di questa guida (vedi i link nell’Abstract) è possibile attivare automaticamente la modalità di pairing semplicemente attivando lo switch “Zigbee2mqtt Main join“, il quale altro non fa – sotto il cofano – che inviare i comandi MQTT di cui sopra:

Home Assistant - zigbee2mqtt mqin join switch

Per i seguenti due minuti (come da timer “Time remaining“) sarà possibile collegare al BRIDGE/Gateway un nuovo componente ZigBee: a questo punto sarà sufficiente premere il pulsante di pairing posto sul compnente ZigBee da integrare (far riferimento alla documentazione ufficiare del componente stesso per scoprire come attivare la modalità di pairing) e attendere qualche secondo. Il componente, se compatibile con zigbee2mqtt, verrà integrato al BRIDGE/Gateway.

N.b. Il paring temporaneo – sebbene consigliato – talvolta può causare problemi, il più tipico è quello di non consentire ai componenti ZigBee che si tenta di integrare di entrare nella rete. In caso, utilizzare il pairing fisso.

Home Assistant

Come spiegato prima, dopo l’avvenuto pairing zigbee2mqtt “presenta” questo nuovo componente tramite un messaggio MQTT pubblicato al broker, dopodiché comincia a girare eventuali telemetrie MQTT e a restare in ascolto di eventuali comandi MQTT destinati a quel componente.

INTEGRAZIONE AUTOMATICA

Se la guida “parte 1” (vedi i link nell’Abstract) è stata eseguita alla lettera, Home Assistant raccoglierà – grazie alla presenza dell’auto-discovery MQTT – il messaggio di “presentazione” del componente pubblicato da zigbee2mqtt, il quale contiene tutte le “coordinate” di configurazioni utili all’HUB per generare delle entità le quali sfrutteranno le telemetrie e i comandi da e per il componente (veicolate via MQTT) appena integrato. Questa è la strada più semplice nonché quella caldamente consigliata.

Ricapitolando: se Home Assistant ha attivato l’auto-disocovery MQTT (come indicato di fare nella “parte 1” della guida), successivamente il pairing di un componente ZigBee con zigbee2mqtt appariranno nuove entità presso l’HUB in modo automatico.

Per esempio, ecco a seguire l’elenco delle entità derivanti dall’integrazione di un sensore termico Xiaomi:

Home Assistant - Xiaomi sensore di temperatura via zigbee2mqtt

Dato che alcun “friendly name” viene attribuito all’entità, presso il frontend Lovelace UI i nomi riportati sono quelli originali. Come si legge nell’immagine, tutte le entità hanno un nome che comincia con “0x0…“, tratto distintivo delle entità integrate via zigbee2mqtt (non è un fatto solo di cultura: è una cosa che serve conoscere più avanti).

N.b. Su HASSIO è possibile “scoprire” i nomi automaticamente assegnati ai componenti integrati alla voce “HASSIO” > “Dashboard” > “zigbee2mqtt” e, in fondo alla scheda, verificare tramite il LOG il “nuovo ingresso”.
INTEGRAZIONE MANUALE

Laddove – per motivi che possono essere i più diversi a partire dalla volontà di personalizzazione spinta – non si voglia utilizzare l’auto-discovery, zigbee2mqtt lascia la libertà all’utente di configurare, come meglio crede, le proprie entità presso Home Assistant.

Per farlo è necessario far riferimento al database di componenti supportati: ogni componente ha la propria lista di codici da aggiungere alla configurazione di Home Assistant.

Nel caso del sensore di cui sopra, usato a mo’ d’esempio, la scheda di riferimento è questa: nel suo caso, il codice è:

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "°C"
    device_class: "temperature"
    value_template: "{{ value_json.temperature }}"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "%"
    device_class: "humidity"
    value_template: "{{ value_json.humidity }}"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "hPa"
    device_class: "pressure"
    value_template: "{{ value_json.pressure }}"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "%"
    device_class: "battery"
    value_template: "{{ value_json.battery }}"

sensor:
  - platform: "mqtt"
    state_topic: "zigbee2mqtt/NOME_COMPONENTE"
    availability_topic: "zigbee2mqtt/bridge/state"
    unit_of_measurement: "-"
    value_template: "{{ value_json.linkquality }}"

Ovviamente il “NOME_COMPONENTE” andrà personalizzato con la stringa usata da zigbee2mqtt per “battezzare” il componente; nell’esempio di cui sopra sarebbe “0x00158d0002f2dccc“.

Per scoprire tale stringa è necessario posizionarsi in ascolto sul broker MQTT consultando tutti i messaggi che passano per intuire quale sia il nome; se si usa RRaspbian (e Mosquitto), un comando tipo potrebbe essere il seguente:

mosquitto_sub -d -v -t +/# -h localhost -u username -P password | grep zigbee2mqtt

Diversamente, è possibile allo stesso scopo utilizzare un client MQTT qualsiasi per collegarsi al broker MQTT e sottoscrivere i messaggi “zigbee2mqtt/#” (ovvero “tutti quelli che cominciano con ‘zigbee2mqtt‘ “).

Cancellazione

Cancellare: dipende cosa si intende. Una cosa è cancellare l’entità presso Home Assistant, una cosa è rimuovere il pairing di un componente ZigBee presso zigbee2mqtt.

Nel primo caso, la pratica da effettuare varia in base a come è stata creata: automaticamente (tramite auto-discovery) o manualmente (tramite configurazione manuale). In quest’ultimo caso, per eliminare l’entità dall’HUB (ma non da zigbee2mqtt) è sufficiente rimuovere la configurazione manuale effettuata e riavviare Home Assistant. Nel primo caso (auto-discovery) è necessario rimuovere il pairing del componente presso zigbee2mqtt.

Per rimuovere il pairing di un componente è necessario inviare a zigbee2mqtt, tramite mqtt, un comando specifico:

zigbee2mqtt/bridge/config/remove NOME_COMPONENTE

dove, ovviamente, il “NOME_COMPONENTE” è la stringa con la quale il componente è battezzato da zigbee2mqtt.

Per inviare tale comando MQTT è possibile:

  • farlo manualmente via client MQTT;
  • inviarlo automaticamente via interfaccia Home Assistant.

Per farlo manualmente è possibile utilizzare un qualsiasi client MQTT connesso al broker oppure il client Home Assistant presso la sua interfaccia (“Strumenti per gli sviluppatori” > “MQTT“).

Se invece si è seguita alla lettera la “parte 1” di questa guida (vedi i link nell’Abstract) è possibile attivare automaticamente la modalità di de-pairing semplicemente attivando lo switch “Zigbee2mqtt Remove“, il quale altro non fa – sotto il cofano – che inviare il comando MQTT di cui sopra:

Home Assistant - zigbee2mqtt remove

Ovviamente, prima di cliccare “ESEGUI” sarà necessario inserire, nel campo di testo, il nome del componente da rimuovere (al posto di “unknown“).

Ricapitolando e concludendo:

  • gli utenti configurati in auto-discovery possono semplicemente rimuovere il parining;
  • gli utenti configurati manualmente devono prima rimuovere la configurazione presso Home Assisatnt relativa al componente da rimuovere, successivamente possono rimuovere il pairing.


Home Assistant Official LogoATTENZIONE: ricorda che sul nostro community FORUM c'è una sezione ad hoc dedica a Home Assistant, per qualsiasi dubbio, domanda, informazione nel merito specifico di queste componenti.


Please comment below