In questa guida andremo a vedere come effettuare l’installazione del software zigbee2mqtt sul nostro Raspberry dotato di Raspbian ed effettuare l’integrazione con il dongle USB CC2531.
Per poter procedere quindi, assicuratevi di aver pronta e funzionante la vostra chiavetta CC2531. Se ve lo siete perso, ecco qui l’articolo.
Inoltre dovrete già avere attivo un broker MQTT sul vostro Raspberry, se così non fosse, installate il broker MOSQUITTO da questa guida.
Attacchiamo quindi la chiavetta ad una porta USB del Raspberry e riavviamo.
Andiamo ora a scoprire il nome della porta USB a cui abbiamo attaccato la nostra chiavetta. (Assicuratevi quindi da ora in poi di utilizzare la chiavetta sempre sulla stessa porta USB)
Creiamo un file:
sudo nano check_usb_port_cc2531.sh
e copiamoci dentro:
#!/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
Salviamo ed usciamo con CTRL+X, Y e INVIO
Successivamente digitiamo:
sudo chmod 777 check_usb_port_cc2531.sh ./check_usb_port_cc2531.sh
Verrà mostrato a schermo un risultato simile a questo:
/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 di nostro interesse è quella che inizia con /dev/tty, quindi nel nostro caso segniamoci:/dev/ttyACM0
INSTALLAZIONE DI ZIGBEE2MQTT
Sempre da terminale SSH, digitiamo:
sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt sudo chown -R pi:pi /opt/zigbee2mqtt cd /opt/zigbee2mqtt
e ancora:
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
infine:
cd /opt/zigbee2mqtt npm install deactivate
Ora andiamo a modificare la configurazione di zigbee2mqtt attraverso il suo file di configurazione configuration.yaml che si trova in /opt/zigbee2mqtt (da non confondere con configuration.yaml di Home Assistant). Possiamo farlo tramite SSH con il comando:
cd /opt/zigbee2mqtt/data/ sudo nano configuration.yaml
Ma io consiglio vivamente di attivare SAMBA per il trasferimento dei file tra Windows e Rapberry.
All’interno del file configuration.yaml troverete un contenuto simile a questo:
homeassistant: true permit_join: true mqtt: base_topic: zigbee2mqtt server: 'mqtt://localhost' user: mqtt_username password: mqtt_password serial: port: /dev/ttyACM0
Personalizziamo quindi i campi:
- user: inseriamo la username del nostro broker MQTT
- password: inseriamo la password del nostro broker MQTT
- port: inseriamo il nome della porta USB dove è collegato il nostro dongle
Salviamo.
Ora andiamo a configurare il servizio per far in modo che zigbee2mqtt si avvii in automatico ad ogni avvio del Raspberry:
sudo nano /etc/systemd/system/zigbee2mqtt.service
Incolliamoci dentro:
[Unit] Description=zigbee2mqtt After=network.target [Service] ExecStart=/bin/bash -c 'source /opt/zigbee2mqtt/bin/activate; /opt/zigbee2mqtt/bin/npm start' WorkingDirectory=/opt/zigbee2mqtt StandardOutput=inherit StandardError=inherit Restart=always User=pi [Install] WantedBy=multi-user.target
Salviamo e andiamo ad avviare il servizio:
sudo systemctl enable zigbee2mqtt.service sudo systemctl start zigbee2mqtt.service
Verifichiamo che ora sia tutto a posto con il comando:
sudo systemctl status zigbee2mqtt.service
Apparirà una schermata simile a questa:
Se vedere la scritta verde: active (running) significa che il tutto funziona correttamente.
INTEGRAZIONE CON HOME ASSISTANT
Andiamo ora a integrare il tutto su Home Assistant, andando a modificare il configuration.yaml e aggiungendo il blocco mqtt, se non già presente:
mqtt: discovery: true broker: 127.0.0.1 port: 1883 username: mqtt_user password: mqtt_password client_id: home-assistant keepalive: 60
con l’accortezza di modificare i campi broker, port, username e password in base ai vostri dati.
Salvare e riavviate Home Assistant.
Andiamo ora a creare un package, per comodità, che raggrupperà tutto ciò che riguarda il servizio zigbee2mqtt. Creiamo una cartella packages all’interno della cartella dove si trova configuration.yaml e all’interno di essa creiamo un nuovo file zigbee2mqtt.yaml con all’interno questo:
# 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: Vecchio nome device Zigbee2mqtt
zigbee2mqtt_new_name:
name: Nuovo nome device Zigbee2mqtt
zigbee2mqtt_remove:
name: Rimuovi device Zigbee2mqtt
# Scripts for renaming & removing devices
script:
zigbee2mqtt_rename:
alias: Rinomina device Zigbee2mqtt
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: Rimuovi device Zigbee2mqtt
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: Tempo rimasto per il join
duration: 120
sensor:
# Sensor for monitoring the bridge state
- platform: mqtt
name: Stato Bridge Zigbee2mqtt
state_topic: "zigbee2mqtt/bridge/state"
icon: mdi:router-wireless
# Sensor for Showing the Zigbee2mqtt Version
- platform: mqtt
name: Versione Zigbee2mqtt installata
state_topic: "zigbee2mqtt/bridge/config"
value_template: "{{ value_json.version }}"
icon: mdi:zigbee
- platform: command_line
command: 'curl https://api.github.com/repos/Koenkk/zigbee2mqtt/releases/latest'
name: Versione Zigbee2mqtt disponibile
scan_interval: 3600
value_template: '{{ value_json.tag_name }}'
#icon: mdi:folder-download
# Sensor for Showing the Coordinator Version
- platform: mqtt
name: Versione Coordinator
state_topic: "zigbee2mqtt/bridge/config"
value_template: "{{ value_json.coordinator.meta.revision }}"
icon: mdi:chip
# Switch for enabling joining
switch:
- platform: mqtt
name: "Abilita join Zigbee2mqtt"
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: Join Zigbee abilitato
trigger:
platform: state
entity_id: switch.abilita_join_zigbee2mqtt
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: Join Zigbee disabilitato
trigger:
- platform: event
event_type: timer.finished
event_data:
entity_id: timer.zigbee_permit_join
- platform: state
entity_id: switch.abilita_join_zigbee2mqtt
to: "off"
action:
- service: timer.cancel
data:
entity_id: timer.zigbee_permit_join
- service: switch.turn_off
entity_id: switch.abilita_join_zigbee2mqtt
Apriamo il file configuration.yaml di Home Assistant e aggiungiamo:
homeassistant: packages: !include_dir_named packages
(nel caso homeassistant: fosse già presente, accodare semplicemente la seconda riga se non lo fosse già stata messa in precedenza: packages: !include_dir_named packages)
Salviamo e riavviamo Home Assistant.
Andiamo ora a creare una custom card di lovelace per la rappresentazione grafica dei componenti appena aggiunti. Apriamo il nostro file ui-lovelace.yaml all’interno del percorso di installazione di Home Assistant e aggiungiamo:
- title: Zigbee2mqtt
type: entities
show_header_toggle: false
entities:
- entity: sensor.stato_bridge_zigbee2mqtt
- entity: sensor.versione_zigbee2mqtt_installata
- entity: sensor.versione_zigbee2mqtt_disponibile
- entity: sensor.versione_coordinator
- entity: input_select.zigbee2mqtt_log_level
- type: divider
- entity: switch.abilita_join_zigbee2mqtt
- 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
Salviamo e riavviamo l’interfaccia lovelace.
Avremo un risultato come questo:
Questo è un pannello puramente amministrativo per la gestione/inserimento di nuovi device.
AGGIORNAMENTO DI ZIGBEE2MQTT
Il package zigbee2mqtt ha già al suo interno un file per eseguirne l’aggiornamento. Quando vedere che è disponibile un aggiornamento dal pannello amministrativo precedente, collegatevi via SSH e digitate:
sudo /opt/zigbee2mqtt/update.sh
AGGIUNGIAMO I DISPOSITIVI (PAIRING)
Vediamo ora come aggiungere/accoppiare nuovi devices al nostro dongle.
Esistono 2 possibilità di pairing: la prima è utilizzando il pannello di controllo installato prima con lovelace, il secondo è manuale cioè andando a modificare una variabile nel file di configurazione ogni volta che dobbiamo inserire nuovi devices.
PAIRING TRAMITE PANNELLO DI CONTROLLO IN LOVELACE
Clicchiamo su Abilita join Zigbee2mqtt. Partirà un timer di 2 minuti nel quale dobbiamo premere il pulsante presente sul nostro dispositivo da accoppiare. (Fare riferimento alle istruzioni del vostro dispositivo, ognuno di essi infatti può avere una procedura diversa per la’accoppiamento, ad esempio la durata di pressione del tasto nella maggior parte dei casi).
A questo punto, se tutto è andato per il verso giusto, il componente risulterà accoppiato.
PAIRING MANUALE
E’ possibile utilizzare il pairing manuale in tutte le occasioni in cui il pairing da pannello lovelace per qualsiasi modo fallisca.
- HOME ASSISTANT SU RASPBIAN: Aprire il file posizionato in opt/zigbee2mqtt/data/configuration.yaml e impostare il campo permit_join in true. Riavviare il servizio con:
sudo systemctl restart zigbee2mqtt
- HASSIO: stoppare l’add-on, modificare il parametro permit_join in true e riavviare l’add-on
Per comodità possiamo ora aprire un terminale e dare il comando:
sudo journalctl -u zigbee2mqtt.service -fil quale farà sì di mostrare a schermo tutto ciò che sta succedendo in background. In questo modo sarà più semplice accorgersi dell’avvenuto pairing di un nuovo dispositivo.
Ora premere il pulsante presente sul nostro dispositivo da accoppiare. (Fare riferimento alle istruzioni del vostro dispositivo, ognuno di essi infatti può avere una procedura diversa per la’accoppiamento, ad esempio la durata di pressione del tasto nella maggior parte dei casi).
Una volta accoppiati tutti i dispositivi necessari, è bene reimpostare il campo permit_join in false per evitare l’inserimento accidentale di nuovi devices (magari il vostro vicino di casa ha componenti zigbee2mqtt e se anche lui sta configurando un Home Assistant, potreste trovarvi un giorno i suoi dispositivi nel vostro sistema!)
HOME ASSISTANT
Una volta completato il pairing, il componente apparirà tra gli stati. Potete verificare andando a controllare in Strumenti per gli sviluppatori -> Stati
Nell’esempio sotto un join di un sensore di temperatura Xiaomi Aqara che si contraddistingue con nomi non simpaticissimi, del tipo 0x…………._temperature
Per HASSIO invece la strada è diversa: basta andare nel menu zigbee2mqtt della Dashboard e verificare i log per controllare l’ultimo accesso eseguito dal nuovo dispositivo.
Ora che il vostro device è stato integrato ed è visibile in Home Assistant, siete liberi di mostrarlo in una custom card di lovelace oppure crearvi la vostra automazione personalizzata.
Changelog revisioni:
04/04/2020
- Rimosso hide_entity: true, deprecato da Home Assistant 0.105
