Zigbee2MQTT auf dem Raspberry Pi installieren – Schritt-für-Schritt-Anleitung für Einsteiger

Wer sein Smart Home mit Zigbee-Geräten aufbauen möchte, kommt früher oder später an Zigbee2MQTT nicht vorbei. Die Open-Source-Software verbindet Zigbee-Hardware direkt mit Home Assistant – ohne Cloud, ohne Hersteller-App, ohne Datenschutzbedenken. In dieser Anleitung zeige ich dir Schritt für Schritt, wie du Zigbee2MQTT auf einem Raspberry Pi installierst und deine ersten Geräte einbindest.

Was ist Zigbee2MQTT überhaupt?

Zigbee2MQTT ist eine Software-Brücke, die Zigbee-Funksignale über einen USB-Koordinator empfängt und als MQTT-Nachrichten weiterleitet. Home Assistant kann diese Nachrichten dann verarbeiten und die Geräte als Entitäten einbinden. Das Schöne daran: Zigbee2MQTT unterstützt über 3.000 verschiedene Zigbee-Geräte von Hunderten Herstellern – von IKEA über Philips Hue bis hin zu günstigen No-Name-Sensoren aus Fernost.

Der große Vorteil gegenüber der Hue Bridge oder anderen proprietären Gateways: Alles läuft lokal. Kein Internet nötig, keine monatlichen Gebühren, keine Server die abgeschaltet werden.

Was du vor der Installation brauchst

Bevor wir starten, stelle sicher, dass folgende Dinge vorhanden sind:

• Raspberry Pi (ab Pi 3B aufwärts empfohlen) mit Raspberry Pi OS oder Ubuntu Server
• Zigbee USB-Koordinator – z.B. Sonoff Zigbee 3.0 USB Dongle Plus oder ConBee II
• MQTT Broker – am einfachsten Mosquitto, läuft ebenfalls auf dem Pi
• SSH-Zugang zum Raspberry Pi oder direkte Tastatur/Monitor-Verbindung
• Home Assistant (als separate Installation oder auf demselben Pi)

Schritt 1: MQTT Broker Mosquitto installieren

Zigbee2MQTT kommuniziert über das MQTT-Protokoll. Deshalb brauchen wir zuerst einen MQTT-Broker. Mosquitto ist die einfachste und zuverlässigste Wahl.

Verbinde dich per SSH mit deinem Pi und führe folgende Befehle aus:

sudo apt update
sudo apt install -y mosquitto mosquitto-clients
sudo systemctl enable mosquitto
sudo systemctl start mosquitto

Anschließend legen wir einen Benutzer für die MQTT-Verbindung an. Ersetze deinbenutzername durch einen Namen deiner Wahl:

sudo mosquitto_passwd -c /etc/mosquitto/passwd deinbenutzername

Du wirst nach einem Passwort gefragt. Merke dir beides – du brauchst es später für die Zigbee2MQTT-Konfiguration.

Jetzt passen wir die Mosquitto-Konfiguration an:

sudo nano /etc/mosquitto/mosquitto.conf

Füge am Ende der Datei folgende Zeilen ein:

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

Speichern mit Strg+O, beenden mit Strg+X. Dann Mosquitto neu starten:

sudo systemctl restart mosquitto

Schritt 2: Zigbee USB-Koordinator einstecken und identifizieren

Stecke den Zigbee USB-Stick in einen freien USB-Port des Raspberry Pi. Dann prüfen wir, unter welchem Gerätepfad er erkannt wird:

ls /dev/serial/by-id/

Du siehst einen Eintrag wie usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_.... Notiere dir diesen vollständigen Pfad – er sieht in etwa so aus:

/dev/serial/by-id/usb-ITead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_...

Diesen Pfad verwenden wir in der Konfiguration. Er ist stabiler als /dev/ttyUSB0, da er sich beim Neustart nicht verändert.

Schritt 3: Node.js installieren

Zigbee2MQTT läuft auf Node.js. Wir installieren die aktuelle LTS-Version:

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Version prüfen:

node --version

Es sollte v20.x.x oder höher ausgegeben werden.

Schritt 4: Zigbee2MQTT installieren

Jetzt geht es ans Eingemachte. Wir legen das Verzeichnis an und klonen Zigbee2MQTT:

sudo mkdir /opt/zigbee2mqtt
sudo chown -R ${USER}: /opt/zigbee2mqtt
git clone --depth 1 https://github.com/Koenkk/zigbee2mqtt.git /opt/zigbee2mqtt
cd /opt/zigbee2mqtt
npm ci

Der npm ci-Befehl installiert alle Abhängigkeiten. Das kann je nach Pi-Modell ein paar Minuten dauern – einfach abwarten.

Schritt 5: Zigbee2MQTT konfigurieren

Jetzt erstellen wir die Konfigurationsdatei:

nano /opt/zigbee2mqtt/data/configuration.yaml

Füge folgenden Inhalt ein und passe die markierten Stellen an:

homeassistant:
  enabled: true

mqtt:
  base_topic: zigbee2mqtt
  server: mqtt://localhost
  user: deinbenutzername
  password: deinpasswort

serial:
  port: /dev/serial/by-id/DEIN-KOORDINATOR-PFAD

frontend:
  enabled: true
  port: 8080

Ersetze deinbenutzername, deinpasswort und den Koordinator-Pfad mit deinen tatsächlichen Werten. Das Frontend auf Port 8080 ermöglicht dir später die bequeme Verwaltung über den Browser.

Schritt 6: Zigbee2MQTT als Systemdienst einrichten

Damit Zigbee2MQTT automatisch beim Booten startet, richten wir einen Systemd-Dienst ein:

sudo nano /etc/systemd/system/zigbee2mqtt.service

Inhalt der Datei:

[Unit]
Description=zigbee2mqtt
After=network.target

[Service]
Environment=NODE_ENV=production
Type=notify
ExecStart=/usr/bin/node index.js
WorkingDirectory=/opt/zigbee2mqtt
StandardOutput=inherit
StandardError=inherit
WatchdogSec=10s
Restart=always
RestartSec=10s
User=pi

[Install]
WantedBy=multi-user.target

Falls dein Benutzername nicht pi ist, passe die User=-Zeile entsprechend an. Dann den Dienst aktivieren und starten:

sudo systemctl enable zigbee2mqtt
sudo systemctl start zigbee2mqtt

Status prüfen:

sudo systemctl status zigbee2mqtt

Wenn alles korrekt eingerichtet ist, siehst du Active: active (running) in der Ausgabe.

Schritt 7: Erste Zigbee-Geräte anlernen

Öffne jetzt den Browser und rufe die Zigbee2MQTT-Weboberfläche auf:

http://IP-DES-PI:8080

Du siehst das Zigbee2MQTT-Frontend. Oben rechts findest du den Button „Gerät anlernen“ (Permit join). Klicke darauf – jetzt hast du 254 Sekunden Zeit, ein Zigbee-Gerät in den Pairing-Modus zu versetzen.

Geräte in den Pairing-Modus versetzen

Das funktioniert bei den meisten Geräten so:

• IKEA Trådfri Lampen: 6x schnell hintereinander ein- und ausschalten
• Aqara/Xiaomi Sensoren: Button 5x schnell drücken bis LED blinkt
• Sonoff ZBMINI: Button 5 Sekunden gedrückt halten
• Philips Hue Lampen: In der Hue App aus dem Netzwerk entfernen, dann anlernen

Sobald das Gerät erkannt wird, erscheint es in der Geräteliste des Frontends. Zigbee2MQTT vergibt automatisch einen Namen und sendet die Gerätedaten per MQTT an Home Assistant.

Zigbee2MQTT in Home Assistant einbinden

Wenn du Home Assistant mit aktivierter MQTT-Integration betreibst, tauchen die Zigbee-Geräte nach dem Anlernen automatisch als neue Entitäten auf. Home Assistant erkennt sie über die MQTT Discovery-Funktion, die wir in der Konfigurationsdatei mit homeassistant: enabled: true aktiviert haben.

Gehe in Home Assistant zu Einstellungen → Integrationen und prüfe, ob neue Geräte zur Einrichtung bereitstehen. Bei einer frischen MQTT-Integration musst du außerdem unter Einstellungen → Integrationen → MQTT die Verbindungsdaten zu deinem Mosquitto-Broker eingeben.

Tipps für einen stabilen Betrieb

• USB-Verlängerungskabel verwenden: Der Koordinator sollte möglichst weit vom Pi entfernt sein, um Interferenzen durch USB 3.0 zu vermeiden
• Zigbee-Mesh aufbauen: Steckdosen und andere dauerhaft stromversorgte Geräte fungieren als Router und vergrößern die Reichweite
• Firmware aktuell halten: Für Sonoff Dongles gibt es regelmäßige Firmware-Updates, die Stabilität und Kompatibilität verbessern
• Regelmäßige Backups: Das /opt/zigbee2mqtt/data/-Verzeichnis enthält alle Geräte und Konfigurationen – sichere es regelmäßig