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
- Welke installatie? Als het menu Instellingen van Home Assistant Apps toont (Add-ons bij oudere versies), heb je Home Assistant OS: zie met apps. Zo niet, dan draait Home Assistant in Docker (Container): zie Docker.
- Welke adapter? Open Instellingen › Apparaten & diensten › Zigbee Home Automation. Onder Hubs staat de adapter met zijn model, bijvoorbeeld SONOFF ZBDongle-E. Kijk dan bij je adapter.
- Maak een back-up van ZHA. Tik op die pagina op het ⚙ naast Zigbee Home Automation en dan op Download backup. Bewaar het bestand. Network information op dezelfde pagina toont het kanaal, het radiotype en de seriële poort.
- Wat er verandert in Home Assistant. Je apparaten komen terug als nieuwe MQTT-apparaten met nieuwe entiteit-ID's. Automatiseringen, scripts en dashboards die ze gebruiken, moet je naar de nieuwe laten verwijzen, en hun geschiedenis begint opnieuw. Groepen en bindingen uit ZHA maak je opnieuw in Zigbee2MQTT.
- Tijd. Elk apparaat wordt gereset en opnieuw gekoppeld, één voor één. Eerlijke tijdsinschattingen hebben we nog niet; reken op een avond voor een klein huis en meer voor een groot huis.
Twee manieren om over te stappen
| Tweede adapter | Dezelfde adapter | |
|---|---|---|
| Kosten | Een nieuwe adapter, ongeveer € 30–60 (bijvoorbeeld een Home Assistant Connect ZBT-2, of een SMLIGHT SLZB-06M of SLZB-07) | Gratis |
| Tijdens de overstap | Alles blijft werken: ZHA houdt de oude adapter | Zigbee ligt stil tot elk apparaat opnieuw gekoppeld is |
| Tempo | Kamer voor kamer, als je wilt verspreid over dagen | Alles in één keer |
| Teruggaan | Makkelijk: haal de nieuwe adapter eruit, ZHA is nooit gestopt | Zet de ZHA-back-up terug (zie Teruggaan) |
Tweede adapter
- 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
GENERATEstaan (de standaard); - kies een ander kanaal dan dat van ZHA (ZHA's ⚙ › Network information toont het); Home Assistant raadt 15, 20 of 25 aan.
- laat de netwerksleutel en PAN ID op
- Houd de twee adapters uit elkaar, elk aan een USB-verlengkabel.
- 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.
- Verhuis één kamer tegelijk: koppel eerst de apparaten op netstroom (lampen, stekkers, inbouwschakelaars: dat zijn routers), daarna de apparaten op batterij.
- Als elk apparaat over is, schakel je ZHA uit (zie hieronder) en houd je de oude adapter als reserve.
Dezelfde adapter
- Download de ZHA-back-up (zie Voordat je begint), vlak voordat je begint.
- Schakel ZHA uit: Instellingen › Apparaten & diensten › Zigbee Home Automation, de ⋮ naast Zigbee Home Automation › Uitschakelen. Niet Verwijderen.
- Zet Zigbee2MQTT op met dezelfde adapter (met apps of Docker) en laat de netwerksleutel en PAN ID op
GENERATEstaan. - Zet je Zigbee-apparaten op netstroom uit, met de wandschakelaar of in de meterkast. Anders blijven ze het oude netwerk zoeken.
- Zet ze één voor één weer aan en koppel elk apparaat zodra het aangaat. Koppel daarna de apparaten op batterij.
Je adapter
- Silicon Labs (Home Assistant Connect ZBT-1 en ZBT-2, Home Assistant Yellow, Sonoff ZBDongle-E, SMLIGHT SLZB-06M en SLZB-07):
adapter: ember. De ZBT-2 heeft ookbaudrate: 460800nodig; de ZBDongle-E heeftrtscts: falsenodig; de SLZB-06M heeft firmware 20240510 of nieuwer nodig. - Texas Instruments (Sonoff ZBDongle-P, SMLIGHT SLZB-06 en SLZB-06P7):
adapter: zstack. - ConBee of RaspBee:
adapter: deconz. - CC2531 of ZiGate: te oud of niet meer onderhouden voor een goed Zigbee2MQTT-netwerk. Kies de manier met een tweede adapter, met een nieuwe adapter.
- Een netwerkadapter (SMLIGHT SLZB-06, SLZB-06M, SLZB-07, MR series): ZHA toont hem als
socket://IP:6638; in Zigbee2MQTT is hettcp://IP:6638, en Docker heeft geen USB-regel nodig. - Multiprotocol (ZBT-1 of Yellow waarop Zigbee en Thread samen draaien; de hardwarepagina in Home Assistant vermeldt dat): Zigbee2MQTT kan geen multiprotocol-firmware gebruiken. Voor de manier met dezelfde adapter zet je multiprotocol uit terwijl je nog op ZHA zit, met de eigen procedure van Home Assistant (ZBT-1, Yellow). Thread-apparaten die het gebruikten, werken niet meer tot een andere Thread-borderrouter ze overneemt. Voor de manier met een tweede adapter laat je het zoals het is en koop je de nieuwe adapter als alleen-Zigbee.
De adapterpagina's van Zigbee2MQTT hebben de details.
Home Assistant met apps (Home Assistant OS)
- Installeer en start in Instellingen › Apps de Mosquitto broker. Home Assistant biedt dan de MQTT-integratie aan onder Instellingen › Apparaten & diensten: accepteer die.
- Voeg de Zigbee2MQTT-repository toe (in de app-store, ⋮ › Repositories:
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt) en installeer dan Zigbee2MQTT. - Stel op het tabblad Configuratie de seriële poort en de adapter in volgens je adapter, bijvoorbeeld:
Stel voor de manier met een tweede adapter vóór de eerste start ook het kanaal in (zie hierboven).port: /dev/serial/by-id/usb-... adapter: ember - 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
- 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.
- 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.
- 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
- ZigDash: open de app en tik op Vind mijn installatie. De app vindt Mosquitto op je netwerk; log in met de MQTT-gebruiker. Of kies Home Assistant en log daar in: dat werkt nu ook, omdat Home Assistant de MQTT-integratie heeft.
- Namen en kamers: Instellingen › Importeren uit Home Assistant in ZigDash haalt de namen en kamers op die je de nieuwe apparaten in Home Assistant hebt gegeven.
- Home Assistant: laat automatiseringen, scripts en dashboards naar de nieuwe apparaten verwijzen. Als je het zeker weet, verwijder je de ZHA-integratie.
Teruggaan
- Tweede adapter: stop Zigbee2MQTT en haal de nieuwe adapter eruit. ZHA is nooit gestopt. Apparaten die je al hebt verhuisd, moet je opnieuw aan ZHA koppelen.
- Dezelfde adapter: stop Zigbee2MQTT en tik dan op de pagina van ZHA op Inschakelen. ZHA meldt "Network settings do not match most recent backup" (netwerkinstellingen komen niet overeen met de laatste back-up), omdat de adapter nu het netwerk van Zigbee2MQTT bevat. Open Instellingen › Reparaties › "Zigbee network settings have changed" (Zigbee-netwerkinstellingen zijn gewijzigd) en kies Restore backup (recommended). Het netwerk van ZHA komt terug zoals het was. Apparaten die je aan Zigbee2MQTT had gekoppeld, moet je opnieuw aan ZHA koppelen. Verschijnt er geen reparatie, gebruik dan ⚙ › Migrate adapter met de back-up die je hebt gedownload.
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.