Installazione chiavetta USB ZiGBEE su RPi

Benvenuti nella rubrica "l'angolo dei lettori". Questo spazio altro non è che una sezione del blog che permette a chiunque di scrivere un articolo o realizzare un video, effettuare prove e test che riguardano il mondo della tecnologia e proporne la pubblicazione su queste pagine.

Oggi Gianpiero Ammendola, che ringraziamo per questa splendida guida, ci spiegherà come configurare una chiavetta USB Zigbee su Raspberry al fine di realizzare un hub per dispositivi compatibili. In pratica con un’unica chiavetta potremmo controllare per esempio PIR e sensori Porta/Finestra Xiaomi, luci Philips Hue e Ikea Tradfri senza dover acquistare 3 diversi gateway.

Requisiti

Conoscenze dell’utente

Conoscenza degli strumenti di base dei sistemi Linux ed utilizzo di editor come nano.

Requisiti tecnici

I requisiti hardware sono:

• Raspberry preferibilmente Pi3/Pi3+ Link Amazon
• Chiavetta USB Zigbee (CC2531 USB sniffer) Link Amazon, Link Aliexpress
• Programmatore USB Zigbee (CC Debuggerr) Link Aliexpress
• Cavetto/prolunga per chiavetta Zigbee  Link Aliexpress

I requisiti software sono:

• Broker MQTT tipo Mosquitto installato su Raspberry o broker integrato nel controller domotico (ad esempio Home Assistant): potete seguire la guida pubblicata qui: (https://www.vincenzocaputo.com/picoblog/view/66/installare_mqtt_broker_su_raspberry)

• Software di domotica (Controller), in questa guida vedremo i passaggi per utilizzare Home Assistant, ma è possibile utilizzare anche altri controller come Domoticz

Installazione firmware custom su USB Sniffer

Il primo passo consiste nel caricare (“flashare”) un firmware custom sulla chiavetta USB zigbee, per fare questo ci sono almeno due modalità:

1. Utilizzo del CC Debuggerr che è la strada che seguiremo in questa guida
2. Utilizzo di ESP8266/Arduino, per le guide potete cercare su Google.

Anche utilizzando il CC Debuggerr abbiamo due strade a disposizione:

Flash con MacOS / Linux

È la strada che ho seguito io, utilizzando un iMac, i passaggi sono i seguenti:

1. Installare le seguenti librerie (per MacOS è neccesario Brew):

• Ubuntu: libusb-1.0, libboost-all-dev

• Fedora: boost-devel, libusb1-devel

• MacOS: libusb boost pkgconfig

2. Costruzione del cc-tool:

git clone https://github.com/dashesy/cc-tool.git

cd cc-tool

./configure

make

3. Collegare tra loro CC Debugger, cavetto e chiavetta CC2531

4. Collegare sia CC Debugger che CC2531 a due porte USB sul PC

5. Scaricare da qui (https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2531/bin) il firmware CC2531ZNP-Prod.hex

6. Flashare il firmware con il commando: sudo ./cc-tool -e -w CC2531ZNP-Prod.hex

Flash con Windows

1. Installare il programmatore SmartRF Flash (http://www.ti.com/tool/FLASH-PROGRAMMER) (non la versione 2). Questo software è gratuito ma richiede un account per il download.

2. Installare il driver (http://www.ti.com/general/docs/lit/getliterature.tsp?baseLiteratureNumber=swrc212&fileType=zip) per il CC Debuggerr CC sul PC Windows. Prima di continuare, verificare che il driver CC Debuggerr sia stato installato correttamente facendo riferimento alla guida Texas Iinstruments (http://www.ti.com/lit/ug/swru197h/swru197h.pdf). Nel caso in cui il CC Debugger non venga riconosciuto correttamente, occorre installare il driver manualmente, come riportato qui: https://www.youtube.com/watch?v=jyKrxxXOvQY.

3. Collegare tra loro CC Debugger, cavetto e chiavetta CC2531

4. Collegare sia CC Debugger che CC2531 a due porte USB sul PC

5. Se la spia sul CC Debugger è ROSSA, premere il pulsante di reset e verificare che la luce diventi VERDE. (N.B a me con il Mac la luce è rimasta rossa e il flashing del firmware è andato comunque a buon fine)

6. Scaricare da qui (https://github.com/Koenkk/Z-Stack-firmware/tree/master/coordinator/CC2531/bin) il firmware CC2531ZNP-Prod.hex

7. Flashare il firmware con SmartRF Flash come nell’immagine di seguito.

Configurazione della chiavetta USB zigbee

Per semplicità la guida ipotizza che la chiavetta sia collegata ad un Raspberry Pi3 con OS Raspian Stretch (in particolare ho utilizzato un RPi3 con Hassbian basato sulla distro Stretch).

Verifica installazione chiavetta

Per prima cosa occorre collegare la chiavetta USB zigbee precedentemente “flashata” con il custom firmware ad una porta USB del Raspberry e verificare quale sia il device di comunicazione, di solito /dev/ttyACM0

pi@hassbian:~/HA$ ls -l /dev/ttyACM0

crw-rw---- 1 root dialout 166, 0 Sep 18 16:33 /dev/ttyACM0

Installazione node.js e NPM

Verificate se non abbiate già installati node.je e NPM:

pi@hassbian:~/HA$ npm --version

5.6.0

pi@hassbian:~/HA$ node --version

v8.11.3

Se non lo fossero procedete all’installazione:

#Setup del repository Node.js

sudo curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -

# Installazione Node.js

sudo apt-get install -y nodejs git make g++ gcc

Una volta verificato che NPM e node.js siano installati, si procede all’installazione del package zigbee2mqtt:

# Clonazione del repository zigbee2mqtt

sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt

sudo chown -R pi:pi /opt/zigbee2mqtt

# Installazione  

cd /opt/zigbee2mqtt

npm install

Dopo numerosi messaggi di warning l’installazione si concluderà con il numero di package installati

Configurazione zigbee2mqtt.

Finalmente siamo arrivati alla parte conclusiva della configurazione, occorre ora inserire i parametri affinché il modulo zigbee2mqtt comunichi con il broker MQTT, editando il file configuration.yaml (NON quello di Home Assistant) con il seguente comando:

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

I parametri da inserire saranno user e password, se necessari, l’indirizzo IP o localhost del broker MQTT e la porta dove è collegata la chiavetta USB.

homeassistant: true
permit_join: true
mqtt:
  base_topic: zigbee2mqtt
  server: 'mqtt://localhost' #o indirizzo IP del RPI3
  user: USER
  password: PASS
serial:
  port: /dev/ttyACM0

Dopo aver inserito i parametri salvare e chiudere il file.

Eccoci quindi all’avvio del software, occorre digitare:

cd /opt/zigbee2mqtt

npm start

Se è tutto Ok vedrete qualcosa tipo questo: (CTRL + C per uscire):

2018-9-18 18:35:09 INFO zigbee-shepherd ready

2018-9-18 18:35:09 INFO Connected to MQTT server

Utilizzo del gestore di servizi systemd

Avviare a mano zigbee2mqtt non è una buona idea, molto meglio far gestire a systemd il software zigbee2mqtt come daemon che gira in background, ecco come fare:

# Creare il file di configurazione per zigbee2mqtt

sudo nano /etc/systemd/system/zigbee2mqtt.service

# Inserire i seguenti comandi nel file appena creato

[Unit]
Description=zigbee2mqtt
After=network.target
[Service]
ExecStart=/usr/bin/npm start
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
StandardError=inherit
Restart=always
User=pi
[Install]
WantedBy=multi-user.target

Salvare il file ed uscire.

Ora si può avviare il daemon e verificare che funzioni:

# caricare la configurazione systemd

sudo systemctl daemon-reload

# Avviare zigbee2mqtt

sudo systemctl start zigbee2mqtt.service

# Mostrare lo stato

sudo systemctl status zigbee2mqtt.service

Se va tutto bene dovreste vedere qualcosa come di seguito, importate è lo stato active (running):

● zigbee2mqtt.service - zigbee2mqtt

  Loaded: loaded (/etc/systemd/system/zigbee2mqtt.service; enabled; vendor preset: enabled)

  Active: active (running) since Tue 2018-09-18 21:23:30 CEST; 1 day 12h ago

Main PID: 582 (npm)

  CGroup: /system.slice/zigbee2mqtt.service

          â”œâ”€582 npm

          â”œâ”€878 sh -c node index.js

          â””─879 node index.js

Per rendere effettiva la configurazione ad ogni riavvio, occorre digitare il seguente comando:

sudo systemctl enable zigbee2mqtt.service

Corretta inizializzazione dei servizi

Affinché Home Assistant funzioni correttamente occorre rispettare la giusta sequenza di avvio dei vari servizi che partono ad ogni reboot del Raspberry: il motivo è che se il daemon home-assistant@homeassistant parte prima di quello zigbee2mqtt Home Assistant non riconoscerà i sensori.

Quindi la giusta sequenza di avvio dei servizi deve essere la seguente:

mqtt (mosquitto) --> zigbee2mqtt --> homeassistant

Per fare questo occorre inserire dei comandi nei file di configurazione dei daemon nella sottosezione [Unit]:

# in /etc/systemd/system/zigbee2mqtt.service

After=network.target mosquitto.service

# in /etc/systemd/system/home-assistant@homeassistant.service

After=network.target mosquitto.service zigbee2mqtt.service

Il problema che si presenta è che il broker MQTT Mosquitto sia configurato con il gestore di servizi init.d e non con systemd, è quindi necessario configurare correttamente Mosquitto con systemd, ecco la procedura:

# Cancellare lo script init.d

sudo systemctl stop mosquitto

sudo update-rc.d mosquitto remove

sudo rm /etc/init.d/mosquito

# Creare il file di configurazione systemd usando l’editor nano

sudo nano /etc/systemd/system/mosquitto.service

#Inserire i seguenti comandi nel file appena creato

[Unit]

Description=MQTT v3.1 message broker

After=network.target

Requires=network.target

[Service]

Type=simple

ExecStart=/usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf

Restart=always

[Install]

WantedBy=multi-user.target

Salvate e uscite, quindi avviate la sequenza di comandi il mosquitto.service:

# caricare la configurazione systemd

sudo systemctl daemon-reload

# Avviare mosquitto

sudo systemctl start mosquitto.service

# Mostrare lo stato

sudo systemctl status mosquitto.service

se è andato tutto bene vedrete qualcosa come di seguito:

● mosquitto.service - MQTT v3.1 message broker

  Loaded: loaded (/etc/systemd/system/mosquitto.service; enabled; vendor preset: enabled)

  Active: active (running) since Tue 2018-09-18 21:23:30 CEST; 1 day 13h ago

Main PID: 579 (mosquitto)

  CGroup: /system.slice/mosquitto.service

          â””─579 /usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf

Per rendere effettiva la configurazione ad ogni riavvio, occorre digitare il seguente comando:sudo systemctl enable mosquitto.service

Pairing dei device Zigbee

Siamo arrivati finalmente alla fine della guida: la chiavetta USB zigbee è stata configurata con il custom firmware, il Rasperry è stato configurato con i vari componenti software, ora si può disaccoppiare il device domotico dal suo gateway/bridge proprietario e accoppiarlo (“pairing”) alla chiavetta.

Ogni famiglia di prodotti ha la sua procedura di unpairing-pairing, di seguito vi scrivo quella per device Xiaomi testata con il cubo Aqara:

• tenere premuto il tastino o premere con lo spillino per 5 secondi, il sensore deve fare 3 blink blu,

• rilasciare il tastino, verificare che faccia un altro blink singolo, aspettare 1 secondo e verificare che ne faccia altri 3 veloci (questo è il segnale che il sensore riesce a vedere qualcosa a cui accoppiarsi).

• subito dopo i tre veloci cliccare di nuovo in modo da far riaccendere il led e ogni volta che si spegne va ripremuto il tasto fino a che il device non è accoppiato, se il paring non va a buon fine, occorre ricominciare il procedimento da capo.

La procedura sembra complicata ma in realtà con un paio di tentativi dovrebbe andare. Per verificare il pairing si può controllare con sudo systemctl status zigbee2mqtt.service ci saranno dei messaggi con lo stato della procedura.

Se in Home Assistant è configurato l’auto discovery dei device MQTT vedrete dei sensori con il formato sensor.0x0015xxxxxxxxxxxx .

Esempio di automazione con Home Assistant

Una volta correttamente riconosciuti da HA possiamo creare tutte le automazioni che vogliamo, ad esempio propongo questa per aumentare la luminosità di una lampadina Yeelight con il cubo Xiaomi Aqara:

automation:
  - alias: aumenta luminosita luce ingresso con cubo
    trigger:
      platform: mqtt
      topic: 'zigbee2mqtt/0x0015xxxxxxxxxxxx'
    condition:
    - condition: template
      value_template: "{{ 'rotate_right' == trigger.payload_json.action }}"
    - condition: state
      entity_id: light.yeelight_luce_ingresso
      state: 'on'
    action:
    - service: light.turn_on
      entity_id: light.yeelight_luce_ingresso
      data_template:
        brightness: >-
       {{ states.light.yeelight_luce_ingresso.attributes.brightness | round(0) + 50 }}

Per diminuire la luminosità si può creare un’altra automazione che intercetta l’evento “rotate_left”.

STAMPA LA COVER PER LA CHIAVETTA IN 3D

Ciliegina sulla torta: Sandrin Enrico ha gentilmente realizzato per vincenzocaputo.com dei file STL personalizzati con il nostro logo, da stampare in 3D, per realizzare la custodia della chiavetta ZigBee utilizzata per questo progetto. Ringraziamo veramente di cuore Enrico per questa sua stupenda iniziativa. Di seguito potete vedere anche il rendering che ha realizzato e potete scaricare i file STL da stampare in 3D.

https://drive.google.com/open?id=1V2mxNBpBuPV_kky2Jx05nA1ZZGOPDeo3 

https://drive.google.com/open?id=1XuI9ZYJTONtefTeSBewv3_mBUabTRjKp

https://drive.google.com/open?id=1BrRK4KyMFb2hQGDlsyudpNWOUQBRv3tH

https://drive.google.com/open?id=1-fGnOSmIE0XxDmTVWWftVN24BNfBthOx

Appendice

Credits

La guida si basa in gran parte sulla wiki pubblicata su github in lingua inglese: https://github.com/Koenkk/zigbee2mqtt

HASS.io

Per Hass.io è disponibile un add-on ufficiale, qui potete trovare le info necessarie: https://github.com/danielwelch/hassio-zigbee2mqtt