Integrare CC2531 con Home Assistant (HASSIO) via zigbee2mqtt (parte 1)

9 minuti di lettura
SCOPI DELLA GUIDA:
  • Integrare un BRIDGE/Gateway ZigBee↔︎TCP/IP CC2531 con Home Assistant (distribuzione HASSIO) tramite l’adozione della sua controparte software zigbee2mqtt. Tale integrazione consente di integrare componenti ZigBee di diversi produttori a Home Assistant.
  • Livello di difficoltà: medio
CONCETTI AFFRONTATI:
  • Utilizzo e configurazione software
COMPONENTI SOFTWARE UTILIZZATE:
PREREQUISITI:
DISPOSITIVI FISICI UTILIZZATI:
GUIDA maggiormente indicatA per:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere effettuata da personale qualificato;
  • qualsiasi modifica attuata in proprio è a propria responsabilità personale nonché a proprio rischio e pericolo (la presente guida ha puro scopo didattico);
  • qualsiasi modifica attuata in proprio a un dispositivo ne fa decadere la garanzia.
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.

CC2531
il dongle USB CC2531.

Per salvare capra e cavoli esiste un’ottima soluzione, ovvero quella di implementare presso la nostra domotica un BRIDGE/Gateway ZigBee↔︎TCP/IP avulso dalle logiche dei singoli produttori: la risposta è data dalla sinergia di zigbee2mqtt (componente software) il dongle USB CC2531 (componente hardware), un’accoppiata che permette di censire il più alto numero di componenti ZigBee possibile scavalcando i problemi di cui sopra. Ovviamente, questo BRIDGE/Gateway “standard” è pienamente integrabile con Home Assistant.

In questa guida vedremo quali siano i passi per integrarlo su Home Assistant in distribuzione HASSIO.
La guida dedicata a chi usa invece Home Assistant installato come applicativo su sistema operativo Raspbian è disponibile qui.

N.b. Questa guida, “parte 1”, serve per realizzare la piena integrazione di zigbee2mqtt. La “parte 2” – di prossima pubblicazione – illustrerà come aggiungere componenti ZigBee al BRIDGE/Gateway ZigBee realizzato con la presente guida.

N.b. Alternativa al binomio zigbee2mqtt+CC2531 è l’adozione di deCONZ+ConBee/RaspBee, non oggetto di questa specifica guida.

Si parte

Installare l’antenna

Innanzitutto è necessario installare correttamente il dongle USB CC2531. Come dovrebbe esser noto, tale componente (a differenza della rivale ConBee) non è pronto all’uso, ma ha bisogno di una riprogrammazione del firmware a monte. Il presente progetto dà per scontata l’avvenuta riprogrammazione della stessa.

Una volta pronta, la chiavetta può essere connessa ad una delle porte USB del computer sul quale è in esecuzione HASSIO, dopodiché è necessario completare l’installazione effettuando un reboot (voce di menu “HASS.io” > “SYSTEM” >”REBOOT“).

VERIFICA POST-INSTALLAZIONE

Dopo aver installato l’antenna e aver avviato HASSIO, accedere a quest’ultimo e, presso la voce di menu “HASS.io” > “SYSTEM” >”HARDWARE” verificare se, nell’elenco dell’hardware installato, appaia o meno il componente, solitamente una voce di questo tipo:

/dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B00076887D9-if00

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

N.b. A volte l’antenna viene semplicemente riconosciuta come /dev/ttyAMA0 .

Installare il broker MQTT

Come suggerisce il nome, il software zigbee2mqtt, per funzionare, necessita della presenza di un broker MQTT sulla rete locale sulla quale il computer che lo esegue è connesso. Sebbene nessuno vieti di installare tale componente su un altro host presente in rete, la pratica più comunemente adottata è quella di utilizzare HASSIO allo scopo, utilizzando l’add-on “Mosquitto Broker” il quale, per l’appunto, installa un broker MQTT chiamato Eclipse Mosquitto.

In caso MQTT sia già presente sulla rete, è possibile procedere oltre, accertandosi solo di avere MQTT  attivo e connesso a tale broker pre-esistente (con “discovery” attiva, anche chiamata “Attiva individuazione”) nella propria configurazione Home Assistant.

Diversamente, provvedere ad installare Mosquitto Broker seguendo passo passo la seguente guida:

Configurare correttamente MQTT su HASSIO (versione addon dalla v3 in poi)

N.b. Procedere nella presente guida senza aver provveduto a installare correttamente il broker MQTT causerà, ovviamente, un malfunzionamento di zigbee2mqtt.

Installare zigbee2mqtt

A questo punto, con MQTT funzionante e antenna installata è possibile provvedere all’installazione di zigbee2mqtt, il quale viene eseguito come processo tramite l’aggiunta di un add-on HASSIO. Si tratta, però, di un add-on custom pertanto non nativamente disponibile presso l’add-on store di HASSIO. Per installarlo è dunque primariamente necessario aggiungere un repository alla lista di quelli già presenti, nello specifico questo indirizzo:

https://github.com/danielwelch/hassio-zigbee2mqtt

Per aggiungerlo, recarsi alla voce di menu “Hass.io” > “ADD-ON STORE” e cliccare su “Add new repository by URL”:

zigbee2mqtt - HASSIO add-on - aggiunta repository

Una volta inserito l’indirizzo indicato sopra, cliccare “ADD“.

Immediatamente dopo nella lista degli add-on disponibili apparirà anche la voce “zigbee2mqtt”. Cliccarci sopra per accedere alla scheda di dettaglio, poi cliccare su “INSTALL“:

zigbee2mqtt - HASSIO add-on - installazione

Al termine dell’installazione, non avviare il plugin: è necessario, prima, configurarlo.

Configurare zigbee2mqtt

La configurazione di zigbee2mqtt non è particolarmente complessa ma importante. È in questa fase, infatti, che si definisco le caratteristiche di connessione del BRIDGE/Gateway da esso rappresentato verso la rete ZigBee e verso il broker MQTT.

Tale configurazione si effettua sempre dalla pagina di dettaglio dell’add-on zigbee2mqtt; scendendo nella pagina, il riquadro “Config” riporta una configurazione di default pressapoco così:

{
  "data_path": "/share/zigbee2mqtt",
  "devices": "devices.yaml",
  "groups": "groups.yaml",
  "homeassistant": true,
  "permit_join": false,
  "mqtt": {
    "base_topic": "zigbee2mqtt",
    "server": "mqtt://core-mosquitto",
    "user": "my_user",
    "password": "my_password"
  },
  "serial": {
    "port": "/dev/ttyACM0"
  },
  "advanced": {
    "pan_id": 6754,
    "channel": 11,
    "network_key": [
      1,
      3,
      5,
      7,
      9,
      11,
      13,
      15,
      0,
      2,
      4,
      6,
      8,
      10,
      12,
      13
    ],
    "availability_blacklist": []
  },
  "ban": [],
  "whitelist": [],
  "queue": {},
  "socat": {
    "enabled": false,
    "master": "pty,raw,echo=0,link=/dev/ttyZ2M,mode=777",
    "slave": "tcp-listen:8485,keepalive,nodelay,reuseaddr,keepidle=1,keepintvl=1,keepcnt=5",
    "restartdelay": 1,
    "initialdelay": 1,
    "options": "-d -d",
    "log": false
  }
}

I campi da personalizzare sono, principalmente, tre: “server“, “user” e “password“.

Nel primo (“server“) va indicato il nostro broker MQTT: se si usa un proprio broker presente sulla rete, è ovviamente necessario indicare in questo campo l’indirizzo IP corretto; diversamente, se si è seguita la nostra guida per installare Mosquitto Broker come add-on HASSIO, allora è necessario indicare semplicemente “mqtt://homeassistant“.

Nei campi “user” e “password“, invece, è necessario indicare le credenziali d’accesso al broker MQTT, indipendentemente da dove esso sia in esecuzione.

Una volta terminata la configurazione, cliccare su “SAVE” e poi, sopra, su “START“: il BRIDGE/Gateway andrà in esecuzione:

zigbee2mqtt - HASSIO add-on

VERIFICA

Per verificare che tutto sia andato per il verso giusto, recarsi sul fondo della pagina e cliccare “REFRESH” nel box “Log“: se è tutto ok, dovrebbe apparire un log similare a questo che segue:

zigbee2mqtt - HASSIO add-on - startup

il quale identifica un corretto avvio di zigbee2mqtt e un’avvenuta connessione col broker MQTT.

Integrazione con Home Assistant

A questo punto l’integrazione, di fatto, è già avvenuta, perché la presenza dell’auto-discovery del componente MQTT fa sì che i servizi di zigbee2mqtt siano immediatamente utilizzabili. Ciò che è necessario fare è renderli fruibili all’utente. In primis, quelli necessari ad attivare il paring con gli accessori ZigBee che si vogliono integrare con Home Assistant.

Per ottenere lo scopo utilizzeremo i “Packages“, ovvero un componente di Home Assistant che permette di definire uno o più file di configurazione specifici per servizio (in questo caso zigbee2mqtt), raggruppando così tutte le sue configurazioni in un solo posto. Esattamente come capita nella suddivisione dei file di configurazione, andremo ad aggiungere una voce in configurazione (“packages:“) configurata in modo da puntare a una cartella che contenga tale file.

Tramite “Configurator” (o a mano via SSH, oppure via Samba o altre tecniche)  creare una cartella sotto “config” (quella che contiene la configurazione di Home Assistant, per capirci) chiamata “packages“. In tale cartella, creare un file chiamato “zigbee2mqtt.yaml” e ricopiarvi per interno il seguente codice:

# Input select for Zigbee2mqtt debug level
input_select:
  zigbee2mqtt_log_level:
    name: Zigbee2mqtt Log Level
    options:
      - debug
      - info
      - warn
      - error
    initial: info
    icon: mdi:format-list-bulleted

# Input text to input Zigbee2mqtt friendly_name for scripts
input_text:
  zigbee2mqtt_old_name:
    name: Zigbee2mqtt Old Name
  zigbee2mqtt_new_name:
    name: Zigbee2mqtt New Name
  zigbee2mqtt_remove:
    name: Zigbee2mqtt Remove

# Scripts for renaming & removing devices
script:
  zigbee2mqtt_rename:
    alias: Zigbee2mqtt Rename
    sequence:
      service: mqtt.publish
      data_template:
        topic: zigbee2mqtt/bridge/config/rename
        payload_template: >-
          {
            "old": "{{ states.input_text.zigbee2mqtt_old_name.state | string }}",
            "new": "{{ states.input_text.zigbee2mqtt_new_name.state | string }}"
          }
  zigbee2mqtt_remove:
    alias: Zigbee2mqtt Remove
    sequence:
      service: mqtt.publish
      data_template:
        topic: zigbee2mqtt/bridge/config/remove
        payload_template: "{{ states.input_text.zigbee2mqtt_remove.state | string }}"

# Timer for joining time remaining (120 sec = 2 min)
timer:
  zigbee_permit_join:
    name: Time remaining
    duration: 120

sensor:
  # Sensor for monitoring the bridge state
  - platform: mqtt
    name: Zigbee2mqtt Bridge state
    state_topic: "zigbee2mqtt/bridge/state"
    icon: mdi:router-wireless
  # Sensor for Showing the Zigbee2mqtt Version
  - platform: mqtt
    name: Zigbee2mqtt Version
    state_topic: "zigbee2mqtt/bridge/config"
    value_template: "{{ value_json.version }}"
    icon: mdi:zigbee
  # Sensor for Showing the Coordinator Version
  - platform: mqtt
    name: Coordinator Version
    state_topic: "zigbee2mqtt/bridge/config"
    value_template: "{{ value_json.coordinator }}"
    icon: mdi:chip

# Switch for enabling joining
switch:
  - platform: mqtt
    name: "Zigbee2mqtt Main join"
    state_topic: "zigbee2mqtt/bridge/config/permit_join"
    command_topic: "zigbee2mqtt/bridge/config/permit_join"
    payload_on: "true"
    payload_off: "false"

automation:
  # Automation for sending MQTT message on input select change
  - alias: Zigbee2mqtt Log Level
    initial_state: "on"
    trigger:
      platform: state
      entity_id: input_select.zigbee2mqtt_log_level
    action:
      - service: mqtt.publish
        data:
          payload_template: "{{ states('input_select.zigbee2mqtt_log_level') }}"
          topic: zigbee2mqtt/bridge/config/log_level
  # Automation to start timer when enable join is turned on
  - id: zigbee_join_enabled
    alias: Zigbee Join Enabled
    hide_entity: true
    trigger:
      platform: state
      entity_id: switch.zigbee2mqtt_main_join
      to: "on"
    action:
      service: timer.start
      entity_id: timer.zigbee_permit_join
  # Automation to stop timer when switch turned off and turn off switch when timer finished
  - id: zigbee_join_disabled
    alias: Zigbee Join Disabled
    hide_entity: true
    trigger:
      - platform: event
        event_type: timer.finished
        event_data:
          entity_id: timer.zigbee_permit_join
      - platform: state
        entity_id: switch.zigbee2mqtt_main_join
        to: "off"
    action:
      - service: timer.cancel
        data:
          entity_id: timer.zigbee_permit_join
      - service: switch.turn_off
        entity_id: switch.zigbee2mqtt_main_join

salvare poi il file e tornare nella cartella “config“, aprire il file “configuration.yaml” e aggiungere in fondo la seguente riga:

homeassistant:
  packages: !include_dir_named packages

N.b. Se il blocco “homeassistant:” esiste già, provvedere solo ad includervi sotto la riga “packages: !include_dir_named packages“.

Infine salvare e uscire. Recarsi alla voce di menu “Configurazione” > “Gestione del server” e cliccare su “CONTROLLA LA CONFIGURAZIONE“: se – e solo se – la configurazione risulta corretta, provvedere a un riavvio di Home Assistant (voce “RIAVVIARE” a fondo pagina).

Al riavvio, nuove entità di diversa natura saranno apparse presso Home Assistant.

Frontend

È il momento di gestire via interfaccia web/app Lovelace UI il BRIDGE/Gateway ZigBee appena creato.

Se il controllo dell’interfaccia Lovelace è stato lasciato automatico, lasciando “fare a lei“, allora certamente saranno apparse nuove interfacce, come segue:

zigbee2mqtt - Home Assistant - Lovelace automatica

si tratta, ovviamente, solo della rappresentazione visiva delle nuove entità appena nate: se non viene visualizzato il tutto è certamente perché Lovelace è stata personalizzata dall’utente e quindi queste interfacce non appaiono automaticamente (oppure è stato sbagliato qualcosa precedentemente nell’attuazione della guida). Per tagliare la testa al toro è sufficiente verificare che esista un’entità (“Strumenti per gli sviluppatori” > “Stati“) di nome sensor.zigbee2mqtt_bridge_state, la quale abbia stato “online”. Questo conferma che l’integrazione è avvenuta in modo corretto.

CUSTOM CARD

La cosa migliore, però, è creare una custom card Lovelace per ottenere solo l’interfaccia minimale di controllo della rete ZigBee. Per farlo è sufficiente cliccare in alto a destra sui tre puntini, e poi su “Configura interfaccia utente”.

A questo punto cliccare in basso a destra sul “+”, selezionando poi “MANUAL CARD“.

Inserire poi in questo punto:

Home Assistant - Lovelace - Nuova Manual card

il seguente codice:

title: Zigbee2mqtt
type: entities
show_header_toggle: false
entities:
  - entity: sensor.zigbee2mqtt_bridge_state
  - entity: sensor.zigbee2mqtt_version
  - entity: sensor.coordinator_version
  - entity: input_select.zigbee2mqtt_log_level
  - type: divider
  - entity: switch.zigbee2mqtt_main_join
  - entity: timer.zigbee_permit_join
  - type: divider
  - entity: input_text.zigbee2mqtt_old_name
  - entity: input_text.zigbee2mqtt_new_name
  - entity: script.zigbee2mqtt_rename
  - type: divider
  - entity: input_text.zigbee2mqtt_remove
  - entity: script.zigbee2mqtt_remove

infine, salvare e uscire.
Presso l’interfaccia di Home Assistant apparirà una box come segue:

zigbee2mqtt - Lovelace manual card

la quale conterrà tutti gli elementi strettamente necessari per la futura amministrazione della rete Zigbee.

Uso

A questo punto il BRIDGE/Gateway presso Home Assistant è pronto e utilizzabile al fine di integrare componenti ZigBee compatibili con l’accoppiata CC2531/zigbee2mqtt. Questo è oggetto della parte 2 di questo progetto, in fase di realizzazione e di prossima pubblicazione.


Home Assistant Official LogoATTENZIONE: 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.


Please comment below