Passer de ZHA à Zigbee2MQTT
ZHA est le Zigbee intégré à Home Assistant. ZigDash fonctionne avec Zigbee2MQTT, il ne peut donc pas afficher les appareils qui sont dans ZHA. Passer à Zigbee2MQTT veut dire appairer à nouveau vos appareils avec Zigbee2MQTT. Home Assistant continue ensuite à les utiliser, via son intégration MQTT.
Avant de commencer
- Quelle installation ? Si le menu Paramètres de Home Assistant affiche Apps (Modules complémentaires sur les anciennes versions), vous avez Home Assistant OS : voir avec apps. Sinon, Home Assistant tourne dans Docker (Container) : voir Docker.
- Quel adaptateur ? Ouvrez Paramètres › Appareils et services › Zigbee Home Automation. Sous Hubs, l'adaptateur apparaît sous son nom de modèle, par exemple SONOFF ZBDongle-E. Consultez ensuite votre adaptateur.
- Sauvegardez ZHA. Sur cette page, touchez le ⚙ à côté de Zigbee Home Automation, puis Download backup. Gardez le fichier. Sur la même page, Network information indique le canal, le type de radio et le port série.
- Ce qui change dans Home Assistant. Vos appareils reviennent comme de nouveaux appareils MQTT, avec de nouveaux identifiants d'entité. Les automatisations, scripts et tableaux de bord qui les utilisent doivent être redirigés vers les nouveaux, et leur historique repart de zéro. Les groupes et liaisons créés dans ZHA sont à refaire dans Zigbee2MQTT.
- Durée. Chaque appareil est réinitialisé puis appairé à nouveau, un par un. Nous n'avons pas encore de durées fiables ; prévoyez une soirée pour un petit logement, et plus pour un grand.
Deux façons de migrer
| Second adaptateur | Même adaptateur | |
|---|---|---|
| Coût | Un nouvel adaptateur, environ 30–60 € (par exemple un Home Assistant Connect ZBT-2, ou un SMLIGHT SLZB-06M ou SLZB-07) | Gratuit |
| Pendant la migration | Tout continue de fonctionner : ZHA garde l'ancien adaptateur | Le Zigbee est coupé jusqu'à ce que chaque appareil soit appairé à nouveau |
| Rythme | Pièce par pièce, sur plusieurs jours si vous le souhaitez | Tout d'un coup |
| Retour en arrière | Facile : débranchez le nouvel adaptateur, ZHA ne s'est jamais arrêté | Restaurez la sauvegarde ZHA (voir Revenir en arrière) |
Second adaptateur
- Installez Zigbee2MQTT sur le nouvel adaptateur (avec apps ou Docker), avec son propre réseau. Choisissez tout cela avant le premier démarrage de Zigbee2MQTT, car changer de canal plus tard peut obliger à tout appairer à nouveau :
- laissez la clé réseau et le PAN ID sur
GENERATE(la valeur par défaut) ; - choisissez un canal différent de celui de ZHA (le ⚙ de ZHA › Network information l'indique) ; Home Assistant conseille 15, 20 ou 25.
- laissez la clé réseau et le PAN ID sur
- Éloignez les deux adaptateurs l'un de l'autre, chacun sur une rallonge USB.
- Sous Home Assistant OS, quand vous branchez le nouvel adaptateur, Home Assistant peut proposer de le configurer pour ZHA ou Thread. Ignorez cette proposition : l'adaptateur est pour Zigbee2MQTT.
- Migrez une pièce à la fois : appairez d'abord ses appareils sur secteur (ampoules, prises, interrupteurs encastrés : ce sont des routeurs), puis ses appareils sur pile.
- Quand tous les appareils sont migrés, désactivez ZHA (voir plus bas) et gardez l'ancien adaptateur en réserve.
Même adaptateur
- Téléchargez la sauvegarde ZHA (voir Avant de commencer), juste avant de commencer.
- Désactivez ZHA : Paramètres › Appareils et services › Zigbee Home Automation, le ⋮ à côté de Zigbee Home Automation › Désactiver. Pas Supprimer.
- Installez Zigbee2MQTT sur le même adaptateur (avec apps ou Docker), en laissant la clé réseau et le PAN ID sur
GENERATE. - Coupez vos appareils Zigbee sur secteur, à l'interrupteur ou au disjoncteur. Sinon, ils continuent à chercher l'ancien réseau.
- Rallumez-les un par un, et appairez chacun dès qu'il est allumé. Appairez ensuite les appareils sur pile.
Votre adaptateur
- Silicon Labs (Home Assistant Connect ZBT-1 et ZBT-2, Home Assistant Yellow, Sonoff ZBDongle-E, SMLIGHT SLZB-06M et SLZB-07) :
adapter: ember. Le ZBT-2 a aussi besoin debaudrate: 460800; le ZBDongle-E a besoin dertscts: false; le SLZB-06M a besoin du firmware 20240510 ou plus récent. - Texas Instruments (Sonoff ZBDongle-P, SMLIGHT SLZB-06 et SLZB-06P7) :
adapter: zstack. - ConBee ou RaspBee :
adapter: deconz. - CC2531 ou ZiGate : trop ancien ou plus maintenu pour un bon réseau Zigbee2MQTT. Utilisez la méthode du second adaptateur, avec un nouvel adaptateur.
- Un adaptateur réseau (SMLIGHT SLZB-06, SLZB-06M, SLZB-07, MR series) : ZHA l'affiche comme
socket://IP:6638; dans Zigbee2MQTT, c'esttcp://IP:6638, et Docker n'a pas besoin de ligne USB. - Multiprotocole (ZBT-1 ou Yellow faisant tourner Zigbee et Thread ensemble ; la page du matériel dans Home Assistant l'indique) : Zigbee2MQTT ne peut pas utiliser un firmware multiprotocole. Pour la méthode du même adaptateur, désactivez le multiprotocole tant que vous êtes encore sur ZHA, avec la procédure de Home Assistant (ZBT-1, Yellow). Les appareils Thread qui l'utilisaient cessent de fonctionner jusqu'à ce qu'un autre routeur de bordure Thread les prenne en charge. Pour la méthode du second adaptateur, n'y touchez pas et achetez le nouvel adaptateur en version Zigbee uniquement.
Les pages sur les adaptateurs de Zigbee2MQTT donnent les détails.
Home Assistant avec apps (Home Assistant OS)
- Dans Paramètres › Apps, installez et démarrez Mosquitto broker. Home Assistant propose alors l'intégration MQTT dans Paramètres › Appareils et services : acceptez-la.
- Ajoutez le dépôt Zigbee2MQTT (dans la boutique d'apps, ⋮ › Dépôts :
https://github.com/zigbee2mqtt/hassio-zigbee2mqtt), puis installez Zigbee2MQTT. - Dans son onglet Configuration, renseignez le port série et l'adaptateur d'après votre adaptateur, par exemple :
Pour la méthode du second adaptateur, réglez aussi le canal (voir plus haut) avant le premier démarrage.port: /dev/serial/by-id/usb-... adapter: ember - Démarrez Zigbee2MQTT et ouvrez sa page web depuis la page de l'app. Ensuite, appairez.
Home Assistant dans Docker (sans apps)
Sans apps, Mosquitto et Zigbee2MQTT tournent dans leurs propres conteneurs, à côté de Home Assistant. Dans un nouveau dossier :
1. compose.yaml (mettez le chemin de votre adaptateur dans devices ; ls /dev/serial/by-id/ l'affiche) :
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
Avec un adaptateur réseau, retirez devices et la ligne udev.
2. mosquitto/config/mosquitto.conf :
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
persistence true
persistence_location /mosquitto/data/
Créez l'utilisateur MQTT (le mot de passe est demandé deux fois ; le fichier doit appartenir à l'utilisateur de Mosquitto, sinon Mosquitto ne démarre pas) :
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 (les lignes de l'adaptateur d'après votre adaptateur) :
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. Pour la méthode du même adaptateur, ZHA est maintenant désactivé (voir plus haut). Si le conteneur de Home Assistant lui-même donne accès à l'adaptateur, retirez cette ligne de son fichier compose ou de sa commande docker run : un seul conteneur peut utiliser l'adaptateur.
5. docker compose up -d, puis ouvrez http://the-machine:8080 : c'est la page web de Zigbee2MQTT.
6. Dans Home Assistant : Paramètres › Appareils et services › Ajouter une intégration › MQTT. Broker : l'adresse IP de la machine, port 1883, utilisateur zigbee et le mot de passe.
Appairer les appareils
- Sur la page web de Zigbee2MQTT, touchez Permit join (ouvert pendant environ quatre minutes). Pour appairer via un routeur proche de l'appareil, choisissez ce routeur dans le menu de Permit join : utile pour Aqara et d'autres appareils difficiles.
- Mettez l'appareil en mode appairage, comme l'indique son fabricant : un appui long pour la plupart des capteurs, quelques cycles allumé/éteint pour les ampoules, une série de basculements pour certains interrupteurs encastrés.
- Quand il apparaît, donnez-lui son nom et sa pièce dans Zigbee2MQTT. Puis passez au suivant.
D'abord les appareils sur secteur, ensuite les appareils sur pile, pour que le nouveau réseau ait des routes.
Après la migration
- ZigDash : ouvrez-le et touchez Trouver mon installation. Il trouve Mosquitto sur votre réseau ; connectez-vous avec l'utilisateur MQTT. Ou choisissez Home Assistant et connectez-vous : cela fonctionne aussi maintenant, puisque Home Assistant a l'intégration MQTT.
- Noms et pièces : dans ZigDash, Paramètres › Importer depuis Home Assistant récupère les noms et pièces que vous avez donnés aux nouveaux appareils dans Home Assistant.
- Home Assistant : redirigez les automatisations, scripts et tableaux de bord vers les nouveaux appareils. Quand vous êtes sûr de vous, supprimez l'intégration ZHA.
Revenir en arrière
- Second adaptateur : arrêtez Zigbee2MQTT et débranchez le nouvel adaptateur. ZHA ne s'est jamais arrêté. Les appareils déjà migrés doivent être appairés à nouveau à ZHA.
- Même adaptateur : arrêtez Zigbee2MQTT, puis sur la page de ZHA touchez Activer. ZHA affiche "Network settings do not match most recent backup" (les paramètres réseau ne correspondent pas à la dernière sauvegarde), car l'adaptateur contient maintenant le réseau de Zigbee2MQTT. Ouvrez Paramètres › Réparations › "Zigbee network settings have changed" (les paramètres du réseau Zigbee ont changé) et choisissez Restore backup (recommended). Le réseau de ZHA revient tel qu'il était. Les appareils que vous aviez appairés à Zigbee2MQTT doivent être appairés à nouveau à ZHA. Si aucune réparation n'apparaît, utilisez ⚙ › Migrate adapter avec la sauvegarde que vous avez téléchargée.
Garder le réseau sans appairer à nouveau
Il existe une troisième méthode : copier le réseau de ZHA dans Zigbee2MQTT pour que les appareils n'aient pas besoin d'être appairés à nouveau. Zigbee2MQTT ne la prend pas en charge, une mauvaise valeur peut effacer le réseau, et elle n'a de sens que pour les grands logements (disons plus de 60 appareils). Si vous voulez en savoir plus : la réponse du mainteneur de Zigbee2MQTT, et des retours de la communauté dans la discussion 24478 et la discussion 26716.