Umstieg von ZHA auf Zigbee2MQTT
ZHA ist das eigene Zigbee von Home Assistant. ZigDash arbeitet mit Zigbee2MQTT und kann deshalb keine Geräte anzeigen, die in ZHA sind. Umsteigen heißt: Du koppelst deine Geräte neu mit Zigbee2MQTT. Home Assistant nutzt sie danach weiter, über seine MQTT-Integration.
Bevor du anfängst
- Welche Installation? Wenn das Menü Einstellungen in Home Assistant Apps zeigt (bei älteren Versionen Add-ons), hast du Home Assistant OS: siehe mit Apps. Wenn nicht, läuft Home Assistant in Docker (Container): siehe Docker.
- Welcher Adapter? Öffne Einstellungen › Geräte & Dienste › Zigbee Home Automation. Unter Hubs steht der Adapter mit seinem Modell, zum Beispiel SONOFF ZBDongle-E. Schau dann unter Dein Adapter nach.
- ZHA sichern. Tippe auf dieser Seite auf das ⚙ neben Zigbee Home Automation, dann auf Download backup. Bewahre die Datei auf. Unter Network information auf derselben Seite siehst du Kanal, Funktyp und seriellen Port.
- Was sich in Home Assistant ändert. Deine Geräte kommen als neue MQTT-Geräte mit neuen Entitäts-IDs zurück. Automationen, Skripte und Dashboards, die sie nutzen, musst du auf die neuen umstellen, und ihr Verlauf beginnt neu. Gruppen und Bindungen aus ZHA werden in Zigbee2MQTT neu angelegt.
- Zeit. Jedes Gerät wird zurückgesetzt und neu gekoppelt, eins nach dem anderen. Ehrliche Zeitangaben haben wir noch nicht; plane für ein kleines Zuhause einen Abend ein und für ein großes mehr.
Zwei Wege zum Umstieg
| Zweiter Adapter | Derselbe Adapter | |
|---|---|---|
| Kosten | Ein neuer Adapter, etwa 30–60 € (zum Beispiel ein Home Assistant Connect ZBT-2 oder ein SMLIGHT SLZB-06M oder SLZB-07) | Kostenlos |
| Während des Umstiegs | Alles läuft weiter: ZHA behält den alten Adapter | Zigbee ist aus, bis jedes Gerät neu gekoppelt ist |
| Tempo | Raum für Raum, gern auch über mehrere Tage | Alles auf einmal |
| Der Weg zurück | Einfach: neuen Adapter abziehen, ZHA lief die ganze Zeit weiter | ZHA-Backup wiederherstellen (siehe Der Weg zurück) |
Zweiter Adapter
- Richte Zigbee2MQTT auf dem neuen Adapter ein (mit Apps oder Docker), mit einem eigenen Netz. Lege all das vor dem ersten Start von Zigbee2MQTT fest, denn wenn du den Kanal später änderst, musst du eventuell neu koppeln:
- lass Netzwerkschlüssel und PAN ID auf
GENERATE(die Voreinstellung); - wähle einen anderen Kanal als ZHA (bei ZHA unter ⚙ › Network information zu sehen); Home Assistant empfiehlt 15, 20 oder 25.
- lass Netzwerkschlüssel und PAN ID auf
- Halte die beiden Adapter auseinander, jeden an einem USB-Verlängerungskabel.
- Unter Home Assistant OS bietet Home Assistant beim Einstecken des neuen Adapters vielleicht an, ihn für ZHA oder Thread einzurichten. Ignoriere das: Der Adapter ist für Zigbee2MQTT.
- Zieh einen Raum nach dem anderen um: Kopple zuerst seine Geräte mit Netzstrom (Lampen, Steckdosen, Unterputzschalter: Das sind Router), dann seine Batteriegeräte.
- Wenn alle Geräte umgezogen sind, deaktiviere ZHA (siehe unten) und behalte den alten Adapter als Ersatz.
Derselbe Adapter
- Lade das ZHA-Backup herunter (siehe Bevor du anfängst), direkt bevor du loslegst.
- Deaktiviere ZHA: Einstellungen › Geräte & Dienste › Zigbee Home Automation, das ⋮ neben Zigbee Home Automation › Deaktivieren. Nicht Löschen.
- Richte Zigbee2MQTT auf demselben Adapter ein (mit Apps oder Docker) und lass Netzwerkschlüssel und PAN ID auf
GENERATE. - Schalte deine Zigbee-Geräte mit Netzstrom aus, am Wandschalter oder an der Sicherung. Sonst suchen sie weiter nach dem alten Netz.
- Schalte sie einzeln wieder ein und kopple jedes, sobald es an ist. Danach koppelst du die Batteriegeräte.
Dein Adapter
- Silicon Labs (Home Assistant Connect ZBT-1 und ZBT-2, Home Assistant Yellow, Sonoff ZBDongle-E, SMLIGHT SLZB-06M und SLZB-07):
adapter: ember. Der ZBT-2 braucht außerdembaudrate: 460800; der ZBDongle-E brauchtrtscts: false; der SLZB-06M braucht Firmware 20240510 oder neuer. - Texas Instruments (Sonoff ZBDongle-P, SMLIGHT SLZB-06 und SLZB-06P7):
adapter: zstack. - ConBee oder RaspBee:
adapter: deconz. - CC2531 oder ZiGate: zu alt oder nicht mehr gepflegt für ein gutes Zigbee2MQTT-Netz. Nimm den Weg mit zweitem Adapter und einen neuen Adapter.
- Ein Netzwerkadapter (SMLIGHT SLZB-06, SLZB-06M, SLZB-07, MR series): ZHA zeigt ihn als
socket://IP:6638; in Zigbee2MQTT ist estcp://IP:6638, und Docker braucht keine USB-Zeile. - Multiprotokoll (ZBT-1 oder Yellow, auf denen Zigbee und Thread zusammen laufen; das steht auf der Hardware-Seite in Home Assistant): Zigbee2MQTT kann keine Multiprotokoll-Firmware nutzen. Für den Weg mit demselben Adapter schaltest du Multiprotokoll noch unter ZHA aus, mit der Anleitung von Home Assistant (ZBT-1, Yellow). Thread-Geräte, die darüber liefen, funktionieren nicht mehr, bis ein anderer Thread-Border-Router sie übernimmt. Für den Weg mit zweitem Adapter lässt du es, wie es ist, und kaufst den neuen Adapter als reinen Zigbee-Adapter.
Mehr Details stehen auf den Adapter-Seiten von Zigbee2MQTT.
Home Assistant mit Apps (Home Assistant OS)
- Installiere und starte unter Einstellungen › Apps den Mosquitto broker. Home Assistant bietet dann unter Einstellungen › Geräte & Dienste die MQTT-Integration an: Bestätige sie.
- Füge das Zigbee2MQTT-Repository hinzu (im App-Store ⋮ › Repositories:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt) und installiere dann Zigbee2MQTT. - Stelle im Tab Konfiguration den seriellen Port und den Adapter laut Dein Adapter ein, zum Beispiel:
Für den Weg mit zweitem Adapter stellst du vor dem ersten Start außerdem den Kanal ein (siehe oben).port: /dev/serial/by-id/usb-... adapter: ember - Starte Zigbee2MQTT und öffne seine Weboberfläche über die Seite der App. Dann geht es ans Koppeln.
Home Assistant in Docker (ohne Apps)
Ohne Apps laufen Mosquitto und Zigbee2MQTT als eigene Container neben Home Assistant. In einem neuen Ordner:
1. compose.yaml (trag den Pfad deines Adapters unter devices ein; ls /dev/serial/by-id/ zeigt ihn):
services:
mosquitto:
image: eclipse-mosquitto:2
restart: unless-stopped
ports:
- 1883:1883
volumes:
- ./mosquitto/config:/mosquitto/config
- ./mosquitto/data:/mosquitto/data
zigbee2mqtt:
image: ghcr.io/koenkk/zigbee2mqtt
restart: unless-stopped
depends_on:
- mosquitto
ports:
- 8080:8080
volumes:
- ./zigbee2mqtt:/app/data
- /run/udev:/run/udev:ro
environment:
- TZ=Europe/Berlin
devices:
- /dev/serial/by-id/usb-...:/dev/ttyACM0
Mit einem Netzwerkadapter lässt du devices und die udev-Zeile weg.
2. mosquitto/config/mosquitto.conf:
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
Leg den MQTT-Benutzer an (der Befehl fragt zweimal nach einem Passwort; die Datei muss dem eigenen Benutzer von Mosquitto gehören, sonst startet Mosquitto nicht):
docker run -it --rm -v "$PWD/mosquitto/config:/mosquitto/config" eclipse-mosquitto:2 \
sh -c "mosquitto_passwd -c /mosquitto/config/passwd zigbee && chown mosquitto:mosquitto /mosquitto/config/passwd"
3. zigbee2mqtt/configuration.yaml (die Adapter-Zeilen aus Dein Adapter):
homeassistant:
enabled: true
frontend:
enabled: true
port: 8080
mqtt:
server: mqtt://mosquitto:1883
user: zigbee
password: your-password
serial:
port: /dev/ttyACM0 # a network adapter: tcp://IP:6638
adapter: ember
advanced:
network_key: GENERATE
pan_id: GENERATE
ext_pan_id: GENERATE
channel: 20 # second adapter: not ZHA's channel
4. Beim Weg mit demselben Adapter ist ZHA jetzt deaktiviert (siehe oben). Wenn der Container von Home Assistant selbst den Adapter einbindet, entferne diese Zeile aus seiner Compose-Datei oder aus docker run: Nur ein Container kann den Adapter nutzen.
5. docker compose up -d ausführen, dann http://the-machine:8080 öffnen: die Weboberfläche von Zigbee2MQTT.
6. In Home Assistant: Einstellungen › Geräte & Dienste › Integration hinzufügen › MQTT. Broker: die IP-Adresse des Rechners, Port 1883, Benutzer zigbee und das Passwort.
Geräte koppeln
- Tippe in der Weboberfläche von Zigbee2MQTT auf Permit join (etwa vier Minuten offen). Um über einen Router in der Nähe des Geräts zu koppeln, wähl diesen Router im Permit-join-Menü: praktisch für Aqara und andere wählerische Geräte.
- Setz das Gerät in den Kopplungsmodus zurück, so wie der Hersteller es beschreibt: bei den meisten Sensoren lange drücken, bei Lampen ein paar Mal aus- und einschalten, bei manchen Unterputzschaltern mehrmals hintereinander schalten.
- Wenn es auftaucht, gib ihm in Zigbee2MQTT seinen Namen und Raum. Dann das nächste.
Erst Geräte mit Netzstrom, danach Batteriegeräte, damit das neue Netz Routen hat.
Nach dem Umstieg
- ZigDash: Öffne die App und tippe auf Mein Setup finden. Sie findet Mosquitto in deinem Netzwerk; melde dich mit dem MQTT-Benutzer an. Oder wähle Home Assistant und melde dich dort an: Das klappt jetzt auch, weil Home Assistant die MQTT-Integration hat.
- Namen und Räume: In ZigDash holt Einstellungen › Aus Home Assistant importieren die Namen und Räume, die du den neuen Geräten in Home Assistant gegeben hast.
- Home Assistant: Stell Automationen, Skripte und Dashboards auf die neuen Geräte um. Wenn du sicher bist, lösch die ZHA-Integration.
Der Weg zurück
- Zweiter Adapter: Stoppe Zigbee2MQTT und zieh den neuen Adapter ab. ZHA lief die ganze Zeit weiter. Geräte, die du schon umgezogen hast, musst du wieder mit ZHA koppeln.
- Derselbe Adapter: Stoppe Zigbee2MQTT und tippe dann auf der ZHA-Seite auf Aktivieren. ZHA meldet "Network settings do not match most recent backup" (Netzwerkeinstellungen passen nicht zum letzten Backup), weil der Adapter jetzt das Netz von Zigbee2MQTT enthält. Öffne Einstellungen › Reparaturen › "Zigbee network settings have changed" (Zigbee-Netzwerkeinstellungen wurden geändert) und wähle Restore backup (recommended). Das Netz von ZHA ist dann wieder so wie vorher. Geräte, die du mit Zigbee2MQTT gekoppelt hattest, musst du wieder mit ZHA koppeln. Wenn keine Reparatur erscheint, nimm ⚙ › Migrate adapter mit dem Backup, das du heruntergeladen hast.
Das Netz behalten, ohne neu zu koppeln
Es gibt einen dritten Weg: das Netz von ZHA in Zigbee2MQTT kopieren, damit die Geräte nicht neu gekoppelt werden müssen. Zigbee2MQTT unterstützt das nicht, ein falscher Wert kann das Netz löschen, und es lohnt sich nur für große Installationen (sagen wir, über 60 Geräte). Wenn du darüber lesen willst: die Antwort des Zigbee2MQTT-Maintainers und Erfahrungsberichte aus der Community in Diskussion 24478 und Diskussion 26716.