Benötigtes Zubehör für diese Anleitung:

• ZigBee CC2531 mit alternativer Firmware CC2531ZNP-Prod von Koenkk
• Raspberry Pi2 oder höher
• Ein Device das Angelernt werden soll (Hier als Beispiel eine Philips HUE White LED Lampe E27)

In diesem Tutorial wird ein Raspian Betriebssystem (hier Jessie) auf einem Raspberry Pi mit installiertem FHEM vorausgesetzt.

Als erstes sollte man immer ein update auf dem Raspberry Pi durchführen, um die neuesten Programmpakete zu erhalten.

sudo apt-get update
sudo apt-get upgrade  [Alle Pakete mit "J" bestätigen - der Vorgang kann eine Weile dauern]

Ein Reboot nach dem Upgrade kann nie schaden. So sieht man, ob das System problemlos wieder gestartet wird.

reboot

Da wir node in der Version 8.11.0 oder höher benötigen, wird zunächst das Repository eingebunden und anschließend node und npm installiert.

sudo curl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash -
sudo apt-get install -y nodejs git make g++ gcc

Prüfung ob beide Versionen korrekt sind:

node --version  # Ausgabe sollte v8.11.X oder höher sein (zum Zeitpunkt dieser Doku v8.15.0)
npm --version   # Ausgabe sollte > 5.X.X oder höher sein (zum Zeitpunkt dieser Doku 6.4.1)

ACHTUNG: Falls die Meldung kommt, dass nodejs aus dem Tarball für ARM-Prozessoren installiert werden soll, dann per wget herunterladen und von Hand installieren.
Zuvor unter https://nodejs.org/dist/ die neueste Version ausfindig machen und nachfolgende Zeilen entsprechend anpassen.

ARM Version prüfen:

root@fhem:~# uname -m
armv7l

In diesem Beispiel wird ARMv71 benötigt.

cd /tmp
wget https://nodejs.org/dist/v8.15.0/node-v8.15.0-linux-armv7l.tar.gz 
tar -xzf node-v8.15.0-linux-armv7l.tar.gz 
cd node-v8.15.0-linux-armv7l
sudo cp -R * /usr/local/
node -v
npm -v

Nach dem Upgrade wird zunächst ein kleiner MQTT Server namens Mosquitto installiert, welcher die Übertragung von Telemetriedaten in Form von Nachrichten zwischen FHEM und dem ZigBee Stick ermöglicht.

sudo apt-get install mosquitto mosquitto-clients
 
sudo service mosquitto status

sudo service mosquitto stop
sudo service mosquitto start

Mosquitto lauscht per default auf dem Port 1883. Ob Mosquitto richtig läuft, lässt sich folgendermaßen überprüfen:
Prozess von Mosquitto prüfen. Hier sieht man auch gleich welches Config-File verwendet wird.

ps -auxf|grep mosquitto
mosquit+  2752  0.2  0.3   5092  3400 ?        S    15:37   0:00 /usr/sbin/mosquitto -c /etc/mosquitto/mosquitto.conf
root      2757  0.0  0.1   4768  1956 pts/1    S+   15:37   0:00 grep mosquitto

Ob der Port geöffnet ist:

netstat -lnpt | grep 1883
tcp        0      0 0.0.0.0:1883            0.0.0.0:*               LISTEN      2752/mosquitto
tcp6       0      0 :::1883                 :::*                    LISTEN      2752/mosquitto

Jetzt wird das zigbee2mqtt Repository von github.com ausgechecked und installiert.

sudo git clone https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
sudo chown -R pi:pi /opt/zigbee2mqtt
cd /opt/zigbee2mqtt
npm install  [dauert eine Weile]

ACHTUNG: warnings können ignoriert werden!
Eventuell müssen wir anschließend noch folgendes ausführen (wird aber angezeigt wenn nötig)

npm audit fix

Nach der Installation ist ein guter Zeitpunkt den ZigBee Stick in den RaspberryPi einzustecken.
Ob dieser erkannt wird prüfen wir wie folgt. Wird eine Device als Texas Instruments angezeigt, ist alles OK.

lsusb
Bus 001 Device 004: ID 0451:16a8 Texas Instruments, Inc.
Bus 001 Device 003: ID 0424:ec00 Standard Microsystems Corp. SMSC9512/9514 Fast Ethernet Adapter
Bus 001 Device 002: ID 0424:9514 Standard Microsystems Corp.
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Nun schauen wir, welche serielle ID der Stick hat:

ls -l /dev/serial/by-id/
insgesamt 0
lrwxrwxrwx 1 root root 13 Aug  6  2017 usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0014D9E042-if00 -> ../../ttyACM0

Den gesamten String benötigen wir gleich für die Konfiguration. Man kann auch die hinten gezeigten ttyACM0 verwenden, aber davon würde ich abraten wenn noch andere Sticks in Zukunft verwendet werden sollen.
Nun konfigurieren wird die .yaml Datei …

vi /opt/zigbee2mqtt/data/configuration.yaml

… und tragen den MQTT Port und die serielle ID des ZigBee-Sticks ein (Achtung in einer .yaml Datei dürfen keine TABS verwendet werden).

# Home Assistant integration (MQTT discovery)
homeassistant: false

# allow new devices to join
permit_join: true

# MQTT settings
mqtt:
  # MQTT base topic for zigbee2mqtt MQTT messages
  base_topic: zigbee2mqtt
  # MQTT server URL
  server: 'mqtt://localhost:1883'
  # MQTT server authentication, uncomment if required:
  # user: my_user
  # password: my_password

# Serial settings
serial:
  # Location of CC2531 USB sniffer
  port: /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0014D9E042-if00

Wir wechseln jetzt ist das Installations-Verzeichnis und starten den Server erstmal von Hand um zu prüfen ob alles OK ist.

cd /opt/zigbee2mqtt
npm start

> zigbee2mqtt@0.1.5 start /opt/zigbee2mqtt
> node index.js

  zigbee2mqtt:info 2018-9-22 15:45:46 Logging to directory: '/opt/zigbee2mqtt/data/log/2018-09-22.15-45-46'
  zigbee2mqtt:info 2018-9-22 15:45:47 Starting zigbee2mqtt version 0.1.5 (commit #7d49e13)
  zigbee2mqtt:info 2018-9-22 15:45:47 Starting zigbee-shepherd
  zigbee2mqtt:info 2018-9-22 15:45:49 zigbee-shepherd started
  zigbee2mqtt:info 2018-9-22 15:45:49 Coordinator firmware version: '20180507'
  zigbee2mqtt:info 2018-9-22 15:45:49 Currently 0 devices are joined:
  zigbee2mqtt:warn 2018-9-22 15:45:49 `permit_join` set to  `true` in configuration.yaml.
  zigbee2mqtt:warn 2018-9-22 15:45:49 Allowing new devices to join.
  zigbee2mqtt:warn 2018-9-22 15:45:49 Set `permit_join` to `false` once you joined all devices.
  zigbee2mqtt:info 2018-9-22 15:45:49 Zigbee: allowing new devices to join.
  zigbee2mqtt:info 2018-9-22 15:45:49 Connecting to MQTT server at mqtt://localhost:1883
  zigbee2mqtt:info 2018-9-22 15:45:49 zigbee-shepherd ready
  zigbee2mqtt:info 2018-9-22 15:45:49 Connected to MQTT server
  zigbee2mqtt:info 2018-9-22 15:45:49 MQTT publish, topic: 'zigbee2mqtt/bridge/state', payload: 'online'

Gibt das Log am Ende online aus, ist der Stick connected und wir können alles als Dienst für den Autostart einrichten.

Nun eine Service-Datei anlegen, welche systemctl verwenden kann.

vi /etc/systemd/system/zigbee2mqtt.service

Inhalt:

[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

Starten und prüfen:

sudo systemctl start zigbee2mqtt
systemctl status zigbee2mqtt.service

● zigbee2mqtt.service - zigbee2mqtt
   Loaded: loaded (/etc/systemd/system/zigbee2mqtt.service; disabled)
   Active: active (running) since Sa 2018-09-22 15:49:52 CEST; 2s ago
 Main PID: 3004 (npm)
   CGroup: /system.slice/zigbee2mqtt.service
           ├─3004 npm
           ├─3014 sh -c node index.js
           └─3015 node index.js

Sep 22 15:49:52 fhem systemd[1]: Started zigbee2mqtt.
Sep 22 15:49:54 fhem npm[3004]: > zigbee2mqtt@0.1.5 start /opt/zigbee2mqtt
Sep 22 15:49:54 fhem npm[3004]: > node index.js

Jetzt aktivieren wir den Service für den Autostart. Mit den folgenden Kommandos wird stop/start ausgeführt, sowie das Logfile angeschaut.

sudo systemctl enable zigbee2mqtt.service
sudo systemctl stop zigbee2mqtt
sudo systemctl start zigbee2mqtt
sudo journalctl -u zigbee2mqtt.service -f

Wenn folgende Ausgabe erscheint, dann funktioniert der Dienst einwandfrei payload: 'online':

-- Logs begin at So 2017-08-06 20:48:46 CEST. --
Sep 22 15:53:35 fhem systemd[1]: Stopping zigbee2mqtt...
Sep 22 15:53:35 fhem systemd[1]: Starting zigbee2mqtt...
Sep 22 15:53:35 fhem systemd[1]: Started zigbee2mqtt.
Sep 22 15:53:35 fhem systemd[1]: Stopping zigbee2mqtt...
Sep 22 15:53:35 fhem systemd[1]: Stopped zigbee2mqtt.
Sep 22 15:53:51 fhem systemd[1]: Starting zigbee2mqtt...
Sep 22 15:53:51 fhem systemd[1]: Started zigbee2mqtt.
Sep 22 15:53:53 fhem npm[4044]: > zigbee2mqtt@0.1.5 start /opt/zigbee2mqtt
Sep 22 15:53:53 fhem npm[4044]: > node index.js
Sep 22 15:53:55 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:55 Logging to directory: '/opt/zigbee2mqtt/data/log/2018-09-22.15-53-55'
Sep 22 15:53:56 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:56 Starting zigbee2mqtt version 0.1.5 (commit #7d49e13)
Sep 22 15:53:56 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:56 Starting zigbee-shepherd
Sep 22 15:53:57 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:57 zigbee-shepherd started
Sep 22 15:53:57 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:57 Coordinator firmware version: '20180507'
Sep 22 15:53:57 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:57 Currently 0 devices are joined:
Sep 22 15:53:57 fhem npm[4044]:   zigbee2mqtt:warn 2018-9-22 15:53:57 `permit_join` set to  `true` in configuration.yaml.
Sep 22 15:53:57 fhem npm[4044]:   zigbee2mqtt:warn 2018-9-22 15:53:57 Allowing new devices to join.
Sep 22 15:53:57 fhem npm[4044]:   zigbee2mqtt:warn 2018-9-22 15:53:57 Set `permit_join` to `false` once you joined all devices.
Sep 22 15:53:57 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:57 Zigbee: allowing new devices to join.
Sep 22 15:53:57 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:57 Connecting to MQTT server at mqtt://localhost:1883
Sep 22 15:53:58 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:58 zigbee-shepherd ready
Sep 22 15:53:58 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:58 Connected to MQTT server
Sep 22 15:53:58 fhem npm[4044]:   zigbee2mqtt:info 2018-9-22 15:53:58 MQTT publish, topic: 'zigbee2mqtt/bridge/state', payload: 'online'

Vor der eigentlichen Definition des ZigBee Sticke, muss das MQTT IODev angelegt werden. Andernfalls führt das nicht Vorhandensein in FHEM zum Crash, wenn man die Bridge anlegt.

define MQTT MQTT localhost:1883

Danach benötigen wir noch ein Modul in FHEM. Dazu müssen wir ein kleines UPDATE durchführen.
Folgendes geben wir in FHEM im Eingabefeld ein:

update add https://raw.githubusercontent.com/oskarn97/fhem-xiaomi-mqtt/master/controls_xiaomi-zb2mqtt.txt
update all xiaomi-zb2mqtt   ---> [Bitte nach dem Ausführen solange warten bis nachfolgender Text erscheint]
---
2018.09.23 13:06:34 1 : UPD FHEM/72_XiaomiMQTTDevice.pm
2018.09.23 13:06:34 1 : saving fhem.cfg
2018.09.23 13:06:34 1 : saving ./log/fhem.save
2018.09.23 13:06:34 1 :
2018.09.23 13:06:34 1 : New entries in the CHANGED file:
2018.09.23 13:06:34 1 : 404: Not Found
2018.09.23 13:06:34 1 : Calling /usr/bin/perl ./contrib/commandref_join.pl -noWarnings, this may take a while
2018.09.23 13:07:48 1 : *** EN FHEM/72_XiaomiMQTTDevice.pm: No document text found
2018.09.23 13:07:48 1 : *** DE FS10: nonempty line after =begin html ignored
2018.09.23 13:07:48 1 :
2018.09.23 13:07:48 1 : update finished, "shutdown restart" is needed to activate the changes.
2018.09.23 13:07:48 1 :
2018.09.23 13:07:48 1 : Please consider using the global attribute sendStatistics
2018-09-23 13:07:48 Global global UPDATE

Wie angegeben muss FHEM jetzt noch neu gestartet werden.

shutdown restart

Danach wird die xBridge angelegt, welche auf den ZigBee USB-Stick zugreift.

define xBridge XiaomiMQTTDevice bridge

Um Geräte anzulernen, muss zuerst in FHEM das autocreate aktiviert werden.
Danach klickt man in FHEM → xBridge auf:

set xBridge pair 1

Danach muss das Gerät in der Anlernphase ganz nah an den ZigBee Stick herangeführt werden.
Bei Geräten mit Anlerntaste, muss selbstverständlich diese zum Anlernen ca. 4 Sekunden gedrückt werden. Glühbirnen einfach einschalten.

ACHTUNG: Zuerst muss gewärleistet sein, dass die Philips HUE Birne noch niemals irgendwo angelernt wurde. Wenn doch, dann muss sie erst zurückgesetzt werden.

Hier erstmal ein kurzes Video, wie man eine Birne zurück setzt. Man benötigt dazu eine Philips HUE Fernbedienung (ZigBee-Fernbedienung).
Zuerst die Lampe einschalten, die Fernbedienung nahe heran führen und die beiden Buttons [I] und [O] gleichzeitig für 10 Sekunden drücken. Die Birne leuchtet kurz auf und FERTIG!

Hier ein Anlern-Beispiel mit einer Philips HUE LED weiß Birne.
Einfach die Lampe einschalten und der ZigBee erkennt die neue Glühbirne automatisch.

Folgendes Kommando vor den Einschalten absetzen um das Logging zu sehen. Anschließend sollten in etwa nachfolgende Ausgaben im Log erscheinen (Ggf. muss man 10-20 Sekunden warten).

sudo journalctl -u zigbee2mqtt.service -f

Sep 23 13:37:26 fhem npm[4713]:   zigbee2mqtt:info 2018-9-23 13:37:26 Connecting with device...
Sep 23 13:37:26 fhem npm[4713]:   zigbee2mqtt:info 2018-9-23 13:37:26 MQTT publish, topic: 'zigbee2mqtt/bridge/log', payload: '{"type":"pairing","message":"connecting with device"}'
Sep 23 13:37:45 fhem npm[4713]:   zigbee2mqtt:info 2018-9-23 13:37:45 Device incoming...
Sep 23 13:37:45 fhem npm[4713]:   zigbee2mqtt:info 2018-9-23 13:37:45 MQTT publish, topic: 'zigbee2mqtt/bridge/log', payload: '{"type":"pairing","message":"device incoming"}'
Sep 23 13:37:45 fhem npm[4713]:   zigbee2mqtt:info 2018-9-23 13:37:45 New device with address 0x00178801034d4631 connected!
Sep 23 13:37:45 fhem npm[4713]:   zigbee2mqtt:info 2018-9-23 13:37:45 MQTT publish, topic: 'zigbee2mqtt/bridge/log', payload: '{"type":"device_connected","message":"0x00178801034d4631"}'
Sep 23 13:37:45 fhem npm[4713]:   zigbee2mqtt:info 2018-9-23 13:37:45 MQTT publish, topic: 'zigbee2mqtt/bridge/log', payload: '{"type":"devices","message":[{"ieeeAddr":"0x00178801034d4631","type":"Router","m odel":"8718696449691","friendly_name":"0x00178801034d4631"}]}'

Links im Menü wird ein Raum namens XiaomiMQTTDevice angezeigt, welcher das neue device inkl. Logfile anzeigt.

Jetzt müssen nur noch ein paar Konfigurationen vorgenommen werden und die Lampe kann verwendet werden.

rename 0x00178801034d4631 Wz.Lampe
attr Wz.Lampe icon hue_filled_white_e27_b22
attr Wz.Lampe stateFormat {lc ReadingsVal($name,"state",0)}
attr Wz.Lampe webCmd brightness:toggle:on:off
attr Wz.Lampe widgetOverride brightness:slider,0,15,255

Zur Info noch die RAW Definition:

defmod Wz.Lampe XiaomiMQTTDevice 8718696449691 0x00178801034d4631
attr Wz.Lampe IODev MQTT
attr Wz.Lampe icon hue_filled_white_e27_b22
attr Wz.Lampe room XiaomiMQTTDevice
attr Wz.Lampe stateFormat {lc ReadingsVal($name,"state",0)}
attr Wz.Lampe webCmd brightness:toggle:on:off
attr Wz.Lampe widgetOverride brightness:slider,0,15,255

setstate Wz.Lampe on
setstate Wz.Lampe 2018-09-26 11:15:18 brightness 90
setstate Wz.Lampe 2018-09-26 11:15:18 state on
setstate Wz.Lampe 2018-09-26 11:15:18 transmission-state incoming publish received

Die Einrichtung der Ikea TRADFRI LED Birnen unterscheidet sich nicht von der Einrichtung der Philips HUE LED Birnen.
Man sollte lediglich die Birne zurücksetzen indem man diese 6x hintereinander ein/aus schaltet. Anschließend verhält sie sich wie eine Philips HUE.

Hier ein Beispiel eines AQARA Cube. Wichtig ist, das der MQTT Server größer gleich Version 0.1.8 ist, sonst wird der Cube nicht erkannt.



Zur Info die RAW Definition für den Cube:

defmod cube1 XiaomiMQTTDevice 8718696449691 0x00158d0002794b29
attr cube1 IODev MQTT
attr cube1 comment Aktionen:\
=========\
- Shütteln       (shake)\
- 90° umlegen    (flip90)\
- 180° umlegen   (flip180)\
- drehen rechts  (rotate_right)\
- drehen links   (rotate_left)\
- klopfen        (tap)\
- schubsen       (slide)
attr cube1 icon wuerfel
attr cube1 room XiaomiMQTTDevice
attr cube1 stateFormat {lc ReadingsVal($name,"action",0)}

setstate cube1 tap
setstate cube1 2018-11-27 21:51:22 action tap
setstate cube1 2018-11-27 21:51:17 angle 105.84
setstate cube1 2018-11-27 21:51:02 from_side 0
setstate cube1 2018-11-27 21:51:22 linkquality 70
setstate cube1 2018-11-27 21:51:22 side 4
setstate cube1 2018-11-27 21:51:02 to_side 1
setstate cube1 2018-11-27 21:51:22 transmission-state incoming publish received

ACHTUNG: Man sollte wissen, dass sich der CC2530 Router wie ein anderes Mitglied im ZigBee Netzwerk verhält.
Ist er einmal gepaired, kann man ihn nicht mehr in ein anderes Netzwerk pairen. Dazu muss er neu geflashed werden, da er keine Knöpfe hat.

Wir bieten einen Reflash-Update-Service an. Für 5,- EUR zzgl. Versandkosten flashen wir jeden CC2531/CC2530 neu mit aktueller Firmware.

Der CC2530 Router lässt sich auch ganz einfach in FHEM einbinden, denn er wird automatisch angelernt, nachdem er mit Strom versorgt wird.
Auch hier muss der CC2530 Router erstmalig nahe am ZigBee CC2531 Coordinator aufgebaut werden. Anschließend wird der Router automatisch in FHEM im Raum XiaomiMQTTDevice eingetragen.
Selbstverständlich muss der Coordinator empfangsbereit für neues devices sein. Also die xBridge muss den Status pair 1 haben.

Jan 29 22:22:40 fhem npm[3252]:   zigbee2mqtt:info 2019-1-29 22:22:40 Device incoming...
Jan 29 22:22:40 fhem npm[3252]:   zigbee2mqtt:info 2019-1-29 22:22:40 MQTT publish, topic: 'zigbee2mqtt/bridge/log', payload: '{"type":"pairing","message":"device incoming"}'
Jan 29 22:22:40 fhem npm[3252]:   zigbee2mqtt:info 2019-1-29 22:22:40 New device with address 0x00124b001bd118c6 connected!

Nach einiger Ziet ändert sich der Status des CC2530 Routers von paired auf true und sendet im Minutentakt ein Lebenszeichen, welches im Logfile des zigbee2mqtt Service foglendermaßen aussieht:
Falls der Router false zurück meldet, hat er sich noch ncht 100% mit dem Coordinator geeinigt und braucht noch eine Weile. Dauert dieser Zustand länger an, kann ein aus- einstecken oder eine Positionsveränderung oder auch ein anderes USB-Netzteil das Problem beheben. Man sollte auch die Linkqualität im Auge behalten. Diese sollte nicht zu schwach sein.

root@fhem:~# sudo journalctl -u zigbee2mqtt.service -f
-- Logs begin at Di 2019-01-29 21:17:15 CET. --
Jan 30 09:01:29 fhem npm[3252]:   zigbee2mqtt:info 2019-1-30 09:01:29 MQTT publish, topic: 'zigbee2mqtt/0x00124b001bd1126f', payload: '{"state":true,"linkquality":68,"description":"54044/0x000B57FFFED65BDC","type":"PARENT","rssi":0}'
Jan 30 09:01:29 fhem npm[3252]:   zigbee2mqtt:info 2019-1-30 09:01:29 MQTT publish, topic: 'zigbee2mqtt/0x00124b001bd1126f', payload: '{"state":true,"linkquality":68,"description":"54044/0x000B57FFFED65BDC","type":"PARENT","rssi":0}'
Jan 30 09:02:29 fhem npm[3252]:   zigbee2mqtt:info 2019-1-30 09:02:29 MQTT publish, topic: 'zigbee2mqtt/0x00124b001bd1126f', payload: '{"state":true,"linkquality":70,"description":"54044/0x000B57FFFED65BDC","type":"PARENT","rssi":0}'

Nachfolgend noch ein paar Attribute in FHEM setzen.

attr CC2530_Router_1 IODev MQTT
attr CC2530_Router_1 devStateIcon false:FS20.off true:FS20.on
attr CC2530_Router_1 icon it_router
attr CC2530_Router_1 room XiaomiMQTTDevice

Beim ioBroker ist das Einbinden genauso einfach. Man muss lediglich den Router sehr nahe (ca. 5-10 cm) an den Coordinator platzieren und den Anlernvorgang starten.
Im nachfolgenden Bild ist die Magnetfußantenne des ZigBee CC2531 Coordinators zu sehen. Eine Coordinator mit aufgedruckter Standard Antenne ist aber genauso verwendbar.
Ebay-Angebot: hier klicken

Während der Anlernphase laufen die gewohnten 60 Sekunden Pairingzeit und melden erfolgreich eine Verbindung.

Anschließend findet man den Router unter den ZigBee Devices.