Zigbee ist ein tolles Protokoll, um sein Zuhause etwas smarter zu machen.
Nicht nur kann es von Haus aus Mesh, es ist auch noch Quelloffen und immer mehr Hersteller bringen passende Geräte raus.
Es ist also eine perfekte Erweiterung für unser openHAB-System!

Doch ein paar Hinweise vorab:
Ich empfehle nicht unbedingt das Zigbee-Binding von openHAB zu nutzen.
Es unterstützt nur eine geringe Anzahl an Coordinatorn und diese dürfen auch nur eine bestimmte Firmware haben.
Wer voll und ganz auf Zigbee setzen möchte, sollte sich an diese Anleitung halten, um Probleme zu vermeiden.
Achte darauf, das du ein Zigbee-Stick mit der Zigbee Firmware 3.0.0 oder höher hast! Neuere Geräte benötigen diese Firmware um zu funktionieren.
Von den Texas Instruments CC2531 rate ich ab. Die sind zwar schön günstig zu bekommen, könen aber kein Zigbee 3.0! Das führ füher oder später zu Problemen, die nur noch nervig sein können.

Was werden wir machen?

Wir werden unseren Zigbee-Stick mit Hilfe von Zigbee2MQTT ansteuern und über Mosquitto die Befehle abgeben, als auch den Status empfangen, damit openHAB damit arbeiten kann.

Was brauchen wir alles?

– Eine bereits laufende openHAB 3 Instanz + Administrator-Rechte
– Ein Linux-System => Sofern dein openHAB schon z.B. auf einem Raspberry Pi läuft, nutzen wir direkt den weiter!
– Root-Zugang
– Einen Zigbee-USB-Stick mit Zigbee Firmware 3.X.X

Installation

1. Stecke den Zigbee-Stick an deinem Raspberry Pi / Server an und starte ihn neu

=> Das Neustarten inizialisiert den Stick komplett und vermeidet Probleme bei der Inbetriebnahme

2. Mosquitto installieren

2.1 Mosquitto über die normalen Paketquellen installieren und den Dienst zur Konfiguration stoppen

# apt install mosquitto -y
# service mosquitto stop

2.2 Wir legen einen Benutzer an, um den Zugriff zu Mosquitto etwas einzuschränken und die Steuerung nicht für jeden im Heimnetz frei zugänglich zu machen.
=> Wir verschlüsseln den Datentransfer nicht, aber ein Benutzername und Passwort ist besser als keiner 🙂
Setze dazu einfach folgenden Befehl ab:

# mosquitto_passwd -c /etc/mosquitto/passwd NUTZERNAME

Ersetze NUTZERNAME durch einen beliebigen Nutzernamen (z.B. zigbee2mqtt oder so). Du musst anschließend 2x ein Passwort angeben. Achtung, das passiert versteckt!
Nutze beim Passwort eine Kombination aus Buchstaben und Zahlen. Nur Zahlen führen bei der Inbetriebnahme von Zigbee2MQTT zu Problemen!

2.3 Nun müssen wir die Konfiguration anpassen. Öffne dazu diese

# nano /etc/mosquitto/mosquitto.conf

und füge folgende Werte ganz unten hinzu:

password_file /etc/mosquitto/passwd
allow_anonymous false

=> Wir lesen die Passwortdatei nun ein und deaktivieren den anonymen Zugriff.

Möchtest du den Login von extern erlauben (z.B. deinem Rechner), füge noch folgende Zeile hinzu:

listener 1883

2.4 Starte Mosquitto neu, damit alles übernommen wird

# service mosquitto start

3. Zigbee2MQTT installieren

3.1 Suche als erstes einmal deinen Zigbee-Stick im System. Er sollte sich “ttyACM0” oder “ttyUSB0” in der Regel nennen. Eventuell gibt es auch ein Informationsschreiben bei deiner Bestellung vom Stick, wie man ihn am besten ins System einbinden kann.

# ls /dev/*

Wenn du keine Ahnung hast, wie du dein Stick finden kannst, nutze die 0815-Methode und zieh den Stick kurz ab, schau welches Gerät fehlt und steck ihn wieder an.
(Neustart vom System ist hier wieder empfehlenswert!)

3.2 Wir benötigen nun NodeJS. Wir besorgen uns daher die aktuellen Setupdaten mit folgendem Befehl:

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

3.3 Nun können wir folgende Pakete installieren:

# apt install -y nodejs git make g++ gcc

3.4 Prüfe mit den beiden Befehlen, ob NodeJS korrekt arbeitet:

# node --version
# npm --version

3.5 Jetzt können wir Zigbee2MQTT installieren. Dazu holen wir uns das Github-Repository:

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

Meine Empfehlung ist, das Ganze in den Ordner /opt/ zu legen. Ich kann nicht garantieren, damit es von anderen Orten aus sauber läuft!

3.6 Damit das Ganze nicht mit Root läuft, setzen wir den Besitzer des Ordners auf einen normalen Nutzer. Ich verwende hier den Benutzer “Pi”, der ein Standardbenutzer auf RaspianOS ist. Du kannst ein anderen Nutzer gerne auswählen 🙂

# chown -R pi:pi /opt/zigbee2mqtt

3.7 Wechsel nun zum Nutzer, der Besitzer des zigbee2mqtt-Ordners ist, gehe in den Ordner und führe npm ci aus

# cd /opt/zigbee2mqtt
# npm ci

=> Zigbee2MQTT wird sich nun installieren und diverse Konfigurationsdaten anlegen. Wichtig dabei ist, dass der USB-Stick steckt und funktionstüchtig ist, da das Script diesen erkennen kann und diverse Parameter passend setzt.

3.8 Ist das Installationsscript durch, müssen wir Zigbee2MQTT noch kurz anpassen. Öffne dazu die Konfiguration.

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

3.9 Füge bei [mqtt] folgende zwei Zeilen ein und ersetze sie mit deinen Daten:

  user: NUTZERNAME
  password: PASSWORT

=> Benutzername und Passwort hast du in Schritt 2.2 angelegt!

WICHTIG: Mit dem Parameter “permit_join” auf “true” aktivieren wir den Peering-Modus. Damit können neue Geräte angelent werden! Sobald wir mit der Einrichtung fertig sind, kannst du den Wert auf “false” setzen und Zigbee2MQTT einmal neu starten lassen. Dann kommen keine unbekannten Geräte ins Netzwerk.

3.10 ändere bei “port:” den Pfad zum Stick ab, sollte diese nicht passen. Hier ist mein Beispiel:

  port: /dev/ttyUSB0

3.11 Füge ganz unten noch folgendes hinzu:

advanced:
  network_key: GENERATE

=> Dies generiert gleich einen Netzwerkschlüssel, um das System noch etwas sicherer zu machen.
ACHTUNG: Alle eingerückten Parameter haben GENAU 2 Leerzeichen davor! Passt das nicht, funktioniert die Config nicht! Ist zwar dumm gemacht, aber nur so funktionieren die yaml-Dateien 🙁

3.12 OPTIONAL: Füge folgende Konfiguration noch am Ende hinzu, um ein Webinterface von Zigbee2MQTT zu aktivieren.

frontend:
  # Optional, default 8080
  port: 7080
  # Optional, default 0.0.0.0
  host: 0.0.0.0
  # Optional, enables authentication, disabled by default
  # auth_token: your-secret-token

Über die IP des Servers (z.B. 192.168.1.50) und dem Port 7080, lässt sich das Webinterface aufrufen. (http://192.168.1.50:7080)

3.13 Nun ist es and er Zeit, Zigbee2MQTT einmal starten, um einen Funktionstest zu machen. Führe daher den Befehl im zigbee2mqtt-Ordner aus:

# npm start

Läuft? Läuft!
Dann drücke STRG + C um das ganze mal wieder zu beenden.

3.14 Wir richten Zigbee2MQTT als Service ein, damit es automatisch gestartet wird. Dazu legen wir eine Serivce-Datei an.

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

3.15 Befülle die Datei mit folgendem Inhalt:

[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
ExecStart=/usr/bin/npm start
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
# Or use StandardOutput=null if you don't want Zigbee2MQTT messages filling syslog, for more options see systemd.exec(5)
StandardError=inherit
Restart=always
User=pi

[Install]
WantedBy=multi-user.target

ACHTUNG: Ersetze bei “User=” den Nutzer “Pi” durch deinen Benutzer, der das Ganze ausführen soll!

3.16 Den Dienst aktivieren und starten

# systemctl enable zigbee2mqtt.service
# systemctl start zigbee2mqtt

4. Binding installieren

4.1 Installiere in openHAB das Binding “MQTT Binding”
4.2 Füge bei Things nun über das MQTT Binding ein “MQTT Broker” hinzu
4.3 Setze den Haken bei “Show advanced” und befülle folgende Zeilen mit deinen Inhalten:
Unique ID: Gebe einen schönen Namen an
Label: Gebe einen schönen Namen an (z.B. Zigbee2MQTT Broker)
Broker Hostname/IP: Wenn du alles auf einem Gerät laufen hast, reicht hier 127.0.0.1, ansonsten die IP des Mosquitto-Servers
Broker Port: 1883
Username: Benutzername aus Schritt 2.2
Password: Passwort aus Schritt 2.2

>> Create Thing!

4.4 Installiere bei “Transformations” (Über die Einstellungen zu finden) das Add-On “JSONPath Transformation“.
Dies ist notwendig, um die Werte von Zigbee-Geräten korrekt in openHAB zu erfassen.
Ohne die Erweiterung können wir zwar Zigbee-Geräte steuern, aber keine Daten wie Temperatur, Status oder ähnliches auslesen.

5. Geräte hinzufügen

Ich gehe hier jetzt kurz Schritt für Schritt durch, wie man neue und daher komplett unbekannte Geräte einbinden. Wer es schon einmal gemacht hat und die Parameter zum Teil bereits kennt, kann abkürzen.

5.1 Lade dir das Tool MQTT-Explorer herunter (installiere es) und starte es.

5.2 Logge dich mit den Zugangsdaten von Schritt 2.2 ein und klappe den Abschnitt “Zigbee2MQTT” auf. Die IP ist die IP des Servers (z.B. des Raspberry Pi’s)
=> Die Liste füllt sich gleich 🙂

5.3 Begebe dich nun mit deinem ersten Zigbee-Gerät in die nähe des USB-Sticks und versetze es in den Peering-Modus.
=> 10 Sekunden lang auf einen Knopf drücken, oder 5x ein / aus schalten, …. sollte das Gerät in den Peering-Modus versetzen.
Der USB-Stick sollte mittlerweile blinken, um zu signalisieren, damit der Peering-Modus aktiv ist.

5.4 Nach wenigen Sekunden sollte dein Gerät sich mit dem Zigbee-Stick verbunden haben.
=> Dein Gerät blinkt nicht mehr, leuchtet gar nicht oder tud sonst eben Dinge, um zu signaliseren, das es verbunden ist.
Du kannst jetzt auch in die configuration.yaml von Zigbee2MQTT schauen. Dort gibts jetzt ganz unten ein neuen Eintrag! 🙂
Dieser sieht in etwa so aus:

Du hast einmal die MAC-Adresse des Gerätes (ID) und in den Anführungszeichen steht ebenfalls die ID drin. Letztere, welche unter dem Parameter friendly_name läuft, ist nur ein Anzeigename und kann gegen einen besseren (z.B. “Schalter Wohnzimmerlicht”) ersetzt werden.

5.5 Ändere nun den Namen des eingelernten Gerätes ab und starte Zigbee2MQTT einmal neu.

# systemctl restart zigbee2mqtt

5.6 Schau jetzt mal in MQTT-Explorer. Im Zweig “Zigbee2MQTT” sollte nun dein Gerät mit deinem Wunschnamen auftauchen.
=> Falls noch die MAC (ID) angezeigt wird, starte MQTT-Explorer kurz einmal neu.

5.7 Um jetzt alle Werte in openHAB nutzen zu können, müssen wir wissen wie diese lauten. Drücke daher mal an deinem Gerät alle verfügbaren Tasten oder löse alle Möglichkeiten die das Gerät unterstützt aus.
Du wirst im MQTT-Explorer nun sehen, das in den geschweiften Klammern nun mehr Werte dazu kommen.
Das sind immer die Live-Werte, aber sie werden nur erfasst, wenn das Gerät sie auch sendet.
Die Werte werden im JSON-Format ausgegeben. Daher haben wir die Transformation in Schritt 4.4 installiert.

5.8 Füge nun in openHAB ein neues MQTT-Gerät hinzu und wähle dort “Generic MQTT Thing” aus.
Unique ID: Gebe eine ID an, um das Gerät später besser zu finden
Label: Gebe einen netten Namen an (z.B. “Zigbee Wohnzimmerlampe”)
Location: Gebe einen Ort an (ist optional)
Bridge: Wähle die in Schritt 4.3 angelegte Bridge aus
OPTIONAL: Solltest du bereits passende URLS kennen, kannst du den Haken “Show advanced” setzen und die Zeilen befüllen. Diese werte sind aber Geräte und Herstellerabhängig. Daher gebe ich hier nichts vor und kann dir auch keine Tipps geben!

Drücke auf “Create Thing”

5.9 Öffne nun dein neues Thing und wähle den Tab “Channels” an.

5.10 Erstelle einen neuen Channel (Add Channel)
Channel Identifier: Gebe einen einzigartigen Namen an (MussZusammenGeschriebenWerden)
Label: Gabe einen schönen Namen an (z.B. “Wohnzimmerlicht Schalter AN / AUS”)
Channel type: Setze die Auswahl auf das, was du nutzen möchtest. Bei einem Lichtschalter wähle “On/Off Switch” Bei z.B. einem Temperaturwert wähle “Number Value” aus und bei Textbasierten Werten “Text Value”.
=> Auch wenn “On” und “Off” als Status dir wie ein Text vor kommt, ist es dennoch ein Schalter 😉

5.10.1 – Beispielvorgehen für ein einfachen EIN-AUS-Schalter
MQTT State Topic: /zigbee2mqtt/Dein Name des Gerätes
=> Ja Leerzeichen sind gültig!
MQTT Command Topic: zigbee2mqtt/Dein Name des Gerätes/set
=> /set gibt an, das wir ein Befehl dem Gerät mitteilen wollen. Nur darauf hört das Gerät überhaupt. Fehlt es, macht es nichts.
Custom On/Open Value: ON
Custom Off/Closed Value: OFF
Incoming Value Transformations: JSONPATH:$.state
HINWEIS: Incoming Value Transformations sollte gesetzt werden, damit Statusänderungen am Gerät selbst von openHAB erfasst werden können. Andernfalls bekommt openHAB nicht mit, wenn du z.B. eine Steckdose direkt per Knopf an der Dose selbst einschaltest. openHAB sieht das Gerät dann weiterhin als “aus”.

5.10.2 – Beispiel für einfache Werte (Temperatur, Helligkeit, Signalstärke,….)
WICHTIG: Mein Beispiel basiert darauf, dass die Werte sich im Hauptzweig des Gerätes befinden und kein Unterzweig besitzen!
MQTT State Topic: /zigbee2mqtt/Dein Name des Gerätes
=> Ja Leerzeichen sind gültig!
MQTT Command Topic: /zigbee2mqtt/Dein Name des Gerätes/set
=> /set gibt an, das wir ein Befehl dem Gerät mitteilen wollen. Nur darauf hört das Gerät überhaupt. Fehlt es, macht es nichts.
Show advanced: Haken gesetzt!
Incoming Value Transformations: JSONPATH:$.linkquality
ACHTUNG: Mein Beispiel mit “linkquality” zeigt dir die Signalstärke des Gerätes. Ändere den Wert gegen dein gewünschten Wert wie z.B. “temperature” ab!

>> Create

Super Hinweis: Auf wer Webseite von Zigbee2MQTT findest du eine riesige Liste an unterstützen Geräte und in der Regel alle möglichen Werte, die ausgelsen und gesetzt werden können.

5.11 Nun müssen wir ein Link zu einem “Item” herstellen. Lege dazu am besten ein neues an.
Tipp: Gehe auf dein Modell und navigiere dich dort hin, wo das Gerät sitzen soll. Sonst hängts automatisch im obsten Ast des Baumes, was doof ist.
Punkt bei: Create a new Item
Name: EinEinzigartigerNameDerAmStueckGeschriebenWird
Label: Ein schöner Name (z.B. Wohnzimmerlicht Ein/Aus-Schalter)
Type: Wähle dir der Typ des Items aus. Ein Schalter ist ein Switch, eine Temperatur ist eine “Number” und ein Textwert ist ein “String”!
Category: Eine passende Kategorie (z.B. “light”)
Semantic Class: Schalter = Switch | Nummernwerte = Point oder None
Semantic Property: Kann bei Bedarf gesetzt werden.
Profile: Standard
>> Link

FERTIG!

Du solltest jetzt über openHAB deine Zigbee-Geräte steuern können.
Sobald du in openHAB z.B. dein Licht einschaltest, solltest du im MQTT-Explorer die Wertänderung sehen können.
Ab jetzt steht dir nichts mehr im Wege, mit openHAB dein Haus zu automatisieren und villeicht die ein oder andere Zeitsteuerung umzusetzen.

---

In der Konfigurationsdatei kannst du nun selbst bestimmen, ob der Stick sich im Paaring-Modus befinden soll oder ob keine neuen Geräte angelegt werden dürfen.
Um neue Geräte einzulernen, setze “permit_join:” auf “true”.

permit_join: true

Wenn alles fertig ist, kannst du den Paaring-Modus mit “false” wieder abschalten.
=> Pro Änderung der Konfiguration muss Zigbee2MQTT neu gestartet werden!

Solltest du eine Datenbank in openHAB aktiv haben (z.B. RRD4j), werden die Werte protokolliert. openHAB legt also ohne weitere Anpassungen ein Logbuch von dein Werten deiner Zigbee-Geräte an. Du hast also automatisch z.B. ein Temperaturverlauf und siehst, wann ein Licht an und aus war.

---

Eine ausführliche Anleitung in Englisch gibt es bei zigbee2mqtt.io direkt.
Dort sind auch noch weitere Tipps und Tricks niedergeschrieben.

---

Wie aktualisiere ich Zigbee2MQTT?

Ganz einfach!
Welchsel in das Installationsverzeichnis von zigbee2mqtt

# cd /opt/zigbee2mqtt

Führe darin die update.sh-Datei einfach aus.

# ./update.sh

Die Aktualisierung kann je nach Leistung deines Servers einen Moment in Anspruch nehmen.

Hinweis: Der Updater gibt dir am Ende ggf. ein Hinweis, das ein npm-Update ebenfalls zur Verfügung steht. Er zeigt dir auch direkt den passenden Befehl an, den du abschicken musst, um npm zu aktualisieren. Macht das am besten auch gleich noch!

Damit alles wieder sauber verbunden wird, ist ein Neustart deines Systems angebracht.

WARNUNG: Solltest du auch in Betracht ziehen, die Firmware deines Zigbee-Coordinators zu aktualisieren, musst du (in der Regel) alle verbundenen Geräte erneut aufnehmen! Weitere Infos gibt es HIER.

Weitere Tipps & Tricks:

– Werden Zigbee-Geräte entfernt, lösche diese zuerst aus Zigbee2MQTT, bevor du das Gerät selbst zurücksetzt! Ansonsten kann sich Zigbee2MQTT komisch verhalten (Das Gerät kann dann nicht sauber aus der Konfiguration gelöscht werden).
– Lass nach einem Neustart des Servers (z.B. Raspberry Pi) die Karte generieren, damit einmal alle Geräte abgefragt werden. Dies beschleunigt die Statusabfrage, um wieder voll Einsatzbereit zu sein.
– Das Anlernen von neuen Geräten funktioniert am besten, wenn man sehr nahe am Gateway – also dem USB-Stick – ist. Anlernen über Router als Schnittstellen kann funktionieren, muss aber nicht.
– Es gibt noch kein Binding, um alle Funktionen von Zigbee2MQTT in openHAB einzubauen. Du kannst aber die Webseite im OH3-Dashboard einbinden und alles darüber steuern. Nicht sonderlich hübsch, aber es funktioniert.
– Sei flexibel bei der Namenswahl. Gerade Steckdosen die schnell wo anders gesteckt werden können, müssen nicht unbedingt z.B. dem Raum im Namen tragen. Hier reicht es, wenn es in openHAB richtig betitel ist. “Steckdose01” reicht ja erst mal.
– Falls sich Zigbee2MQTT nach normalen Systemupdates merkwürdig verhält, hast du mit Sicherheit NodeJS aktualisiert. Schau mal ob es ein Update zu Zigbee2MQTT gibt und installiere dies, starte dein System danach einmal neu. Dann sollte wieder alles laufen.
– Drücke nach Zigbee2MQTT-Updates auf “Neu konfigurieren” , damit das System dein Endgerät neu einlernt. Das hilft bei Ausleseproblemen. Keine Sorge, deine Konfiguration in openHAB geht nicht verloren, es geht alles danach wie bisher auch.
– Wenn dein Zigbee-Mesh nicht mehr korrekt vorhanden ist, lern deine Geräte mit “neu Konfigurieren” erneut ein. Geht 1-2 Sekuden pro Gerät und anschließend sollte das Mesh wieder laufen.
– Wenn Updates nicht installiert werden können, sichere den data-Ordner, lösche anschließend alles von zigbee2mqtt (davor vielleicht über den Service den Dienst stoppen), führe die Schritte 3.5 bis 3.7 durch, füge anschließend den Ordner data wieder mit allen Daten ein (pass auf die Berechtigungen auf!), geh dann zu Schritt 3.13 und schau das alles wieder läuft.