Zigbee2MQTT einrichten – Schritt-für-Schritt mit Home Assistant
Hinweis: Dieser Artikel enthält Affiliate-Links. Bei einem Kauf über diese Links erhalte ich eine kleine Provision – für dich ohne Mehrkosten. Mehr Infos
Ihr habt Home Assistant auf dem Raspberry Pi laufen und wollt jetzt endlich Zigbee-Geräte einbinden? Dann ist Zigbee2MQTT das richtige Werkzeug. Es verbindet euren Zigbee-Dongle mit Home Assistant über das MQTT-Protokoll – ohne Cloud, ohne Hersteller-App, ohne Datenschutzbedenken. Über 3.000 Geräte werden unterstützt: Lampen, Steckdosen, Sensoren, Thermostate und vieles mehr.
In diesem Guide zeige ich euch Schritt für Schritt, wie ihr Zigbee2MQTT in Home Assistant einrichtet, euren ersten Dongle verbindet und das erste Zigbee-Gerät anlernet. Am Ende habt ihr ein vollständig lokal laufendes Zigbee-Netzwerk.
Inhaltsverzeichnis
- Was ist Zigbee2MQTT?
- Was braucht ihr?
- Mosquitto Broker installieren
- Zigbee2MQTT Add-on installieren
- Serial Port des Dongles herausfinden
- Zigbee2MQTT konfigurieren
- Erstes Zigbee-Gerät anlernen
- Gerät in Home Assistant verwenden
- Troubleshooting
- FAQ
1. Was ist Zigbee2MQTT?
Zigbee ist ein Funkprotokoll, das speziell für Smart-Home-Geräte entwickelt wurde: stromsparend, zuverlässig und mesh-fähig (Geräte reichen das Signal weiter). Das Problem: Jeder Hersteller hat früher seinen eigenen Hub gebraucht. Philips Hue nur mit Philips-Bridge, IKEA Tradfri nur mit IKEA-Gateway.
Zigbee2MQTT löst dieses Problem radikal: Ein einziger USB-Dongle am Raspberry Pi empfängt das Zigbee-Signal. Die Software übersetzt es in MQTT-Nachrichten, die Home Assistant direkt versteht. Ergebnis: alle Geräte aller Hersteller in einer einzigen Oberfläche, lokal und ohne Cloud.
| Eigenschaft | Zigbee2MQTT | Hersteller-Hub |
|---|---|---|
| Gerätekompatibilität | 3.000+ Geräte aller Hersteller | Nur eigene Produkte |
| Cloud-Abhängigkeit | Keine – vollständig lokal | Meist Cloud-pflichtig |
| Kosten | Kostenlos (nur Dongle ~15–30 €) | Hub 50–100 € pro Hersteller |
| Integration in Home Assistant | Nativ via MQTT, automatisch | Meist über Umweg |
| Mesh-Netzwerk | Ja, herstellerübergreifend | Nur eigene Geräte |
2. Was braucht ihr?
Für diesen Guide benötigt ihr folgende Hardware und Software:
- Raspberry Pi mit laufendem Home Assistant OS (siehe Artikel 2)
- Zigbee-Dongle (Coordinator) – meine Empfehlung: Sonoff Zigbee 3.0 USB Dongle Plus
- USB-Verlängerungskabel (empfohlen, um Interferenzen durch den Pi zu minimieren)
Empfohlene Hardware mit Links
| Produkt | Warum empfohlen | Preis ca. | Link |
|---|---|---|---|
| Sonoff Zigbee 3.0 USB Dongle Plus (E) | Beste Reichweite, sehr stabile Firmware, top Zigbee2MQTT-Support | 20 € | Amazon |
| USB-Verlängerungskabel (30 cm) | Abstand vom Pi reduziert USB-Interferenzen, verbessert Empfang | 5 € | Amazon |
| Raspberry Pi 5 (4 GB) | Empfohlen als Basis für Home Assistant | 70 € | Amazon |
Tipp: Den Dongle unbedingt über ein USB-Verlängerungskabel anschließen, nicht direkt in den Pi stecken. Der Prozessor erzeugt elektromagnetische Interferenzen, die die Zigbee-Reichweite erheblich reduzieren können.
3. Mosquitto Broker installieren
Zigbee2MQTT kommuniziert mit Home Assistant über MQTT. Dafür braucht ihr zuerst einen MQTT-Broker – Mosquitto ist die Standardlösung und als offiziellem Home Assistant Add-on kostenlos verfügbar.
- In Home Assistant: Einstellungen → Add-ons → Add-on Store
- Sucht nach „Mosquitto broker“
- Klickt auf Installieren und wartet
- Nach der Installation: Starten aktivieren und „Beim Start starten“ einschalten
- Klickt auf Start
Wichtig: Mosquitto nutzt automatisch euren Home Assistant Benutzernamen und Passwort. Ihr müsst nichts manuell konfigurieren.
Sobald Mosquitto läuft, richtet sich die Home Assistant MQTT-Integration automatisch ein. Ihr seht eine Benachrichtigung unten links: „Es wurde eine neue MQTT-Integration entdeckt“. Klickt auf Konfigurieren und bestätigt.
4. Zigbee2MQTT Add-on installieren
Zigbee2MQTT ist nicht im offiziellen Add-on Store – ihr müsst das Repository manuell hinzufügen.
- Geht zum Add-on Store (Einstellungen → Add-ons → Store)
- Klickt oben rechts auf die drei Punkte (⋮) → Repositories
- Fügt folgende URL ein und klickt Hinzufügen:
1 | https://github.com/zigbee2mqtt/hassio-zigbee2mqtt |
- Schließt das Fenster und ladet den Store neu (Seite aktualisieren)
- Sucht nach „Zigbee2MQTT“ – es erscheinen zwei Einträge: die stabile und die Edge-Version. Wählt Zigbee2MQTT (stabil)
- Klickt auf Installieren – das dauert 1–2 Minuten
Noch nicht starten! Zuerst müsst ihr den Serial Port des Dongles herausfinden.
5. Serial Port des Dongles herausfinden
Steckt den Zigbee-Dongle (per USB-Verlängerungskabel) in den Raspberry Pi. Jetzt müsst ihr herausfinden, unter welchem Gerätepfad er erscheint.
Der zuverlässigste Weg in Home Assistant OS:
- Einstellungen → System → Hardware
- Klickt auf die drei Punkte (⋮) oben rechts → Alle Hardware
- Sucht nach eurem Dongle – beim Sonoff Dongle Plus erscheint etwas wie:
1 | /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXX-if00-port0 |
Notiert euch diesen vollständigen Pfad. Der /dev/serial/by-id/-Pfad ist stabiler als /dev/ttyUSB0, weil er sich beim Neustart nicht ändert.
Falls ihr keinen by-id-Pfad seht, ist der Dongle auch unter /dev/ttyUSB0 oder /dev/ttyACM0 erreichbar – je nach Dongle-Typ:
| Dongle | Typischer Pfad | Adapter-Typ |
|---|---|---|
| Sonoff ZBDongle-P (Plus) | ttyUSB0 | zstack |
| Sonoff ZBDongle-E | ttyACM0 | ember |
| ConBee II / III | ttyACM0 oder ttyUSB0 | deconz |
| SMLIGHT SLZB-06 | Netzwerk-Adapter (IP) | zstack |
6. Zigbee2MQTT konfigurieren
Jetzt konfiguriert ihr das Add-on mit dem Serial Port:
- Geht zur Zigbee2MQTT Add-on-Seite → Konfiguration
- Tragt folgendes ein (Serial Port anpassen):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | data_path: /config/zigbee2mqtt socat: enabled: false master: pty,raw,echo=0 slave: tcp-listen:8485,keepalive,nodelay,reuseaddr,keepidle=1,keepintvl=2,keepcnt=5 options: "-d -d" log: false zigbee2mqtt_config: homeassistant: enabled: true permit_join: false mqtt: base_topic: zigbee2mqtt server: mqtt://core-mosquitto serial: port: /dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_XXXXXXXX-if00-port0 |
Ersetzt den port-Wert mit dem Pfad, den ihr in Schritt 5 notiert habt.
- Klickt auf Speichern
- Geht auf den Tab Info → Start
- Öffnet den Tab Log – ihr solltet nach wenigen Sekunden sehen:
1 | Zigbee2MQTT:info 2026-03-20 ...: Started successfully |
Falls ihr Fehler seht, schaut in den Troubleshooting-Abschnitt.
7. Erstes Zigbee-Gerät anlernen
Mit Zigbee2MQTT habt ihr jetzt eine eigene Web-Oberfläche in der Home Assistant Seitenleiste:
- Klickt in der HA-Seitenleiste auf Zigbee2MQTT
- Oben rechts: „Permit join“ aktivieren (Zeitlimit: 255 Sekunden)
- Versetzt euer Zigbee-Gerät in den Kopplungsmodus (je nach Gerät verschieden):
- Sonoff-Geräte: Taste 5 Sekunden halten bis LED blinkt
- IKEA Tradfri: Taste neben der Birne 6 Sekunden halten
- Aqara-Sensoren: Taste kurz drücken (3–5 mal)
- Shelly BLU: Taste 10 Sekunden halten
- Das Gerät erscheint automatisch in der Geräteliste
- Klickt auf das Gerät und vergebt einen sinnvollen Namen (z.B. „Wohnzimmer Steckdose“)
- Deaktiviert „Permit join“ wieder, wenn ihr fertig seid
Tipp: Haltet das Gerät beim ersten Anlernen nah am Zigbee-Dongle (max. 1–2 Meter). Danach kann es weiter weg platziert werden.
8. Gerät in Home Assistant verwenden
Dank der MQTT Discovery-Funktion erscheint das angelernte Gerät automatisch in Home Assistant – ihr müsst nichts manuell konfigurieren.
- Einstellungen → Geräte & Dienste → MQTT
- Euer Gerät ist bereits als Entität eingetragen
- Ihr könnt es direkt im Dashboard einbinden: Übersicht → Bearbeiten → Karte hinzufügen
Von hier aus könnt ihr:
- Geräte manuell über das Dashboard steuern
- Home Assistant Automationen (z.B. Licht an bei Bewegung)
- Energieverbrauch messen (bei entsprechenden Steckdosen)
- Messwerte in Diagrammen visualisieren
Eine vollständige Anleitung zu Automationen folgt in Artikel 10 dieser Serie.
9. Troubleshooting
| Problem | Ursache | Lösung |
|---|---|---|
| „Cannot find adapter“ | Falscher Serial Port in der Konfiguration | Port in HA Hardware-Ansicht prüfen, Konfiguration anpassen |
| Gerät lässt sich nicht anlernen | Gerät zu weit weg oder Kopplungsmodus falsch | Gerät näher an Dongle bringen, Kopplungsvorgang im Handbuch prüfen |
| Add-on startet nicht | Mosquitto läuft nicht oder MQTT-Verbindung schlägt fehl | Mosquitto-Status prüfen, zuerst Mosquitto starten, dann Z2M |
| Gerät erscheint nicht in Home Assistant | MQTT Discovery deaktiviert | In Z2M-Konfiguration: homeassistant.enabled: true setzen |
| Schlechte Reichweite / Verbindungsabbrüche | Dongle direkt im Pi steckt (USB-Interferenz) | USB-Verlängerungskabel verwenden, Dongle 30–50 cm vom Pi |
| Port ändert sich nach Neustart | Verwendung von /dev/ttyUSB0 statt by-id | Immer den /dev/serial/by-id/-Pfad verwenden |
| „Error: MQTT is not connected“ | Mosquitto-Broker nicht erreichbar | Mosquitto neustarten, Server-URL auf mqtt://core-mosquitto prüfen |
10. FAQ
Brauche ich für Zigbee2MQTT zwingend Home Assistant?
Nein. Zigbee2MQTT läuft auch eigenständig auf einem Linux-System und kann mit jedem MQTT-fähigen System zusammenarbeiten (ioBroker, openHAB, Node-RED). Für diesen Guide empfehlen wir aber Home Assistant als Komplettlösung.
Was ist der Unterschied zwischen Zigbee2MQTT und ZHA?
ZHA (Zigbee Home Automation) ist die in Home Assistant eingebaute Zigbee-Lösung – einfacher einzurichten, aber mit weniger Gerätesupport und weniger Konfigurationsmöglichkeiten. Zigbee2MQTT unterstützt deutlich mehr Geräte und bietet tiefere Einstellmöglichkeiten. Wer flexibel bleiben will, greift zu Zigbee2MQTT. Einen ausführlichen Vergleich gibt es in Artikel 4.
Wie viele Zigbee-Geräte kann ich anschließen?
Ein Zigbee-Netzwerk kann bis zu 65.000 Geräte verwalten (theoretisch). Praktisch sind mit einem guten Coordinator wie dem Sonoff Dongle Plus problemlos 50–200 Geräte möglich. Jedes Gerät mit Netzbetrieb (Steckdose, Lampe) stärkt außerdem das Mesh-Netz und verbessert die Reichweite für batteriebetriebene Sensoren.
Kann ich Zigbee2MQTT und ZHA gleichzeitig betreiben?
Nein. Beide Systeme können nicht denselben Dongle gleichzeitig nutzen. Ihr müsst euch für eines entscheiden – oder zwei separate Dongles verwenden.
Funktionieren Zigbee-Geräte verschiedener Hersteller zusammen?
Ja, das ist einer der größten Vorteile von Zigbee2MQTT. Aqara-Sensoren, IKEA-Lampen, Sonoff-Steckdosen und Philips Hue Birnen können alle im selben Netzwerk laufen und gemeinsam im Mesh das Signal weitergeben.
Was tue ich, wenn mein Gerät nicht in der Geräteliste steht?
Prüft die offizielle Gerätedatenbank auf zigbee2mqtt.io. Dort sind alle 3.000+ unterstützten Geräte gelistet. Für nicht unterstützte Geräte gibt es eine Community-Option, neue Geräte über GitHub zu melden und zur Datenbank beizutragen.
