Zigbee2MQTT installieren:
jetzt bauen wir die Funkzentrale
In Folge 1 haben wir die Begriffe sortiert. Jetzt verbinden wir die vier Bausteine: Coordinator, Zigbee2MQTT, MQTT und Home Assistant. Dabei geht es noch nicht ums erste Gerät – am Ende dieser Folge soll die Infrastruktur sauber laufen.
Diese Anleitung beschreibt den bequemen Weg mit Home Assistant OS und Add-ons. Du brauchst einen funktionierenden Home-Assistant-Rechner und einen unterstützten Zigbee-Coordinator. Noch keinen ausgesucht? Dann spring erst zu unserer Coordinator-Folge.
Unser Aufbau
Der Coordinator spricht per Funk mit den Geräten. Zigbee2MQTT versteht diese Geräte. Der MQTT-Broker transportiert die Nachrichten. Home Assistant macht daraus Entitäten, Dashboards und Automationen.
Mosquitto Broker installieren
Öffne in Home Assistant Einstellungen → Add-ons → Add-on-Store und installiere Mosquitto broker. Danach starten. Für einen normalen Home-Assistant-Aufbau musst du hier nicht gleich an Ports und exotischen Optionen drehen.
Home Assistant sollte den MQTT-Dienst anschließend entdecken. Unter Einstellungen → Geräte & Dienste prüfen wir, ob MQTT eingerichtet ist.
Zigbee2MQTT installieren
Zigbee2MQTT wird in Home Assistant als Add-on betrieben. Je nach Home-Assistant-/Add-on-Stand kann dafür zunächst das Zigbee2MQTT-Repository im Add-on-Store hinzugefügt werden. Danach das Add-on Zigbee2MQTT installieren.
Wichtig: Noch nicht hektisch auf „Start“ klicken. Zuerst muss Zigbee2MQTT wissen, welchen Coordinator es verwenden soll.
USB-Stick, LAN oder PoE – watt nehmen wir?
Ohne Coordinator gibt es kein eigenes Zigbee-Netz. Dabei muss der Coordinator heute nicht mehr zwingend ein USB-Stick direkt am Home-Assistant-Rechner sein. Es gibt drei sinnvolle Wege:
direkt und günstig
Funkstandort frei wählen
LAN + Strom über ein Kabel
oft wichtiger als das Modell
USB passt gut, wenn Home Assistant selbst an einem funktechnisch guten Ort steht. Beispiele sind Home Assistant Connect ZBT-2 oder SONOFF ZBDongle-E. Bei einem Proxmox-/VM-Server im Keller oder Rack muss USB außerdem an die VM durchgereicht werden.
LAN-/PoE-Coordinatoren wie Geräte aus der SMLIGHT-SLZB-Reihe können unabhängig vom Server dort stehen, wo der Funk sinnvoll startet. Genau deshalb ist diese Bauform bei virtualisierten Installationen interessant. Für einen Netzwerk-Coordinator bevorzugen wir eine kabelgebundene Ethernet-Verbindung statt WLAN.
USB, LAN und PoE inklusive Home Assistant Connect ZBT-2, SONOFF ZBDongle-E und SMLIGHT SLZB-06 vergleichen wir ausführlich in „Felix checkt's · Folge 2: Zigbee-Koordinator – USB, LAN oder PoE?“ →. Wer noch keinen Coordinator hat, sollte diesen Vergleich lesen, bevor er hier weiter installiert.
Danach: Coordinator in Zigbee2MQTT eintragen
Bei einem USB-Adapter verwenden wir möglichst den stabilen Gerätepfad unter /dev/serial/by-id/… statt eines wechselnden Namens wie /dev/ttyUSB0. Bei einem LAN-/PoE-Coordinator wird stattdessen dessen Netzwerkverbindung eingetragen. Welche Adapter-Einstellung nötig ist, hängt vom verwendeten Coordinator und dessen Funkchip ab.
Der häufigste Anfängerfehler ist eine Beispielkonfiguration für einen anderen Coordinator. USB-Pfad, Netzwerkadresse und Adaptertyp müssen zu deinem Gerät passen.
Zigbee2MQTT mit MQTT verbinden
Zigbee2MQTT braucht die Adresse des MQTT-Brokers sowie Zugangsdaten. Beim Home-Assistant-Add-on-Aufbau liegt Mosquitto im selben System. Die konkreten Zugangsdaten gehören nicht in einen Screenshot oder öffentlichen Forenbeitrag.
mqtt: server: mqtt://core-mosquitto user: DEIN_MQTT_BENUTZER password: DEIN_PASSWORT
Das ist bewusst nur das Prinzip. Die aktuelle Zigbee2MQTT-Oberfläche kann Teile der Einrichtung über den Einrichtungsdialog abfragen.
Starten und Log lesen
Jetzt Zigbee2MQTT starten und das Protokoll öffnen. Wir wollen keine endlose rote Fehlerkette sehen, sondern drei Dinge bestätigt bekommen: Der Coordinator wurde geöffnet, die Verbindung zum MQTT-Broker steht und Zigbee2MQTT ist gestartet.
Wenn es hier scheitert, nicht schon Geräte anlernen. Erst den Grund beheben. Typische Ursachen sind falscher serieller Pfad, falscher Adaptertyp, falsche MQTT-Zugangsdaten oder ein Coordinator, den bereits eine andere Zigbee-Integration verwendet.
Home Assistant prüfen
Öffne Einstellungen → Geräte & Dienste → MQTT. Zigbee2MQTT nutzt MQTT Discovery, damit unterstützte Geräte später automatisch in Home Assistant auftauchen können. Jetzt ist noch kein Sensor nötig – entscheidend ist, dass die Kette technisch steht.
Mosquitto läuft, Zigbee2MQTT läuft ohne grundlegenden Verbindungsfehler, der Coordinator wird erkannt und MQTT ist in Home Assistant eingerichtet. Dann erst gehen wir ans Pairing.
Wenn Zigbee2MQTT nicht startet, bringt wildes Neuinstallieren meist nichts. Die letzten Logzeilen sagen fast immer, welcher der vier Bausteine nicht verbunden ist. Genau dort suchen wir.