ZigDash

Overstappen van ZHA naar Zigbee2MQTT

ZHA is de eigen Zigbee van Home Assistant. ZigDash werkt met Zigbee2MQTT en kan dus geen apparaten tonen die in ZHA zitten. Overstappen betekent dat je je apparaten opnieuw koppelt met Zigbee2MQTT. Home Assistant blijft ze daarna gebruiken, via de MQTT-integratie.

Voordat je begint

Twee manieren om over te stappen

Tweede adapterDezelfde adapter
KostenEen nieuwe adapter, ongeveer € 30–60 (bijvoorbeeld een Home Assistant Connect ZBT-2, of een SMLIGHT SLZB-06M of SLZB-07)Gratis
Tijdens de overstapAlles blijft werken: ZHA houdt de oude adapterZigbee ligt stil tot elk apparaat opnieuw gekoppeld is
TempoKamer voor kamer, als je wilt verspreid over dagenAlles in één keer
TeruggaanMakkelijk: haal de nieuwe adapter eruit, ZHA is nooit gestoptZet de ZHA-back-up terug (zie Teruggaan)

Tweede adapter

  1. Zet Zigbee2MQTT op met de nieuwe adapter (met apps of Docker), met een eigen netwerk. Kies dit allemaal vóór de eerste start van Zigbee2MQTT, want als je het kanaal later wijzigt, moet je misschien opnieuw koppelen:
    • laat de netwerksleutel en PAN ID op GENERATE staan (de standaard);
    • kies een ander kanaal dan dat van ZHA (ZHA's ⚙ › Network information toont het); Home Assistant raadt 15, 20 of 25 aan.
  2. Houd de twee adapters uit elkaar, elk aan een USB-verlengkabel.
  3. Op Home Assistant OS kan Home Assistant bij het insteken van de nieuwe adapter aanbieden om hem in te stellen voor ZHA of Thread. Negeer dat: de adapter is voor Zigbee2MQTT.
  4. Verhuis één kamer tegelijk: koppel eerst de apparaten op netstroom (lampen, stekkers, inbouwschakelaars: dat zijn routers), daarna de apparaten op batterij.
  5. Als elk apparaat over is, schakel je ZHA uit (zie hieronder) en houd je de oude adapter als reserve.

Dezelfde adapter

  1. Download de ZHA-back-up (zie Voordat je begint), vlak voordat je begint.
  2. Schakel ZHA uit: Instellingen › Apparaten & diensten › Zigbee Home Automation, de ⋮ naast Zigbee Home Automation › Uitschakelen. Niet Verwijderen.
  3. Zet Zigbee2MQTT op met dezelfde adapter (met apps of Docker) en laat de netwerksleutel en PAN ID op GENERATE staan.
  4. Zet je Zigbee-apparaten op netstroom uit, met de wandschakelaar of in de meterkast. Anders blijven ze het oude netwerk zoeken.
  5. Zet ze één voor één weer aan en koppel elk apparaat zodra het aangaat. Koppel daarna de apparaten op batterij.

Je adapter

De adapterpagina's van Zigbee2MQTT hebben de details.

Home Assistant met apps (Home Assistant OS)

  1. Installeer en start in Instellingen › Apps de Mosquitto broker. Home Assistant biedt dan de MQTT-integratie aan onder Instellingen › Apparaten & diensten: accepteer die.
  2. Voeg de Zigbee2MQTT-repository toe (in de app-store, ⋮ › Repositories: https://github.com/zigbee2mqtt/hassio-zigbee2mqtt) en installeer dan Zigbee2MQTT.
  3. Stel op het tabblad Configuratie de seriële poort en de adapter in volgens je adapter, bijvoorbeeld:
    port: /dev/serial/by-id/usb-...
    adapter: ember
    Stel voor de manier met een tweede adapter vóór de eerste start ook het kanaal in (zie hierboven).
  4. Start Zigbee2MQTT en open de webpagina vanaf de pagina van de app. Daarna koppelen.

Home Assistant in Docker (zonder apps)

Zonder apps draaien Mosquitto en Zigbee2MQTT als eigen containers naast Home Assistant. In een nieuwe map:

1. compose.yaml (zet het pad van je adapter bij devices; ls /dev/serial/by-id/ toont het):

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

Met een netwerkadapter laat je devices en de udev-regel weg.

2. mosquitto/config/mosquitto.conf:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/

Maak de MQTT-gebruiker aan (er wordt twee keer om een wachtwoord gevraagd; het bestand moet van de eigen gebruiker van Mosquitto zijn, anders start Mosquitto niet):

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 (de adapterregels uit je 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. Bij de manier met dezelfde adapter is ZHA nu uitgeschakeld (zie hierboven). Als de eigen container van Home Assistant de adapter doorgeeft, haal die regel dan weg uit het compose-bestand of uit docker run: maar één container kan de adapter gebruiken.

5. docker compose up -d, open dan http://the-machine:8080: de webpagina van Zigbee2MQTT.

6. In Home Assistant: Instellingen › Apparaten & diensten › Integratie toevoegen › MQTT. Broker: het IP-adres van de machine, poort 1883, gebruiker zigbee en het wachtwoord.

De apparaten koppelen

  1. Tik op de webpagina van Zigbee2MQTT op Permit join (ongeveer vier minuten open). Wil je koppelen via een router dicht bij het apparaat, kies die router dan in het permit-join-menu: handig voor Aqara en andere kieskeurige apparaten.
  2. Reset het apparaat naar de koppelmodus, zoals de fabrikant het beschrijft: lang drukken bij de meeste sensoren, een paar keer uit en aan bij lampen, een reeks keer schakelen bij sommige inbouwschakelaars.
  3. Als het verschijnt, geef het in Zigbee2MQTT zijn naam en kamer. Dan het volgende.

Eerst de apparaten op netstroom, daarna die op batterij, zodat het nieuwe netwerk routes heeft.

Na de overstap

Teruggaan

Getest: op 17 november 2026, met Home Assistant 2026.11 en een Sonoff ZBDongle-E, kwam het netwerk van ZHA precies terug (kanaal, PAN ID en netwerksleutel). Met gekoppelde apparaten hebben we het nog niet gecontroleerd, dus bewaar het back-upbestand.

Het netwerk houden zonder opnieuw te koppelen

Er is een derde manier: het netwerk van ZHA naar Zigbee2MQTT kopiëren, zodat apparaten niet opnieuw gekoppeld hoeven te worden. Zigbee2MQTT ondersteunt dat niet, een verkeerde waarde kan het netwerk wissen, en het is alleen zinvol voor grote huizen (zeg, meer dan 60 apparaten). Wil je erover lezen: het antwoord van de maintainer van Zigbee2MQTT, en ervaringen uit de community in discussie 24478 en discussie 26716.

Laat ons weten hoe het ging. Deze gids is nieuw. Klopte een stap niet of ontbrak er iets, schrijf dan naar [email protected] of de community.