Integrare componenti Zigbee a Home Assistant via SLSys Gateway e MQTT

SCOPI DELLA GUIDA: Integrare uno o più componenti ZigBee con Home Assistant utilizzando il BRIDGE/Gateway SLSys Gateway Livello di difficoltà: medio/basso Categoria d’integrazione: Local Push CONCETTI AFFRONTATI: Utilizzo e configurazione software	COMPONENTI SOFTWARE UTILIZZATE: Home Assistant Componente Home Assistant “MQTT“ PREREQUISITI: Home Assistant configurato e funzionante SLSys Gateway correttamente installato e configurato DISPOSITIVI FISICI UTILIZZATI: Il computer sul quale è in esecuzione Home Assistant Il/i componente ZigBee da integrare Uno (o più) SLSys Gateway
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.1

Abstract

Il protocollo ZigBee.

Come sappiamo l’interoperabilità 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.

Si parte

• Come funziona
• Pairing
• Home Assistant
  • Integrazione automatica
  • Integrazione manuale
• Cancellazione

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.

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“:

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 movimento Xiaomi/LUMI):

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

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.

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.

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ì:

mqtt:
  sensor:
  - 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"

mqtt:
  switch:
  - 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:
  - action: 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.