Raspberry Pi Zigbee2MQTT

Passende Hardware im Überblick

Zigbee-Sticks – der Koordinator entscheidet über die Stabilität:
Sonoff Zigbee Dongle MG24 – der Preis-Leistungs-Sieger (Link)*
Home Assistant Connect ZBT-2 – der offizielle Stick mit Firmware-Pflege (Link)*
Sonoff Zigbee 3.0 Dongle Plus (CC2652P) – der bewährte Klassiker (Link)*
Sonoff ZBDongle-E – günstig, braucht aber die richtige Firmware (Link)*
Aeotec Z-Stick 10 Pro – Zigbee und Z-Wave in einem (Link)*
Sonoff Thread Dongle Lite – für Matter parallel zum Zigbee-Stick (Link)*

Der Raspberry Pi und das Nötigste drumherum:
Raspberry Pi 5 mit 8GB RAM – die Empfehlung fürs Smart Home (Link)*
Raspberry Pi 5 mit 16GB RAM – wenn noch viel dazukommen soll (Link)*
Raspberry Pi 5 mit 4GB RAM – reicht für Zigbee2MQTT locker (Link)*
Raspberry Pi 4 Starter-Set – wenn es günstig sein soll (Link)*
USB-Verlängerung gegen Funkstörungen – das wichtigste Zubehör (Link)*
Offizielles 27-W-Netzteil für den Pi 5 (Link)*
SanDisk Extreme A2 128GB – solide Speicherkarte (Link)*

Zigbee-Geräte, die das Mesh tragen:
NOUS A7Z Zigbee-Steckdose 16A – arbeitet als Repeater (Link)*
NOUS A1Z Zigbee-Steckdose 10A – die günstige Variante (Link)*
Aqara Tür- und Fenstersensoren im 3er-Pack (Link)*
Aqara FP1E Präsenzmelder – Zigbee statt WLAN (Link)*

Kurz gesagt: Was bringt Zigbee2MQTT auf dem Raspberry Pi?

Das Wichtigste zum Thema Raspberry Pi Zigbee2MQTT in sechs Punkten:

• Ein Stick statt fünf Bridges: Ein einziger USB-Koordinator am Pi spricht mit Lampen, Sensoren und Tastern aller Hersteller – Hue-Bridge, IKEA-Gateway und Aqara-Hub werden überflüssig.
• Die Firmware ist wichtiger als der Preis: Ein moderner Stick mit aktueller Koordinator-Firmware (EmberZNet 8.x bzw. Z-Stack 2022) läuft stabil, ein Uralt-Stick mit Werksstand macht Ärger.
• USB-Verlängerung ist Pflicht: Direkt am Pi steckend fängt der Stick Störungen von USB-3-Ports und WLAN ein – ein bis zwei Meter Abstand lösen die meisten Reichweitenprobleme.
• Installation per Docker: Zigbee2MQTT und der Broker Mosquitto laufen als zwei Container aus einer einzigen compose-Datei.
• Netzbetriebene Geräte sind Repeater: Jede Zigbee-Steckdose vergrößert das Mesh, Batteriegeräte tun das nicht.
• Ohne Backup wird es teuer: Die Datei coordinator_backup.json enthält das Funknetz – fehlt sie beim Stick-Tausch, müssen alle Geräte neu angelernt werden.

Raspberry Pi Zigbee2MQTT: Was die Software wirklich leistet

Zigbee2MQTT ist eine Software, die auf dem Raspberry Pi läuft und einen USB-Koordinator ansteuert. Sie übersetzt alles, was im Zigbee-Funknetz passiert, in MQTT-Nachrichten – und umgekehrt. MQTT ist eine offene, sehr einfache Sprache, die Home Assistant, Node-RED, ioBroker und jedes selbstgeschriebene Skript verstehen.

Der eigentliche Gewinn ist die Herstellerunabhängigkeit. Die Geräteliste des Projekts umfasst mehrere tausend Modelle von hunderten Herstellern – eine Hue-Lampe, ein IKEA-Taster und ein Aqara-Sensor hängen im selben Netz am selben Stick. Kein Hersteller-Konto, keine Cloud, kein Internet nötig.

Dazu kommen Funktionen, die proprietäre Bridges bewusst nicht anbieten: Firmware-Updates für die Geräte selbst, eine grafische Netzwerkkarte mit Signalstärken, direkte Bindungen zwischen Taster und Lampe (die auch dann funktionieren, wenn der Pi gerade neu startet) und der volle Rohdaten-Zugriff auf jedes Attribut, das ein Gerät sendet.

Was Zigbee2MQTT nicht ist: eine Smart-Home-Zentrale. Es liefert keine Automationen und keine schöne Bedienoberfläche für den Alltag, sondern ausschließlich die Funkanbindung. Die Logik übernimmt danach Home Assistant oder ein anderes System. Seit der Version 2.0 ist die alte Legacy-API entfernt, die Konfiguration wird beim ersten Start automatisch migriert – aktuell ist inzwischen die Serie 2.12.

Zigbee-Stick auswählen – warum die Firmware entscheidet

Der Zigbee-Koordinator ist das Bauteil, an dem die meisten Setups scheitern. Nicht weil die Sticks schlecht wären, sondern weil ab Werk oft eine veraltete Firmware aufgespielt ist. Zigbee2MQTT hat den alten ezsp-Treiber entfernt; Silabs-Sticks brauchen heute den Treiber ember und dazu passende EmberZNet-Firmware (7.4.x oder neuer). Texas-Instruments-Sticks laufen mit zstack.

Ein Punkt, der oft übersehen wird: Ein Stick kann Zigbee oder Thread, nicht beides gleichzeitig. Wer beides will, steckt zwei Sticks an den Pi. Und egal welches Modell: Der Stick gehört an eine USB-2.0-Verlängerung, mindestens einen Meter weg vom Pi, von der SSD und vom Netzteil. Berichte aus der Community zeigen, dass dieser eine Handgriff mehr Reichweite bringt als jeder Modellwechsel – USB-3-Ports und ihre Kabel strahlen breitbandig genau im 2,4-GHz-Band.

Zigbee2MQTT installieren – Schritt für Schritt

1. Stick anschließen: Über die USB-Verlängerung an einen USB-2.0-Port (die schwarzen Buchsen am Pi), nicht direkt neben eine SSD.
2. Port ermitteln: ls -l /dev/serial/by-id/ zeigt einen langen, eindeutigen Namen. Genau diesen später eintragen – /dev/ttyACM0 kann nach einem Neustart auf ein anderes Gerät zeigen.
3. Docker einrichten: Falls noch nicht geschehen, Docker installieren mit curl -sSL https://get.docker.com | sh und sudo usermod -aG docker $USER.
4. Ordner anlegen: mkdir -p ~/zigbee2mqtt/data ~/zigbee2mqtt/mosquitto/config – ein Verzeichnis für alles.
5. compose.yaml schreiben in ~/zigbee2mqtt:
   services:
     mosquitto:
       image: eclipse-mosquitto:2
       container_name: mosquitto
       restart: unless-stopped
       ports:
         - "1883:1883"
       volumes:
         - ./mosquitto/config:/mosquitto/config
         - ./mosquitto/data:/mosquitto/data
     zigbee2mqtt:
       image: ghcr.io/koenkk/zigbee2mqtt
       container_name: zigbee2mqtt
       restart: unless-stopped
       depends_on:
         - mosquitto
       ports:
         - "8080:8080"
       volumes:
         - ./data:/app/data
         - /run/udev:/run/udev:ro
       environment:
         - TZ=Europe/Berlin
       devices:
         - /dev/serial/by-id/DEIN-STICK:/dev/ttyACM0
6. Broker konfigurieren: In mosquitto/config/mosquitto.conf genügen im Heimnetz drei Zeilen: listener 1883, allow_anonymous true und persistence true.
7. Starten: docker compose up -d, danach docker compose logs -f zigbee2mqtt beobachten. Meldet der Stick sich, steht dort die Firmware-Version.
8. Weboberfläche öffnen: http://<IP-des-Pi>:8080 – hier läuft ab jetzt der gesamte Alltag. Wer die Container lieber grafisch verwaltet, nutzt zusätzlich Portainer.

Konfiguration: Serieller Port, Kanal und Netzwerkschlüssel

Die Datei data/configuration.yaml ist das Herz der Installation. Sie darf beim ersten Start schlank sein – Zigbee2MQTT ergänzt den Rest selbst:

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://mosquitto:1883
serial:
  port: /dev/ttyACM0
  adapter: ember
frontend:
  enabled: true
  port: 8080
homeassistant:
  enabled: true
advanced:
  channel: 25
  network_key: GENERATE
  pan_id: GENERATE

Der Netzwerkschlüssel wird mit GENERATE beim ersten Start einmalig erzeugt und danach im Klartext in die Datei geschrieben. Er ist die Identität des Funknetzes: Wer ihn verliert, verliert alle Geräte. Er gehört deshalb ebenso ins Backup wie die Datenbank.

Noch wichtiger ist die Kanalwahl, denn Zigbee und WLAN teilen sich das 2,4-GHz-Band. Ein WLAN-Kanal überdeckt jeweils mehrere Zigbee-Kanäle, und WLAN sendet um ein Vielfaches stärker. Der Kanal sollte vor dem Anlernen des ersten Geräts feststehen – ein späterer Wechsel bedeutet in vielen Fällen, dass Batteriegeräte nicht mitziehen und neu angelernt werden müssen.

Geräte anlernen und das Mesh richtig aufbauen

Das Anlernen läuft komplett über die Weboberfläche: Schalter „Permit join" aktivieren, das Gerät in den Kopplungsmodus bringen (meist Reset-Taste fünf Sekunden halten) und warten, bis es in der Liste auftaucht. Seit Version 2.0 gibt es die frühere Dauerfreigabe in der Konfigurationsdatei nicht mehr – das Netz bleibt also von selbst geschlossen, was gut so ist.

Entscheidend ist die Reihenfolge. Zigbee ist ein Mesh-Netz, in dem es zwei Sorten von Teilnehmern gibt: Netzbetriebene Geräte – Steckdosen, Lampen, Unterputzaktoren – arbeiten als Router und reichen Funksignale weiter. Batteriebetriebene Sensoren schlafen die meiste Zeit und leiten nichts weiter. Wer zuerst die Steckdosen anlernt und danach die Sensoren, gibt den Sensoren von Anfang an einen Router in der Nähe.

Als Faustregel gilt in der Praxis: alle fünf bis acht Meter beziehungsweise pro Etage mindestens ein Router, und Stahlbeton oder eine Fußbodenheizung zählen dabei wie zwei Wände. Die Netzwerkkarte in der Oberfläche zeigt anschließend, welches Gerät über welchen Router hängt und mit welcher Signalqualität. Geräte, die dort nur eine dünne Linie direkt zum Koordinator haben, sind die Wackelkandidaten – dort hilft eine Zigbee-Steckdose auf halbem Weg mehr als jede Konfigurationsänderung.

Home Assistant anbinden – und der Vergleich mit ZHA

Steht homeassistant: enabled: true in der Konfiguration, veröffentlicht Zigbee2MQTT für jedes Gerät eine Discovery-Nachricht. In Home Assistant muss dann nur noch die MQTT-Integration hinzugefügt und auf den Broker gezeigt werden – die Geräte erscheinen samt Entitäten von selbst, inklusive Batteriestand und Signalstärke.

Matter löst Zigbee übrigens nicht ab, sondern liegt eine Ebene höher: Die Funkschicht heißt dort Thread und funkt ebenfalls im 2,4-GHz-Band. Wer heute hunderte Zigbee-Geräte im Handel findet und eine Handvoll bezahlbarer Thread-Geräte, trifft die Entscheidung schnell – beide Netze lassen sich parallel betreiben.

Backup der Koordinator-Daten – der wichtigste Handgriff

Im Ordner data liegen drei entscheidende Dateien: configuration.yaml mit Kanal und Netzwerkschlüssel, database.db mit allen angelernten Geräten und coordinator_backup.json mit dem Zustand des Sticks selbst. Diese Sicherung schreibt Zigbee2MQTT beim sauberen Beenden – ein hartes Ausschalten des Pi kann sie also überspringen.

Der Wert zeigt sich beim Defekt oder Wechsel des Sticks: Mit den drei Dateien übernimmt ein neuer Koordinator Netzwerkschlüssel und PAN-ID, und die Geräte melden sich nach dem Start von selbst zurück. Ohne sie bleibt nur, jedes einzelne Gerät neu anzulernen – bei fünfzig Geräten ein Wochenende mit Leiter. Der Ordner gehört deshalb in jedes Raspberry-Pi-Backup.

Typische Fehler und Stolpersteine

• Stick wird nicht erkannt: Bleibt /dev/serial/by-id/ leer, liegt es fast immer am Kabel (Ladekabel ohne Datenadern) oder an einem passiven Hub. Nach jedem Umstecken muss der Container neu gestartet werden, weil der Gerätepfad beim Start fest verdrahtet wird.
• Port belegt: Auf Systemen mit Desktop greift der ModemManager gerne auf serielle Geräte zu. sudo apt purge modemmanager beendet das Thema dauerhaft.
• Falscher Treiber: adapter: ember für Silabs-Sticks, adapter: zstack für die CC2652-Familie. Ein falscher Eintrag führt zu Zeitüberschreitungen direkt beim Start.
• Geräte fallen sporadisch ab: Der Klassiker ist der Stick direkt am Pi neben einer USB-3-SSD. Verlängerung, Abstand, Signalqualität in der Netzwerkkarte prüfen.
• Kanalkonflikt mit dem WLAN: Läuft der Router auf einem automatisch wechselnden 2,4-GHz-Kanal, wandert die Störung mit. WLAN-Kanal fest einstellen und den Zigbee-Kanal danach wählen.
• Zu wenig Reichweite: Meist fehlen schlicht Router. Batteriegeräte verlängern das Netz nicht, egal wie viele es sind.
• SD-Karte am Limit: Die Datenbank wird permanent geschrieben. Für Dauerbetrieb ist eine SSD die deutlich langlebigere Basis.

Häufige Fragen zu Zigbee2MQTT auf dem Raspberry Pi

Brauche ich zwingend einen MQTT-Broker?
Ja, Zigbee2MQTT redet ausschließlich über MQTT. Mosquitto ist dafür der Standard und läuft als winziger Container problemlos auf demselben Pi mit.

Welcher Raspberry Pi reicht dafür aus?
Zigbee2MQTT allein läuft schon auf einem Pi 3 oder Pi Zero 2 W. Sobald Home Assistant, Datenbank und weitere Container dazukommen, ist ein Pi 4 oder Pi 5 mit 4 GB die vernünftige Basis.

Zigbee2MQTT oder ZHA – was ist besser?
ZHA ist in Home Assistant eingebaut und in fünf Minuten fertig. Zigbee2MQTT unterstützt mehr Geräte, bietet Firmware-Updates und läuft unabhängig von Home Assistant weiter. Ab etwa dreißig Geräten spricht viel für Zigbee2MQTT.

Funktionieren Hue-Lampen wirklich ohne Bridge?
Ja, Hue-Leuchtmittel sind normale Zigbee-Geräte und lassen sich direkt anlernen. Man verzichtet dabei auf die Hue-App und deren Szenenverwaltung, gewinnt aber die volle Kontrolle im eigenen System.

Kann ein Stick Zigbee und Thread gleichzeitig?
Nein. Die aktuellen Sticks beherrschen zwar beide Protokolle, aber nur eines davon zur selben Zeit. Für Zigbee und Matter parallel braucht es zwei Sticks – und dann bitte mit ein paar Zentimetern Abstand zueinander.

Wie viele Geräte verkraftet ein Netz?
Mit genügend Routern sind zweihundert Geräte machbar. Die praktische Grenze setzen eher die Router selbst: Jeder kann nur eine begrenzte Zahl schlafender Geräte als Kinder führen.

Was passiert bei einem Kanalwechsel?
Router und Koordinator ziehen meist mit, Batteriegeräte oft nicht. Deshalb den Kanal vor dem ersten Gerät festlegen – und wenn es später doch sein muss, vorher ein Backup ziehen.

Fazit

Die Kombination aus Raspberry Pi und Zigbee2MQTT ist die günstigste Art, ein Smart Home vom Hersteller zu befreien: Ein Stick für rund zwanzig Euro ersetzt den kompletten Bridge-Zoo, und jedes Gerät liegt danach offen auf MQTT. Unsere klare Empfehlung: Nimm einen aktuellen Stick mit EFR32MG24, hänge ihn an eine USB-Verlängerung und leg den Kanal fest, bevor das erste Gerät angelernt wird. Diese drei Entscheidungen bestimmen, ob das Netz jahrelang unauffällig läuft oder dauernd zickt. Und der vierte Punkt kostet nichts: Sichere den data-Ordner mit der coordinator_backup.json regelmäßig mit – er ist das einzige, was zwischen einem Stick-Defekt und einem Wochenende voller Anlern-Arbeit steht.

* = Affiliate Link (raspi-config.de ist Teilnehmer des Partnerprogramms von Amazon EU, das zur Bereitstellung eines Mediums für Websites konzipiert wurde, mittels dessen durch die Platzierung von Werbeanzeigen und Links zu Amazon.de Werbekostenerstattung verdient werden kann.)