MEINHAUSSMART DURCHSUCHEN

Was möchtest du wissen?

Tippe mindestens zwei Zeichen ein. Passende Artikel erscheinen hier direkt.

Direkt zu:Home AssistantZigbeeWLANPV
MEINHAUSSMART · ANLEITUNG

Zigbee2MQTT in Home Assistant einrichten – vom USB-Stick bis zum ersten Sensor

Richte Zigbee2MQTT mit Mosquitto auf Home Assistant OS ein. Vom USB-Koordinator bis zur ersten Entität und zur Lösung häufiger Startprobleme.

Artikel teilen
WhatsApp E-Mail

Smart-Home-Server mit USB-Zigbee-Koordinator, smarter Steckdose und Türkontakt auf einem Schreibtisch
Anleitung

Deine Anleitung im Überblick

Über die Gliederung gelangst du direkt zum gewünschten Abschnitt.

Mit Zigbee2MQTT kannst du Zigbee-Sensoren, Lampen und Taster verschiedener Hersteller über einen gemeinsamen Koordinator in Home Assistant einbinden. Diese Anleitung zeigt den konkreten Aufbau für Home Assistant OS, einen USB-Koordinator und Mosquitto. Am Ende soll ein Türkontakt sowohl in Zigbee2MQTT als auch in Home Assistant zuverlässig zwischen offen und geschlossen wechseln. Für die Wahl zwischen ZHA und Zigbee2MQTT gibt es bereits die Zigbee-Grundlagen auf MeinHausSmart.

Voraussetzungen für die Installation

Der Datenweg ist Zigbee-Gerät → USB-Koordinator → Zigbee2MQTT → MQTT-Broker → Home Assistant. Das hilft bei der Fehlersuche: Erscheint der Türkontakt schon in Zigbee2MQTT, fehlt aber in Home Assistant, hat die Funkseite ihren Teil bereits erledigt. Prüfe dann zuerst Broker, MQTT-Integration und Discovery.

1. Den Koordinator anschließen und identifizieren

Schließe den Koordinator über eine kurze USB-Verlängerung an. Abstand zu Rechnergehäuse, USB-3-Geräten und WLAN-Access-Point kann Funkstörungen reduzieren. Für Home Assistant OS in einer VM musst du das USB-Gerät zunächst dem Gast durchreichen. Im Gast sollte das Gerät unter Einstellungen → System → Hardware sichtbar sein.

Hat der Adapter einen permanenten Pfad wie /dev/serial/by-id/…, verwende diesen. Ein Name wie /dev/ttyUSB0 kann sich ändern, wenn du USB-Geräte umsteckst oder der Host sie in anderer Reihenfolge erkennt. Ein Adapter kann jeweils nur von einem Dienst verwendet werden. Für ein bestehendes ZHA-Netz nutze zum Ausprobieren einen zweiten Koordinator oder plane eine eigene Migration. Das Abschalten von ZHA macht aus dem vorhandenen Netz nicht automatisch ein Zigbee2MQTT-Netz. Adapter-Konfiguration

2. Mosquitto und die MQTT-Integration einrichten

Öffne Einstellungen → Apps → App-Store, installiere Mosquitto broker und starte die App. Danach sollte Home Assistant unter Einstellungen → Geräte & Dienste einen erkannten MQTT-Broker anbieten. Richte die MQTT-Integration ein. Falls du schon einen Broker verwendest, prüfe dessen Erreichbarkeit und verwende ihn für beide Seiten.

Für die interne Mosquitto-App ist die Broker-URL in der Regel mqtt://core-mosquitto:1883. Bei einem externen Broker nimmst du seinen tatsächlichen Hostnamen oder seine IP-Adresse sowie die dafür eingerichtete Authentifizierung. Wenn das Onboarding keine Verbindung aufbaut, kontrolliere zuerst das Broker-Protokoll. Veröffentliche keine Zugangsdaten in Screenshots und leite MQTT-Port oder Zigbee2MQTT-Oberfläche nicht ins Internet weiter. MQTT-Integration von Home Assistant · Mosquitto-App

3. Die Zigbee2MQTT-App installieren

  1. Öffne den App-Store und wähle im Menü Repositories.

  2. Füge https://github.com/zigbee2mqtt/hassio-zigbee2mqtt hinzu.

  3. Installiere die reguläre App Zigbee2MQTT. Die Variante Edge folgt der Entwicklung und ist für diesen Aufbau nicht erforderlich.

  4. Starte Zigbee2MQTT und öffne seine Weboberfläche. Wähle unter den erkannten Geräten deinen Koordinator.

  5. Prüfe Adapterpfad und Treiber. Ein SONOFF ZBDongle-P verwendet zstack. Beim ZBDongle-E kommt mit geeigneter Firmware ember zum Einsatz. Gleiche die Modellbezeichnung auf dem Gerät mit der Dokumentation ab.

  6. Gib im Onboarding die erforderlichen MQTT-Einstellungen an und aktiviere die Home-Assistant-Integration. Nach dem Speichern zeigt das Protokoll, ob Koordinator und Broker erreichbar sind. Offizielles App-Repository · Home-Assistant-Discovery in Zigbee2MQTT

Falls du die Einstellungen direkt in der Zigbee2MQTT-Konfiguration prüfst, sieht der relevante Ausschnitt für einen ZBDongle-P beispielsweise so aus. Ersetze den USB-Pfad durch den Wert deines eigenen Geräts und ergänze die Authentifizierung des Brokers dort, wo sie in deiner Installation vorgesehen ist.

mqtt:
  server: mqtt://core-mosquitto:1883
serial:
  port: /dev/serial/by-id/DEIN_KOORDINATOR
  adapter: zstack
homeassistant:
  enabled: true

Wähle den Zigbee-Kanal passend zur WLAN-Umgebung, bevor du viele Geräte koppelst. Die im Onboarding angebotene Auswahl berücksichtigt den nahen WLAN-Kanal. Vermeide spontane Kanalwechsel bei einem etablierten Netz. Je nach Gerät kann danach ein erneutes Anlernen nötig werden. Zigbee-Netzwerkparameter

4. Einen Türkontakt koppeln und die Entität prüfen

Aktiviere in Zigbee2MQTT kurz Permit join und versetze den Türkontakt gemäß Herstelleranleitung in den Kopplungsmodus. Warte, bis das Gerät vollständig erkannt ist, und schließe den Beitritt danach wieder. Vergib einen klaren Namen wie „Türkontakt Abstellraum“, bevor du ihn in Automationen einsetzt.

Öffne und schließe den Kontakt mehrmals. Prüfe zuerst den Zustand auf der Geräteseite in Zigbee2MQTT, dann die entsprechende Entität unter Einstellungen → Geräte & Dienste → MQTT in Home Assistant. Montiere den Sensor erst, wenn beide Ansichten plausibel reagieren. Teste ihn am endgültigen Standort erneut. Bei mehreren Räumen helfen kompatible, dauerhaft versorgte Zigbee-Router wie geeignete Zwischenstecker. Prüfe im Zweifel in den Geräteinformationen, welche Geräte tatsächlich routen. Geräte beitreten lassen

Wenn Zigbee2MQTT nicht startet oder Geräte fehlen

Symptom

Zuerst prüfen

Konkreter nächster Schritt

Der Koordinator wird nicht geöffnet

USB-Durchreichung, Adapterpfad, konkurrierender Dienst

Hardwareliste der VM oder von HAOS ansehen und den Pfad erneut abgleichen.

Adapter initialisiert nicht

Plattform und Firmware

Modellnummer prüfen und laut Hersteller passenden Treiber beziehungsweise Koordinator-Firmware auswählen.

MQTT verweigert die Anmeldung

Broker-Adresse, Benutzer und Broker-Protokoll

Gleichen Broker in Zigbee2MQTT und Home Assistant eintragen und Anmeldedaten abgleichen.

Der Sensor erscheint nur in Zigbee2MQTT

Discovery und MQTT-Integration

homeassistant.enabled prüfen und die MQTT-Verbindung in Home Assistant kontrollieren.

Am Zielort kommen Zustände verspätet an

Funkabstand, Router im Mesh, genutzte Kanäle

Sensor zuerst in Koordinatornähe testen und danach die Position beziehungsweise das Mesh verbessern.

Wenn der Aufbau funktioniert, prüfe nach einem kontrollierten Neustart, ob Mosquitto und Zigbee2MQTT starten und der Türkontakt wieder meldet. Sichere auch die Zigbee2MQTT-Konfiguration und die zum Adapter passenden Netzwerk-Sicherungsdaten. Welche Wiederherstellung möglich ist, hängt vom Adapter ab. Netzwerkschlüssel und Broker-Zugangsdaten gehören in eine private Sicherung. Fehlersuche bei Zigbee2MQTT

Häufige Fragen

Kann ich ZHA und Zigbee2MQTT parallel betreiben? Ja, mit getrennten Koordinatoren und getrennten Zigbee-Netzen. Einen einzelnen Koordinator solltest du jeweils nur einem Dienst zuweisen.

Brauche ich ein Hersteller-Gateway? Für direkt unterstützte Zigbee-Geräte brauchst du in diesem Aufbau einen kompatiblen Koordinator. Prüfe das exakte Gerätemodell, denn herstellerspezifische Zusatzfunktionen können sich unterscheiden.

Läuft Zigbee2MQTT im Marketplace? Auf Home Assistant OS installierst du es als App aus dem App-Store mit zusätzlichem Repository. Der Marketplace ab Home Assistant 2026.11 verwaltet dagegen Community-Projekte wie Integrationen und Dashboard-Karten.

Titelbild: KI-generierte Illustration eines möglichen Aufbaus.

Artikel teilen
WhatsApp E-Mail