Maak je eigen ZigBee-gateway

ZigBee is een protocol voor draadloze communicatie op korte afstand en met laag stroomverbruik. Ideaal voor domotica, zou je denken, en inderdaad: zo zijn de lampen van Philips Hue en IKEA Trådfri op ZigBee gebaseerd. Ook Xiaomi en heel wat andere fabrikanten hebben een breed gamma aan ZigBee-apparaten, zoals contactsensoren voor deuren en ramen, temperatuursensoren enzovoort. Vergeleken met Z-Wave, een vergelijkbare technologie, zijn ZigBee-apparaten meestal betaalbaarder.

Om ZigBee-apparaten aan je thuisnetwerk te koppelen zodat je bijvoorbeeld je lampen met je smartphone kunt aansturen, heb je een gateway nodig. Sommige fabrikanten noemen dat ook een hub of een bridge. In correcte ZigBee-termen heet het eigenlijk een concentrator of coördinator. We zullen in deze masterclass afwisselend de termen gateway en coördinator gebruiken.

Mesh-netwerk

ZigBee is een mesh-netwerk: in plaats van elk apparaat rechtstreeks met de gateway te verbinden, communiceren alle apparaten van het netwerk met elkaar. Ze sturen een boodschap gewoon door naar naburige apparaten, die die weer doorstuurt, tot ze bij de ontvanger is aangekomen. Zo kunnen twee ZigBee-apparaten zelfs met elkaar communiceren als ze zich niet in elkaars bereik bevinden, zolang er maar een apparaat tussen staat dat zich in het bereik van de twee apparaten bevindt.

Elk ZigBee-netwerk heeft één coördinator, die het netwerk opstart en beheert. In domotica wordt dit vaak de gateway genoemd, omdat dit apparaat het ZigBee-netwerk ook met je thuisnetwerk verbindt (een gateway verbindt altijd twee incompatibele netwerken). Daarnaast zijn er ook routers: die hebben een eigen taak, zoals een lamp, schakelaar of sensor, en sturen daarnaast boodschappen van andere ZigBee-apparaten door. Omdat een router het best altijd ingeschakeld is, zijn dat meestal apparaten die je in het stopcontact steekt, zoals een lamp.

Tot slot heb je ook de gewone apparaten, die hun taak uitvoeren maar geen boodschappen doorsturen omdat ze op batterijen werken en dus niet altijd ingeschakeld zijn. Elk van deze apparaten stuurt zijn boodschappen rechtstreeks naar de coördinator of naar een router.

Je eigen gateway

De meeste mensen gebruiken ZigBee met een gateway van de fabrikant van hun apparaten. De kans is groot dat je bijvoorbeeld de Philips Hue Bridge gebruikt om je Philips Hue-lampen op afstand aan te sturen, en de IKEA hub als je IKEA Trådfri-lampen hebt gekocht. Maar dat hoeft niet: uiteindelijk gaat het onderliggend allemaal om de ZigBee-standaard en kun je in principe dus om het even welke gateway gebruiken die deze standaard ondersteunt.

In deze masterclass tonen we je hoe je van een Raspberry Pi een ZigBee-gateway maakt, door een ZigBee-transceiver op een usb-poort aan te sluiten. Met de software Zigbee2MQTT maak je dan een coördinator van je Raspberry Pi, en kun je in Home Assistant of andere domoticasoftware via het berichtenprotocol MQTT je ZigBee-netwerk aansturen. Aan het einde van deze masterclass krijg je de metingen van je ZigBee-sensoren dus in je dashboard van Home Assistant te zien en kun je ook je ZigBee-lampen en -schakelaars via ditzelfde dashboard aansturen.

ZigBee-adapter

Om de ZigBee-signalen te kunnen ontvangen en uitsturen op je Raspberry Pi heb je een adapter nodig. Zigbee2MQTT ondersteunt meerdere adapters. De bekendste adapter is de ConBee II, en die zou out-of-the-box bruikbaar moeten zijn, maar de ondersteuning in Zigbee2MQTT is nog experimenteel.

Voor kleine netwerken (minder dan 20 ZigBee-apparaten) is de Texas Instruments CC2531 bruikbaar. Die is voor ongeveer 5 euro te vinden op AliExpress, maar je moet er zelf nog (eenmalig) firmware op flashen (al verkoopt iTead ze ook met compatibele firmware voorgeïnstalleerd). Daarvoor heb je nog een speciale downloaderkabel nodig en vier jumperdraden. Voor grotere netwerken zijn de Electrolama zig-a-zig-ah! en de CC2652RB-stick van slaesh aan te raden: ze kunnen meer dan 100 ZigBee-apparaten aan, hebben een beter bereik door een externe antenne en hebben geen extra hardware nodig om de firmware erop te flashen. In deze masterclass maken we gebruik van de CC2531.

Sluit de CC2531 aan

De downloaderkabel bestaat uit een vierkanten printplaatje met 10-pins header aan de ene kant en een kleinere header met 10 pinnen aan de andere kant. Er zit ook een dunne lintkabel bij. Daarvan steek je de ene connector in de kleine header van het printplaatje, en de andere connector in dezelfde header op de CC2531. Wees voorzichtig wanneer je de connectors insteekt, want de pinnetjes zijn klein en kwetsbaar. De grote header van het downloaderprintplaatje sluit je nu met jumperdraden als volgt op de gpio-pinnen van je Raspberry Pi aan zoals in tabel 1.

Kijk op de website voor de pinnummers van de Raspberry Pi. De pinnnummers van de downloader vind je op de printplaat achter de header.

Nadat je de CC2531 op de downloader hebt aangesloten en alle jumperdraden tussen het downloaderprintplaatje en de Raspberry Pi hebt aangesloten, steek je de CC2531 in een usb-poort van je Raspberry Pi. Hij is nu klaar om van nieuwe firmware te voorzien.

Interferentie met bluetooth en wifi

Flashprogramma

We gaan nu vanaf je Raspberry Pi nieuwe firmware flashen op de CC2531. Installeer eerst wiringPi en git:

sudo apt install wiringpi git

Download dan de software om je CC2531 te flashen en controleer of de software de chip herkent:

git clone https://github.com/jmichault/flash_cc2531.git
cd flash_cc2531
./cc_chipid

Die laatste opdracht zou ID = b524. moeten teruggeven. Zo niet, controleer dan of je alles goed hebt aangesloten.

Flash de firmware

Download de firmware van www.tiny.cc/z-stack. Je vindt deze in de map coordinator. Voor de CC2531 is de firmware Z-Stack_Home_1.2 aangeraden. Ga daarin naar de map bin. Is je netwerk minder dan dertig apparaten groot, open dan de map default, anders source_routing. Open dan het juiste zip-bestand voor de CC2531. Op je Raspberry Pi download je dat zip-bestand en pak je het uit:

wget https://github.com/Koenkk/Z-Stack-firmware/raw/master/coordinator/Z-Stack_Home_1.2/bin/default/CC2531_DEFAULT_20190608.zip

unzip CC2531_DEFAULT_20190608.zip

Wis daarna het flashgeheugen van de CC2531 en schrijf de nieuwe firmware ernaar:

./cc_erase

./cc_write CC2531ZNP-Prod.hex

Als je je uiteindelijk flash OK te zien krijgt, is het flashen gelukt. Verwijder de jumperdraden tussen de downloader en de Raspberry Pi, haal de CC2531 uit de usb-poort en verwijder ook de downloaderkabel van de CC2531. Die laatste is nu een ZigBee-coördinator. Steek de CC2531 weer in de usb-poort, het liefst met een usb-verlengkabel ertussen (zie het kader ‘Interferentie met bluetooth en wifi’). Bekijk dan met de opdracht dmesg|grep tty wat het apparaatbestand van de CC2531 is. Normaal gesproken is dat /dev/ttyACM0.

Softwarevereisten

We gaan ervan uit dat je al een MQTT-broker hebt draaien. De bekendste is Eclipse Mosquitto, die je rechtstreeks in Raspberry Pi OS kunt installeren (met het commando sudo apt install mosquitto), als een Docker-container kunt draaien of in de vorm van een Home Assistant-add-on.

Zigbee2MQTT draai je het gemakkelijkst in een Docker-container en dat gaan we ook doen met Zigbee2MQTT Assistant (een webinterface voor Zigbee2MQTT). Installeer dus eerst Docker en Docker Compose op je Raspberry Pi als dat nog niet is gebeurd:

curl -sSL https://get.docker.com | sh

sudo usermod pi -aG docker

sudo apt install python3-pip

sudo pip3 install docker-compose

sudo reboot

Docker Compose

Maak nu een directory aan voor de Zigbee2MQTT-container (Zigbee2MQTT Assistant heeft geen directory nodig):

cd

mkdir -p containers/zigbee2mqtt

Voeg vervolgens de containerdefinitie toe aan het bestand docker-compose.yml in je home-directory:

version: '3.7'

services:

zigbee2mqtt:

image: koenkk/zigbee2mqtt

container_name: zigbee2mqtt

volumes:

- ./containers/zigbee2mqtt:/app/data

devices:

- /dev/ttyACM0:/dev/ttyACM0

restart: always

environment:

- TZ=Europe/Amsterdam

zigbee2mqttassistant:

image: carldebilly/zigbee2mqttassistant

container_name: zigbee2mqttassistant

environment:

- Z2MA_SETTINGS__MQTTSERVER=MQTT_BROKER

- Z2MA_SETTINGS__MQTTUSERNAME=MQTT_USER

- Z2MA_SETTINGS__MQTTPASSWORD=MQTT_PASSWORD

- TZ=Europe/Brussels

ports:

- 8880:80

restart: always

Pas de nodige waardes aan jouw situatie aan. Het apparaatbestand bijvoorbeeld als dat bij jou verschilt. En vul de hostname of het ip-adres van je MQTT-broker in na het gelijkheidsteken bij Z2MA_SETTINGS__MQTTSERVER, en doe hetzelfde met de gebruikersnaam en het wachtwoord als je die voor je MQTT-broker nodig hebt.

Start de containers daarna:

docker-compose up -d

Dat kan een tijdje duren, omdat Docker de images voor beide containers downloadt en de containers dan start.

Stel MQTT in

De configuratie van Zigbee2MQTT Assistant heb je al gedaan in het Docker Compose-bestand, maar Zigbee2MQTT werkt met een afzonderlijk configuratiebestand. Toen de Docker-container zonet voor het eerst startte, is dat configuratiebestand aangemaakt. Stop eerst de container, zodat je het bestand veilig kunt bewerken:

docker-compose stop zigbee2mqtt

Open nu het configuratiebestand met het programma nano:

sudo nano /home/pi/containers/zigbee2mqtt/configuration.yaml

Ga naar de sectie die begint met mqtt: en vul daar de juiste gegevens in voor de server. Dat ziet er als volgt uit:

mqtt:

base_topic: zigbee2mqtt

server: 'mqtt://SERVER'

user: USER

password: PASSWORD

Als je Mosquitto in een Docker-container op dezelfde Raspberry Pi hebt draaien, dan kun je in de plaats van SERVER eenvoudigweg de naam van de container opgeven, anders vul je hier het ip-adres of de hostname in. Als je geen authenticatie hebt ingesteld voor je MQTT-broker, laat je de regels met user en password gewoon weg.

Stel de netwerksleutel in

Nu is er nog één beveiligingsinstelling nodig. Een ZigBee-netwerk versleutelt zijn verkeer, maar de standaardsleutel die Zigbee2MQTT instelt, is voor elke gebruiker hetzelfde. Dat verander je dus het best. Een netwerksleutel is een 128bit-getal of dus 16 bytes. Zigbee2MQTT vraagt om die netwerksleutel in te voeren in de vorm van 16 getallen van 0 tot 255.

Zo’n willekeurige reeks getallen genereer je met de volgende opdracht:

dd if=/dev/urandom bs=1 count=16 2>/dev/null | od -A n -t u1 | awk '{printf "["} {for(i = 1; i< NF; i++) {printf "%s, ", $i}} {printf "%s]\n", $NF}'

Laat je niet afschrikken door wat er als een magische toverspreuk uitziet. We laten de Raspberry Pi hier 16 willekeurige bytes genereren en zetten die met wat transformaties om naar de vorm die Zigbee2MQTT verwacht. Het resultaat kun je dan eenvoudig plakken naar de juiste sectie in het configuratiebestand van Zigbee2MQTT. Ga naar advanced en vul daar de netwerksleutel in bij network_key. Een voorbeeld:

advanced:

network_key: [225, 167, 199, 215, 99, 234, 178, 75, 98, 151, 167, 200, 155, 149, 50, 85]

Sla nu het bestand in nano op met Ctrl+O en sluit het programma af met Ctrl+X. Start de container dan opnieuw op:

docker-compose start zigbee2mqtt

Controleer ook even in de logs of Zigbee2MQTT correct opstart:

docker-compose logs -f zigbee2mqtt

Je zou alleen groene en gele boodschappen mogen zien.

Rechtstreekse ZigBee-ondersteuning in Home Assistant

Toestemming voor het netwerk

Normaal was dit de laatste keer dat je Zigbee2MQTT zelf hebt moeten zien. Het toevoegen en configureren van je ZigBee-apparaten doe je vanaf nu in de webinterface van Zigbee2MQTT Assistant. Open daarvoor de url http://IP:8880, waarbij je IP vervangt door het ip-adres van je Raspberry Pi. Zonder gepaarde apparaten krijg je nu één apparaat te zien: de Coordinator. Zo niet, kijk dan weer in de logs van Zigbee2MQTT.

Dan moet je nu een voor een je ZigBee-apparaten toevoegen. Zigbee2MQTT Assistant laat automatisch de eerste twintig minuten na het starten apparaten toe om tot het netwerk toe te treden. Als het al langer geleden is, ga dan naar de pagina Status en klik op Allow new devices to join the network. Daarna heb je weer twintig minuten de tijd om een apparaat toe te voegen, of tot je op dezelfde pagina op Deny new devices to join the network klikt.

Voeg je apparaten toe

Hoe je je ZigBee-apparaten aan het netwerk toevoegt, hangt van het type apparaat af. Bekijk daarvoor de handleiding. Vaak moet je gewoon enkele seconden een knop op het apparaat ingedrukt houden. Zoek op de webpagina met ondersteunde apparaten naar je apparaat en kijk op de apparaatspecifieke pagina of er speciale instructies voor pairing staan.

Voor de Xiaomi Aqara-contactsensor voor een deur of raam dien je bijvoorbeeld vijf seconden lang de resetknop ingedrukt te houden. Zodra het blauwe ledje begint te knipperen, kun je loslaten en is de sensor aan je netwerk toegevoegd. Wil je een Philips Hue-lamp toevoegen die je al met je Philips Hue Bridge hebt gebruikt, dan dien je eerst een factory reset van de lamp uit te voeren. Het eenvoudigste is om de lamp gewoon in de Philips Hue-app van de bridge te verwijderen.

Lijst met apparaten

Wanneer je zo al je ZigBee-apparaten aan je netwerk hebt toegevoegd, krijg je ze te zien op de pagina Devices van Zigbee2MQTT Assistant, inclusief een productfoto en de door het apparaat aangeboden componenten. Voor een contactsensor waarmee je kunt zien of je deur open of dicht is, zijn dat bijvoorbeeld battery, contact en linkquality.

De apparaten krijgen als naam standaard een numeriek ID, maar dat is niet erg gebruiksvriendelijk. Klik daarom op de naam (in het blauw) in de lijst met apparaten, vul onder Rename de nieuwe naam in en klik dan rechts op Rename. Daarna krijg je in de lijst de nieuwe naam te zien. Wanneer je zo al je apparaten een normale naam hebt gegeven, herstart je het best Zigbee2MQTT met de volgende opdracht:

docker-compose restart zigbee2mqtt

Integratie met Home Assistant

Voor je je ZigBee-apparaten in Home Assistant ziet, dien je Home Assistant met je MQTT-broker te laten spreken. Dat kan in Instellingen / Integraties, waarna je op het plusteken rechts onderaan klikt en dan MQTT kiest. Voer hier nu de hostname, poort (1883) en indien nodig gebruikersnaam en wachtwoord in. Vink ook Detectie inschakelen aan, zodat Home Assistant automatisch apparaten aanmaakt voor diensten met MQTT-boodschappen die de conventies van Home Assistant volgen, waaronder Zigbee2MQTT.

Nadat de integratie is opgeslagen, toont Home Assistant je al welke apparaten het ontdekt. Normaal gezien zou je nu alle apparaten die je in Zigbee2MQTT hebt toegevoegd moeten zien. Je vindt ze allemaal in het tabblad Apparaten van je integraties. Als je op een apparaat klikt, krijg je meer informatie over het apparaat te zien, inclusief de entiteiten die in Home Assistant beschikbaar zijn. Vanaf nu kun je deze entiteiten in automatiseringen gebruiken en ook in de Lovelace-gebruikersinterface tonen.

MQTT

Zigbee2MQTT kun je ook perfect met andere domoticasystemen gebruiken, als ze maar MQTT spreken. Je kunt nu ook in je eigen Python-scripts bijvoorbeeld je ZigBee-lampen aansturen door de juiste MQTT-boodschappen te sturen, of op een ESPHome-apparaatje luisteren naar MQTT-boodschappen die van je contactsensor of temperatuursensor komen om deze op een klein schermpje te tonen.

In de documentatie van Zigbee2MQTT is te vinden wat de structuur van de MQTT-onderwerpen en -boodschappen is. Je vindt daar ook enkele voorbeelden. De boodschappen zijn in JSON-formaat. Specifieke informatie over jouw apparaten zoek je het best op de pagina van dat apparaat op de website van Zigbee2MQTT op.

MQTT-boodschappen bekijken en sturen

De JSON-inhoud van een boodschap als je een deur opent, ziet er dan bijvoorbeeld als volgt uit:

{"battery":100,"voltage":3015,"contact":true,"linkquality":13}

Een schakelaar zoals de Xiaomi Mi power plug schakel je in door de volgende boodschap naar het onderwerp zigbee2mqtt/naamvanschakelaar/set te sturen:

{"state": "ON"}

En op deze manier kun je al je ZigBee-apparaten via MQTT op je eigen netwerk aansturen en uitlezen.

Geavanceerde mogelijkheden