zigbee2mqtt auf dem Raspberry Pi (docker)

In diesem Beitrag wollen wir dir zeigen, wie du zigbee2mqtt auf einem Raspberry Pi installierst. Dafür werden wir auch einen mosquitto als MQTT-Broker aufsetzen. Die Ausführung erfolgt über docker. Aus diesem Grund benötigst du einen Raspberry Pi mit installiertem docker. Die Installation von docker beschreiben wir in unserem Beitrag Docker auf dem Raspberry Pi installieren. Des weiteren Verwenden wir in diesem Beitrag docker-compose. Wie man dieses Tool installiert zeigen wir in unserem Beitrag Node-RED auf dem Raspberry Pi installieren (Docker). Neben dem Raspberry Pi benötigst du außerdem einen CC2531-Stick mit installierter Firmware. Diese Sticks findest du für ca. 15€ mit bereit installierter Firmware bei eBay.

Adresse des Sticks herausfinden

Standardmäßig wird der CC2531-Stick von Raspberry Pi OS unter dem Pfad /dev/ttyACM0 ins System eingebunden. Um dies zu verifzieren, führe bevor du den Stick mit dem Raspberry Pi verbindest den folgenden Befehl aus:

ls -l /dev/ttyACM0

Du solltest die folgende Ausgabe sehen:

ls: cannot access '/dev/ttyACM0': No such file or directory
Code-Sprache: JavaScript (javascript)

Wenn du jetzt den Stick verbindest und den Befehl erneut ausführst, sollte das Verzeichnis gefunden werden. In diesem Fall musst du für das weitere vorgehen nichts weiteres beachten. Wenn der Stick nicht unter dem Pfad /dev/ttyACM0 zu finden ist, versuche ihn über den folgenden Befehl zu finden:

ls -l /dev/serial/by-id

Eventuell wird dir hier auch das Verzeichnis, in dem der Stick eingebunden wird angezeigt. Falls dies nicht der Fall ist, benutze einfach den Pfad, unter dem du den Stick gefunden hast. Bei mir sah die Ausgabe des Befehls so aus:

total 0 lrwxrwxrwx 1 root root 13 Sep 6 11:22 usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018E27921-if00 -> ../../ttyACM0

Der Pfad des Sticks ist also /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018E27921-if00. In den folgenden Schritten musst du also den Host-Pfad /dev/ttyACM0 durch den Pfad des CC2531-Sticks ersetzen.

Start der benötigten Software

Bevor du die Software startest, solltest du deinen CC2531-Stick mit dem Raspberry Pi verbinden. Anschließend kannst du die folgende docker-compose.yml-Datei anlegen. Beachte hierbei, dass du die Adresse deines CC2531-Sticks vor dem Doppelpunkt in Zeile 22 anpassen musst, falls du den Stick nicht unter dieser Adresse finden konntest.

version: "3.0" services: mqtt-broker: image: eclipse-mosquitto:latest restart: always ports: - "1883:1883" - "9001:9001" volumes: - ./data/mosquitto/config:/mosquitto/config - ./data/mosquitto/data:/mosquitto/data - ./data/mosquitto/log:/mosquitto/log zigbee2mqtt: image: koenkk/zigbee2mqtt restart: always depends_on: - mqtt-broker volumes: - ./data/zigbee2mqtt:/app/data - /run/udev:/run/udev:ro devices: - /dev/ttyACM0:/dev/ttyACM0 restart: always environment: - TZ=Europe/Amsterdam
Code-Sprache: YAML (yaml)

Solltest du einen Raspberry Pi Zero für dieses Tutorial verwenden, füge bitte noch die Zeile platform: linux/arm/v6 für den Service zigbee2mqtt hinzu. Des Weiteren musst du die docker-compose Version in der ersten Zeile auf 2.4 setzen. Docker scheint standardmäßig auf dem Raspberry Pi Zero und dem Raspberry Pi 1 das falsche Image zu verwenden, was zu einem Fehler beim starten von zigbee2mqtt führt.

Lege jetzt noch zwei Konfigurationsdateien an. Zum einen benötigt der MQTT-Broker eine Konfigurationsdatei unter dem Pfad ./data/mosquitto/config/mosquitto.conf:

persistence true persistence_location /mosquitto/data/ log_dest file /mosquitto/log/mosquitto.log
Code-Sprache: JavaScript (javascript)

In dieser Beispiel-Config wird angegeben, ob MQTT-Nachrichten auf der Festplatte gespeichert werden sollen und wo die Logs des MQTT-Brokers gespeichert werden sollen. Beide Verzeichnisse werden bereits durch die docker-compose-Datei auf das Dateisystem des Raspberry PI’s gemountet.

Des Weiteren solltest du auch eine Konfigurationsdatei für zigbee2mqtt unter dem Pfad ./data/zigbee2mqtt/configuration.yaml anlegen:

homeassistant: false permit_join: false mqtt: base_topic: zigbee2mqtt server: 'mqtt://mqtt-broker' serial: port: /dev/ttyACM0 devices: {}
Code-Sprache: JavaScript (javascript)

Du kannst die docker-compose-Datei jetzt einfach über den folgenden Befehl starten:

docker-compose up

Wenn du das Programm direkt im Hintergrund starten möchtest, verwende einfach den folgenden Befehl:

docker-compose up -d

Verbindung mit dem MQTT-Broker herstellen

Zur Verbindung mit dem MQTT-Broker benötigst du einen MQTT-Client. Ich verwende hierfür das OpenSource-Projekt MQTT-Explorer. Der MQTT-Explorer ist für alle gängigen Betriebssysteme (Windows, Linux, MacOS) verfügbar.

MQTT-Explorer: Neue Verbindung erstellen
Neue Verbindung erstellen

Klicke auf den gelben Plus-Button, nachdem du den MQTT-Explorer installiert und gestartet hast. Trage im folgenden Fenster einen Namen für die Verbindung, sowie die Adresse deines Raspberry Pi’s ein.

MQTT-Explorer: Speichern und Verbinden
Verbindung speichern und herstellen

Klicke anschließend auf Save und anschließend auf Connect. Hierdurch kannst du beim nächsten mal direkt eine Verbindung mit dem MQTT-Broker herstellen, ohne die Daten erneut eingeben zu müssen.

MQTT-Explorer: Übersicht über die Topics
Übersicht über die Topics des MQTT-Broker’s

zigbee-Gerät verbinden

Jetzt werden wir ein Gerät mit der zigbee2mqtt-Installation verbinden. Ich verwende dafür die Funksteckdose von IKEA. Im Grunde ist das vorgehen aber bei allen ansteuerbaren Geräten identisch. Du kannst also auch eine zigbee-kompatible Glühbirne verwenden. Diese sollte allerdings bei den offiziell unterstützen Geräten von zigbee2mqtt aufgelistet sein.

zigbee2mqtt: Verbindungen aktivieren
Verbindungen aktivieren

Aktiviere zunächst bei zigbee2mqtt den Verbindungs-Modus. Scrolle hierfür im MQTT-Explorer auf der rechten Seite des Fensters etwas nach unten. Du siehst einen Bereich mit dem Namen publish. Trage hier unter topic zigbee2mqtt/bridge/config/permit_join und in dem großen Textfeld true ein. Klicke anschließend auf PUBLISH. Damit ist zigbee2mqtt jetzt im Pairing-Modus.

Jetzt musst du nur noch das zigbee-Gerät in den pairing-Modus versetzen. Wie das funktioniert kannst du entweder auf der Seite des Herstellers oder auf der Seite der unterstützen Geräten von zigbee2mqtt nachlesen.

zigbee2mqtt: Gerät erfolgreich verbunden
Gerät erfolgreich verbunden

Nachdem das Gerät verbunden ist, sollte ein log-Eintrag auf der rechten Seite auftauchen, in dem interview_successful, sowie der Name des neuen zigbee-Gerätes (in diesem Fall 0x14b457fffec32ee5) steht. Merke dir diesen Namen, wir brauchen ihn für den Test des zigbee-Gerätes.

Testen des zigbee-Gerätes

Jetzt können wir die Verbindung mit dem zigbee-Gerät überprüfen, indem wir das Gerät einmal ein-, bzw. ausschalten. Trage hierfür im Eingabefeld topic zigbee2mqtt/<Name des zigbee-Gerätes>/set ein. Gebe in dem großen Textfeld den folgenden Text (JSON) ein:

{ "state": "ON" }
Code-Sprache: JSON / JSON mit Kommentaren (json)

Nach einem Klick auf publish sollte das zigbee-Gerät jetzt angehen. Wenn du jetzt ON durch OFF ersetzt und auf publish klickst, sollte das Gerät aus gehen.

Auf der zigbee2mqtt-Seite findest du weitere Optionen, die du eventuell mit deinem zigbee-Gerät verwenden kannst. Probiere einfach über den MQTT-Explorer aus, was du alles machen kannst und wie sich dein zigbee-Gerät verhält. Wir wünschen dir viel Spaß dabei!