Wenn Sie Zigbee2MQTT einrichten, können Sie Zigbee-Sensoren, -Lampen und -Schalter vieler Marken ohne deren Hubs oder Clouds nutzen, und jedes Gerät erscheint als einfache MQTT-Topics. In dieser Anleitung wählen Sie einen Koordinator, betreiben Zigbee2MQTT in Docker, verbinden es mit einem Broker, lernen Geräte an und benennen sie um, steuern sie über die Kommandozeile und beobachten ihre Zustände auf einem Dashboard. Alles wird zunächst mit einem eindeutigen Basis-Topic gegen den kostenlosen öffentlichen MQTT-Broker getestet, der für Tests und nicht für den Produktivbetrieb gedacht ist.
Wie Zigbee2MQTT zusammenspielt
Zigbee2MQTT ist eine Bridge. Auf der einen Seite steuert es einen Zigbee-Koordinator (einen USB-Stick oder Netzwerkadapter), der Ihr Zigbee-Mesh aufbaut. Auf der anderen Seite ist es ein MQTT-Client, der den Zustand jedes Geräts als JSON veröffentlicht und auf Befehle hört. Alles, was MQTT spricht, etwa Home Assistant, Node-RED, ein Python-Skript oder eine Smartphone-App, kann diese Geräte dann nutzen.
[Zigbee devices] ~~radio~~ [Coordinator] --USB/TCP-- [Zigbee2MQTT] --MQTT-- [Broker] -- [Dashboards, automations]
Der Broker steht in der Mitte und ist das Einzige, womit sich jeder Abnehmer verbindet. Wenn Sie auffrischen möchten, was ein MQTT-Broker macht, lohnt sich vor dem Start ein kurzer Blick.
Einen Koordinator auswählen
Der Koordinator bestimmt, welche adapter-Einstellung Sie verwenden. Beliebte, gut unterstützte Optionen:
| Koordinator | Chip | adapter-Wert |
Hinweise |
|---|---|---|---|
| Sonoff Zigbee 3.0 USB Dongle Plus (ZBDongle-P) | TI CC2652P | zstack |
Sehr weit verbreitet, aktuelle Z-Stack-Firmware flashen |
| Sonoff ZBDongle-E | Silicon Labs EFR32MG21 | ember |
Aktuelle EmberZNet-Firmware verwenden |
| SMLIGHT-SLZB-06-Familie | CC2652P oder EFR32 | zstack oder ember |
Ethernet/PoE, Verbindung über tcp://IP:6638 |
| ConBee II / III | Dresden Elektronik | deconz |
Funktioniert, aber TI- und Silicon-Labs-Adapter sind verbreiteter |
Zwei praktische Tipps machen einen großen Unterschied. Verwenden Sie ein USB-Verlängerungskabel von etwa einem halben Meter, um den Stick von USB-3-Ports und SSDs fernzuhalten, deren Störungen die Zigbee-Reichweite stark beeinträchtigen können. Und fügen Sie früh einige netzbetriebene Router (Zwischenstecker oder Lampen) hinzu, denn batteriebetriebene Geräte routen nicht, und ein Mesh nur aus Endgeräten ist anfällig.
Zigbee2MQTT mit Docker installieren
Ermitteln Sie den stabilen Pfad Ihres Adapters, der sich zwischen Neustarts nicht ändert:
ls -l /dev/serial/by-id/
Legen Sie einen Ordner mit einer docker-compose.yml an:
services:
zigbee2mqtt:
container_name: zigbee2mqtt
image: ghcr.io/koenkk/zigbee2mqtt:latest
restart: unless-stopped
volumes:
- ./data:/app/data
- /run/udev:/run/udev:ro
ports:
- "8080:8080"
environment:
- TZ=Europe/Berlin
devices:
- /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXX-if00-port0:/dev/ttyACM0
Ersetzen Sie den Gerätepfad durch den Ihres Systems und stellen Sie Ihre Zeitzone ein. Für eine dauerhafte Installation sollten Sie das Image auf einen bestimmten Release-Tag statt latest festlegen, damit Updates nur dann erfolgen, wenn Sie es wollen.
Die Konfiguration beim Einrichten von Zigbee2MQTT
Legen Sie vor dem ersten Start data/configuration.yaml an. Wählen Sie ein zufälliges Segment für das Basis-Topic, denn der öffentliche MQTT-Broker wird gemeinsam genutzt und ist für alle lesbar:
homeassistant:
enabled: false
frontend:
enabled: true
port: 8080
mqtt:
base_topic: connectmq/demo/z7q4/z2m
server: mqtt://broker.connectmq.com:1883
client_id: z2m-z7q4-bridge
serial:
port: /dev/ttyACM0
adapter: zstack
availability:
enabled: true
advanced:
log_level: info
channel: 25
network_key: GENERATE
pan_id: GENERATE
ext_pan_id: GENERATE
Die wichtigsten Punkte:
base_topicist das Präfix für alles, was Zigbee2MQTT veröffentlicht. Hier hat es vier Ebenen und lässt damit Spielraum innerhalb des Limits von 8 Topic-Ebenen des öffentlichen MQTT-Brokers.client_idmuss auf dem Broker eindeutig und darf nicht leer sein.channellässt sich später nicht ändern, ohne jedes Gerät neu anzulernen. Die Kanäle 15, 20 und 25 vermeiden die häufigsten Überschneidungen mit WLAN; prüfen Sie, welche WLAN-Kanäle in Ihrer Umgebung belegt sind.GENERATEsorgt dafür, dass Zigbee2MQTT beim ersten Start einen zufälligen Netzwerkschlüssel und zufällige IDs erzeugt und in die Datei zurückschreibt. Sichern Sie anschließendconfiguration.yamlundcoordinator_backup.jsonaus dem Datenordner.availabilityveröffentlicht pro Gerät{"state":"online"}oderoffline, was auf Dashboards sehr nützlich ist.
Starten Sie den Container und verfolgen Sie das Log:
docker compose up -d
docker compose logs -f zigbee2mqtt
Sie sollten die Firmware-Version des Koordinators sehen und danach eine Zeile, die die Verbindung zum MQTT-Broker bestätigt. Wenn Sie ohne Konfigurationsdatei starten, öffnen neuere Versionen auf Port 8080 eine Onboarding-Seite, auf der Sie dieselben Werte in ein Formular eintragen können.
Geräte anlernen und benennen
Öffnen Sie das Frontend unter http://<host>:8080 und klicken Sie auf Permit join (All), oder erlauben Sie das Anlernen per MQTT für bis zu 254 Sekunden:
mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
-t "connectmq/demo/z7q4/z2m/bridge/request/permit_join" -m '{"time": 254}'
Versetzen Sie das Gerät in den Kopplungsmodus (meist durch langes Drücken der Taste oder bei Lampen durch eine Ein-/Aus-Sequenz). Es erscheint mit einer IEEE-Adresse wie 0x00158d0001abcd12. Benennen Sie es sofort sinnvoll um, denn der Name wird zu seinem Topic:
mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
-t "connectmq/demo/z7q4/z2m/bridge/request/device/rename" \
-m '{"from": "0x00158d0001abcd12", "to": "living_room_lamp"}'
Beenden Sie das Anlernen mit {"time": 0}, wenn Sie fertig sind. Ein offenes Netzwerk lädt Geräte der Nachbarn ein, versehentlich beizutreten.
Verwenden Sie beim Testen auf dem öffentlichen MQTT-Broker Unterstriche statt Schrägstrichen in Anzeigenamen. Ein Name wie living_room/lamp ist erlaubt und ergibt schönere Hierarchien, aber jeder Schrägstrich fügt eine Topic-Ebene hinzu, und bridge/request/device/rename nutzt mit diesem Basis-Topic bereits alle 8 Ebenen.
Geräte per MQTT auslesen und steuern
Abonnieren Sie alles unterhalb des Basis-Topics:
mosquitto_sub -h broker.connectmq.com -p 1883 -i z2m-watch-z7q4 -t "connectmq/demo/z7q4/z2m/#" -v
Ein Temperatursensor veröffentlicht auf connectmq/demo/z7q4/z2m/hallway_sensor:
{"battery": 97, "humidity": 48.2, "linkquality": 116, "temperature": 21.4, "voltage": 2995}
Steuern Sie eine Lampe, indem Sie auf ihr set-Topic veröffentlichen:
mosquitto_pub -h broker.connectmq.com -p 1883 -i z2m-cli-z7q4 \
-t "connectmq/demo/z7q4/z2m/living_room_lamp/set" \
-m '{"state": "ON", "brightness": 180, "color_temp": 370, "transition": 2}'
Um ein Gerät nach seinem aktuellen Zustand zu fragen, veröffentlichen Sie {"state": ""} auf seinem get-Topic. Geräte-Topics enthalten den vollständigen Zustand, sodass ein Dashboard nur ein Abonnement pro Gerät braucht.
Von MQTT zum Dashboard
Da Zigbee2MQTT reines MQTT spricht, haben Sie mehrere Dashboard-Optionen:
- Das Zigbee2MQTT-Frontend für die Verwaltung: Geräteliste, Netzwerkkarte, OTA-Updates und Logs.
- Home Assistant über die MQTT-Integration. Setzen Sie
homeassistant.enabled: true, dann veröffentlicht Zigbee2MQTT Discovery-Nachrichten, sodass Entitäten automatisch erscheinen; die Home-Assistant-MQTT-Anleitung behandelt diese Seite. - Node-RED Dashboard, das Geräte-Topics mit einem
mqtt in-Node und einem JSON-Node abonniert. - Ein Browser-Dashboard mit MQTT über WebSocket, das sich mit
wss://broker.connectmq.com:8084/mqttverbindet.
Für schnelle Prüfungen ohne eigenen Aufbau zeigt der Live-Topic-Explorer im ConnectMQ-Portal jedes Zigbee2MQTT-Topic, sobald es sich ändert, was beim Anlernen und Umbenennen praktisch ist.
Fehlersuche beim Einrichten von Zigbee2MQTT
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| „Failed to connect to the adapter“ | Falscher adapter oder Gerätepfad |
Mit der Tabelle oben abgleichen; /dev/serial/by-id-Pfad verwenden |
| Geräte fallen aus oder lassen sich schlecht anlernen | USB-3-Störungen, keine Router | Verlängerungskabel, netzbetriebene Router hinzufügen |
| Verbindet sich mit dem Broker und trennt dann | Doppelte Client ID | Eindeutige client_id pro Bridge |
| Bridge-Nachrichten werden vom öffentlichen MQTT-Broker abgelehnt | Große bridge/devices- oder bridge/definitions-Payloads in größeren Netzwerken |
Mit wenigen Geräten testen, für vollständige Netzwerke einen privaten Broker verwenden |
| Umbenennen wirkt nicht | Topic-Tiefe über den 8 Ebenen des öffentlichen MQTT-Brokers | base_topic oder Namen kürzen |
Der öffentliche MQTT-Broker begrenzt jeden Client außerdem auf 10 Nachrichten pro Sekunde; ein kleines Testnetz bleibt deutlich darunter, ein großes Netzwerk kann diese Grenze beim Start aber überschreiten. Ein weiterer Grund, warum der öffentliche MQTT-Broker nur für Tests gedacht ist; der Beitrag zum kostenlosen öffentlichen MQTT-Broker listet alle Limits auf.
Umstieg auf einen privaten Broker
Zigbee2MQTT steuert Schlösser, Lichter und Alarmanlagen, daher braucht der Produktivbetrieb Zugangsdaten und TLS. Mit einem verwalteten MQTT-Broker wie ConnectMQ legen Sie im Portal einen Broker an, kopieren den generierten Benutzernamen, das Passwort und die Client ID und ändern nur den mqtt-Block:
mqtt:
base_topic: zigbee2mqtt
server: mqtts://broker.connectmq.com:8883
user: YOUR_USERNAME
password: YOUR_PASSWORD
client_id: YOUR_CLIENT_ID
version: 5
Das Let's-Encrypt-Zertifikat wird gegen das System-CA-Bundle im Container validiert, zusätzliche Zertifikatsdateien sind also nicht nötig. Der kostenlose Serverless-Tarif erlaubt Nachrichten bis 256 KB, was für typische Bridge-Payloads bequem reicht, und die kostenpflichtigen Tarife erhöhen das auf 1 MB. Die Anleitung Zigbee2MQTT mit einem Cloud-Broker geht tiefer auf Fernzugriff und Setups mit mehreren Standorten ein, und der IoT-Automatisierungsleitfaden zeigt, wo Zigbee in einem größeren Haus- oder Gebäudesystem seinen Platz hat. Wer Zigbee-Sensoren gewerblich nachrüstet, etwa für Raumklima oder Energiemonitoring in einer Werkhalle, sollte das Basis-Topic gleich in einen Unified Namespace (UNS) nach ISA-95-Hierarchie einordnen, zum Beispiel unter acme/werk-muenchen/halle-2/zigbee2mqtt.
Zigbee2MQTT mit ConnectMQ betreiben
ConnectMQ bietet Ihrer Zigbee2MQTT-Bridge einen privaten MQTT-Broker mit TLS, Secure WebSocket für Browser-Dashboards und ein Portal, in dem Sie jedes Geräte-Topic live verfolgen. Erstellen Sie einen kostenlosen Serverless-Broker unter app.connectmq.com, ganz ohne Kreditkarte, und richten Sie Ihr mqtt.server darauf aus.
Häufig gestellte Fragen
Welcher Koordinator eignet sich am besten, um Zigbee2MQTT neu einzurichten?
Ein Stick mit Texas Instruments CC2652P und dem Adapter zstack oder ein Stick mit Silicon Labs EFR32MG21 und dem Adapter ember sind die gängigsten, gut unterstützten Optionen. Netzwerkadapter sind nützlich, wenn der Server weit von den Geräten entfernt steht.
Kann ich den Zigbee-Kanal später ändern?
Technisch ja, aber die meisten Geräte müssen dann neu angelernt werden. Wählen Sie den Kanal sorgfältig, bevor Sie irgendetwas anlernen.
Braucht Zigbee2MQTT Home Assistant?
Nein. Zigbee2MQTT braucht nur einen MQTT-Broker. Home Assistant ist einer von vielen optionalen Abnehmern, neben Node-RED, Skripten und Dashboards.
Ist es sicher, Zigbee2MQTT auf einem öffentlichen MQTT-Broker zu betreiben?
Nur zum Testen. Jeder kann öffentliche Topics lesen und auf sie veröffentlichen, auch auf Ihre set-Topics; verwenden Sie für echte Geräte deshalb einen privaten Broker mit Zugangsdaten und TLS.
