Zigbee2MQTT : migrer son coordinateur

Changer de coordinateur Zigbee2MQTT sans réappairer tous les appareils est possible dans certains cas, mais copier la clé réseau ne suffit pas. Il faut vérifier les familles de radios, conserver les données de Zigbee2MQTT et préparer la reprise de l’adresse IEEE du coordinateur. Un changement USB vers Ethernet ne dit rien, à lui seul, de la compatibilité de la migration.

Ce guide concerne une installation Zigbee2MQTT existante. Pour une première mise en service, commencez par installer Zigbee2MQTT.

Analyse documentaire. Cette synthèse repose sur les documentations et articles consultés le 7 octobre 2026. Aucun coordinateur n’a été remplacé et aucun délai de reprise n’a été mesuré par la rédaction. Les retours d’autres auteurs illustrent des cas particuliers ; ils ne garantissent pas le résultat sur votre réseau.

Peut-on éviter le réappairage ?

La FAQ officielle de Zigbee2MQTT réserve la sauvegarde et la restauration du coordinateur aux pilotes zstack et ember. La présence d’un appareil dans la liste du matériel compatible ne signifie donc pas que sa sauvegarde est transférable à n’importe quelle radio.

Situation de départ	Ce qu’il faut prévoir
Même coordinateur, nouveau serveur	Déplacer aussi le dossier de données ; vérifier le chemin série. Ce n’est pas un remplacement de radio.
Radio `zstack` vers `zstack`, ou `ember` vers `ember`	Migration à envisager avec sauvegarde compatible et reprise de l’IEEE ; contrôler la combinaison exacte.
`zstack` vers `ember`, ou l’inverse	Résultat variable, migration non officiellement prise en charge par Zigbee2MQTT ; prévoir des réappairages.
Ancien CC2530/CC2531 Zigbee 1.2 vers une radio Zigbee 3.0	Réappairage requis selon la documentation actuelle, malgré certains anciens tutoriels.
Autre pilote ou absence de sauvegarde exploitable	Ne pas promettre une migration sans réappairage.

La procédure ci-dessous reste centrée sur deux radios de la même famille. Changer simultanément de serveur, de logiciel Zigbee et de canal rendrait les causes d’un éventuel échec plus difficiles à distinguer.

Choisir une radio de remplacement cohérente

Relevez le modèle exact et le pilote actuel avant tout achat. Deux dongles SONOFF d’apparence voisine appartiennent à des familles différentes :

le ZBDongle-P, à puce CC2652P, figure dans la liste officielle zStack ;
le ZBDongle-E, à puce EFR32MG21, figure dans la liste officielle EmberZNet, comme le SMLIGHT SLZB-06M. Ce dernier ne doit pas être confondu avec le SLZB-06 sans suffixe.

Pour remplacer un ZBDongle-P défaillant tout en conservant cette famille de radio, un autre ZBDongle-P est une option documentée du catalogue. Cela suppose une sauvegarde exploitable et un firmware de coordinateur adapté. Ce n’est ni une promesse de portée supérieure, ni une raison de remplacer une clé qui fonctionne.

Si votre besoin est surtout de déplacer l’antenne, notre comparatif des coordinateurs USB et Ethernet aide à choisir le format. Le choix du branchement vient après celui de la compatibilité de migration.

Sauvegarder les données avant de débrancher

Commencez par un inventaire : appareils visibles, noms utilisés, groupes et automatisations à contrôler après la bascule. Notez les versions du logiciel et du firmware, le pilote et l’adresse IEEE du coordinateur.

Zigbee2MQTT fournit une requête de sauvegarde du dossier de données. Son API reçoit un message vide sur zigbee2mqtt/bridge/request/backup et renvoie une archive ZIP encodée en Base64, hors journaux. Le préfixe zigbee2mqtt doit correspondre à votre configuration. Vérifiez le statut de la réponse et conservez l’archive téléchargée, pas seulement le message de demande.

Avant la modification, contrôlez que votre copie contient les fichiers attendus, notamment configuration.yaml, database.db et, pour une radio prise en charge, coordinator_backup.json. Conservez tout le dossier plutôt qu’une sélection manuelle de deux valeurs. Si vous faites une copie de fichiers directement, arrêtez d’abord le service pour figer son état.

Gardez cette copie sur un autre support, conformément à notre guide de sauvegarde 3-2-1. Elle contient des secrets : ne la joignez pas à une demande d’aide publique. Un Zigbee2MQTT hébergé séparément doit avoir sa propre sauvegarde.

Reprendre l’adresse IEEE sans écriture aveugle

L’adresse IEEE est l’identifiant radio du coordinateur, distinct du PAN ID et de la clé réseau. La procédure officielle de copie de l’IEEE explique que certains appareils recherchent leur coordinateur par cette adresse. Elle se consulte dans Settings → About → Coordinator IEEE Address, ou dans l’entrée du coordinateur au début de database.db.

Arrêtez Zigbee2MQTT et débranchez l’ancienne radio avant la bascule. Gardez-la intacte pour disposer d’une possibilité de retour. Sur la nouvelle, utilisez l’outil et le firmware prévus pour son modèle ; les manipulations diffèrent entre Texas Instruments et Silicon Labs. Après écriture, vérifiez l’adresse utilisée par le coordinateur dans Zigbee2MQTT.

Ne cochez pas une option « Force » par réflexe. La documentation avertit que, sur certains EFR32 dont le firmware ne prend pas en charge les jetons NV3, forcer l’écriture peut programmer une adresse une seule fois, sans retour possible. Une erreur à cette étape justifie de s’arrêter et de relire la procédure propre au modèle, pas de multiplier les essais.

Modifier la connexion, préserver le réseau

Le guide des paramètres d’adaptateur distingue serial.port, qui désigne la connexion, et serial.adapter, qui sélectionne le pilote. Relevez le nouveau chemin USB stable sous /dev/serial/by-id/, ou l’adresse et le port TCP indiqués par le coordinateur Ethernet. Pour ce dernier, stabilisez l’adresse IP. Vérifiez également les réglages de débit et de contrôle de flux exigés par son firmware.

Dans Home Assistant, examinez aussi les options de l’application Zigbee2MQTT : elles peuvent fournir des paramètres en plus du fichier. Le retour espagnol de Tecnotizate, publié le 25 avril 2026, décrit justement une incohérence entre ces deux endroits lors d’un passage vers un Dongle-M. Retenez ce point de contrôle ; sa procédure de contournement entre familles de puces n’est pas une garantie générale.

Pour conserver le réseau, gardez ses identifiants et ses fichiers d’origine. N’en profitez pas pour changer la clé réseau ou le canal. Le diagnostic des interférences Zigbee et Wi-Fi est une opération distincte, à mener une fois la migration validée.

Vérifier chaque usage avant de ranger l’ancienne clé

Le guide de migration SONOFF prévoit notamment de vérifier l’IEEE après remplacement. Complétez ce contrôle par une liste adaptée à votre logement :

Démarrage : absence d’erreur de port, de pilote ou de restauration dans les journaux ; adresse du coordinateur conforme à celle relevée.
Appareils alimentés : une commande réelle et un retour d’état cohérent pour plusieurs prises ou lampes, y compris loin de la radio.
Capteurs sur pile : réveil selon leur notice, puis réception d’un nouvel événement. Une ancienne valeur affichée n’est pas une preuve de communication.
Home Assistant : entités attendues et automatisations importantes encore utilisables, avec les noms habituels.
Commandes directes : vérification des groupes et des liaisons de binding Zigbee que vous utilisez réellement.

Notre méthode pour repérer les capteurs Zigbee silencieux peut compléter cet inventaire. Fixez votre propre période d’observation selon le rythme des appareils ; aucun délai universel ne prouve que tout fonctionne.

Si le démarrage échoue, conservez les journaux et la sauvegarde initiale avant toute autre modification. Ne supprimez pas database.db pour essayer au hasard. Pour envisager un retour, arrêtez le service, débranchez la nouvelle radio et reprenez l’ancienne avec les fichiers et paramètres conservés. N’alimentez pas simultanément deux coordinateurs portant la même identité réseau. Si des appareils ont déjà été réinitialisés ou rattachés à un autre réseau, le retour ne les réintègre pas automatiquement.

Ce que les retours étrangers permettent de conclure

En Allemagne, le récit de Smart Home & more du 23 mai 2025 décrit un passage vers un coordinateur Ethernet pour faciliter l’hébergement virtualisé. L’auteur signale du matériel fourni par le fabricant. Son expérience éclaire l’intérêt du placement ; ses délais et résultats ne sont pas transposés ici.

En Pologne, le retour de SP2ASO du 23 octobre 2024 rapporte une migration entre CC2652P et EFR32MG21 avec des outils supplémentaires, puis le réappairage de trois appareils. Ce cas montre pourquoi un récit de réussite ne suffit pas à promettre une migration universelle entre zstack et ember.

La décision utile est donc de choisir la nouvelle radio à partir de votre sauvegarde et de votre famille actuelle, puis de vérifier les usages un par un. Pour une installation stable qui répond déjà à vos besoins, garder le coordinateur existant reste une option valable.