Integrare componenti ZigBee su Home Assistant via ZigBee2MQTT

6 minuti di lettura
SCOPI DELLA GUIDA:
CONCETTI AFFRONTATI:
  • Utilizzo e configurazione software
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
GUIDA maggiormente indicatA per:

Ambienti CORE HASSIO

Note e disclaimer
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO 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.0

ZigBee via ZigBee2MQTT su Home Assistant

Abstract

Non ci stiamo a dilungare più di tanto: se si è raggiunta questa guida, è perché si sa già (o almeno si dovrebbe) che ZigBee2MQTT è il BRIDGE/Gateway software implementato in proprio per la gestione di componenti ZigBee diversi (e di diverse marche) e Home Assistant è l’HUB personale per la gestione della propria domotica personale.

Lo scopo di questa guida, quindi, è quello di integrare facilmente ZigBee2MQTT (e quindi le componenti ZigBee ad esso associate) con il proprio HUB, così da controllare/censire tramite esso le componenti ZigBee di cui sopra.

N.b. Questa guida è adatta sia agli utenti Home Assistant CORE che HASSIO.

Si parte

Assunti

Si assume che ZigBee2MQTT sia già operativo; qualora non lo sia, si rimanda all’elenco di modalità di installazioni disponibili sulla nostra scheda ad esso dedicata.

Si assume altresì che, ovviamente, anche Home Assistant sia già operativo.

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 funge 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. ZigBee2MQTT è poi 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. 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 gli eventuali 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 “parlarci” tramite il broker MQTT.

zigbee2mqtt architecture
lo schema funzionale dell’integrazione.

MQTT & Home Assistant

Dato che questa integrazione utilizza MQTT come tramite, va da sé che si debba avere a disposizione un broker MQTT – ma se ZigBee2MQTT è già operativo, va da sé che sia a sua volta già operativo anche tale elemento (altrimenti ZigBee2MQTT non funzionerebbe).

Assunto quindi che il broker MQTT sia già disponibile, è altresì necessario configurare l’integrazione MQTT presso Home Assistant, al fine di rendere quest’ultimo in grado di dialogare tramite tale protocollo. Se si è già configurata tale integrazione è possibile saltare al prossimo paragrafo; diversamente, qui spieghiamo come provvedere a tale rapida integrazione.

Home Assistant

Home Assistant, una volta messa in funzione la sua integrazione MQTT col broker, è pronto a definire delle entità le quali accolgano le metriche e i comandi esposti dai componenti ZigBee associati a ZigBee2MQTT.

Per farlo ci sono due strade: una estremamente facilitata (ma meno flessibile) e una un po’ più complicata (ma enormemente più flessibile):

  1. AUTOMATICA: lasciare fare a tutto a ZigBee2MQTT/Home Assistant. Con l’autodiscovery attivo ambo i lati, ogni qual volta un nuovo componente ZigBee viene associato a ZigBee2MQTT automaticamente vengono anche create le relative entità;
  2. MANUALE: è lasciare che ZigBee2MQTT pubblichi su broker MQTT, come da suo design, i topic telemetrici (oltre a stare in ascolto di eventuali topic di comando) e che la definizione delle entità venga effettuata manualmente dall’utente lato Home Assistant.

La seconda opzione è, lo diciamo da subito, tendenzialmente preferibile.
Questo perché:

  • consente la personalizzazione delle proprie entità (anche nel loro comportamento);
  • evita la creazione di alcune entità magari non necessaria per l’utente;
  • evita di “sporcare” la configurazione di Home Assistant e consente di definire nomi arbitrari alle entità (ZigBee2MQTT utilizza, come nomi, dei seriali i quali sì, possono essere modificati in un secondo momento, ma comunque in prima battuta Home Assistant riceve quelli).

La scelta è personale e comunque reversibile: per questo si consiglia, comunque, di tentare prima l’approccio manuale.

Integrazione Automatica

Come spiegato sopra, affinché il meccanismo automatico funzioni è necessario che l’auto-discovery sia attivo lato ZigBee2MQTT così come lato Home Assistant.

Per il primo, è necessario che nella configurazione di ZigBee2MQTT sia stato indicato il campo homeassistant: true (far riferimento alla guida di installazione ZigBee2MQTT precedentemente usata); per il secondo, è necessario che durante l’integrazione di MQTT su Home Assistant sia stato attivata “l’auto identificazione”.

A fronte di questa configurazione, ogni qual volta si assocerà tramite pairing un uovo componente a ZigBee2MQTT, automaticamente appariranno su Home Assistant le entità previste per quel componente.

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).

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.

UN ESEMPIO

Il sensore sopracitato (l’ambientale Xiaomi) ha – come tutti i componenti compatibili – una propria scheda presso il sito di ZigBee2MQTT (per accedere a quella dei propri componenti basta prima accedere alla lista dispositivi e cliccare l’etichetta sotto la colonna “Model). Accedendo poi al paragrafo “Manual Home Assistant configuration“, il sito propone la configurazione “tipo” da usarsi presso il file di 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, sempre presso l’interfaccia web di ZigBee2MQTT, osservare l’etichetta posta sotto la colonna “Friendly name” (personalizzabile a piacere).

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 è sufficiente cliccare sull’icona del cestino (sempre presso l’interfaccia web di ZigBee2MQTT).

Ricapitolando e concludendo:

  • gli utenti che utilizzino la procedura automatica di integrazione possono limitarsi rimuovere il parining presso ZigBee2MQTT (le entità presso Home Assistant spariranno da sole);
  • gli utenti configurati manualmente devono prima rimuovere presso Home Assistant le configurazioni relativa al componente in questione; successivamente possono rimuovere il pairing lato ZigBee2MQTT.


Home Assistant Official Logo ATTENZIONE: 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.

   
Telegram News Channel