✅ Du willst deine ZigBee-Geräte zuverlässig in Home Assistant steuern – lokal, herstellerunabhängig und ohne fünf verschiedene Apps und Bridges? Dann führt auch 2026 kein Weg an Zigbee2MQTT vorbei. In diesem Beitrag richten wir Zigbee2MQTT komplett neu ein: vom richtigen Stick über Mosquitto bis zum ersten angelernten Gerät.
Zigbee2MQTT (Z2M) macht aus der Komplexität eines ZigBee-Funknetzes etwas Universelles: Es nimmt dein ZigBee-Netz und macht es über einen MQTT-Broker (Mosquitto) in Home Assistant steuerbar. Das Ganze ist Open Source, kostenlos, extrem schnell 🚀 und unterstützt unglaublich viele Geräte.
Seit meinem ersten Video von 2022 hat sich allerdings einiges geändert: Die Oberfläche wurde komplett überarbeitet, es gibt einen neuen Onboarding-Assistenten – und meine Stick-Empfehlung von damals ist heute nicht mehr meine erste Wahl. Alles Aktuelle findest du hier im Beitrag 🙌
Falls du prüfen willst, ob dein ZigBee-Gerät mit Zigbee2MQTT kompatibel ist oder wissen möchtest, wie du den Pairing-Modus aktivieren kannst, kannst du auf der offiziellen Seite nachschauen. Aktuell werden dort über 1900 Geräte gelistet – inklusive aller Funktionen, die pro Gerät verfügbar sind („Exposes“).
Alternativ findest du meine Empfehlungen direkt hier im Gerätefinder.
Inhaltsverzeichnis
- Voraussetzungen
- Benutzte Repos / Links
- Zigbee2MQTT oder ZHA?
- Der richtige ZigBee-Stick (2026)
- Einrichtung: Mosquitto installieren
- Zigbee2MQTT installieren
- Der Onboarding-Assistent
- ZigBee-Geräte anlernen
- Die wichtigsten Zigbee2MQTT-Einstellungen
- Manuelle Konfiguration (wenn der Onboarding-Assistent nicht will)
- Fehlerbehebung
- ZigBee Reichweite verbessern
- Hinweis zu Schaltern & Dimmern
- Erweitertes Wissen
- Geräte für HA
- Hardware für Home Assistant
- Fazit
Voraussetzungen
- Ein laufendes Home Assistant OS, z.B. auf dem Raspberry Pi
- Ein ZigBee-Stick (Empfehlungen direkt hier unten 👇)
- Eine USB-Verlängerung (kein Scherz – dazu später mehr)
Benutzte Repos / Links
- www.zigbee2mqtt.io (die Doku ist wirklich sehr gut!)
- Empfohlene Adapter
- Mosquitto (MQTT Broker)
- Link für die Add-on Repository:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt - Sonoff Dongle Flasher (Firmware-Updates für alle Sonoff-Sticks, auch als Home Assistant Add-on)
Zigbee2MQTT oder ZHA?
Meine Empfehlung hat sich hier über die Jahre geändert – Stand heute ist sie klar: Nimm gleich Zigbee2MQTT und spar dir den Umweg. ZHA hängt bei der Geräteunterstützung bis heute hinterher, gerade bei den exotischeren Sensoren: Zigbee2MQTT unterstützt aktuell über 1900 Geräte, ZHA nur rund 800. Dazu bekommst du in Z2M oft mehr Funktionen pro Gerät und mächtigere Werkzeuge (Netzwerk-Karte, OTA-Updates, feinere Einstellungen).
Und Matter bzw. Thread? Matter-Geräte sind meist teurer, viele Gerätetypen gibt es schlicht nur mit ZigBee. Außerdem ist ZigBee ebenfalls ein Mesh-Netzwerk – es erweitert sich also selbst mit jedem strombetriebenen Gerät und hat den Test der Zeit längst bestanden. Ich sage nicht, dass Thread oder Matter schlecht sind. Aber mit ZigBee bekommst du dieselben Vorteile günstiger. Und wenn du Home Assistant nutzt, brauchst du Matter eigentlich ohnehin nicht – du hast ja alle Geräte zentral in Home Assistant und kannst sie von dort z.B. per Matter an Google Home oder Alexa weitergeben.
Der richtige ZigBee-Stick (2026)
Hier hat sich seit meinem ersten Video aus 2022 am meisten getan. Damals war die einzige offizielle Empfehlung ein Stick mit Z-Stack-Chipsatz (Texas Instruments) – heute sind die EmberZNet-basierten Adapter (Silicon Labs) offiziell unterstützt, weit verbreitet und bringen in Firmware und Treiber einige Vorteile mit, die du später vielleicht brauchen wirst. Mit dem Z-Stack-Treiber gibt es unter Umständen Probleme, die ich selbst auch schon hatte.
Wichtig: Musst du dir jetzt einen neuen Stick kaufen? Ganz sicher nicht – außer du hast Probleme! Wenn dein alter Stick sauber läuft, lass ihn laufen. Aber wenn du neu anfängst, würde ich dir dringend einen EmberZNet-basierten Stick empfehlen 👇
Meine Go-to-Empfehlung: Sonoff Dongle MG24
Der Sonoff ZigBee 3.0 USB-Dongle MG24 ist meine universelle Empfehlung für alle, die heute mit Zigbee2MQTT starten – moderner EFR32MG24-Chipsatz, offiziell unterstützt und preislich fair.
Alternativen
Sonoff ZBDongle-E (V2): Kannst du nehmen, wenn du ihn günstig schießen kannst – meine erste Wahl ist er aber nicht mehr.
Home Assistant Connect ZBT-2: Die offizielle Hardware funktioniert ebenfalls sehr gut – ist allerdings deutlich teurer und hat den gleichen Chipsatz wie der MG24. Ich würde eher zum MG24 greifen.
Wenn Du es Dir leisten kannst, hat der Home Assistant Connect zusätzlich den Vorteil, dass Du die Firmware direkt in Home Assistant aktualisieren kannst, ohne externes Tool, und natürlich unterstützt Du damit auch die Entwicklung von Home Assistant direkt.
Sonoff ZBDongle-P (meine 2022er-Empfehlung): Läuft bei vielen (auch bei mir) seit Jahren stabil. Wer ihn hat und keine Probleme hat, muss nicht wechseln – für einen Neukauf ist er aber nicht mehr meine Empfehlung.
Noch mehr Auswahl findest du bei den Funk-Sticks im Geräte-Finder.
USB-Verlängerung ist Pflicht!
Schließe deinen ZigBee-Stick immer über eine USB-Verlängerung an – egal ob USB-2.0- oder 3.0-Port. Direkt am Gerät stören USB-3.0-Ports und andere Elektronik den 2,4-GHz-Empfang massiv. Das ist der wichtigste Einzeltipp in diesem ganzen Beitrag.
Übrigens: Die Antennen der Sticks sind Rundstrahlantennen. Das ZigBee-Netz wird ringförmig um die Antenne herum abgestrahlt – richte die Antenne also möglichst senkrecht nach oben aus, statt sie irgendwo hin zu legen. Wenn du deine Stick relativ nah an der Decke montierst, also ab circa 2 Meter, würde ich sie eher nach unten als nach oben ausrichten.
PoE-/Netzwerk-Sticks: nur wenn es nicht anders geht
PoE-Sticks sind dann sinnvoll, wenn dein Stick weiter weg vom Server sein muss – etwa weil der Server im Keller steht und du dort mit USB-Verlängerung schlicht keinen Empfang hättest. Aber ganz ehrlich: Das wäre immer meine letzte Empfehlung, weil du dir mit dem Netzwerk (Switch, Kabel, Router, IP-Adressen) eine zusätzliche Fehlerquelle in die Kette holst. Ein USB-Stick ist immer zu bevorzugen.
Ich habe einige PoE-Sticks durchprobiert – richtig zuverlässig lief bei mir ehrlich gesagt nur einer: der Sonoff Dongle Max. Der lief bei mir sowohl für ZigBee als auch für Thread sauber.
Dongle Max: So läuft er wirklich zuverlässig
Der Dongle Max hat bei der Ersteinrichtung ein paar, sagen wir mal, Eigenheiten. Wenn du diese Schritte in genau dieser Reihenfolge machst, erspart dir das die Fehlersuche (z.B. den Fehler zh:ember:uart:ash: Port Error: read ECONNRESET, wenn sich schon etwas anderes den Stick geschnappt hat):
- Dongle anstecken
- Passwort vergeben
- Falls danach irgendwas nicht funktionieren sollte:
- Einfach die Werkseinstellungen zurücksetzen (Taste auf Gehäuse ~10 Sekunden gedrückt halten)
- dann nochmal ein Kennwort vergeben
- Dann klappt es meistens 😅
- Firmware über die Web-Oberfläche des Dongles aktualisieren (im Coordinator-Modus, und dieser Modus muss aktiv sein)
- Danach direkt einmal auf Werkseinstellungen zurücksetzen (Taste auf Gehäuse ~10 Sekunden gedrückt halten)
- Das Kennwort in der Web-Oberfläche neu vergeben
- Die ZHA-Integration in Home Assistant ignorieren
- In der Web-Oberfläche des Sticks unter
Sicherheit -> IP Whitelistdie erlaubten Verbindungs-IPs auf deine Home-Assistant-Instanz beschränken (der Dongle nimmt nur EINE Verbindung an!) - Den Home-Assistant-Host neu starten
- Erst danach den Dongle in Zigbee2MQTT einrichten
Kleiner Check vorab: Die Statusanzeige oben rechts in der Web-Oberfläche des Dongles darf nicht „Zigbee2MQTT verbunden“ anzeigen, solange Zigbee2MQTT noch gar nicht läuft – sonst blockiert bereits eine andere Verbindung den Stick.
📖 Alles zu PoE-Sticks, den Eigenheiten des Dongle Max und wie du deinen Stick wechselst, hoffentlich ohne Geräte neu anzulernen: ZigBee-Stick wechseln in Zigbee2MQTT
Einrichtung: Mosquitto installieren
Zigbee2MQTT heißt Zigbee2MQTT – wir brauchen also zuerst einen MQTT-Broker. Dafür nutzen wir das Mosquitto-Add-on:
Einstellungen → Apps → App installieren→ Mosquitto broker suchen und installieren- Add-on einfach starten – du musst hier nichts konfigurieren!
Einstellungen → Geräte & Dienste→ die automatisch gefundene MQTT-Integration hinzufügen (falls sie nicht auftaucht: Integration hinzufügen → MQTT)
Wichtig, falls du alte Anleitungen kennst: Du musst keinen Benutzer mehr anlegen und nichts an der Konfiguration anpassen. Das stimmt alles nicht mehr – Add-on installieren, starten, Integration hinzufügen, fertig.
📹 Mehr zu MQTT im Video: https://www.youtube.com/watch?v=6dakzuffues
Zigbee2MQTT installieren
Einstellungen → Apps → App installieren → ⋮ (drei Punkte oben rechts) → Repositories- Folgende URL hinzufügen 👉
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt - Danach nach Zigbee2MQTT suchen und das normale Zigbee2MQTT-Add-on installieren
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt
Anders als früher musst du hier erstmal nichts konfigurieren – Zigbee2MQTT findet und konfiguriert die meisten Adapter heute automatisch über den Onboarding-Assistenten. Bevor wir den starten, machen wir aber noch drei Dinge, die dir später Ärger ersparen.
1. Firmware-Update für den Stick (Sonoff Dongle Flasher)
Wenn wir schon dabei sind, bringen wir den Stick direkt auf den aktuellen Firmware-Stand. Für alle USB Sonoff-Sticks gibt es den Sonoff Dongle Flasher – entweder direkt im Browser oder als Home Assistant Add-on (Link zur Add-on-Repository findest du unten auf der Flasher-Seite; die Repository fügst du genauso hinzu wie eben bei Zigbee2MQTT).
- Add-on installieren, in der Seitenleiste anzeigen und starten
Connect→ der Stick (z.B. MG24) wird erkannt →Confirm- Aktuelle Firmware auswählen und
Flash– davon geht nichts kaputt, und der RAM des Chips wird dabei zurückgesetzt (auch das ist gut so) - Danach das Flasher-Add-on wieder stoppen und Auto-Start rausnehmen (installiert lassen schadet nicht)
2. ZHA-Integration ignorieren (wichtig!)
Unter Einstellungen → Geräte & Dienste wird dein Stick sehr wahrscheinlich von der ZigBee Home Automation (ZHA)-Integration automatisch entdeckt. Das kann den Zugriff auf den Stick blockieren!
Wenn du Zigbee2MQTT nutzen willst: Die entdeckte ZHA-Integration unbedingt auf „Ignorieren“ setzen – NICHT einrichten!
3. Host einmal komplett neu starten
Optional, aber ich empfehle es: Einstellungen → System → Hardware/Entwicklerwerkzeuge → Erweiterte Optionen → System neu starten.
Damit ist sichergestellt, dass wirklich kein Prozess mehr den Stick blockiert – gerade nach Firmware-Update und ZHA-Ignorieren der sauberste Weg, der in 99 % der Fälle funktioniert.
Der Onboarding-Assistent
Jetzt startest du das Zigbee2MQTT-Add-on (Seitenleiste anzeigen, Watchdog an – automatische Updates sind Geschmackssache, ich lasse sie aus und schaue vorher in die Release Notes) und öffnest die Oberfläche. Dich begrüßt der neue Onboarding-Assistent:
- Bei den gefundenen Geräten deinen Stick auswählen (z.B. Sonoff Dongle MG24) – alles Weitere wird automatisch konfiguriert
- PAN-ID, Extended PAN-ID und Network Key werden automatisch generiert – so lassen!
- Funk-Kanal: Wenn dein WLAN-Router auf einem festen Kanal funkt und nah am ZigBee-Stick steht, wähle diesen WLAN-Kanal im Assistenten aus – Zigbee2MQTT schlägt dir dann den passenden ZigBee-Kanal vor. Falls du keinen festen WLAN-Kanal gesetzt hast: unter
Advancedden Kanal 25 wählen – der überschneidet sich am wenigsten mit WLAN-Netzen Submit→ Zigbee2MQTT übernimmt die Werte und startet neu. Falls die Oberfläche danach hängt, einfach in der Seitenleiste nochmal auf Zigbee2MQTT klicken
📹 Mehr zu Funk-Interferenzen & Kanaloptimierung im Video: https://www.youtube.com/watch?v=SESZqOxCQfs
ZigBee-Geräte anlernen
Das Anlernen läuft immer nach demselben Muster – und geht am bequemsten am Smartphone, weil du beim Einrichten sowieso am Gerät stehst:
- In der Zigbee2MQTT-Oberfläche im Menü „Beitritt erlauben“ aktivieren (gilt dann für 5 Minuten)
- Das Gerät in den Anlern-Modus versetzen – meist einen Knopf gedrückt halten, bis es blinkt; bei Batterie-Geräten manchmal Batterie kurz raus oder mit einer Büroklammer die Reset-Taste drücken
- Das Gerät taucht in Zigbee2MQTT auf → direkt umbenennen (dazu gleich mehr)
- Bei den Expose-Funktionen siehst du alles, was das Gerät kann – vom Schalten über Countdown-Timer bis zu gerätespezifischen Einstellungen wie Power Outage Memory oder Kindersicherung
Kleiner Stolperstein in der neuen Oberfläche: Ein Klick auf die Karte eines Geräts öffnet nur eine Schnell-Vorschau. Für die richtige Einstellungsseite musst du auf den unterstrichenen Gerätenamen klicken.
Batteriebetriebene Geräte: dort anlernen, wo sie hin sollen
ZigBee ist ein Mesh-Netzwerk: Jedes strombetriebene Gerät (Steckdosen, Lampen …) erweitert das Netz als Router. Batteriebetriebene Geräte funken über den nächstgelegenen Router – und manche Geräte sind schlecht darin, diesen Partner später zu wechseln. Vor allem alte Geräte der Firma Aqara sind dafür bekannt. Es gibt aber auch noch einige andere Kandidaten, wenn auch weniger weit verbreitet.
Trotzdem deshalb meine Empfehlung: Batterie-Geräte am besten direkt dort anlernen, wo sie später eingesetzt werden.
Geräte mit Dual-Protokoll (ZigBee + Thread)
Immer mehr Geräte – z.B. neuere Aqara-Sensoren und -Schalter – unterstützen ZigBee und Thread. Über ZigBee bieten sie meist deutlich mehr Funktionen als über Thread/Matter. Der Haken: Du musst sie oft erst in den ZigBee-Modus schalten, und das geht nur über die App des Herstellers:
- Gerät in der Hersteller-App (z.B. Aqara) als neues Gerät suchen – einen Hub brauchst du dafür nicht
- Beim Einrichten ZigBee statt Thread wählen – die App überträgt bei Aqara beispielsweise die ZigBee-Firmware per Bluetooth aufs Gerät
- Die Einrichtung in der Hersteller-App dann abbrechen (wir wollen ja nicht zum Hersteller-Hub) und das Gerät ganz normal über „Beitritt erlauben“ in Zigbee2MQTT anlernen
Umbenennen: immer in Zigbee2MQTT, nicht in Home Assistant
Benenne deine Geräte in Zigbee2MQTT um (inkl. Haken bei „Home Assistant Entity ID aktualisieren“) – nicht in Home Assistant. Falls ein Gerät mal neu erstellt wird, heißt es sonst wieder so wie in Zigbee2MQTT, und deine Home-Assistant-Namen sind futsch. Die Geräte findest du in Home Assistant übrigens unter Einstellungen → Geräte & Dienste → MQTT.
Die wichtigsten Zigbee2MQTT-Einstellungen
In der Zigbee2MQTT-Oberfläche unter Einstellungen würde ich dir für den Anfang genau diese Anpassungen empfehlen – den Rest kannst du lassen, wie er ist:
- Verfügbarkeit: aktivieren (Timeout-Werte so lassen) – damit siehst du, ob Geräte offline sind
- Home Assistant Integration → Legacy Action Sensor: aktivieren – viele Blueprints und Automationen verlassen sich auf diesen Aktions-Sensor
- Erweitert → Last Seen: auf
ISO_8601_localstellen – damit siehst du pro Gerät, wann es zuletzt aktiv war - Adapter Concurrency / Delay: auf keinen Fall ändern (außer du weißt wirklich, was du tust)
Gut zu wissen: Unter Werkzeuge kannst du ein Zigbee2MQTT-Backup anfordern (bei einem vollen Home-Assistant-Backup ist Z2M aber sowieso dabei). Der Systemzustand zeigt dir, ob ein Gerät ungewöhnlich viele Nachrichten pro Sekunde sendet und damit dein Netzwerk stört. Und in den Logs kannst du das Log-Level anpassen – eine gute Anlaufstelle, wenn du beim Debuggen etwas an eine KI weitergeben willst. Unter Netzwerk gibt es außerdem eine Karte deines ZigBee-Mesh.
Achtung beim ZigBee-Kanal: Den kannst du unter Erweitert zwar jederzeit ändern – aber danach musst du die meisten Geräte neu anlernen. Also: einmal am Anfang richtig setzen (siehe Onboarding-Assistent) und dann in Ruhe lassen.
Manuelle Konfiguration (wenn der Onboarding-Assistent nicht will)
Bei den Sonoff-USB-Sticks sollte der Onboarding-Assistent eigentlich immer funktionieren. Bei PoE-Sticks (und exotischerer Hardware) kann es aber sein, dass du manuell ran musst. Der Weg: Einstellungen → Apps → Zigbee2MQTT → Konfiguration – entscheidend sind die Serial-Einstellungen.
Die passenden Parameter für deinen Stick findest du in der Zigbee2MQTT-Doku auf der jeweiligen Adapter-Seite. Zwei Stolpersteine aus der Praxis:
- RTS/CTS heißt in der Add-on-Oberfläche nicht so – das ist der unscheinbare Toggle unten (an = true, aus = false)
- Beim MG24 sagt die Doku sinngemäß „stellt sicher, dass Software-Flow-Control nicht auf true ist“ – heißt also: auf false stellen
Beispiel-Konfiguration für den Sonoff Dongle MG24, wenn du dir die Konfiguration von der Z2M App als YAML anzeigen lässt (oben rechts in der Ecke geht das):
serial: port: /dev/ttyUSB0 adapter: ember rtscts: false
Wenn du den Assistenten übersprungen hast, solltest du zusätzlich bei den optionalen Konfigurationsparametern das Force-Onboarding ausschalten – sonst begrüßt dich der Assistent trotzdem wieder. Danach speichern, starten und die Netzwerk-Settings festlegen. Aber wie gesagt: Wenn der Onboarding-Assistent läuft, nutz ihn einfach.
Den Port herausfinden
Am einfachsten über Einstellungen → System → Hardware: Dort findest du unter der System-Hardware deinen Stick, und bei den DevLinks den Eintrag /dev/serial/by-id/… – den obersten Link kopieren und als Port eintragen.
Alternative über SSH
- 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
PoE-Dongles manuell einrichten
PoE-Sticks haben eine eigene Web-Oberfläche, über die du auch die Firmware aktualisierst. Dort findest du für Zigbee2MQTT (und ZHA) die fertigen Verbindungsparameter – meist unter „TCP Connection“. Diese Werte kannst du 1:1 in die Serial-Einstellungen von Zigbee2MQTT kopieren, der Port sieht dann z.B. so aus: tcp://IP.des.Dongles:PORT.
Alternative Addon-Konfigurationen (ältere Hardware)
Hier noch Konfigurationen für weitere Hardware – teils Feedback aus der Community, vielen Dank an euch alle 🙌
Sonoff ZBDongle-P (die 2022er-Empfehlung)
serial: port: /dev/ttyUSB0 adapter: zstack rtscts: false
Sonoff ZBDongle-E (V2)
serial: port: /dev/ttyUSB0 adapter: ember
ConBee / ConBee II / RaspBee / RaspBee II (NICHT EMPFOHLEN)
Ü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 / Connect ZBT-1 (NICHT MEHR EMPFOHLEN)
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, in dem 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 (Einstellungen → Geräte & Dienste) 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 ZigBee-Kanal im 2,4-GHz-Band wechseln. Denn genau wie bei WLAN (auch 2,4 GHz) überlagern sich diese Kanäle gegenseitig – funkt dein WLAN auf demselben Kanal, kann es zu Störungen kommen. Meine Empfehlung: Kanal 25, der überschneidet sich am wenigsten mit WLAN.
Aber Achtung: Wenn du den Kanal in Zigbee2MQTT nachträglich änderst, musst du alle Geräte neu anlernen. Deshalb den Kanal am besten direkt im Onboarding-Assistenten richtig setzen – oder alternativ eher den Kanal am WLAN-Router ändern.
Falls du es trotzdem machen willst, geht das in den Zigbee2MQTT-Einstellungen unter Erweitert oder in der Add-on-Konfiguration (Code als YAML anzeigen):
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: 25
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)
📹 Mehr zu Interferenzen & Kanaloptimierung im Video: https://www.youtube.com/watch?v=SESZqOxCQfs
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 👇
Wichtig: Viele dieser Blueprints verlassen sich auf den Legacy Action Sensor – den solltest du in den Zigbee2MQTT-Einstellungen aktiviert haben (siehe oben bei den wichtigsten Einstellungen).
Aqara 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 – zum Beispiel vom alten ZBDongle-P auf den MG24 – geht das heute erstaunlich unkompliziert und ohne die Geräte neu anzulernen. Zigbee2MQTT hat mittlerweile Mechanismen, die das Netzwerk beim Stickwechsel automatisch auf den neuen Coordinator „umbiegen“ (unterstützt für Silicon Labs und Texas Instruments). Die IEEE-Adresse musst du dafür nicht mehr ändern.
📖 Ausführliche Anleitung inkl. aller Stolpersteine: ZigBee-Stick wechseln in Zigbee2MQTT – Netzwerk migrieren ohne Neuanlernen
Hier begleitet dich außerdem ein ausführliches Video durch den Wechsel des Sticks:
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!
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 deine ZigBee-Geräte zuverlässig, lokal und herstellerunabhängig in Home Assistant haben willst, ist Zigbee2MQTT auch 2026 die beste Wahl – über 1900 unterstützte Geräte, keine Bridge-Sammlung, keine fünf Apps. Und dank des neuen Onboarding-Assistenten war die Einrichtung noch nie so einfach wie heute.
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.