Zigbee2MQTT mit Docker einrichten: Zigbee-Geräte per MQTT einbinden

Zigbee-Geräte wie Sensoren, Schalter und Lampen sprechen ein eigenes Funkprotokoll und sind ab Werk oft an eine Hersteller-App oder eine Cloud gebunden. Zigbee2MQTT durchbricht diese Bindung: Es liest die Zigbee-Funksignale über einen USB-Coordinator aus und übersetzt sie in MQTT-Nachrichten, die jedes beliebige Smart-Home-System weiterverarbeiten kann. So baust du ein lokales, herstellerneutrales und cloudfreies Zigbee-Netz, das mehrere hundert Geräte verschiedener Marken unter einem Dach vereint. Diese Anleitung zeigt dir, was Zigbee2MQTT leistet, was du dafür brauchst und wie du es sauber als Docker-Container betreibst.

Was ist Zigbee2MQTT?

Zigbee2MQTT ist eine quelloffene Bridge, die zwischen deinen Zigbee-Geräten und der MQTT-Welt vermittelt. Es nimmt die Funksignale, die ein angeschlossener Zigbee-Coordinator (ein USB-Stick) empfängt, entgegen, übersetzt sie in lesbare MQTT-Nachrichten und veröffentlicht sie auf einem MQTT-Broker. Umgekehrt nimmt es Steuerbefehle über MQTT entgegen und sendet sie als Zigbee-Kommandos an die Geräte. Dadurch löst du deine Sensoren, Lampen und Schalter aus den geschlossenen Ökosystemen der Hersteller und betreibst sie vollständig lokal, ohne Cloud-Zwang und ohne herstellerspezifische Hubs.

Wofür eignet sich Zigbee2MQTT?

Herstellerneutrales Smart Home. Geräte unterschiedlichster Marken laufen über einen einzigen Coordinator und Broker zusammen, statt für jede Marke ein eigenes Gateway zu betreiben.

Lokale Steuerung ohne Cloud. Die gesamte Kommunikation bleibt im eigenen Netz; das Smart Home funktioniert auch ohne Internetverbindung und ohne Datenabfluss zu Dritten.

Anbindung an bestehende Systeme. Über MQTT lässt sich Zigbee2MQTT mit Home Assistant, Node-RED, openHAB oder eigenen Skripten kombinieren und in Automationen einbinden.

Volle Transparenz und Kontrolle. Das Web-Frontend zeigt die Netzwerk-Topologie, Verbindungsqualität und jedes einzelne Gerät; Firmware, Geräte-Datenbank und Konfiguration liegen bei dir.

Wichtige Konzepte und Voraussetzungen

Zigbee-Coordinator. Ein USB-Funkadapter (z. B. mit zStack- oder EmberZNet-Firmware) bildet die Funkbasis des Netzes und wird dem Container als Gerät durchgereicht. Statt des wechselnden Pfads /dev/ttyACM0 oder /dev/ttyUSB0 verwendest du am besten den stabilen Pfad unter /dev/serial/by-id/, der sich bei einem Neustart nicht ändert.

MQTT-Broker (zwingend). Zigbee2MQTT braucht einen erreichbaren MQTT-Broker wie Eclipse Mosquitto. Ohne erreichbaren Broker bricht der Dienst beim Start ab; die Broker-Adresse trägst du in der configuration.yaml ein.

configuration.yaml und Geräte-Datenbank. Im Datenverzeichnis /app/data liegen die zentrale Konfiguration (configuration.yaml, beim ersten Start automatisch angelegt) und die Geräte-Datenbank (database.db) mit den angelernten Geräten. Dieser Pfad muss dauerhaft persistiert werden, sonst gehen alle Pairings verloren.

Web-Frontend. Über Port 8080 erreichst du die Weboberfläche zum Anlernen, Umbenennen und Überwachen der Geräte sowie zur Pflege der Netzwerk-Topologie.

Zigbee2MQTT läuft nicht allein: Du brauchst zwingend einen erreichbaren MQTT-Broker (z. B. Eclipse Mosquitto) und einen physischen Zigbee-Coordinator als USB-Stick, der dem Container durchgereicht wird. Ermittle vor dem Start mit ls -l /dev/serial/by-id/ den stabilen Pfad deines Sticks (er ändert sich beim Neustart nicht) und trage die Broker-URL in der configuration.yaml unter mqtt.server ein.

Installation mit Docker

Zigbee2MQTT speichert configuration.yaml und die Geräte-Datenbank (database.db, mit allen angelernten Geräten) im Verzeichnis /app/data. Genau dieser Pfad muss persistent sein, denn ohne ihn verlierst du beim Neustart oder Container-Update sämtliche Pairings und müsstest jedes Gerät erneut anlernen. Wir legen ihn deshalb auf ein benanntes Volume. Zusätzlich reichst du den USB-Coordinator per --device durch (am besten über den stabilen Pfad /dev/serial/by-id/) und gibst Port 8080 für das Frontend frei. Den MQTT-Broker setzen wir hier als bereits vorhanden voraus (Adresse in der configuration.yaml unter mqtt.server). Als Image verwenden wir die offizielle Variante ghcr.io/koenkk/zigbee2mqtt.

1docker run -d \
2  --name zigbee2mqtt \
3  --restart=unless-stopped \
4  --device=/dev/serial/by-id/DEIN-ADAPTER:/dev/ttyACM0 \
5  -p 8080:8080 \
6  -v z2m-data:/app/data \
7  -v /run/udev:/run/udev:ro \
8  -e TZ=Europe/Zurich \
9  ghcr.io/koenkk/zigbee2mqtt

Oder als wiederverwendbare docker-compose.yml:

1services:
2  zigbee2mqtt:
3    image: ghcr.io/koenkk/zigbee2mqtt
4    container_name: zigbee2mqtt
5    restart: unless-stopped
6    ports:
7      - "8080:8080"
8    volumes:
9      - z2m-data:/app/data
10      - /run/udev:/run/udev:ro
11    devices:
12      - /dev/serial/by-id/DEIN-ADAPTER:/dev/ttyACM0
13    environment:
14      - TZ=Europe/Zurich
15
16volumes:
17  z2m-data:

Passe das --device bzw. devices auf den realen Pfad deines Coordinators an: Statt des fest verdrahteten /dev/serial/by-id/DEIN-ADAPTER trägst du den Pfad ein, den dir ls -l /dev/serial/by-id/ liefert (alternativ /dev/ttyACM0 oder /dev/ttyUSB0). Trage in /app/data/configuration.yaml unter mqtt.server die URL deines Brokers ein (z. B. mqtt://192.168.1.10:1883) und sichere das Frontend nicht ungeschützt ins Internet, sondern stelle es nur intern oder hinter einem Reverse-Proxy mit Authentifizierung bereit. Das benannte Volume z2m-data enthält deine gesamte Geräte-Datenbank; sichere es regelmässig. Hinweis: Die offizielle Doku nutzt ghcr.io/koenkk/zigbee2mqtt; das identische Image liegt alternativ unter koenkk/zigbee2mqtt auf Docker Hub.

Nach dem Start prüfst du Logs und erreichst das Web-Frontend im Browser:

1docker logs -f zigbee2mqtt
2# Frontend im Browser öffnen:
3http://SERVER:8080

Fazit

Zigbee2MQTT ist der Schlüssel zu einem herstellerneutralen, lokalen Zigbee-Netz: Es entkoppelt deine Geräte von proprietären Hubs und macht sie über MQTT für jedes System nutzbar. Wichtig ist, dass du zwei Voraussetzungen erfüllst, einen durchgereichten Zigbee-Coordinator und einen erreichbaren MQTT-Broker, und dass du das Datenverzeichnis /app/data über ein benanntes Volume persistierst, damit deine Geräte-Datenbank Updates und Neustarts übersteht. In Kombination mit einem Broker wie Mosquitto und einem System wie Home Assistant erhältst du ein vollständig selbstbestimmtes Smart Home ohne Cloud-Abhängigkeit.