ZigDash

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

Zwei Wege zum Umstieg

Zweiter AdapterDerselbe Adapter
KostenEin 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 UmstiegsAlles läuft weiter: ZHA behält den alten AdapterZigbee ist aus, bis jedes Gerät neu gekoppelt ist
TempoRaum für Raum, gern auch über mehrere TageAlles auf einmal
Der Weg zurückEinfach: neuen Adapter abziehen, ZHA lief die ganze Zeit weiterZHA-Backup wiederherstellen (siehe Der Weg zurück)

Zweiter Adapter

  1. 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.
  2. Halte die beiden Adapter auseinander, jeden an einem USB-Verlängerungskabel.
  3. 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.
  4. Zieh einen Raum nach dem anderen um: Kopple zuerst seine Geräte mit Netzstrom (Lampen, Steckdosen, Unterputzschalter: Das sind Router), dann seine Batteriegeräte.
  5. Wenn alle Geräte umgezogen sind, deaktiviere ZHA (siehe unten) und behalte den alten Adapter als Ersatz.

Derselbe Adapter

  1. Lade das ZHA-Backup herunter (siehe Bevor du anfängst), direkt bevor du loslegst.
  2. Deaktiviere ZHA: Einstellungen › Geräte & Dienste › Zigbee Home Automation, das ⋮ neben Zigbee Home Automation › Deaktivieren. Nicht Löschen.
  3. Richte Zigbee2MQTT auf demselben Adapter ein (mit Apps oder Docker) und lass Netzwerkschlüssel und PAN ID auf GENERATE.
  4. Schalte deine Zigbee-Geräte mit Netzstrom aus, am Wandschalter oder an der Sicherung. Sonst suchen sie weiter nach dem alten Netz.
  5. Schalte sie einzeln wieder ein und kopple jedes, sobald es an ist. Danach koppelst du die Batteriegeräte.

Dein Adapter

Mehr Details stehen auf den Adapter-Seiten von Zigbee2MQTT.

Home Assistant mit Apps (Home Assistant OS)

  1. 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.
  2. Füge das Zigbee2MQTT-Repository hinzu (im App-Store ⋮ › Repositories: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt) und installiere dann Zigbee2MQTT.
  3. Stelle im Tab Konfiguration den seriellen Port und den Adapter laut Dein Adapter ein, zum Beispiel:
    port: /dev/serial/by-id/usb-...
    adapter: ember
    Für den Weg mit zweitem Adapter stellst du vor dem ersten Start außerdem den Kanal ein (siehe oben).
  4. 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

  1. 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.
  2. 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.
  3. 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

Der Weg zurück

Getestet: Am 17. November 2026 kam mit Home Assistant 2026.11 und einem Sonoff ZBDongle-E das Netz von ZHA exakt zurück (Kanal, PAN ID und Netzwerkschlüssel). Mit gekoppelten Geräten haben wir das noch nicht geprüft, also bewahre die Backup-Datei auf.

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.

Erzähl uns, wie es lief. Diese Anleitung ist neu. Wenn ein Schritt falsch war oder gefehlt hat, schreib an [email protected] oder in die Community.