Integrare CC2531 con Home Assistant via zigbee2mqtt su Raspberry Pi (parte 1)

10 minuti di lettura
SCOPI DELLA GUIDA:
  • Integrare un BRIDGE/Gateway ZigBee↔︎TCP/IP CC2531 con Home Assistant (installato su Raspberry Pi con sistema operativo Raspbian) 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:
  • Home Assistant configurato e funzionante come applicativo su sistema operativo Raspbian
DISPOSITIVI FISICI UTILIZZATI:
GUIDA maggiormente indicatA per:

Tutti gli ambienti

Note e disclaimer
  • qualsiasi modifica all'impianto elettrico dev'essere progettata ed effettuata 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.

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, tale BRIDGE/Gateway “standard” è pienamente integrabile con Home Assistant.

In questa guida vedremo infatti quali siano i passi per integrarlo su Home Assistant installato come applicativo su Raspberry Pi con sistema operativo Raspbian. La versione dedicata alla distribuzione HASSIO è invece disponibile qui.

N.b. Questa guida, “parte 1”, serve per realizzare la piena integrazione di zigbee2mqtt. La “parte 2” – disponibile qui – 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.

VERIFICA POST-INSTALLAZIONE

Dopo aver installato l’antenna su una porta USB e aver riavviato Raspberry Pi è il momento di effettuare una verifica e riconoscere a quale porta logica sia stata assegnata.

A questo scopo andiamo a definire uno script; via terminale, eseguire il seguente comando:

sudo nano cc2531.sh

e copiare all’interno dell’editor che si aprirà il seguente codice:

#!/bin/bash

for sysdevpath in $(find /sys/bus/usb/devices/usb*/ -name dev); do
    (
        syspath="${sysdevpath%/dev}"
        devname="$(udevadm info -q name -p $syspath)"
        [[ "$devname" == "bus/"* ]]
        eval "$(udevadm info -q property --export -p $syspath)"
        [[ -z "$ID_SERIAL" ]]
        echo "/dev/$devname - $ID_SERIAL"
    )
done

Poi uscire e salvare (CTRL-X, Y, invio).
Eseguire poi i seguenti comandi:

sudo chmod 777 cc2531.sh 
./cc2531.sh

Il secondo comando eseguirà lo script, il quale riporterà un output similare al seguente:

/dev/bus/usb/001/001 - Linux_4.19.81-v7+_dwc_otg_hcd_DWC_OTG_Controller_3f980000.usb
/dev/bus/usb/001/003 - 0424_ec00
/dev/bus/usb/001/002 - 0424_9514
/dev/ttyACM0 - Texas_Instruments_TI_CC2531_USB_CDC___0X00124B00076887D9
/dev/bus/usb/001/004 - Texas_Instruments_TI_CC2531_USB_CDC___0X00124B00076887D9

La riga che inizia con “tty” e prosegue con “Texas_Instruments_TI_CC2531_USB_CDC è quella che identifica la porta (in questo caso la /dev/ttyACM0).

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

Installare il broker MQTT

Come suggerisce il nome, il software zigbee2mqtt, per funzionare, necessita della presenza di un broker MQTT sulla rete locale alla 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 lo stesso Raspberry Pi allo scopo, installando 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:

Come installare e configurare il broker MQTT “Mosquitto” su Raspberry Pi

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 un’installazione specifica.

Per installare zigbee2mqtt, sempre da terminare, cominciare con la clonazione del repository:

sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
sudo chown -R pi:pi /opt/zigbee2mqtt
cd /opt/zigbee2mqtt

successivamente, installare/aggiornare pip, wheel e setuptools e node:

source /opt/zigbee2mqtt/bin/activate
pip install --upgrade pip wheel setuptools
pip install nodeenv
nodeenv -p -n 10.15.1
deactivate
source /opt/zigbee2mqtt/bin/activate

installare infine le dipendenze:

cd /opt/zigbee2mqtt
npm install
deactivate

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 modificando il file “configuration.yaml” presente presso il path “/opt/zigbee2mqtt/“.

Eseguire, sempre da terminale, il seguente comando:

cd /opt/zigbee2mqtt/data/
sudo nano configuration.yaml

L’editor esporrà il contenuto del file di configurazione:

homeassistant: true
permit_join: true
mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://localhost'
  user: mqtt_username
  password: mqtt_password
serial:
  port: /dev/ttyACM0
devices:
  '0x00158d0002f2dccc':
    friendly_name: '0x00158d0002f2dccc'

I campi da personalizzare sono, principalmente: “homeassistant“, “server“, “user” e “password” (questi ultimi due, da aggiungere) e infine “port“.

Il campo “homeassistant” è necessario impostare “true” al fine di far sì che Home Assistant riconosca automaticamente il BRIDGE zigbee2mqtt; nel campo “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, allora è necessario indicare semplicemente “mqtt://localhost“.

Nei campi “user” e “password“, invece, è necessario indicare le credenziali d’accesso al broker MQTT, indipendentemente da dove esso sia in esecuzione. Infine, nel campo “port” indicare la porta precedentemente identificata.

Una volta terminata la personalizzazione della configurazione, uscire salvando (CTRL+X, Y, invio).

A questo punto abilitare e avviare il servizio zigbee2mqtt tramite i comandi:

sudo systemctl enable zigbee2mqtt.service
sudo systemctl start zigbee.mqtt.service

VERIFICA

Per verificare che tutto sia andato per il verso giusto, eseguire il seguente comando:

sudo systemctl status zigbee2mqtt.service

L’output dovrebbe essere all’incirca il seguente:

zigbee2mqtt service status

il quale status (“active (running)“) identifica un corretto avvio di zigbee2mqtt e un’avvenuta connessione col broker MQTT.

Integrazione con Home Assistant

Arrivati a questo punto siamo pronti per integrare il BRIDGE/Gateway a Home Assistant. Per far ciò è necessario che sia attivo il componente MQTT e, nello specifico, che sia attiva la sua funzionalità di discovery.

È pertanto necessario effettuare una modifica alla configurazione di Home Assistant, aggiungendo (o perfezionando, qualora già esista) il seguente blocco di codice:

mqtt:
  discovery: true
  broker: 127.0.0.1
  port: 1883
  username: mqtt_user
  password: mqtt_password
  client_id: home-assistant
  keepalive: 60

Ovviamente i campi “broker“, “porta“, “username” e “password” dovranno esser personalizzati come precedentemente fatto all’atto della configurazione di zigbee2mqtt.

Al termine della configurazione, riavviare Home Assistant.

A questo punto l’integrazione, di fatto, sarà stata completata, perché la presenza dell’auto-discovery del componente MQTT farà 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.

Creare dunque una cartella che contiene la configurazione di Home Assistant (solitamente”/home/homeassistant/.homeassistant“) 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 di configurazione, 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, disponibile qui.

Aggiornamento di zigbee2mqtt

Per effettuare un eventuale aggiornamento successivo del server zigbee2mqtt, la sequenza di comandi è la seguente:

# Stop zigbee2mqtt and go to directory
sudo systemctl stop zigbee2mqtt
cd /opt/zigbee2mqtt

# Activate environment
source /opt/zigbee2mqtt/bin/activate

# Backup configuration
cp -R data data-backup

# Update
git checkout HEAD -- npm-shrinkwrap.json
git pull
rm -rf node_modules
npm install

# Restore configuration
cp -R data-backup/* data
rm -rf data-backup

# Deactivate environment
deactivate

# Start zigbee2mqtt
sudo systemctl start zigbee2mqtt


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