Zigbee2MQTT: Zigbee-Geräte mit jedem MQTT-Broker verbinden

Zigbee2MQTT macht aus einem USB-Zigbee-Koordinator ein MQTT-Gateway: Jeder angelernte Sensor, jede Lampe und jeder Schalter erscheint als JSON-Nachricht auf einem Topic, und jedes Topic mit der Endung /set wird zum Befehl. Einen Broker bringt es nicht mit – du trägst einen in configuration.yaml ein, und jeder standardkonforme MQTT-Broker funktioniert: ein lokales Mosquitto, das Home-Assistant-Add-on oder ein Managed Broker in der Cloud.

Dieses Tutorial konfiguriert Zigbee2MQTT (2.x) mit einem externen Broker, erklärt das Topic-Layout und zeigt, wie du die Verbindung prüfst und ein Gerät von der Kommandozeile aus steuerst.

Wie die Teile zusammenspielen

Zigbee device ──radio──▶ Coordinator (USB) ──serial──▶ Zigbee2MQTT ──MQTT──▶ Broker ──▶ Home Assistant / Node-RED / your app

Zigbee2MQTT ist einfach ein weiterer MQTT-Client. Das hat zwei praktische Folgen: Der Broker kann überall stehen, wo er übers Netzwerk erreichbar ist, und alles andere, was MQTT spricht – ein Dashboard, ein Skript, der Online-Client –, sieht genau dieselben Nachrichten wie deine Hausautomations-Software.

Minimale Konfiguration

Zigbee2MQTT liest data/configuration.yaml. Der MQTT-Abschnitt verbindet es mit deinem Broker:

mqtt:
  base_topic: testmqtt/z2m          # Standard ist "zigbee2mqtt"
  server: mqtts://broker.connectmq.com:8883
  user: '!secret user'
  password: '!secret password'
  client_id: z2m-living-room
  keepalive: 60
  version: 5                        # 3, 4 (3.1.1) oder 5

serial:
  port: /dev/ttyACM0
  adapter: ember                    # zstack, ember, deconz, zigate, zboss

frontend:
  enabled: true
  port: 8080

homeassistant:
  enabled: false                    # true, wenn Home Assistant Geräte automatisch erkennen soll

advanced:
  log_level: info

user: username
password: password

Hinweise zu den wichtigen Schlüsseln:

• server – mqtt://host:1883 für unverschlüsseltes TCP, mqtts://host:8883 für TLS. WebSocket-URLs (wss://host:8084/mqtt) funktionieren ebenfalls, weil Zigbee2MQTT intern MQTT.js nutzt, für ein Gateway ist TCP aber die übliche Wahl.
• base_topic – die Wurzel von allem, was Zigbee2MQTT publiziert. Behalte auf einem privaten Broker den Standard zigbee2mqtt; auf einem geteilten Test-Broker nimm eine eindeutige Wurzel wie oben, damit du nicht mit anderen Nutzern kollidierst.
• client_id – muss auf dem Broker eindeutig sein. Zwei Instanzen mit derselben ID werfen sich gegenseitig in einer Schleife raus; siehe Best Practices für Client-IDs.
• ca, key, cert – nur für eine private CA oder Mutual TLS nötig. Ein Broker mit öffentlich vertrauenswürdigem Zertifikat funktioniert allein mit mqtts://. "Behebe" Zertifikatsfehler in Produktion niemals mit reject_unauthorized: false.
• !secret – legt die Zugangsdaten in secret.yaml ab, damit du configuration.yaml gefahrlos teilen oder committen kannst.

Jede Option lässt sich auch über Umgebungsvariablen setzen, was in Containern praktisch ist: ZIGBEE2MQTT_CONFIG_MQTT_SERVER, ZIGBEE2MQTT_CONFIG_MQTT_USER, ZIGBEE2MQTT_CONFIG_MQTT_PASSWORD und so weiter.

Betrieb mit Docker

services:
  zigbee2mqtt:
    image: ghcr.io/koenkk/zigbee2mqtt
    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-if00-port0:/dev/ttyACM0

Binde den Koordinator über seinen /dev/serial/by-id/...-Pfad ein: /dev/ttyUSB0 kann sich nach einem Neustart oder beim Einstecken eines anderen USB-Geräts ändern. Wenn du einen lokalen Broker in derselben Compose-Datei betreibst, sprich ihn über den Servicenamen an (mqtt://mosquitto:1883), nicht über localhost – im Container ist localhost der Container selbst. Der Leitfaden zum Docker-Compose-Stack beschreibt dieses Setup.

Starte es und verfolge das Log:

docker compose up -d
docker compose logs -f zigbee2mqtt

Ein gesunder Start loggt Connecting to MQTT server at mqtts://broker.connectmq.com:8883, gefolgt von Connected to MQTT server. Siehst du MQTT error: Connection refused: Not authorized oder MQTT failed to connect, exiting..., prüfe zuerst die Zugangsdaten und die Kombination aus Port und Schema – der Leitfaden zu Zigbee2MQTT-Fehlern geht jede Meldung durch.

Das Topic-Layout

Neue Geräte heißen nach ihrer IEEE-Adresse (0x00158d0001a2b3c4). Benenne sie sinnvoll um; ein Schrägstrich im Namen erzeugt eine Hierarchie, aus living_room/ceiling wird also testmqtt/z2m/living_room/ceiling. So kommst du am einfachsten zu einem sauberen Smart-Home-Topic-Baum.

bridge/state, bridge/info und bridge/devices sind Retained Messages: Jeder Client, der später abonniert, erfährt sofort, ob die Bridge läuft und welche Geräte existieren.

Jeden Schritt auf der Kommandozeile testen

1. Ist die Bridge verbunden? Abonniere den Bridge-Status; der Retained-Wert kommt sofort:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/bridge/state' -v
# testmqtt/z2m/bridge/state {"state":"online"}

2. Beobachte den gesamten Traffic, während du einen Taster drückst oder einen Türsensor öffnest:

mosquitto_sub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/#' -v

3. Lerne ein Gerät an, indem du das Netz für begrenzte Zeit öffnest (Zigbee2MQTT 2.x verlangt time; 0 schließt es wieder):

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" \
  -t 'testmqtt/z2m/bridge/request/permit_join' -m '{"time": 120}'

Die Antwort kommt auf bridge/response/permit_join, und bridge/event meldet device_joined und device_interview, während das Gerät angelernt wird.

4. Umbenennen und steuern:

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/bridge/request/device/rename' \
  -m '{"from": "0x00158d0001a2b3c4", "to": "living_room/ceiling"}'

mosquitto_pub -h broker.connectmq.com -p 8883 --capath /etc/ssl/certs \
  -u "$MQTT_USER" -P "$MQTT_PASS" -t 'testmqtt/z2m/living_room/ceiling/set' \
  -m '{"state": "TOGGLE", "brightness": 180, "transition": 1}'

Der neue Zustand der Lampe erscheint innerhalb einer Sekunde auf testmqtt/z2m/living_room/ceiling. Bewirkt ein Befehl nichts, schau in bridge/logging – dort protokolliert Zigbee2MQTT abgelehnte Payloads.

Dieselben Schritte gehen auch im Browser: Öffne den Online-MQTT-Client, abonniere testmqtt/z2m/# und publiziere über das Publish-Panel auf die /set-Topics.

Zigbee2MQTT-Topics live beobachten

Integration mit Home Assistant

Setze homeassistant: enabled: true, dann publiziert Zigbee2MQTT Discovery-Nachrichten unter homeassistant/.... Die MQTT-Integration von Home Assistant muss auf denselben Broker zeigen; die Geräte erscheinen dann automatisch mit allen Entitäten. Hast du base_topic geändert, musst du sonst nichts anpassen – die Discovery-Payloads enthalten die richtigen State- und Command-Topics. Die Broker-Seite beschreibt Home Assistant und MQTT.

Checkliste für die Produktion

1. Gib Zigbee2MQTT einen eigenen Broker-Benutzer und beschränke ihn auf <base>/#, plus homeassistant/#, wenn Discovery aktiv ist.
2. Nutze TLS (mqtts://), sobald der Broker nicht auf demselben Host läuft.
3. Aktiviere availability, damit Offline-Geräte gemeldet werden, statt still zu veralten.
4. Halte permit_join geschlossen, außer beim Anlernen.
5. Sichere das gesamte data/-Verzeichnis – es enthält den Netzwerkschlüssel und das Koordinator-Backup, nicht nur die Konfiguration.

Zigbee2MQTT ist der einfachste Weg, Zigbee-Geräte von Hersteller-Hubs zu befreien: Ein YAML-Block zeigt auf einen beliebigen Broker, und ab dann ist jedes Gerät nur noch ein Topic. Prüfe zuerst den Bridge-Status, beobachte den Traffic beim Anlernen und steuere Geräte mit einfachem mosquitto_pub, bevor du Automationen darauf aufbaust.

Häufig gestellte Fragen