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

8 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
  • Categoria d’integrazione: Local Push
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.3

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” – 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.

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 “Supervisor” > “SYSTEM” >”REBOOT“).

VERIFICA POST-INSTALLAZIONE

Dopo aver installato l’antenna e aver avviato HASSIO, accedere a quest’ultimo e, presso la voce di menu “Supervisor” > “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 .

Broker e client 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, nonché la presenza delle funzionalità client MQTT presso Home Assistant.

Per configurare broker e/o client MQTT su HASSIO, si faccia riferimento a questa guida.

N.b. Procedere nella presente guida senza aver provveduto a installare correttamente broker e client MQTT causerà, ovviamente, un malfunzionamento di zigbee2mqtt. IMPORTANTE: In fase di configurazione della parte client, avere cura di attivare la voce “Attiva l’individuazione

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 “Supervisor” > “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: MIO_USERNAME_MQTT
  password: MIA_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.

ATTENZIONE: se l’avvio va in errore, fermare l’add-on, modificare il campo “port” della configurazione indicando il percorso individuato installando l’antenna, salvare e provare ad avviarlo.

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 package, una funzione di Home Assistant che permette di definire uno o più file di configurazione specifici, raggruppando così tutte le sue configurazioni in un solo posto. Per capire come utilizzare questo componente e installato è utile leggere questa scheda.

Tramite “File Editor” (o a mano via SSH, oppure via Samba o altre tecniche) creare, nella cartella scelta per i packages (solitamente “packages” all’interno della cartella che contiene i file di configurazione di Home Assistant), 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
    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
    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

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.


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