Damit Home Assistant direkt mit ZigBee-Geräten kommunizieren kann, wird ein sogenannter ZigBee-Koordinator benötigt. In meinem Fall verwende ich einen ZigBee 3.0 USB Dongle OpenHAB mit dem EFR32MG21 SoC. Der Stick wird einfach per USB an den Home-Assistant-Server angeschlossen und stellt anschließend das ZigBee-Netzwerk bereit.
Da ich Home Assistant jedoch nicht als Home Assistant OS, sondern als Docker-Container betreibe, gibt es einen kleinen zusätzlichen Schritt: Der USB-Stick muss vom Host-System in den Docker-Container durchgereicht werden. Andernfalls erkennt Home Assistant den Stick zwar auf dem Linux-System, kann aber innerhalb des Containers nicht darauf zugreifen.
USB-Stick unter Linux erkennen
Nachdem der ZigBee-Stick eingesteckt wurde, kann man zunächst prüfen, ob er vom System erkannt wurde:
lsusb
In meinem Fall wird der Stick als serieller USB-Adapter erkannt. Zusätzlich sollte geprüft werden, unter welchem stabilen Gerätepfad der Stick erreichbar ist:
ls -l /dev/serial/by-id/
Die Ausgabe sieht beispielsweise so aus:
Wichtig ist hier der Pfad unter /dev/serial/by-id/. Dieser ist stabiler als /dev/ttyUSB0, da sich /dev/ttyUSB0 ändern kann, wenn später weitere USB-Geräte angeschlossen werden.
Der vollständige Pfad lautet in diesem Beispiel:
/dev/serial/by-id/usb-1a86_USB_Serial-if00-port0
Docker Compose anpassen
Damit Home Assistant den ZigBee-Stick verwenden kann, muss die docker-compose.yml erweitert werden. Entscheidend ist der Abschnitt devices.
Ein Beispiel für meine Home-Assistant-Konfiguration sieht so aus:
Datei compose.yml mit dem Pfad zum ZigBee-Gerät
services:
homeassistant:
container_name: homeassistant
image: ghcr.io/home-assistant/home-assistant:stable
volumes:
- /opt/homeassistant/config:/config
- /etc/localtime:/etc/localtime:ro
- /run/dbus:/run/dbus:ro
devices:
- /dev/serial/by-id/usb-1a86_USB_Serial-if00-port0:/dev/ttyUSB0
environment:
TZ: Europe/Berlin
restart: unless-stopped
privileged: true
network_mode: host
Auf der linken Seite steht der Gerätepfad auf dem Host-System. Auf der rechten Seite wird festgelegt, unter welchem Pfad der Stick im Container verfügbar ist. In diesem Beispiel ist der Stick innerhalb des Home-Assistant-Containers unter /dev/ttyUSB0 erreichbar.
Nach der Änderung muss der Container neu erstellt und neu gestartet werden:
docker compose up -d --force-recreate
Anschließend kann geprüft werden, ob Home Assistant sauber gestartet ist:
docker compose logs -f homeassistant
ZHA-Integration in Home Assistant einrichten
Jetzt kann die eigentliche Einrichtung in Home Assistant erfolgen.
Dazu öffnest du in Home Assistant:
Einstellungen → Geräte & Dienste → Integration hinzufügen
Dort suchst du nach „Zigbee Home Automation“
Falls Home Assistant den Stick automatisch erkennt, wird die Einrichtung direkt vorgeschlagen. Andernfalls kann die Integration manuell hinzugefügt werden.
Die Einrichtung erfolgt über einen Wizard, welcher durch die Schritte führt. In meinem Fall wähle ich die automatische Einrichtung, welche am Ende dazu führt, dass mein Gerät als ZigBee-Koordinator eingerichtet ist.
Erstes Zigbee-Gerät hinzufügen: Shelly Plus 1 Gen4 einrichten
Nachdem der Zigbee USB-Stick erfolgreich in Home Assistant eingerichtet wurde, kann das erste Zigbee-Gerät hinzugefügt werden. In meinem Fall verwende ich dafür einen Shelly Plus 1 Gen4.
Der Shelly Plus 1 Gen4 ist besonders interessant, da er nicht mehr nur per WLAN und Bluetooth genutzt werden kann, sondern zusätzlich auch Matter und Zigbee unterstützt. Dadurch lässt sich der smarte Schalter sehr flexibel in unterschiedliche Smart-Home-Systeme integrieren.
Bevor ich den Shelly in Home Assistant eingebunden habe, habe ich ihn zunächst ganz normal über die Shelly Cloud eingerichtet. Anschließend wurde das Gerät auf die Firmware-Version 1.7.5 aktualisiert. Erst danach konnte ich im lokalen Webfrontend des Shelly unter:
Settings → Switch to ZigBee Firmware
die Firmware auf den Zigbee-Betrieb umstellen.
Der Wechsel dauert einige Sekunden. Währenddessen wird die passende Zigbee-Firmware auf das Gerät übertragen und der Shelly startet anschließend im Zigbee-Modus neu. Danach steht das Gerät nicht mehr wie gewohnt über die WLAN-Firmware zur Verfügung, sondern kann als Zigbee-Gerät an einem Zigbee-Koordinator angelernt werden.
In Home Assistant wird dazu die bereits eingerichtete ZHA-Integration geöffnet. Dort kann über Gerät hinzufügen beziehungsweise Add Device die Suche nach neuen Zigbee-Geräten gestartet werden. Sobald der Shelly im Pairing-Modus ist, wird er von Home Assistant erkannt und kann anschließend benannt sowie einem Bereich zugeordnet werden.
Damit das Gerät gefunden / gekoppelt werden kann, muss dieses in den Kopplungsmodus versetzt werden. Wie man diesen Modus einstellt, ist vom Gerät abhängig, bei Shelly Geräten klappt dies ab der Firmware Version 1.7.0 über die Weboberfläche.
Wird das Gerät erkannt, so wird eine Verbindung aufgebaut und zunächst lediglich die Adresse angezeigt.
Im Anschluss wird der korrekte Name angezeigt, welchen man nach Belieben ändern kann, und das Gerät lässt sich einem Bereich/ Raum zuordnen.
Nach der erfolgreichen Einrichtung steht der Shelly Plus 1 Gen4 als smarter Schalter in Home Assistant zur Verfügung und kann dort für Automationen, Szenen oder Dashboards verwendet werden.
Wichtig: Ein Zigbee-Gerät kann immer nur mit einem Zigbee-Netzwerk verbunden sein. Wird der Shelly über Home Assistant eingebunden, ist er Teil dieses Zigbee-Netzwerks. Soll er später wieder über eine andere Plattform oder einen anderen Funkstandard genutzt werden, muss die Firmware bzw. der Betriebsmodus entsprechend erneut gewechselt werden.
Fazit
Die Einrichtung eines Zigbee USB-Sticks unter Home Assistant ist grundsätzlich recht einfach. Die eigentliche Besonderheit entsteht erst dann, wenn Home Assistant – wie in meinem Fall – als Docker-Container betrieben wird. Der USB-Stick wird zwar vom Linux-System erkannt, muss aber zusätzlich sauber an den Container durchgereicht werden.
Mit dem stabilen Gerätepfad unter /dev/serial/by-id/ und der passenden Erweiterung in der docker-compose.yml lässt sich der Zigbee-Koordinator zuverlässig in Home Assistant einbinden. Anschließend übernimmt die ZHA-Integration die Einrichtung des Zigbee-Netzwerks.
Besonders spannend wird es mit Geräten wie dem Shelly Plus 1 Gen4. Durch die Unterstützung von WLAN, Bluetooth, Matter und Zigbee lässt sich der smarte Schalter sehr flexibel einsetzen. Nach dem Wechsel auf die Zigbee-Firmware kann er direkt in Home Assistant angelernt und für Automationen, Szenen oder Dashboards verwendet werden.
Damit ist der Grundstein für ein eigenes Zigbee-Netzwerk in Home Assistant gelegt. Weitere Sensoren, Schalter, Lampen oder Aktoren können nun Schritt für Schritt hinzugefügt und zentral über Home Assistant gesteuert werden.
Letzte Aktualisierung am: 31. Mai 2026
