Zigbee2MQTT 2.x : guide migration Home Assistant

Si vous gérez un mesh Zigbee sur Home Assistant via Zigbee2MQTT, vous avez forcément vu passer la fameuse mise à jour 2.0, sortie début 2025. Plus d'un an plus tard, en avril 2026, la branche 2.x est stabilisée (versions 2.5.x au moment de la rédaction — vérifiez la version courante sur les releases GitHub avant de migrer), mais les retours d'expérience FR sur sa migration restent éparpillés entre fils HACF d'entraide et discussions GitHub en anglais. Ce guide consolide tout : pourquoi migrer, comment préparer la bascule, ce qui casse vraiment, comment réparer vos automatisations Home Assistant et comment rollbacker si tout part en vrille.

Trois profils de lecteurs trouveront ici ce qu'ils cherchent. Le premier hésite à migrer et veut une matrice de décision claire — section 1. Le second s'apprête à migrer et veut anticiper les pièges — sections 2 à 6. Le troisième vient de migrer et la moitié de ses télécommandes ne marchent plus — directement sections 7 à 10. Tous les exemples YAML donnés sont copie-collables et testés sur des installations réelles.

Pourquoi (et quand) migrer vers Zigbee2MQTT 2.x en 2026

Zigbee2MQTT 2.0 est sortie le 3 janvier 2025, après plusieurs semaines de tests sur la branche dev (ouverte aux early adopters dès le 2 décembre 2024). La 2.x apporte plusieurs gains tangibles. Le premier est un nettoyage massif des entités dupliquées que la 1.x exposait à Home Assistant (un capteur d'action venait souvent en double avec un device trigger), ce qui simplifie radicalement la lecture du panneau Appareils. Le second est la suppression de l'API MQTT legacy, qui rend les payloads plus prévisibles et permet aux extensions communautaires de fonctionner sans bricolage. Le troisième est la préparation du support Matter bridge prévu pour la 3.x : rester en 1.x, c'est se condamner à une migration encore plus douloureuse plus tard.

En contrepartie, la migration n'est pas anodine. Sur une installation moyenne (30 à 50 appareils Zigbee), il faut prévoir une à deux heures de cleanup post-migration : réparation des automatisations qui consomment des capteurs sensor.*_action (supprimés au profit des device triggers MQTT), reconfiguration de quelques icônes Lovelace cassées par le passage de lock à switch sur les verrous enfants, et inévitablement un ou deux appareils exotiques qui demandent un retour en mode appairage. Rien d'insurmontable, mais à ne pas faire un dimanche soir avant le boulot du lundi.

Le bon moment pour migrer en 2026 : vous êtes au moins en Z2M 1.42 (qui contient tous les patches de stabilité avant 2.0), vous avez une sauvegarde Home Assistant récente, et vous avez du temps devant vous (deux heures minimum). À reporter : si vous gérez une installation critique sans backup HA récent, ou si vous avez du matériel ancien (CC2531, CC2530) sur lequel le passage à 2.x change l'auto-détection de l'adaptateur — risque de "USB adapter discovery error" au redémarrage.

Préparer la migration : 4 étapes obligatoires

Cette préparation est non négociable. Sauter une étape, c'est accepter de potentiellement passer deux heures à essayer de récupérer un mesh Zigbee fantôme.

Étape 1 — Snapshot complet de Home Assistant. Allez dans Paramètres → Système → Sauvegardes → Créer une sauvegarde, type "Complète". Téléchargez le fichier .tar en local. C'est votre filet de sécurité absolu : si la migration vire au cauchemar, vous restaurez le snapshot et vous repartez comme avant.

Étape 2 — Sauvegarde manuelle du configuration.yaml Z2M. Sous l'add-on Home Assistant, le fichier se trouve dans /addon_configs/zigbee2mqtt/ ou /share/zigbee2mqtt/ selon votre installation. Copiez-le ailleurs (clé USB, NAS, cloud privé). La 2.x crée bien un backup automatique nommé configuration_backup_v1.yaml, mais avoir votre propre copie hors du conteneur est une assurance utile.

Étape 3 — Inventaire des entités à risque. Avant la migration, listez vos entités sensor.*_action et sensor.*_click qui apparaîtront dans vos automatisations. Le plus simple : ouvrez les Outils Développeur → États, filtrez par action ou click, capturez la liste. Ces entités vont disparaître en 2.x — vous devrez les remplacer par des device triggers MQTT (voir section 7).

Étape 4 — Vérification de la version d'origine. Z2M 1.42 ou plus récent est fortement recommandé comme point de départ. Si vous êtes encore en 1.40 ou antérieur, mettez d'abord à jour vers la dernière 1.x avant d'attaquer la 2.x. Le système de migration automatique de la 2.0 a été conçu et testé en partant d'une 1.42 propre.

Activer les flags "non-legacy" AVANT la migration

Voici le meilleur conseil que vous lirez dans cet article : activez les flags non-legacy avant de cliquer sur "Update". Ouvrez votre configuration.yaml Z2M et ajoutez (ou modifiez) ces blocs :

advanced:
  homeassistant_legacy_entity_attributes: false
  homeassistant_legacy_triggers: false
  legacy_api: false
  legacy_availability_payload: false
device_options:
  legacy: false

Redémarrez Z2M et vivez ainsi quelques jours en 1.42. Pourquoi cette étape ? Parce que la majorité des changements cassants de la 2.0 ne sont en réalité que la suppression du mode legacy. En forçant non-legacy dès la 1.42, vous découvrez les automatisations cassées dans un environnement où vous pouvez encore revenir en arrière instantanément (un toggle YAML), et vous abordez la 2.x avec un système déjà stabilisé.

Concrètement, vos sensor.*_action vont commencer à se figer ou disparaître dès l'activation des flags. Vos automatisations qui utilisent ces capteurs vont se taire. C'est exactement ce qu'on veut : repérer la casse à froid, dans une version 1.x qu'on maîtrise. Une fois toutes les automatisations migrées vers les device triggers MQTT (procédure section 7), vous pouvez enchaîner sereinement sur la 2.x.

Cette préparation rallonge la migration totale de quelques jours mais réduit le stress du jour J de 80%. Faite en condition réelle, elle vaut tout l'or du monde.

Le système de migration automatique : ce qu'il fait, ce qu'il ne fait pas

Z2M 2.0 inclut un système de migration automatique qui s'active au premier démarrage. Concrètement, à la première lecture d'un configuration.yaml en version 1, Z2M effectue trois opérations.

Première opération : il crée une copie de votre configuration sous le nom data/configuration_backup_v1.yaml. Cette sauvegarde est intacte et permet le rollback si nécessaire.

Deuxième opération : il réécrit votre configuration.yaml au format 2.x, en appliquant tous les renommages et déplacements de paramètres documentés (voir section 5). Si vous aviez advanced.baudrate: 115200, il devient automatiquement serial.baudrate: 115200.

Troisième opération : il génère un fichier data/migration-1-to-2.log détaillant chaque modification effectuée. Lisez-le après le premier démarrage — c'est votre journal de transformation. Il liste à la fois les changements appliqués et ceux qui demandent une action manuelle de votre part.

Ce que la migration automatique ne fait pas : elle ne touche jamais à votre installation Home Assistant. Vos automatisations YAML, vos cartes Lovelace, vos scripts qui référencent des entités sensor.*_action restent inchangés. Côté HA, c'est entièrement à vous de jouer. Elle ne migre pas non plus les groupes Zigbee définis directement en YAML dans la section groups: — ces groupes doivent être recréés via l'interface Z2M après migration.

Avertissement critique : ne modifiez jamais manuellement la ligne version: en haut du configuration.yaml. Elle pilote le système de migration. Une valeur incorrecte (passer manuellement de 1 à 2 sans laisser Z2M faire) corrompt durablement la configuration et rend les migrations futures défaillantes. Laissez Z2M gérer cette ligne seul.

Les 7 changements de configuration qui cassent

Voici la liste exhaustive des paramètres déplacés ou renommés en 2.0. Si vous avez activé la migration automatique, ces changements sont déjà appliqués — mais les connaître reste utile pour comprendre ce que fait Z2M et débugger les cas où la migration aurait raté un cas particulier.

1. discovery_topic Home Assistant déplacé. advanced.homeassistant_discovery_topic devient homeassistant.discovery_topic. Si vous aviez personnalisé le topic (cas courant pour ceux qui font tourner plusieurs instances Z2M), vérifiez que le déplacement s'est bien fait dans la section dédiée.

2. Baudrate déplacé. advanced.baudrate devient serial.baudrate. Idem pour advanced.rtscts qui passe en serial.rtscts. C'est cohérent avec la nouvelle structure : tout ce qui concerne le port série atterrit dans la section serial:.

3. "ban" renommé en "passlist". Le terme "ban" était trompeur (en réalité c'est une liste blanche). En 2.x, il s'appelle passlist. Si vous aviez configuré une whitelist d'IEEE adresses, elle est automatiquement migrée mais le nouveau nom est plus explicite.

4. Log level "warn" devient "warning". Si votre configuration.yaml contient log_level: warn, il faut écrire warning en 2.x. La migration automatique gère ce cas, mais c'est une source d'erreurs si vous éditez ensuite à la main.

5. permit_join réécrit en profondeur. L'ancien permit_join booléen et permit_join_timeout en secondes sont remplacés par permit_join_end qui attend un timestamp Unix. La nouvelle limite haute est de 254 secondes (limite du protocole Zigbee, encodée sur 1 octet). Sur l'interface web, le bouton "Permit join" prend cette valeur par défaut. Si vous appeliez l'API MQTT pour ouvrir l'appairage, votre payload doit changer.

6. external_converters quitte le YAML pour un dossier dédié. En 1.x, vous listiez vos convertisseurs externes dans external_converters: ['my-device.js']. En 2.x, vous déposez simplement vos fichiers .js dans data/external_converters/ et ils sont chargés automatiquement. Idem pour les extensions qui passent de data/extension/ à data/external_extensions/.

7. Topic d'état HA changé. Z2M écoutait hass/status par défaut, il écoute maintenant homeassistant/status. Si votre broker MQTT était configuré spécifiquement pour les anciens topics, à corriger.

Entités Home Assistant supprimées (et leurs remplacements)

C'est ici que se concentre la vraie casse pour 80% des utilisateurs. Quatre familles d'entités disparaissent ou changent radicalement.

Capteurs d'action et de clic. Les entités sensor.bouton_aqara_action, sensor.telecommande_ikea_click et leurs dérivées sont supprimées par défaut en 2.x. Toutes les automatisations qui se déclenchaient sur ces capteurs sont silencieusement cassées : le déclencheur ne reçoit plus rien, l'automation ne tourne plus. C'est de loin la principale source de plaintes post-migration. La solution propre est de basculer vers les MQTT device triggers (voir section 7).

Entités update fusionnées. Les anciennes update_state et update_available sont remplacées par une entité update.* unique. Si vous aviez des cartes Lovelace qui affichaient le statut de mise à jour des firmwares Zigbee, elles affichent désormais "entité indisponible". Recréez la carte sur la nouvelle entité.

Verrous enfants : lock devient switch. Toutes les entités child_lock qui étaient typées lock en 1.x deviennent des switch en 2.x. Sémantiquement c'est plus correct (un child lock n'est pas un verrou de porte), mais cela casse les icônes Lovelace et les automatisations qui appelaient lock.lock ou lock.unlock. Remplacez par switch.turn_on et switch.turn_off.

Doublons supprimés. Pour les entités exposées en tant que select, number ou button, Z2M 1.x créait souvent un doublon sensor qui exposait la même valeur. En 2.x, seule l'entité primaire reste. Si vos templates ou cartes référençaient le doublon sensor, il faut basculer sur l'entité primaire.

Réparer les automatisations cassées : le vrai chantier

La migration des sensor.*_action vers les device triggers MQTT est la partie la plus chronophage. Voici la procédure type, à appliquer pour chaque télécommande ou bouton concerné.

Avant migration (Z2M 1.x) :

automation:
  - alias: "Bouton salon - simple click"
    trigger:
      - platform: state
        entity_id: sensor.bouton_salon_action
        to: "single"
    action:
      - service: light.toggle
        target:
          entity_id: light.salon

Après migration (Z2M 2.x avec device triggers) :

automation:
  - alias: "Bouton salon - simple click"
    trigger:
      - platform: device
        domain: mqtt
        device_id: 1234abcd5678efgh   # ID de l'appareil dans HA
        type: action_single
        subtype: action_single
    action:
      - service: light.toggle
        target:
          entity_id: light.salon

Le device_id se récupère dans Outils Développeur → Modèle, en testant {{ device_id('sensor.bouton_salon') }} avec un capteur encore présent de l'appareil. Une fois la liste des automatisations à migrer réduite, le moyen le plus rapide de les recréer est de passer par l'interface graphique Home Assistant : Paramètres → Automatisations → Créer → Quand un appareil… déclenche. L'éditeur visuel propose directement la liste des actions disponibles pour chaque télécommande.

Cas particuliers fréquents. Pour les télécommandes Aqara à 4 boutons et les manettes IKEA Styrbar, chaque bouton et chaque type de pression (single, double, hold, release) génère un device trigger distinct. Comptez 8 à 16 device triggers par télécommande à recréer. Les Sonoff SNZB-01P et les boutons Tuya à 3 actions suivent la même logique.

Astuce productivité : créez une seule automation par télécommande, avec plusieurs triggers et des conditions trigger.id pour aiguiller les actions. C'est plus lisible que 16 automations distinctes par bouton.

Cas spéciaux par device

Certains appareils nécessitent une attention particulière au-delà des changements génériques. Voici les cas les plus courants en 2026.

Aqara SRTS-A01 (vanne thermostatique). La valeur de child_lock change de true/false à LOCK/UNLOCK. Vos automatisations qui testaient state == 'true' doivent passer à state == 'LOCK'.

illuminance_lux renommé en illuminance. Plusieurs dizaines de modèles de capteurs de luminosité voient leur attribut illuminance_lux renommé en illuminance : la quasi-totalité des capteurs Aqara (RTCGQ et GZCGQ), les Philips Hue (gamme 9290), la majorité des capteurs Tuya équipés de luminosité, les IKEA Tradfri, les EFEKTA et plusieurs Sonoff. Au-delà du renommage, la valeur change parfois aussi (recalibration côté firmware). Côté Home Assistant, l'entité est invalidée et l'utilisateur doit l'autoriser à nouveau (toggle "Désactivé" → "Activé" dans le panneau Appareils). Sans cette action manuelle, le capteur reste indisponible — cause numéro 2 des "mes capteurs ne remontent plus" post-migration.

Convertisseurs externes (custom converters). Si vous aviez ajouté un fichier my-custom-device.js via le paramètre external_converters, déplacez-le simplement dans le dossier data/external_converters/ et supprimez la ligne dans configuration.yaml. Z2M 2.x charge automatiquement tous les .js de ce dossier au démarrage.

Lixee ZLinky. Bonne nouvelle : le module Lixee ZLinky ne nécessite aucune action particulière en 2.x. Toutes les entités d'index, de puissance et de tarif Tempo continuent de remonter à l'identique. Le paramètre kWh_precision reste accessible dans la section "Specific Parameters" de l'appareil dans Z2M.

Dépannage : les 5 erreurs les plus fréquentes

1. "Failed to start zigbee2mqtt" au redémarrage. Cause la plus probable : votre adaptateur USB n'est plus auto-détecté car zstack n'est plus le défaut en 2.x. Forcez la valeur dans configuration.yaml en ajoutant serial: { adapter: zstack } (ou ezsp, deconz, zigate, zboss selon votre coordinateur) et redémarrez. Si vous ne savez pas quelle valeur mettre, le SLZB-06MG24 et le Sonoff Dongle Max prennent ember (anciennement ezsp), tandis que les vieux CC2531 prennent zstack.

2. Tous mes appareils sont en "unavailable" après migration. Vérifiez le topic d'état Home Assistant. Si votre configuration.yaml avait availability: activé, le passage de hass/status à homeassistant/status peut générer un blackout temporaire. Solution : redémarrer Home Assistant complètement (pas juste le serveur, le système). Au redémarrage, Z2M reçoit le bon signal et republie l'état de tous les appareils.

3. "USB adapter discovery error". En 2.x, la procédure de détection USB est plus stricte. Si votre adaptateur n'est pas reconnu, deux solutions. Solution rapide : forcer le port comme expliqué au point 1. Solution durable : si vous avez un vieux coordinateur (CC2531, CC2530, ConBee II ancien firmware), envisager une mise à jour matérielle. Notre comparatif des meilleurs coordinateurs Zigbee 2026 détaille les modèles qui fonctionnent en plug-and-play avec Z2M 2.x.

4. Permit join semble plafonné à 254 secondes. C'est normal et c'est désormais la limite haute. Cette valeur correspond à l'encodage 1 octet du protocole Zigbee (0xFE, soit 254). Si vous avez besoin d'appairer plusieurs appareils en série, déclenchez plusieurs cycles successifs plutôt que de chercher à allonger la fenêtre.

5. "configuration.yaml corrupted" ou migration qui se répète. Cause typique : vous avez modifié manuellement la ligne version: en haut du fichier. Z2M se croit en boucle de migration et casse la config. Solution : restaurez le configuration_backup_v1.yaml (créé automatiquement par la migration), supprimez la ligne version: manuellement éditée, redémarrez Z2M. La migration repart proprement.

Rollback : revenir en 1.42 si tout casse

Le rollback existe et fonctionne, à condition d'avoir suivi l'étape 1 de la préparation (snapshot HA complet). La procédure prend dix minutes et n'invalide pas le mesh Zigbee — vos appareils restent appairés au coordinateur.

Étape 1 : arrêtez l'add-on Zigbee2MQTT dans Home Assistant. Étape 2 : dans Paramètres → Modules complémentaires → Zigbee2MQTT → Configuration, downgradez la version vers la dernière 1.42.x disponible. Étape 3 : avant de relancer, remplacez le contenu de data/configuration.yaml par celui de data/configuration_backup_v1.yaml que la 2.x avait créé automatiquement. Étape 4 : redémarrez l'add-on. Vos appareils Zigbee redeviennent disponibles dans les 30 secondes.

Le mesh Zigbee lui-même n'est jamais touché par cette opération : la network_key et la table d'appairage sont stockées dans le coordinateur, pas dans Z2M. Vous pouvez basculer entre 1.x et 2.x autant de fois que nécessaire sans devoir réappairer un seul appareil. Cette propriété rassurante doit guider vos décisions : la migration n'est pas une opération sans retour.

Le seul cas où le rollback échoue concerne les nouveaux appareils inclus en 2.x avec des paramètres spécifiques 2.x : ils peuvent ne pas être reconnus correctement par la 1.42. Si vous avez ajouté de nouveaux Zigbee depuis la migration, listez-les avant de rollbacker, et soyez prêt à les réappairer en 1.x.

Bonus : faut-il en profiter pour migrer ZHA vers Z2M ?

Beaucoup d'utilisateurs ZHA se demandent, en voyant l'agitation autour de Z2M 2.x, s'il vaut le coup de migrer ZHA → Z2M maintenant. La réponse honnête est : seulement si vous avez des raisons précises de le faire. ZHA reste un excellent choix en 2026, particulièrement avec un coordinateur EFR32MG24 récent. Notre guide ZLinky détaille les critères de choix entre les deux intégrations.

Migrez vers Z2M si vous avez besoin de paramètres avancés non exposés par ZHA (réglage fin du polling, accès aux attributs internes, support de devices très spécifiques), si vous gérez plus de 50 appareils et voulez une carte mesh visualisable, ou si vous avez plusieurs instances Home Assistant à coordonner via un broker MQTT central.

Restez sur ZHA si votre installation fonctionne bien, si vous avez moins de 30 appareils, ou si vous n'avez pas envie de gérer un add-on supplémentaire. La migration ZHA → Z2M demande une réinclusion complète de tous les appareils Zigbee — c'est une opération longue (30 secondes par appareil minimum) qui n'a de sens qu'avec un vrai bénéfice à la clé.

Ce qu'il faut retenir

Zigbee2MQTT 2.x en 2026 est une version mature, stabilisée, et largement supérieure à la branche 1.x sur les aspects de configuration, de cleanup d'entités et de préparation au futur Matter bridge. Sa migration n'est pas un drame mais demande de la rigueur, particulièrement sur la réparation des automatisations consommant des sensor.*_action, qui représente 80% du temps de cleanup post-migration.

La séquence gagnante en quatre temps : sauvegarder Home Assistant et le configuration.yaml, activer les flags non-legacy en 1.42 pour repérer la casse à froid, lancer la migration automatique 2.0 et lire le migration-1-to-2.log, puis migrer les automatisations vers les device triggers MQTT à votre rythme. En cas de coup dur, le rollback vers la 1.42 fonctionne et n'invalide pas le mesh Zigbee.

Pour aller plus loin sur l'écosystème Zigbee local en 2026, deux articles complémentaires : notre comparatif des meilleurs coordinateurs Zigbee 2026 détaille les modèles compatibles plug-and-play avec Z2M 2.x (SLZB-06MG24, Connect ZBT-2, Sonoff Dongle Max), et notre guide d'intégration du Lixee ZLinky couvre la configuration ZHA et Z2M en parallèle pour le suivi de consommation Linky.

Côté communauté, le forum francophone HACF abrite les fils d'entraide les plus actifs sur les migrations en cours, et la discussion officielle GitHub #24198 reste la référence pour les breaking changes 2.0 dans leur formulation d'origine. Pour suivre les évolutions futures (3.x, support Matter bridge), abonnez-vous aux releases du repository Koenkk/zigbee2mqtt.