Integrare componenti Zigbee a Home Assistant via SLSys Gateway e MQTT

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

Tutti gli ambienti

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

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 esistono svariate soluzioni, una delle quali, ottimale, è quella di implementare presso la nostra domotica un BRIDGE/Gateway ZigBee↔︎TCP/IP avulso dalle logiche dei singoli produttori: la risposta è SLSys Gateway, un BRIDGE/Gateway autonomo che permette di gestire 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 generico componente ZigBee su Home Assistant utilizzando appunto tale BRIDGE/Gateway, il quale si intende già installato e configurato.

N.b. Alternativa all’uso di SLSys Gateway è, per esempio, l’adozione di deCONZ+ConBee/RaspBee, non oggetto di questa specifica guida. Le alternative sono illustrate sulla pagina dedicata a ZigBee.

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 SLSys Gateway, e perché ci consente di integrare diversi componenti ZigBee?
Arrivati sin qui dovrebbe già essere chiaro, ma qualora non lo fosse, repetita iuvant.

SLSys Gateway consente di fare da ponte tra il protocollo ZigBee e il protocollo MQTT (via TCP/IP); quest’ultimo è ben compreso e gestito da Home Assistant, il quale riesce così ad integrare eventuali componenti ZigBee compatibili con tale gateway. Questo “fare ponte” significa “tradurre” il protocollo ZigBee in messaggi MQTT, da e per il/i componente/i.

SLSys Gateway è dunque 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 SLSys Gateway (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 SLSys Gateway avrà anche sottoscritto sul broker i topic di comando per quel componente, se si pubblicherà un comando MQTT sul broker SLSys Gateway lo riceverà e lo girerà al componente via zigbee. E via così.

Dunque, è chiaro come SLSys Gateway 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, alla prima pubblicazione sul broker da parte di SLSys Gateway 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.

SLSys Gateway architecture

Pairing

Il pairing, ovvero l’associazione di un dispositivo ZigBee con BRIDGE/Gateway in uso (in questo caso il nostro SLSys Gateway), avviene impostando quest’ultimo in questa modalità specifica e poi attivando il componente da associare in modalità di registrazione.

Per farlo è necessario recarsi presso l’interfaccia web di SLSys Gateway alla voce di menu “ZigBee” > “Join” e cliccare su “Enable Join“:

SLSys Gateway - Web interface - ZigBee - Join

Per i successivi quattro minuti circa (255 secondi per la precisione) SLSys Gateway rimarrà in attesa di un componente ZigBee che si presenti per la registrazione. Ovviamente ogni componente attiva tale registrazione in modo diverso, quindi sarà necessario far riferimento alle istruzioni specifiche del componente.


Al termine della procedura, apparirà la scheda riassuntiva del componente aggiunto (nell’esempio, il sensore di presenza Xiaomi/LUMI):

SLSys Gateway - Web interface - ZigBee - Joined

Più sotto l’interfaccia offre la possibilità di modificare il componente appena integrato, aggiungendo eventuali friendly name, bind o consentirne la rimozione.

SLSys Gateway - Web interface - ZigBee - Edit
l’edit.

Home Assistant

Come spiegato prima, dopo l’avvenuto pairing SLSys Gateway “presenta” il 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 si è seguita la guida alla prima configurazione dell’SLSys Gateway (paragrafo “auto-discovery MQTT“), Home Assistant raccoglierà il messaggio di “presentazione” del componente pubblicato dal BRIDGE/Gateway, 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.

N.b. Non solo SLSys Gateway deve avere l’auto-discovery MQTT attivo, ma anche lo stesso Home Assistant. Per attivare quest’ultima funzione, far riferimento a questa guida.

Come detto, tramite l’integrazione automatica a ogni avvenuto pairing apparirà automaticamente presso Home Assistant la corrispondente entità (o più d’una) di natura appropriata in base alla tipologia di componente integrato.

Home Assistant - SLSys Gateway - Entità

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, SLSys Gateway lascia la libertà all’utente di configurare, come meglio crede, le proprie entità presso Home Assistant.

Per farlo, ovviamente, è necessario disabilitare l’auto-discovery (almeno lato SLSy Gateway) e modellare a mano la configurazione YAML che determini le varie entità tramite l’uso del componente “MQTT”di Home Assistant nonché le sue piattaforme derivate.

Ovviamente, per determinare tali configurazioni è necessario mettersi in ascolto del broker (leggi come, con Mosquitto) e intercettare topic e payload MQTT, determinando così la configurazione.

Per esempio, una presa IKEA si integra così:

sensor:

- platform: mqtt
  name: "Presa Ikea LinkQuality"
  state_topic: "Zigbee7634/presa_ikea"
  availability_topic: "Zigbee7634/bridge/state"
  payload_available: "online"
  payload_not_available: "offline"
  value_template: "{{ value_json.linkquality }}"
  device_class: "signal_strength"

switch:

- platform: mqtt
  name: "Presa Ikea Switch"
  state_topic: "Zigbee7634/presa_ikea"
  command_topic: "Zigbee7634/presa_ikea/set/state"
  value_template: "{{ value_json.state }}"
  payload_on: "ON"
  payload_off: "OFF"
  availability_topic: "Zigbee7634/bridge/state"
  payload_available: "online"
  payload_not_available: "offline"
  optimistic: false
  qos: 1
  retain: false

rest_command:
  presa_ikea_getstate:
    url: 'http://IP_DEL_GATEWAY/api/zigbee?dev=presa_ikea&action=getState&name=state'
    timeout: '300' 

N.b. Come si nota è stato aggiunto anche un rest_command alla configurazione. Questa chiamata HTTP serve a recuperare lo stato del componente quando viene avviato Home Assistant, stato che altrimenti sarebbe sconosciuto fino al successivo primo cambio stato della presa. Questo viene fatto via HTTP perché per ora non c’è modo di “interrogare” i componenti via MQTT. Si interroga quindi direttamente il gateway che mette a disposizione delle API.

Ne consegue che all’avvio di HA andremo ad impostare un’automazione per recuperare questo stato:

automation:
- alias: Presa Ikea Announce
  trigger:
  - event: start
    platform: homeassistant
  action:
  - service: rest_command.presa_ikea_getstate 

Questo è ovviamente solo un esempio: ogni componente prevede infatti una propria configurazione ad hoc che va, come spiegato sopra, dedotta e ricavata tramite il broker e i messaggi che passano.


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