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

Scopi della guida: Realizzare una rete ZigBee utilizzando il motore ZHA (ZigBee Home Automation) di Home Assistant Livello di difficoltà: bassa Concetti affrontati: Configurazione software	Componenti software utilizzate: Home Assistant Componente Home Assistant “ZHA (ZigBee Home Automation)“ Prerequisiti: Home Assistant configurato e funzionante Dispositivi fisici utilizzati: Il computer sul quale è in esecuzione Home Assistant Un’antenna ZigBee coordinator compatibile con ZHA (illustrato a seguire)
GUIDA INDICATA A UTENTI CON ISTALLAZIONE:
NOTE E DISCLAIMER qualsiasi eventuale modifica agli impianti domestici dev'essere progettata e 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; gli articoli di inDomus sono totalmente indipendenti e non sponsorizzati. Se mai questo cambiasse, verrà segnalato chiaramente sulle pagine oggetto di sponsorizzazione; questa pagina è materialmente scritta e manutenuta da più individui: non ci si aspetti né si pretenda un supporto personale. In caso di difficoltà, chiedere supporto alla community sul nostro forum o sulla nostra chat; se hai bisogno di orientarti, c'è la mappa.
Revisione guida: 1.4

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.

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

Si parte

• Assunti
• ZigBee coordinator (antenna)
  • Aggiornamento firmware
  • Verifica post-installazione
    • Su Home Assistant OS
    • Su Home Assistant Core
• Scelta del canale radio
• Istanziare ZHA
  • Con antenne coordinator fisicamente collegate all’host (USB ecc.)
  • Con antenne coordinator decentrate
• Uso
• Aggiornamento

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:

e svariate altre. 

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

Firmware

• aggiornamento firmware per ITEAD Sonoff ZigBee 3.0 Dongle Plus;
• aggiornamento firmware per ITEAD Sonoff ZigBee 3.0 Dongle Plus v2 (ZBDongle-E) - firmware NCP
• aggiornamento firmware per Z-Wave.Me Z-Station - firmware NCP
• aggiornamento firmware per ConBee/Raspbee;
• aggiornamento firmware per Z-Bee Duo ("quella di Giovanni");
• aggiornamento firmware per ITEAD Sonoff ZigBee Bridge (con firmware Tasmota);
• aggiornamento firmware per CC2531 (anche senza debugger);
• aggiornamento firmware per CC2530.

• riprogrammazione con firmware Zigbee2Tasmota per Sonoff ZigBee Bridge (ZB Bridge);
• riprogrammazione con firmware Zigbee2Tasmota per Sonoff ZigBee Bridge Pro (ZB Bridge-P);
• riprogrammazione firmware per ITEAD Sonoff ZigBee 3.0 Dongle Plus v2 (ZBDongle-E) - firmware Multi-PAN (RCP) - si consiglia l'uso della versione 4.3.1 e non quelle superiori (le quali risultano buggate)
• riprogrammazione firmware per Z-Wave.Me Z-Station - firmware Multi-PAN (RCP)

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.

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 ZBDongle-E ZigBee3.0 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.

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

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

Quale che sia l’installazione di Home Assistant (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“.

Natuaralmente, la configurazione varia in relazione all’uso di antenne coordinator fisicamente collegate all’host ospitante Home Assistant (e quindi ZHA) oppure antenne decentrate.

Con antenne fisicamente collegate all’host (USB ecc.)

Ecco come configurare in caso di antenna fisicamente collegata all’host.

andando ovviamente a scegliere la voce che rappresenta l’antenna coordinator installata, in questo caso la “Sonoff ZBDongle-E 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:

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

Congratulazioni, la rete ZigBee basata su ZigBee è operativa.

Con antenne decentrate

In caso di antenne decentrate, la configurazione cambia da caso a caso.
Noi abbiamo documentato i seguenti casi:

• Sonoff ZigBee Bridge (ZB Bridge) riprogrammato ZigBee2Tasmota;
• Sonoff ZigBee Bridge (ZB Bridge-P) riprogrammato ZigBee2Tasmota;
• Antenne coordinator con firmware RCP (eg. Sonoff ZBDongle-E) e Silicon Labs Multiprotocol.

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 ZigBee 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