community italiana di domotica personale
 
ZHA (ZigBee Home Automation): come configurarlo su Home Assistant

ZHA (ZigBee Home Automation): come configurarlo su Home Assistant

Scopi della guida:
Concetti affrontati:
  • Configurazione software
Componenti software utilizzate:
Prerequisiti:
Dispositivi fisici utilizzati:
  • Il computer sul quale è in esecuzione Home Assistant
  • Un’antenna ZigBee coordinator compatibile con ZHA (illustrato a seguire)
Guida indicata per utenti con installazione:
Ambiente Home Assistant HassOS-Supervised-Core
NOTE E DISCLAIMER
  • qualsiasi eventuale modifica agli impianti domestici dev'essere progettata ed realizzata SOLO da personale qualificato;
  • qualsiasi modifica non prevista attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (i contenuti della presenta pagina hanno infatti puro scopo didattico) e fa decadere garanzia, omologazioni e certificazioni di qualità; dei dispositivi interessati;
  • tutte le tecniche descritte si intendono applicate a software e firmware aggiornati alle ultime versioni disponibili;
  • questa pagina è materialmente scritta e manutenuta da più individui: non ci si aspetti né si pretenda un supporto personale. In presenza di difficoltà, chiedere supporto alla community sul nostro forum o sulla nostra chat.
Revisione guida: 1.2

ZHA - Home Assistant

Abstract

Sua maestà ZigBee, uno degli standard più adottati in domotica personale.

Spesso l’interoperabilità tra componenti basati su questo protocollo ma di diverse tipologie e diversi produttori rappresenta 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.

Per salvare capra e cavoli esistono varie possibilità, tra le quali quelle di implementare presso la nostra domotica un BRIDGE/Gateway software avulso dalle logiche dei singoli produttori. Tra le varie alternative, è il caso di ZHA (o ZigBee Home Automation), oggetto della presente guida, componente software basato sul progetto zigpy e parte dell’HUB Home Assistant che consente per l’appunto di dotarsi gratuitamente di una rete ZigBee.

IMPORTANTE: ZHA (ZigBee Home Automation) è sì un modo rapido ed efficace per realizzare una propria rete ZigBee, ma anche degli svantaggi noti: il primo, innanzitutto, quello di essere legato alla realtà operativa di Home Assistant. Invece di essere un processo a se stante, come sarebbe corretto che fosse (per vari motivi squisitamente architetturali che non staremo a elencare in questa occasione), viene eseguito in ambito interno all’HUB. Questo significa che in caso di down di quest’ultimo, anche la rete ZigBee (che magari potrebbe essere connessa ad altre realtà operative, per diversi motivi) cesserebbe di funzionare. C’è poi un tema di rapidità nell’aggiunta di componenti hardware ZigBee supportati: BRIDGE/Gateway indipendenti dalla realtà evolutiva di Home Assistant sono mediamente molto più rapidi a correggere e/o aggiungere configurazioni utili a supportare (in pieno) l’hardware più moderno. Infine, altre soluzioni offrono maggiore spazio di manovra per la configurazione puntuale del comportamento degli end-device ZigBee ad essi connessi (calibrazioni, impostazioni di default, aggiornamenti firmware OTA e molto altro).

Se si sceglie ZHA per motivi di semplicità, bene, ma lo si faccia solo come ultima spiaggia. Il nostro consiglio è sempre e comunque quello di utilizzare il BRIDGE/Gateway software più adottato, supportato ed evoluto, ovvero ZigBee2MQTT – il quale certamente è inizialmente più difficile da dominare ma che, sul lungo periodo, dà risultati nettamente superiori.

ZHA resta comunque una soluzione semplice e valida per amministrare reti ZigBee, anche se non evolutissima.

N.b. A come e perché scegliere un BRIDGE/Gateway ZigBee piuttosto che un altro abbiamo dedicato un FOCUS ad hoc.

Scopo della presente guida è quello di capire come configurare ZHA su Home Assistant e quindi dotarsi facilmente di una rete ZigBee.

Si parte

Assunti

Si assume che Home Assistant sia già operativo.

Si assume altresì che eventuali altri BRIDGE/Gateway software o comunque software che utilizzino l’antenna coordinator che utilizzeremo per ZHA (ZigBee2MQTT, deCONZ o altri) siano stati preventivamente fermati.

ZigBee Coordinator (antenna)

Prima cosa, ancor prima di avventurarsi nell’installazione del BRIDGE/Gateway software ZHA, è l’installazione dell’antenna, ovvero del componente cardine di una rete mesh ZigBee: lo ZigBee “coordinator”. Tale elemento è rappresentato da un’antenna interfacciata al computer ospitante via USB, via seriale o altro.

ZHA supporta molte antenne diverse, tra le quali abbiamo documentato e testato:

  • ConBee II (dongle USB, di media potenza, stack 3.0, supporta fino a 200 componenti ZigBee, già pronta all’uso, compatibile anche con il BRIDGE/Gateway software deCONZ e ZigBee2MQTT);
  • 🔆 ITEAD Sonoff ZigBee 3.0 Dongle Plus v2 (dongle USB, segnale molto potente, stack 3.0, supporta fino a 200 componenti ZigBee, già pronta all’uso, compatibile anche con il BRIDGE/Gateway software ZigBee2MQTT);
  • Z-Bee Duo (“quella di Giovanni”, fatta a mano, dongle USB, piuttosto potente e versatile);
  • USB Stick CC2652P (USB, potente e versatile, stack 3.0, supporta fino a 200 componenti ZigBee, già pronta all’uso);
  • RaspBee II (HAT per Raspberry Pi, discretamente potente, supporta fino a 200 componenti ZigBee, già pronta all’uso, compatibile anche con il BRIDGE/Gateway software deCONZ);
  • CC2531 (dongle USB, non troppo potente, molto economica, da riprogrammare manualmente) – sconsigliato per obsolescenza;
  • CC2530 (seriale, poco potente, molto economica, da riprogrammare manualmente) – sconsigliato per obsolescenza;
  • CC2652RB;
  • CC2538 (PCB e HAT per Raspberry Pi);
  • Bitronvideo QIVICON Homebase (dongle USB);
  • ZiGate;
  • protocollo EZSP

e svariate altre. 

N.b. Sul tema “potenza” si disquisisce quotidianamente nei salotti di domotica quale argomento principe. Parlare di potenza trasmissiva ha per lo più poco senso: le reti mesh come quelle basate su ZigBee sono concepite per esser ripetute e non per aver un singolo nodo di potenza massima che provveda a coprire tutta la superficie – la differenza vera semmai la fa, piuttosto, l’affidabilità del componente stesso. In caso di ambienti ampi e/o con muri spessi, se i componenti ZigBee risultano irraggiungibili la scelta dell’antenna può quindi non essere legata alla sua potenza: basta infatti introdurre, oltre all’antenna principale, dei router (repeater) ZigBee (banalmente, bastano delle lampadine per illuminazione ZigBee, le quali hanno anche questa funzione – anche da “spente” – come le Philips HUE, le IKEA e molte alte) per garantirsi una copertura più che ottimale.

È quindi necessario installare correttamente l’antenna (se è un dongle USB basta inserirla nella porta del computer ospitante Home Assistant dopodiché appurare che il sistema operativo “veda” tale device.

Aggiornamento firmware

Prima di iniziare a utilizzare il coordinator, si consiglia caldamente di provvedere all’eventuale aggiornamento firmware. Non potendo documentare qualunque procedura per qualunque antenna, abbiamo documentato le seguenti:

L’aggiornamento potrebbe anche non essere necessario (magari la versione del firmware è già quella più recente), ma è bene controllare prima di procedere.

Dopo l’aggiornamento/verifica, è possibile installare il coordinator sul computer ospitante Home Assistant.

Verifiche post-installazione

Prima di provvedere a instanziare l’antenna coordinator verso Home Assistant è necessario far sì che essa venga “vista” dal sistema operativo sul quale è in esecuzione tale HUB.

Su Home Assistant OS

Dopo aver fisicamente installato l’antenna sul computer ospitante Home Assistant, riavviare e poi accedere a quest’ultimo e, presso la voce di menu “Sistema” > “Host” > “Hardware” (menu puntini) verificare se, nell’elenco dell’hardware installato, appaia o meno il componente, solitamente una voce specifica; nel caso di un’antenna Sonoff Dongle USB v2, per esempio, appare una voce di questo tipo:

/dev/serial/by-id/ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2_XXXXXXXXXXXXX

In caso appaia l’installazione sarà considerata valida; segnarsi mentalmente la stringa, servirà più avanti.

N.b. A volte l’antenna viene semplicemente riconosciuta come /dev/ttyAMAx, oppure come /dev/ttyUSBx.
Su home assistant core

Dopo aver fisicamente installato l’antenna sul computer ospitante Home Assistant e aver riavviato quest’ultimo, è il momento di effettuare una verifica per appurare porta logica sia stata assegnata all’antenna dal sistema operativo. A questo scopo andiamo a definire uno script come da nostra guida per Linux Debian oppure Raspberry Pi.

Eseguito lo script, l’elemento che inizia con “tty” e prosegue con la descrizione dell’antenna (per esempio dresden_elektronik_ingenieurtechnik_GmbH_ConBee” per la ConBee II, ITEAD_SONOFF_Zigbee_3.0_USB_Dongle_Plus_V2 per la Sonoff Dongle USB v2, e così via) è quello che identifica la porta che ci interessa (per esempio /dev/ttyACM0).

In presenza di questo elemento, l’antenna è riconosciuta correttamente dal sistema; segnarsi mentalmente tale stringa, servirà a seguire.

NOTA IMPORTANTE PER UTENTI DOCKER/DOCKER COMPOSE: Una volta effettuata la verifica per la quale il coordinator venga visto dal sistema operativo, è mandatorio provvedere a ricreare il container di Home Assitant Core@Docker in modo da “passargli” l’hardware in questione. Diversamente, malgrado il sistema operativo veda il coordinator, a non vederlo sarà Home Assitant Core – pertanto, ZHA non potrà essere instanziato e configurato.

Tipicamente, alla configurazione “Docker Compose” (vedi qui esempio per su Linux Debian) andrà aggiunta la porzione relativa al coordinator, per esempio:

...
  home-assistant:
    container_name: home-assistant
    image: ghcr.io/home-assistant/home-assistant:stable
    volumes:
    - /home/deb/homeassistant:/config
    - /run/dbus:/run/dbus:ro
    devices:
    - /dev/ttyACM0:/dev/ttyACM0
    environment:
    - TZ=Europe/Rome
    network_mode: host
    restart: always

Va da sé che la riga contenente /dev/ttyACM0:/dev/ttyACM0 possa cambiare in funzione della propria configurazione specifica, per esempio /dev/ttyACM1:/dev/ttyACM0 – tutto in funzione a come verrà riconosciuto dal sistema operativo il proprio coordinator.

Dopo la modifica alla configurazione, ricordarsi di reistanziare il container.

Vetrina - Offerte del giorno

Scelta del canale radio

Prima di istanziare ZHA è necessario scegliere con accuratezza il canale radio da fargli utilizzare. Va fatto prima perché cambiarlo successivamente significa perdere l’associazione di tutti gli end-device e router connessi alla rete mesh ZigBee e perché, scegliendolo a caso si potrebbe incappare in importanti problemi di interferenza.

Per capire come scegliere al meglio il canale da usare, far rifemento a questo focus:

Canali Wi-Fi e ZigBee: come evitare interferenze e ottenere le migliori prestazioni

Una volta effettuata la propria scelta, modificare il file di configurazione di Home Assistant aggiungendo la seguente porzione:

zha:
  zigpy_config:
    network:
      channel: 18             # Il canale da utilizzare
      channels: [18, 20, 25]  # Channel mask (opzionale)

avendo ovviamente cura di personalizzarlo come da propria scelta. Nel campo (opzionale) “channels“, è possibile indicare canali anternativi a quello principale, utili a ZHA per “spostare” le comunicazioni in caso di interferenze. Questa configurazione comunque è opzionale: in assenza, verrà utilizzato il canale 15.

Ricordasi, dopo la modifica, di riavviare Home Assistant.

Istanziare ZHA

Con il coordinator correttamente installato e il canale radio scelto, siamo pronti a istanziare ZHA su Home Assitant.

Quale che sia l’installazione di Home Assitant (OS, Supervised o Core), recarsi alla voce di menu “Configurazione” > “Dispositivi e servizi” di Home Assistant, oppure direttamente usando il link che segue:

 

è possibile cercare e configurare l’integrazione “ZigBee Home Automation“:

ZHA - Configurazione - 1

andando ovviamente a scegliere la voce che rappresenta l’antenna coordinator installata, in questo caso la “Sonoff ZigBee 3.0 USB Dongle Plus V2“.

Nel passo successivo si viene interrogati su cosa si voglia fare. Scegliere la voce che consente di creare una nuova rete:

ZHA - Configurazione - 2

Al termine della procedura si viene informati dell’avvenuta configurazione del BRIDGE/Gateway ZHA:

ZHA - Configurazione - 3

Congratulazioni, la rete ZigBee basata su ZigBee è operativa.

 

Uso

A questo punto il BRIDGE/Gateway ZHA è pronto e utilizzabile al fine di integrare componenti ZigBee compatibili con tale software, alcuni dei quali da noi testati e recensiti in dettaglio.


Ogni componente compatibile, una volta associato a ZHA, può essere comandato e censito tramite Home Assistant e amministrato attraverso la sua interfaccia web:

Come usare l’interfaccia web di ZHA (per pairing, impostazioni ed altro)

Maggiori info (ufficiali) sono disponibili qui.

Aggiornamento

Parte di Home Assistant Core, ZHA non può che essere aggiornato direttamente in fase di aggiornamento dell’intero HUB, come spiegato in dettaglio qui:

Utilità: come aggiornare Home Assistant

⚠️ Se di Home Assistant ne sai poco ma sei interessato a capirne di più, ti suggeriamo di partire da qui.

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. Se ti sei perso, a tua disposizione c'è la mappa.
Telegram News Channel