Zigbee2MQTT in Home Assistant einrichten: Zigbee-Dongle, Mosquitto und das erste Gerät koppeln

Mosquitto-Broker installieren

Zigbee2MQTT spricht über MQTT mit Home Assistant, deshalb zuerst den Broker: Einstellungen → Apps → App-Store → Mosquitto broker installieren und starten. Lege unter Einstellungen → Personen → Benutzer einen eigenen Benutzer (z. B. mqtt) an – die MQTT-Integration erscheint danach automatisch unter Geräte & Dienste; dort Konfigurieren klicken.

Zigbee2MQTT-Repository hinzufügen

Unter Einstellungen → Apps → App-Store → ⋮ (oben rechts) → Repositories folgende Adresse einfügen:

https://github.com/zigbee2mqtt/hassio-zigbee2mqtt

Danach erscheinen zwei Apps: Zigbee2MQTT (stabil, empfohlen) und Zigbee2MQTT Edge (Entwicklungsstand). Die stabile Version installieren, noch nicht starten.

Dongle einstecken und Port ermitteln

Dongle per Verlängerungskabel an einen USB-2.0-Port stecken. Den eindeutigen Gerätepfad zeigt Einstellungen → System → Hardware → Alle Hardware (nach „tty“ suchen) oder das Terminal:

ha hardware info
ls /dev/serial/by-id/

Verwende den langen /dev/serial/by-id/usb-…-Pfad, nicht /dev/ttyUSB0 – letzterer kann sich nach einem Neustart ändern.

Zigbee2MQTT konfigurieren

In der App-Konfiguration (Reiter Konfiguration) den Bereich serial ausfüllen. Beispiel für den ZBDongle-E:

serial:
  port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXX-if00-port0
  adapter: ember

Für den ZBDongle-P und andere Texas-Instruments-Sticks lautet der Adapter zstack, für ConBee/RaspBee deconz. Die MQTT-Verbindung zum Mosquitto-Broker trägt die App auf Home Assistant OS automatisch ein. Speichern und die App starten; im Protokoll sollte „Zigbee2MQTT started!“ erscheinen.

Funkkanal prüfen

Zigbee und WLAN teilen sich das 2,4-GHz-Band. Nutzt dein WLAN Kanal 1, ist Zigbee-Kanal 11 ungünstig; bei WLAN-Kanal 11 meide Zigbee 26. Der Kanal steht in der Zigbee2MQTT-Oberfläche unter Settings → Advanced → Channel – und sollte vor dem Koppeln der Geräte festgelegt werden, weil ein späterer Wechsel alle Geräte neu koppeln lässt.

Erstes Gerät koppeln

Öffne die Zigbee2MQTT-Oberfläche (Seitenleiste). Klicke oben auf „Permit join (All)“ – das Netz nimmt jetzt 254 Sekunden lang neue Geräte auf. Versetze das Gerät in den Kopplungsmodus (meist Taste 5 Sekunden halten, bei Lampen sechsmal ein/aus). Es erscheint in der Geräteliste, wird erkannt („Interviewing“) und danach mit Modellname angezeigt. Vergib einen sprechenden Namen wie tuer_haustuer.

In Home Assistant nutzen

Dank MQTT-Discovery tauchen die Geräte ohne weiteres Zutun unter Geräte & Dienste → MQTT auf – mit allen Entitäten (Kontakt, Batterie, Verbindungsqualität). Ab hier funktionieren Dashboards und Automationen wie mit jedem anderen Gerät. Netzstromgeräte wie Steckdosen und Lampen arbeiten zusätzlich als Router und vergrößern die Reichweite des Zigbee-Netzes.