You are currently viewing ZHA: ZigBee in Home Assistant

ZHA: ZigBee in Home Assistant

  • Autore dell'articolo:
  • Categoria dell'articolo:Home Assistant
  • Commenti dell'articolo:7 commenti
  • Ultima modifica dell'articolo:21 Marzo 2021

In questo articolo impareremo a conoscere ed utilizzare Zigbee Home Automation, ovvero ZHA: l’integrazione nativa di Home Assistant per utilizzare dispositivi ZigBee.

Come abbiamo appreso nel primo articolo dedicato a ZigBee (se non l’hai letto fallo ora: Home Assistant e ZigBee: orientiamoci ) ZHA è l’integrazione più performante ed intuitiva, sebbene abbia ancora aree migliorabili. Per me è quindi la prima scelta da utilizzare, a meno che non ci siano motivi specifici come coordinator o dispositivi esotici non correttamente gestiti.

Impareremo quindi come aggiungere, configurare e gestire i dispositivi con ZHA. Tieniti forte, partiamo!

Prerequisiti

Se stai migrando da un'altra integrazione zigbee (Deconz, Zigbee2mqtt)

E’ importante capire che i coordinato ZigBee espongono normalmente una porta seriale, niente di più.
I coordinator USB lo fanno tramite una seriale virtuale over USB mentre gli hat per Raspberry Pi usano la UART presente nel Raspberry Pi stesso.

Per definizione una seriale può essere aperta da un unico chiamante, motivo per il quale se hai installato più integrazioni o add-on che ne fanno uso soltanto uno di essi funzionerà, gli altri troveranno la porta occupata.
Ecco perchè se stai migrando da Deconz o Zigbee2MQTT è importante capire che devi eliminare totalmente tali software, prima di procedere ad usare ZHA.

Ma prima di tutto ricorda di fare un backup o uno snapshot, a seconda della versione di Home Assistant che stai usando, questo ti permetterà di poter tornare sui tuoi passi qualora qualcosa andasse storto o ZHA non ti piacesse.

La brutta notizia te la do subito: ogni volta che cambi integrazione ZigBee devi riassociare tutti i tuoi dispositivi. Eh si. Perchè ogni integrazione crea una diversa chiave di criptazione del network. Quindi i backup ti permettono di tornare indietro ma i dispositivi andranno comunque riassociati. E perdi anche dispositivi ed entità che verranno nominati in modo differente (ma li potrai modificare con lo stesso entity_id che avevano precedentemente, non perdendo il funzionamento delle automazioni e degli script)

Una volta fatto il backup dovrai eliminare ogni traccia dell’integrazione che utilizzavi prima.
Se usavi Deconz dovrai disinstallare l’add-on Deconz e l’integrazione Phoscon.
Se stati usando Zigbee2MQTT dovrai disinstallare l’add-on Zigbee2MQTT e, se non ne fai altro uso, il broker MQTT che usavi, oltre in tal caso al client MQTT.

Dopo esserti assicurato che nessuno dei tuoi dispositivi sia sopravvissuto all’ecatombe, effettua un riavvio del supervisor. Questo ti assicurerà che non rimane codice in esecuzione che fa uso della seriale.

Se stai usando un coordinator Conbee / Raspbee

Se intendi usare ZHA con il coordinator di Dresden Elektronik Conbee II come consiglio nel primo articolo dedicato alla scelta dell’integrazione zigbee di Home Assistant, assicurati che il firmware della chiavetta o dell’hat siano all’ultima versione.

Il metodo più semplice per farlo è collegando la chiavetta ad una porta USB del tuo PC Windows.

Scarica l’ultima versione dell’utility GCFFlasher (attualmente la 3.10) che trovi a questa pagina e scompattane il contenuto in una cartella, diciamo c:\conbee.

Se stai usando Windows 10 non hai bisogno di alcun driver. Se invece utilizzi Windows 7 dovrai scaricare ed installare il seguente driver (se hai bisogno di ulteriori informazioni consulta la pagina di aiuto).

Scarica l’ultimo firmware per il tuo dispositivo da questa pagina. Nel caso di una Conbee II limitati ai file il cui nome inizia con deCONZ_ConBeeII e la cui estensione sia .bin.GCF. Salva il file nella cartella creata sopra c:\conbee.

Ora apri un prompt dei comandi, accedi tramite cd \conbee alla cartella creata prima e verifica che la chiavetta venga riconosciuta correttamente tramite il seguente comando:

GCFFlasher -l

Se la Conbee II viene vista correttamente sapremo la COM virtuale che dovremo usare:

Utilità gcfflasher

A questo punto chiediamo di aggiornare il firmware con il seguente comando (sostituisci il nome del firmware con quello scaricato precedentemente):

GCFFlasher.exe -f deCONZ_ConBeeII_0x26680700.bin.GCF

Dovresti vedere il progresso dell’aggiornamento e il suo termine. Se non accade nulla significa invece che il firmware è già aggiornato.

Aggiunta dell’integrazione ZHA

Prima di partire tieni sottomano la pagina di documentazione ufficiale, come sempre è il posto giusto dove cercare informazioni in caso di problemi o dubbi e per verificare che il tuo coordinator sia supportato.

Aggiungere l’integrazione è semplicissimo. Vai in Impostazioni -> Integrazioni e clicca il tasto + AGGIUNGI INTEGRAZIONE in basso a destra.
Nella selezione delle integrazioni posizionati al termine della lista o seleziona “zigbee” nella ricerca. La voce su cui cliccare è Zigbee Home Automation.

Aggiunta dell'integrazione ZHA

Se ZHA rileva il coordinator

A questo punto se ZHA rileva automaticamente una periferica Zigbee ti proporrà di utilizzarla (troverai il tuo coordinator nella casella a discesa):

Percorso seriale durante l'aggiunta di ZHA

Una volta premuto INVIA… hai finito di configurare ZHA, che ti presenterà il riassunto con la scelta dell’area di casa dov’è presente il coordinator:

Integrazione ZHA aggiunta correttamente ad Home Assistant

Se ZHA non rileva il coordinator

Nel caso in cui ZHA non rilevasse il coordinator (perchè ad esempio è remoto, come per il Sonoff ZBBridge, oppure perchè la seriale virtuale esposta è tenuta occupata da un add-on) ti verrà prima chiesto di selezionare il tipo di coordinator installato tramite la seguente finestra (nella schermata è selezionata l’opzione da scegliere per la Conbee II):

Selezione tipo di coordinator durante l'aggiunta di ZHA a Home Assistant

Premendo INVIA ti verrà quindi richiesto di inserire il percorso della porta seriale da utilizzare (o altri parametri con altri tipi di coordinator):

Percorso seriale durante l'aggiunta di ZHA ad Home Assistant

Ma dove trovare il percorso?

Se hai Home Assistant Operating System puoi andare in Supervisor, Sistema e nel pannello di destra Host cliccando sui tre puntini clicca sulla voce Hardware e scorri fino a trovare la voce normalmente chiamata - name: ttyACM0

cerca la riga seguente che inizia con by_id e copia il contenuto dell’intera riga successiva, facendo attenzione a scorrere finché la riga non termina.

Se hai Home Assistant Core digita il seguente comando dalla shell:

# ls /dev/serial/by-id/*

Nel caso in cui ZHA riuscirà a colloquiare con il coordinator vedrai il riassunto e la scelta dell’area di casa alla quale assegnare il coordinator, come nel paragrafo precedente:

Integrazione ZHA aggiunta correttamente ad Home Assistant

Se tutto è andato bene ti ritroverai con un’integrazione in più che si mostra più o meno così:

Integrazione ZHA: Zigbee Home Automation di Home Assistant

Configurazione di ZHA

ZHA è talmente semplice che non necessita di configurazione obbligatoria.
Puoi comunque aggiungere delle opzioni tramite configuration.yaml. L’unica opzione che ti consiglio di aggiungere prima di iniziare è il canale Zigbee. Scegli con cura un canale che non si sovrapponga con il tuo Wifi e con quelli vicini di una certa potenza. Se vuoi più informazioni a riguardo ti consiglio di leggere questo articolo: ZigBee: copertura, router, canali.

Per selezionare un canale aggiungi il seguente codice al tuo configuration.yaml:

zha:
  zigpy_config:
    network:
      channel: 25             # Numero del canale che desideri utilizzare

Dopo ogni modifica alla configurazione del dispositivo ricorda di riavviare Home Assistant.

Aggiungere un dispositivo

Siamo ora pronti ad aggiungere il nostro primo dispositivo ZigBee ad Home Assistant.
Per farlo abbiamo due possibilità:

  1. Cliccando il link CONFIGURA dell’integrazione e quindi il tasto + AGGIUNGI DISPOSITIVO in basso a destra.
  2. Cliccando il link n dispositivi dell’integrazione, selezionando il coordinator o il router che vuoi usare per il collegamento e infine cliccando sul link AGGIUNGI DISPOSITIVI TRAMITE QUESTO DISPOSITIVO
Aggiunta di un dispositivo tramite un router Zigbee con integrazione ZHA in Home Assistant

In entrambi i casi si attiverà la modalità di aggiunta dispositivi:

Ricerca dispositivi Zigbee con integrazione ZHA in Home Assistant

Se vuoi vedere cosa sta avvenendo dietro alle quinte premi il link in alto a destra SHOW LOGS. Può essere utile se sospetti ci sia un malfunzionamento durante la ricerca.

Questa fase dura un paio di minuti nei quali è permessa l’aggiunta di dispositivi alla tua rete zigbee. Durante questi minuti dovrai resettare il dispositivo da associare (ognuno ha la sua modalità, leggi tra le istruzioni del dispositivo) in modo che si accoppi con le chiavi di protezione della rete ed entri a far parte del tuo network zigbee.

Quando il dispositivo viene rilevato appare una card blu. A quel punto ZHA sta ancora comunicando con esso per prelevarne i dati e le peculiarità. Al termine di questa interrogazione la card diventerà verde ad indicare che l’operazione è terminata. L’unica operazione residua sarà dare un nome identificativo al dispositivo e assegnarlo ad un’area della casa tramite gli appositi campi nella card.

Il mio personale consiglio è di usare sempre la seconda modalità (AGGIUNGI DISPOSITIVI TRAMITE QUESTO DISPOSITIVO) partendo dal coordinator, quando colleghi dispositivi vicini ad esso, oppure partendo dal router che vorresti che il dispositivo utilizzi per comunicare poi fino al coordinator. Questo perchè alcuni dispositivi non rispettano al 100% le specifiche Zigbee e tendono a rimanere collegati al router con cui sono stati aggiunti.

Mappa dei dispositivi Zigbee

ZHA, come tutte le integrazioni Zigbee, offre la possibilità di mostrare una mappa dei dispositivi collegati che può essere utile per capire la topologia di rete e identificare eventuali problemi.

Nel momento in cui scrivo (ver. 2021.3.4) la mappa di ZHA è ancora piuttosto acerba, graficamente poco gradevole e non priva di difetti. Avrà ampio margine di miglioramnto nelle versioni future.

Per visualizzarla basta andare in Impostazioni -> Integrazioni -> Zigbee -> Configura -> Visualizzazione:

Menu configurazione integrazione ZHA in Home Assistant

La mappa si presenta quindi in questo modo:

Mappa dei dispositivi Zigbee con ZHA in Home Assistant

E’ possibile zoomarla usando la rotella del mouse o il pinch to zoom su dispositivi touchscreen e scrollare tenendo premuto il tasto sinistro. Aumentandone l’ingrandimento si vedranno anche i dati di ogni dispositivo e dei link di collegamento:

Ingrandimento mappa dei dispositivi Zigbee con integrazione ZHA in Home Assistant

Come leggere la mappa

Ci sono tre tipi di simboli sulla mappa:

  • Rettangolo: rappresenta il coordinator
  • Ovale: rappresenta un dispositivo router che contribuisce alla rete mesh
  • Cerchio: rappresenta un end-device, solitamente dispositivi a batteria che non contribuiscono alla rete mesh

All’interno di ognuno di essi possiamo trovare:

  • Il nome assegnato al dispositivo
  • L’indirizzo IEEE (puoi pensarlo come il parallelo del MAC address in versione Zigbee. Esso rappresenta infatti univocamente un dispositivo a livello globale)
  • Il tipo di dispositivo (Router o EndDevice)
  • L’indirizzo NWK (puoi pensarlo come il parallelo dell’indirizzo IP, univoco all’interno della tua rete Zigbee)
  • La descrizione del modello di dispositivo

Le linee che collegano i dispositivi tra loro sono i possibili collegamenti che i dispositivi utilizzano per comunicare e formano una strada tra il dispositivo di partenza e quello di destinazione.
Il colore delle linee è verde se il valore di LQI è superiore a 192, giallo se è tra 129 e 192, rosso se è minore o uguale 128 e grigio se è davvero troppo basso. Nel capitolo seguente sarà spiegato il significato di LQI.

Allo stato attuale c’è un bug nella mappa che non mostra molti link tra il coordinator e gli end device collegati direttamente ad esso.

Identificare la qualità di comunicazione

Per capire quanto un dispositivo comunichi bene è necessario andare nella card Informazioni sul dispositivo nei device di Zigbee:

Informazioni sulla qualità del segnale di un dispositivo Zigbee: RSSI e LQI con integrazione ZHA in Home Assistant

LQI è l’acronimo di Link Quality Indication ed è un dato cumulativo che ogni dispositivo registra e rappresenta il numero di errori di trasmissione. Il suo valore va da 0 a 255, dove 255 significa comunicazione perfetta, valori più bassi indicano una incidenza di errori di comunicazione sempre più elevati.
RSSI è l’acronimo di Received Signal Strength e misura la potenza ricevuta in antenna grezza, senza tenere in conto eventuali disturbi. E’ negativa e più vicina allo zero significa più potente. -50 è migliore di -70.

Normalmente al decrescere di RSSI decresce LQI. Ma LQI può decrescere anche se RSSI non varia, ad esempio se vi sono disturbi di comunicazione.

I gruppi Zigbee

Con ZHA è possibile creare dei gruppi di dispositivi per poterli comandare in modo simultaneo come fossero un tutt’uno.
Si, certo, si potrebbero raggruppare in un group oppure in un light group ma la peculiarità di creare un gruppo nell’integrazione è che possiamo utilizzare tale gruppo direttamente da dispositivi Zigbee di comando, come vedremo nel prossimo articolo riguardante il binding. Ovviamente il gruppo sarà anche esposto come entità direttamente utilizzabile in automazioni e script come fosse un light group.

Le singole entità rimarranno comandabili, interrogabili e utilizzabili nelle automazioni anche singolarmente ma in più avrai un gruppo che ti permetterà di accendere tutte le lampadine alla stessa intensità e alla stessa temperatura/colore (qualora lo supportino).
Ti consiglio quindi di usare questa funzione per luci omogenee Zigbee e non group o light group.

Per accedere ai gruppi andare in Impostazioni -> Integrazioni -> Zigbee -> Configura -> Gruppi:

Gruppi Zigbee in configura integrazione

In tale sezione troverai i gruppi configurati:

E’ probabile che troverai dei gruppi già esistenti, come i “no name group” dello screenshot sopra. Ti consiglio di non rimuovere questi gruppi ma semplicemente di ignorarli

Come sempre per aggiungere un gruppo usiamo il tasto in basso a destra + AGGIUNGI GRUPPO:

Aggiungi gruppo dispositivi Zigbee con integrazione ZHA in Home Asssistant

Non ci resta che inserire un nome per il gruppo (che poi sarà trasformato per essere anche l’entity_id) e selezionare i dispositivi che faranno parte del gruppo:

Parametri aggiunta gruppo dispositivi Zigbee con integrazione ZHA di Home Assistant

Non ha senso selezionare dispositivi di tipo diverso per raggrupparli in un gruppo zigbee. E’ invece utile creare gruppi di luci, gruppi di smart plugo gruppi di qualunque dispositivo che si ha intenzione di comandare contemporaneamente.

Gestione dei cluster

Normalmente questo argomento è piuttosto avanzato ma è bene sapere che i cluster (set di funzioni resi standard da Zigbee Alliance) possono essere gestiti dalla pagina del dispositivo. Troviamo questa funzione tramite il link GESTISCI CLUSTER:

Gestione dei cluster

Si aprirà un’interfaccia con molti dati, limitiamoci alla prima: Clusters:

Interfaccia comunicazione attributi dei cluster con integrazione ZHA di Home Assistant

I clusters sono insiemi di attributi con valore raggruppati per tipologia omogenea. Tali valori degli attributi possono essere letti e, in alcuni casi, scritti nel dispositivo.
Selezionando una voce in Clusters, ad esempio Basic, apparirà la sezione sottostante dove poter selezionare un attributo del cluster. Selezioniamo ad esempio manufacturer, che ci indicherà il produttore del dispositivo, e premiamo OTTIENI l’ATTRIBUTO ZIGBEE per interrogarne il valore dal dispositivo stesso.
Il valore, se l’operazione va a buon fine, verrà scritta nella casella Valore.

Qualora si volesse modificare il valore di un attributo (solo se sai esattamente cosa si sta facendo!) inserisci il nuovo valore che desideri impostare nella casella Sostituzione codice produttore e premi IMPOSTA L’ATTRIBUTO ZIGBEE.

Alcuni dispositivi permettono infatti di configurarne il comportamento tramite attributi, come la sensibilità, il tempo o altro ancora.

Aggiornamenti OTA dei dispositivi Zigbee

ZHA permette l’update automatico dei firmware dei dispositivi che rendono pubblici i propri aggiornamenti.

Al momento in cui scrivo solo Ikea e Ledvance rendono disponibili in modo chiaro i propri aggiornamenti e sono pertanto gli unici dispositivi a poter ricevere aggiornamenti automatici OTA (Over The Air).

Come riportato dalla pagina ufficiale di ZHA, per default gli aggiornamenti sono disabilitati. Per abilitarli basterà aggiungere alla nostro configuration.yaml (o in un package) il seguente codice:

zha:
  zigpy_config:
    ota:
      ikea_provider: true                        # Auto update Trådfri devices
      ledvance_provider: true                    # Auto update LEDVANCE devices
      #otau_directory: /path/to/your/ota/folder  # Utilize .ota files to update everything else

Dopo ogni modifica ai parametri OTA sarà necessario riavviare Home Assistant perchè i nuovi parametri abbiano effetto.

La terza voce commentata otau_directory permette di specificare una cartella dove salvare i firmware scaricati personalmente, se si desiderasse utilizzarli per gli aggiornamenti.

Molto più comodo è invece attivare ikea_provider e/o ledvance_provider come nell’esempio sopra. In tal modo verrà automaticamente effettuato il controllo della versione firmware di ogni dispositivo, scaricato automaticamente ogni eventuale aggiornamento e applicato ai dispositivi senza nulla chiedere.

Un aggiornamento alle lampadine smart le fa normalmente spegnere per qualche decina di secondi per poi riaccendersi aggiornate.
Per sapere se un device è stato aggiornato sarà necessario verificare la versione firmware, accessibile dalla pagina del dispositivo Zigbee, prima e dopo il presunto aggiornamento:

Versione firmware dispositivi zigbee

Cosa fare in caso di problemi con ZHA

Quando le cose non vanno come devono, ad esempio il coordinator non funziona, il join dei dispositivi non va a buon fine o per qualunque problema è possibile abilitare la modalità di debug delle varie componenti di cui ZHA. Di seguito il codice da inserire in configuration.yaml o in un package:

logger:
  default: info
  logs:
    homeassistant.core: debug
    homeassistant.components.zha: debug
    bellows.zigbee.application: debug
    bellows.ezsp: debug
    zigpy: debug
    zigpy_cc: debug
    zigpy_deconz.zigbee.application: debug
    zigpy_deconz.api: debug
    zigpy_xbee.zigbee.application: debug
    zigpy_xbee.api: debug
    zigpy_zigate: debug
    zigpy_znp: debug
    zhaquirks: debug

In caso di problemi con il coordinator o con il pairing di dispositivi sconsiglio di attivare tutte le opzioni, altrimenti il log diventerà molto prolisso e cercare le informazioni molto noioso. In particolare è probabile che NON ti interessi abilitare homeassistant.core, zhaquirks (molto prolisso! Attivare quest’ultimo solo se stai analizzando le peculiarità di un device zigbee non aderente alle specifiche zigbee)

Una volta attivate le voci desiderate riavviare Home Assistant, effettuare le operazioni che generano il problema e salvare una copia del log, normalmente presente in config/home-assistant.log.

Non lasciare attivo il log senza un motivo a lungo termine perchè il log generato è molto più ampio e concorre al wearing del supporto di memorizzazione, specialmente se hai solo una scheda SD su Raspberry Pi (in tal caso ti consiglio di leggere questo articolo)

Se pensi di postare il log su di un gruppo Facebook assicurati di utilizzare un servizio come PasteBin per inserire il codice e postare solo il link di pastebin al tuo codice. In tal modo è molto più leggibile che incollarlo in un post e faciliti la vita a chi vorrà darti una mano nell’analisi.

Ulteriori informazioni per approfondire ZHA

Ti è piaciuto questo contenuto?

Se ti è stato utile l’articolo che hai letto potresti pensare di darmi una mano offrendomi un caffè!
Oltre ad aiutarmi a star sveglio nelle nottate di ricerche e scrittura mi daresti una mano concreta nel sostenere le spese del server web, incentivandomi a produrre altri contenuti di qualità.
(se non vedi il tasto di seguito clicca QUI)

Henrik Sozzi

Sono un analista programmatore per lavoro e per passione. Amo la domotica, la stampa 3D e la tecnologia in generale.

Questo articolo ha 7 commenti.

  1. giacomo

    chiavetta cc2530 + hassio + rasp.3b + dispositivi LUMI, tutto ok fino a quando non spengo il rasp, all’accensione devo riconfigurare tutti i dispositivi

    1. Henrik Sozzi

      Potrebbe essere la SD che ha esaurito il suo ciclo vitale. E’ abbastanza frequente che quando capiti le SD vengano lette ma le scritture non cambino quel che sta scritto nel supporto, sebbene sembri andare a buon fine. E quindi quando riparte il Raspberry ricarica l’elenco di dispositivi dalla SD che… non c’è.
      E’ l’unica spiegazione che mi viene in mente.

Rispondi