Suchst du nach einer Möglichkeit, deine ZigBee-Geräte mit Home Assistant zu steuern? In diesem Video erfährst du, wie ZigBee2MQTT dir dabei helfen kann.
ZigBee2MQTT (Z2M) ist ein Add-on, mit dem du dich durch einen ZigBee-Stick mit ZigBee-Geräten verbinden und sie von Home Assistant über einen MQTT-Broker (Mosquitto) steuern kannst. Das Ganze funktioniert sehr zuverlässig, ist extrem schnell 🚀 und es werden unglaublich viele Geräte unterstützt.
Außerdem ist es Open Source und kostenlos, also probiere es noch heute aus 🙌
Falls du prüfen willst, ob dein ZigBee Geräte mit ZigBee2MQTT kompatibel ist oder wissen möchtest, wie du den Pairing-Modus aktivieren kannst, kannst du auf der offiziellen Seite nachschauen.
Inhaltsverzeichnis
- Voraussetzungen
- Benutze Repos / Links
- Bevor du startest
- Der ZigBee USB-Stick
- Fehlerbehebung
- ZigBee Reichweite verbessern
- Hinweis zu Schaltern & Dimmern
- Erweitertes Wissen
- SMLIGHT SLZB-07P7
- Geräte für HA
- Hardware für Home Assistant
- Fazit
Voraussetzungen
Benutze Repos / Links
- www.zigbee2mqtt.io
- Empfohlene Adapter
- Mosquitto (MQTT Broker)
- Link für die Add-on Repository:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
Bevor du startest
Für wen ist ZigBee2MQTT, für wen ZHA, geeignet?
Diese Frage beantwortet vermutlich jeder anders und meine Empfhelungen ändern sich natürlich auch im Laufe der Ziet…
Aktuell würde ich sagen: Neue Nutzer sollten mit ZHA beginnen und prüfen, ob alle gewünschten Geräte (falls vorhanden) unterstützt werden. Für neue Geräte kann man hier im Gadget-Finder oder auf Blackadder schauen, welche Geräte unterstützt werden.
Falls man bereits Z2M nutzt, oder weiß, dass man viele Spezial-Geräte hat, die mit ZHA nicht funktionieren, würde ich eher zu Z2M raten.
Meine Empfehlung geht aber tatsächlich mehr in Richtung ZHA. Der einfache Start für Neueinsteiger, die exzellente Unterstützung des SkyConnect sowie die native Integration in Home Assistant und die tollen Reaktionszeiten der Geräte, machen es für jeden zu einer guten Wahl.
Der ZigBee USB-Stick
Auch 2025 noch meine allgemeine Pauschal-Empfehlung für alle – Der Sonoff ZBDongle-P mit CC2652P Chipsatz von Texas Instruments!
Addon-Konfiguration für die Sticks
SONOFF Zigbee 3.0 USB Dongle Plus ZBDongle-P (CC2652P)
Dies ist die Version, die auch im Video genutzt wurde.
serial: port: /dev/ttyUSB0 adapter: zstack
Sonoff Zigbee 3.0 USB Dongle Plus ZBDongle-E (EFR32MG21)
Den Sonoff Stick gibt es seit 2023 in einer V2 Edition, mit Chipsatz von Silicon Labs. Das ist auf der Verpackung (und bei meiner Bestellung) nur bei sehr genauem Hinsehen zu erkennen. Das Ding heißt immer noch “Zigbee USB 3.0 Dongle Plus”. Auf der Rückseite des Dongles ist aber die Modellnummer “ZBDongle-E” zu lesen.
Gemäß den Herstellerangaben wird hier ein andere Chipsatz ( “EFR32MG21”) verbaut.
Dies ist die neuere Version des Chipsatzes – Kann ich persönlich NICHT für ZigBee empfehlen, Texas Instruments Chips laufen mMn stabiler!
serial: port: /dev/ttyUSB0 adapter: ember
Port herausfinden
Neben dem gezeigten Weg im Video gibt es noch eine weitere Möglichkeit:
- Im SSH-Addon den Befehl
ls -l /dev/serial/by-ideingeben - Der Port wird rechts nach dem -> angezeigt, aber ohne /dev/
- In diesem Beispiel wäre also
port: /dev/ttyUSB0korrekt
Alternative Addon-Konfigurationen
Hier noch ein paar weitere Konfigurationen für andere Hardware (nicht der Sonoff-Stick, diese sind hier oben drüber ☝)
Diese Hardware habe ich nicht selber getestet, es handelt sich um Feedback aus der Community. Vielen Dank an euch alle 🙌
SONOFF ZBBridge
serial:
port: 'tcp://IP.Adresse.Der.Bridge:20108'
adapter: ember
ConBee / ConBee II / RaspBee / RaspBee II
Über USB angeschlossene Adapter (ConBee und ConBee II) und Raspberry Pi GPIO Module (RaspBee und RaspBee II). Wenn Zigbee2MQTT nicht startet, versuche Folgendes:
serial: adapter: deconz
Home Assistant SkyConnect
serial:
port: >-
/dev/serial/by-id/usb-Nabu_Casa_SkyConnect_v1.0_2e07db08b114ed11a749bc8be054580b-if00-port0
adapter: ember
Schau dir auch gerne den zugehörigen Beitrag zum SkyConnect an, indem du auch erfährst, wie man den Coordinator (Funk-Stick) von ZigBee2MQTT tauschen kann!
Fehlerbehebung
Was tun, wenn Zigbee2MQTT nicht startet?
- Der Zugriff auf den Stick darf nicht durch ZHA oder andere Integrationen / Add-ons blockiert werden. Wenn diese eingerichtet waren, bitte deaktivieren oder löschen!
- Das Mosquitto-Addon (oder dein eigener MQTT-Broker) muss bereits gestartet sein, bevor Zigbee2MQTT gestartet wird! (Kann zu
502: Bad GatewayFehlern führen) - Kontrolliere, ob du die richtige Konfiguration für deinen Stick hast ☝
- Home Assistant Host neu starten
- Port des Zigbee-Sticks kontrollieren
- Zigbee2MQTT deinstallieren, Home Assistant Host neu starten, Zigbee2MQTT wieder installieren
- Was sagen die Log-Files des Add-on?
- Wenn du dir die Add-on-Konfiguration als YAML anzeigen lässt (3 Punkte oben rechts in der Ecke): Stimmt die Datei überein, mit deinen eingegebenen Werten? (Besonders der Abschnitt serial:)
- Zigbee2MQTT Add-on starten und dann erst den Stick anschließen 👇
- Du nutzt RaspberryMatic? Schau mal hier
ZigBee2MQTT startet nicht, wenn der Stick eingesteckt ist
Bei manchen Installationen kommt es vor, dass Zigbee2MQTT erst gestartet sein muss und anschließend der Stick an den USB-Port gesteckt werden muss. Sonst kommt es beim Starten von Zigbee2MQTT zu Fehlermeldungen, wie beispielsweise der hier:
'AddonManager.Install' blocked from execution, system is not healthy
Davor muss aber der Port (port: /dev/ttyUSB0) schon angegeben wurden sein.
Im Zweifelsfall also einfach mal testen und danke an Maikel für das Feedback 😉
ZigBee2MQTT Reset error: Error: {“sequence”:-1} after 10000ms
Der Fehler Reset error: Error: {"sequence":-1} after 10000ms at /app/node_modules/zigbee-herdsman/src/adapter/ezsp/driver/uart.ts kann auftreten, wenn Z2M bereits eingerichtet war und etwas mit den (alten) Konfigurationsdateien nicht stimmt:
Lösung:
- Komplettes HA Backup erstellen (nur zur Sicherheit)
- Z2M Add-on Deinstallieren
- Den bestehenden alten Konfigurationsordner von Z2M im /config Ordner von Home Assistant komplett löschen
- Add-on neu installieren
Ansicht des zu löschenden Ordners:
Nach dem Löschen des Ordners kann man Z2M neu konfigurieren & wieder starten. Natürlich muss der Ordner zum Löschen über den File-Editor leer sein, insofern ist beispielsweise die Nutzung des Samba-Addons schneller, als alle Ordner durchzugehen und die Dateien “von unten nach oben” zu löschen 😉
Geräte tauchen in Home Assistant nicht auf
Wenn die Geräte zwar in Zigbee2MQTT sind, aber nicht in Home Assistant als Entität auftauchen, ist vermutlich mit dem MQTT-Broker irgendwas im Argen.
Hinweis: Ich gehe hier mal davon aus, du nutzt wie im Video gezeigt Mosquitto und hast dieses Add-on bereits gestartet.
- (Empfohlen) Ist die MQTT-Integration, wie im Video ab 14:20 zu sehen, eingerichtet?
- Falls das nicht klappt, kannst du alternativ versuchen, folgenden Code in deine configuration.yaml hinzuzufügen:
mqtt: broker: http://homeassistant.local
Natürlich musst du http://homeassistant.local gegebenenfalls gegen deine eigenen Home Assistant URL oder die deines MQTT-Brokers austauschen.
ZigBee Reichweite verbessern
Die Reichweite von ZigBee wird durch alle “Router”-fähigen Geräte erweitert (fast alle Geräte, die an der Steckdose betrieben werden). Falls das nicht reicht, gibt es noch zusätzlich folgende Optionen:
2,4 GHz Antenne
Prinzipiell funktioniert jede, oben ist nur die, die ich benutze. Bringt etwas mehr LQI, aber vor allem funktionieren bei mir nun die Geräte mit geringem LQI deutlich zuverlässiger.
Der Aufstellungsort ist essenziell, möglichst entfernt von Störquellen und ohne Metall bzw. dicke Wände im “Weg” zu den Geräten.
Zigbee-Repeater von Ikea
Siehe hier: https://www.zigbee2mqtt.io/devices/E1746.html
ZigBee-Kanal ändern
In ZigBee2MQTT kannst du den Standard-Kanal 11 des 2,4-GHz-Bandes wechseln. Denn genau wie bei WLAN (auch 2,4 GHz), überlagern sich diese Kanäle gegenseitig und angenommen dein WLAN funkt auch auf Kanal 11, kann es zu Störungen kommen.
Generell empfehle ich immer, den Kanal eher am WLAN-Router zu ändern (also einen anderen Kanal als 11), da du, wenn du ihn in ZigBee2MQTT änderst, alle Geräte neu anlernen musst.
Falls du das trotzdem machen willst, kannst du das in den Add-on-Einstellungen (Code als YAML anzeigen) wie folgt tun:
advanced: # Optional: ZigBee channel, changing requires re-pairing of all devices. (Note: use a ZLL channel: 11, 15, 20, or 25 to avoid Problems) # (default: 11) channel: 6
Anschließend musst du noch, falls der Stick bereits angesteckt war, die Datei coordinator_backup.json löschen (Auffindbar über das File Editor Add-on)
Hinweis zu Schaltern & Dimmern
Bei manchen Geräten wie Fernbedienungen, Schaltern und Co. kann es sein, dass man für die Schalter-Aktionen Home Assistant Automationen erstellen muss.
Häufig gibt es hierfür aber bereits Blueprints (also Vorlagen für Automationen) in denen lediglich das Gerät ausgewählt werden muss und dann für jede mögliche Aktion, wie das Drücken einer Taste, eine Zeil-Entität ausgewählt werden kann 👇
Aquara Cube
Zigbee2MQTT – Xiaomi Cube Controller Blueprint
Hue Dimmer
Hue Dimmer Switch Universal Blueprint
Ikea Fernbedienung (5 Buttons)
Zigbee2Mqtt – IKEA five button remote
Erweitertes Wissen
Zigbee2MQTT Expertentipps
Du willst noch mehr in Z2M einsteigen? Hier ein Video für dich:
ZigBee Adapter wechseln, ohne Geräte neu anzulernen
Wenn du deinen ZigBee-Coordinator in Zigbee2MQTT wechseln willst oder musst, habe ich hier ein sehr ausführliches Video gemacht, das dich durch den Wechsel des Sticks begleitet.
In den meisten Fällen musst du mit dieser Variante die Geräte nicht neu anlernen, was bei großen Netzwerken ein echter Pluspunkt ist!
Hinweis zur IEEE in der coordinator_backup.json
Beim Import eines Backups kann es zu Fehlern mit ZHA kommen, wie ja auch im Video erklärt, aber zusätzlich, wenn bestimmte Werte in der JSON-Datei nicht im erwarteten Format vorliegen.
Ein Beispiel ist die “pan_id”, die in meinem Fall nur drei statt vier Hexadezimalstellen hatte (z. B. 123 anstelle von 0123).
ZHA erwartet offenbar immer die vollen 16 Bit und toleriert keine verkürzten Werte ohne führende Nullen. Falls beim Backup-Import also Fehler auftreten, sollte geprüft werden, ob Werte wie die “pan_id” oder ähnliche IDs korrekt formatiert sind. Eine führende Null (0123 statt 123) kann das Problem lösen.
Dieses Verhalten ähnelt einem bereits gemeldeten GitHub-Issue und könnte auch andere Nutzer betreffen. Falls ihr auf ähnliche Probleme stoßt, lohnt sich ein Blick in die JSON-Datei!
Adapter-Empfehlungen für einen Wechsel
Falls du bisher Probleme mit deinem Silicon Labs Chip hattest, würde ich dir (wie auch allgemein) dringend zu einem Chip von Texas Instruments (TI) raten. Diese laufen mit zStack, sind sehr zuverlässig, allgemein bewährt und auch ich persönlich hatte mit meinen TI-Adaptern seit mehr als 5 Jahren noch keinerlei Probleme.
Mögliche & empfehlenswerte Chipsätze von Texas Instruments sind CC2652P, CC2652P7 oder CC2674P10, wobei die letzten beiden im Wesentlichen modernere Versionen des CC2652P sind (+ mehr RAM).
Netzwerke mit circa 50 Geräten
Übrigens heißt “mit circa 50 Geräten” nicht, dass dein ZigBee-Netz ab 51 Geräten nicht mehr funktioniert. Aber bei 70 Geräten lohnt es sich dann schon, über ein Upgrade nachzudenken 😉
USB-Version – Sonoff ZBDongle-P
Wenn auch schon älter, mit Abstand einer der besten ZigBee-Sticks aktuell! Die IEEE-Adresse kannst du über das Tool ZigStarGW-MT ändern.
Beispiel Adapter-Konfiguration für Zigbee2MQTT (serial)
port: /dev/ttyUSB0 adapter: zstack rtscts: false
PoE-Version – SMLIGHT SLZB-06
Alternativ: AliExpress* (meistens deutlich günstiger)
Netzwerke mit 70 + Geräten
USB-Version – SMLIGHT SLZB-07P7
Ein wirklich guter Stick mit dem moderneren CC2652P7 Chipsatz (genau wie sein PoE-Bruder), der auch noch HW-Flow-Control unterstützt. Für große Netzwerke sehr zu empfehlen. Die IEEE-Adresse kannst du über das Tool ZigStarGW-MT ändern.
Beispiel Adapter-Konfiguration für Zigbee2MQTT (serial)
port: /dev/ttyUSB0 adapter: zstack rtscts: true
PoE-Version – SMLIGHT SLZB-06P7
Alternativ: AliExpress* (meistens deutlich günstiger)
Geräte für HA
Mehr Geräte für Home Assistant, HACS oder auch Alexa, Google Home, HomeKit sowie Homebridge findest du in unserem Smart Home Gerätefinder!
Hardware für Home Assistant
Dein Home Assistant ist langsam, reagiert unzuverlässig oder stürzt ab? Du hast noch gar keinen am Laufen?
Im Beitrag unten findest du empfehlenswerten Hardware & Tipps, damit dein Home Assistant so richtig gut läuft und dein Smarthome schnell wie der Blitz wird 🚀
Fazit
Wenn du also nach einer Möglichkeit suchst, deine ZigBee-Geräte mit dem Home Assistant zu steuern, oder einfach nur einen einfachen und zuverlässigen Weg suchst, all deine ZigBee-Zentralen in den Home Assistant zu vereinen, dann schau dir ZigBee2MQTT an.
Es ist schnell, quelloffen und kostenlos. Was kann man mehr verlangen?
Hallo,
ich habe einen Hinweis zur Konfiguration des Adapters im aktuellen Zigbee2MQTT: es gibt einen Bug bei Verwendung des “serial” Feldes in der Konfiguration des Addons. Wenn man das Feld verwendet, startet Z2M nicht mit der Meldung “Error: spawn udevadm ENOENT”.
Verwendet man stattdessen die Option “Als YAML bearbeiten”, und fügt den Adapter dort unter serial: ein, startet Z2M.
Das Problem hat mich locker 3 Stunden und leider auch 30€ gekostet, weil ich zwischenzeitlich auch den zuerst gekauften SonOff USB-Stick in Verdacht hatte, und daher noch einen anderen gekauft hatte.
Auch der SonOff funktioniert einwandfrei, wenn ich die Konfiguration über die YAML mache. Ich habe es auf einer 2. HA Installation gegengeprüft, auch dort tritt der Bug auf.
Ist bei mir eine ganze Weile her, dass ich Z2M integriert habe, aber ich kann mich an solche Probleme nicht erinnern. Hast du vielleicht die Einrückung nicht korrekt gesetzt? Es sollte wie hier steht gesetzt sein:
Ich bin mir allerdings nicht mehr sicher ob ich die Konfig nicht doch direkt per YAML gemacht hatte, da ich meinen bereits für ZHA genutzen Sonoff Stick übertragen wollte. Ehrlich gesagt hab ich für Z2M sogar Tage gebraucht bis es mal lief, aber trotz etwas Ärger, möchte ich Z2M und MQTT nicht mehr missen!
Ich hatte das (via Copy & Paste) exakt so wie im Artikel gesetzt, und natürlich zig Mal kontrolliert ob das genau so aussieht. Ohne Erfolg.
Dann Google Fu aktiviert, und u.A. auch mal den SonOff Stick auf die aktuelle Firmware zu flashen versucht.
Nen Aeotec Stick gekauft, und das gleiche Problem damit gehabt.
Dann das Google Fu++ aktiviert, und den entscheidenden Hinweis hier gefunden:
Ich habe drei verschiedene HA Instanzen in 3 verschiedenen Häusern/Wohnungen aufgesetzt (Rpi4/5). Zigbee2Mqtt hat immer Probleme gemacht und das Problem konnte immer gleich gelöst werden: USB 3.0 Verlängerungskabel.
Auch ein guter Hinweis mit der Verlängerung, ich hatte das schon berücksichtigt.
Ich habe auf meiner Testinstallation jetzt nochmal das Verhalten nachvollzogen:
Im Artikel fehlt tatsächlich einfach nur der Hinweis, dass man bei Verwendung des Copy Buttons die YAML Option nutzen muss. Oder halt nur den Teil nach serial: kopieren darf, wenn man direkt das Feld unter “Konfiguration” verwenden möchte.
Sonst landet nämlich ein überflüssiges serial: in der YAML, und das lässt Z2M mit der total aussagekräftigen Fehlermeldung auf die Nase fallen.