Mettre à jour le firmware Zigbee avec Zigbee2MQTT (OTA)

Zigbee2MQTT peut mettre à jour le firmware de la plupart de vos appareils Zigbee (ampoules, capteurs, interrupteurs) directement par les ondes, sans manipulation physique : c'est l'OTA, pour Over-The-Air. Depuis l'onglet OTA de l'appareil, un clic suffit pour lancer la mise à jour ; en coulisses, Zigbee2MQTT interroge le dépôt communautaire Koenkk/zigbee-OTA, télécharge l'image adaptée et la transfère par blocs via le réseau Zigbee. Depuis la version 2.12.0, vous pouvez même annuler une mise à jour en cours si elle bloque. Ce guide couvre l'activation, la marche à suivre, la compatibilité par marque, et l'automatisation dans Home Assistant.

Qu'est-ce qu'une mise à jour OTA Zigbee, et pourquoi Zigbee2MQTT change la donne

Une mise à jour OTA (Over-The-Air) transmet un nouveau firmware à un appareil Zigbee directement via le réseau radio, sans câble ni reset manuel. Contrairement au Wi-Fi, la mise à jour transite par le coordinateur puis par les routeurs du maillage Zigbee avant d'atteindre l'appareil cible.

Zigbee2MQTT récupère par défaut les images depuis le dépôt communautaire Koenkk/zigbee-OTA, qui centralise les firmwares publiés par les fabricants (IKEA, Sonoff, Aqara, etc.) sous un format unique exploitable par n'importe quel coordinateur. Le processus dure de 10 à 100 minutes selon la taille du firmware, la qualité du signal et le type d'appareil : un module sur secteur reçoit généralement l'image plus vite qu'un capteur sur batterie, qui doit économiser son énergie pendant le transfert.

Ne confondez pas cette mise à jour avec le firmware du coordinateur lui-même, abordé dans notre article sur Zigbee 4.0 : ici, il s'agit du firmware de l'appareil final — ampoule, capteur, interrupteur —, pas du dongle qui pilote l'ensemble du réseau.

Activer et vérifier les mises à jour OTA dans Zigbee2MQTT

Par défaut, Zigbee2MQTT ignore les demandes de vérification automatique envoyées par les appareils compatibles. Pour les activer, ajoutez la section ota dans configuration.yaml, redémarrez Zigbee2MQTT, puis ouvrez la fiche d'un appareil et cliquez sur l'onglet OTA pour vérifier manuellement si une mise à jour est disponible.

ota:
  update_check_interval: 1440   # vérification automatique une fois par jour (en minutes)
  disable_automatic_update_check: false

Les appareils compatibles OTA envoient périodiquement une demande de vérification ; Zigbee2MQTT interroge alors le dépôt zigbee-OTA et publie le résultat sur le topic MQTT de l'appareil, avec un état available si une image existe. Vous pouvez aussi forcer une vérification manuelle sans attendre le cycle automatique, directement depuis l'interface web ou par un message MQTT dédié.

Si un appareil semble ignorer vos demandes, passez temporairement le niveau de log de Zigbee2MQTT sur info : c'est le seul réglage qui affiche clairement le détail des échanges OTA (requête reçue, image trouvée ou non, blocs transférés) dans les logs. Sans ce niveau de détail, un échec silencieux ressemble à s'y méprendre à une absence de réponse, alors que la cause réelle — image introuvable, version déjà à jour, appareil hors de portée — est en fait explicitement journalisée.

Si vous venez tout juste de basculer sous Zigbee2MQTT 2.x, notre guide de migration couvre les changements de configuration à connaître avant d'aller plus loin — les entités renommées lors du passage en 2.x n'ont toutefois aucun impact sur le fonctionnement de l'OTA.

Nouveau avec la 2.12.x : annuler une mise à jour OTA en cours

Zigbee2MQTT 2.12.0, sortie le 9 juin 2026 et actuellement la version stable la plus récente, a ajouté la possibilité d'annuler une mise à jour OTA déjà lancée. Auparavant, une mise à jour bloquée ou démarrée par erreur devait aller à son terme ou échouer d'elle-même : il n'existait aucun moyen propre de l'interrompre en cours de route.

Cette même version 2.12.0 corrige par ailleurs une erreur MALFORMED_COMMAND qui affectait spécifiquement les mises à jour firmware des appareils Philips Hue — un correctif direct sur l'un des points de friction évoqués plus bas dans ce guide.

La commande passe par le topic MQTT zigbee2mqtt/bridge/request/device/ota_update/update/abort, avec le même payload {"id": "nom_ou_adresse_ieee"} que pour lancer ou vérifier une mise à jour. Aucun des guides francophones consultés pour cet article ne mentionne encore cette fonctionnalité à ce jour : c'est l'un des ajouts les plus utiles de ce cycle de versions pour qui gère un parc d'appareils Zigbee un peu conséquent, où une mise à jour mal chronométrée (juste avant de quitter la maison, par exemple) devenait auparavant impossible à stopper.

Mettre à jour un appareil pas à pas (interface et commandes MQTT)

Deux méthodes coexistent dans Zigbee2MQTT : l'interface web, avec l'onglet OTA d'un appareil et ses boutons Vérifier puis Mettre à jour, pour un usage ponctuel ; et les topics MQTT bruts, pour scripter ou automatiser le processus depuis Home Assistant, Node-RED, ou un script maison.

Action	Topic MQTT
Vérifier une mise à jour	bridge/request/device/ota_update/check
Lancer une mise à jour	bridge/request/device/ota_update/update
Annuler une mise à jour en cours (2.12.x+)	bridge/request/device/ota_update/update/abort
Revenir à la version précédente	bridge/request/device/ota_update/update/downgrade
Planifier au prochain contact de l'appareil	bridge/request/device/ota_update/schedule

La mise à jour publie sa progression sur le topic de l'appareil, avec un état updating accompagné d'un pourcentage et d'un temps restant estimé, réévalué à chaque rapport (environ toutes les 30 secondes). Pour un appareil sur batterie qui ne répond pas immédiatement à une demande manuelle, la planification attend la prochaine requête spontanée de l'appareil au lieu d'exiger une réponse immédiate — utile pour certaines télécommandes qui ne se réveillent que sur pression d'un bouton.

Deux précautions évitent la majorité des blocages sur les appareils sur batterie : vérifiez que le niveau de charge dépasse 70% avant de lancer une mise à jour (une batterie faible qui s'épuise en cours de transfert est la cause la plus fréquente d'échec sur les capteurs), et forcez un réveil de l'appareil — appui sur un bouton, ouverture d'un contact — juste avant d'envoyer la demande, plutôt que d'attendre passivement son prochain rapport spontané.

Compatibilité OTA par marque : IKEA, Sonoff, Aqara, Tuya, Philips Hue

Le support OTA varie fortement d'un fabricant à l'autre. Selon la liste des appareils supportés de zigbee2mqtt.io et les retours de la communauté HACF et r/homeassistant, IKEA Tradfri publie des mises à jour fréquentes et fiables ; Sonoff couvre la majorité de ses modèles récents ; Aqara et Tuya restent variables selon les gammes ; Philips Hue, elle, pose un problème particulier via Zigbee2MQTT.

Marque	Support OTA via Zigbee2MQTT
IKEA Tradfri	Excellent, mises à jour fréquentes
Sonoff	Bon support sur les modèles récents
Aqara / Xiaomi	Variable selon les modèles
Tuya	Limité, dépend du fabricant d'origine du module
Philips Hue	Partiel et risqué — voir ci-dessous

domocraft a déjà documenté ce point précis dans son guide de migration des ampoules Hue vers Zigbee2MQTT : le support OTA via Z2M pour les appareils Hue reste partiel, et des cas de bricking sont documentés par la communauté. Si vous migrez des ampoules Hue depuis le pont officiel, mettez à jour leur firmware via l'application Hue avant la bascule, pas après — c'est la seule marque de ce tableau où l'ordre des opérations change vraiment le résultat.

Automatiser une alerte Home Assistant quand une mise à jour est disponible

Quand l'intégration Home Assistant de Zigbee2MQTT est activée, chaque appareil compatible OTA expose une entité update.* standard, au même titre qu'une mise à jour d'add-on ou d'intégration HACS. Cette entité permet de construire une automatisation de notification sans surveiller manuellement chaque appareil un par un.

automation:
  - alias: "Notifier mise à jour firmware Zigbee disponible"
    trigger:
      - platform: state
        entity_id: update.capteur_salon_firmware
        to: "on"
    action:
      - service: notify.notify
        data:
          message: >
            Mise à jour firmware disponible pour
            {{ trigger.to_state.attributes.friendly_name }}

Pour surveiller plusieurs appareils sans dupliquer l'automatisation, groupez les entités update.* concernées dans un groupe Home Assistant et déclenchez sur l'état du groupe plutôt que sur chaque entité individuellement — plus simple à maintenir à mesure que le parc d'appareils grandit.

Que faire en cas d'échec, et peut-on revenir en arrière ?

Un échec OTA ne corrompt généralement pas l'appareil : le firmware précédent reste actif tant que la nouvelle image n'est pas validée en fin de transfert. Rapprochez l'appareil du coordinateur ou d'un routeur, redémarrez Zigbee2MQTT, puis relancez la mise à jour un appareil à la fois plutôt qu'en série.

Le dépôt zigbee-OTA conserve généralement la dernière version et l'avant-dernière, ce qui permet un retour en arrière via le même mécanisme que la mise à jour, en ciblant les topics dédiés au downgrade. Le firmware plus ancien n'est toutefois pas garanti disponible indéfiniment, et certains appareils refusent de repasser sous une version antérieure — la spécification Zigbee autorise le downgrade, mais chaque fabricant reste libre de le bloquer côté firmware.

Pour une installation sans accès internet, Zigbee2MQTT accepte un index OTA personnalisé pointant vers des fichiers de firmware stockés localement — utile pour un déploiement isolé du réseau, au prix d'une maintenance manuelle du catalogue d'images à tenir soi-même à jour.

Des échecs répétés, en particulier sur des appareils éloignés, trahissent souvent un réseau Zigbee mal maillé ou un coordinateur ancien à faible portée plutôt qu'un problème de mise à jour en tant que tel. Ajouter quelques routeurs (prises ou ampoules sur secteur) ou passer sur un coordinateur plus récent et à meilleure portée résout la majorité de ces cas avant même de relancer la mise à jour.

Le SMLIGHT SLZB-06MG24, alimenté en PoE et basé sur la puce EFR32MG24, est une option fréquemment citée pour ce cas précis : portée nettement supérieure à un simple dongle USB, sans dépendre du bus USB d'un serveur Home Assistant parfois source d'instabilité. Ce n'est pas un prérequis pour l'OTA en tant que tel, seulement un correctif possible quand le maillage est la cause réelle des échecs.

Questions fréquentes

Faut-il toujours mettre à jour le firmware de ses appareils Zigbee ?

Non. Si l'appareil fonctionne correctement et que la mise à jour ne corrige pas un problème identifié, il n'est pas indispensable de la faire. Mettez à jour en priorité les correctifs de sécurité, les bugs qui vous affectent réellement, ou une fonctionnalité dont vous avez besoin — pas par principe systématique.

Que faire si une mise à jour OTA Zigbee échoue ?

Rapprochez l'appareil du coordinateur ou d'un routeur, vérifiez le niveau de batterie (70% minimum recommandé), redémarrez Zigbee2MQTT, puis relancez la mise à jour. Le firmware précédent reste normalement actif tant que le transfert n'est pas validé en totalité : l'appareil ne reste presque jamais bloqué dans un état intermédiaire.

Peut-on annuler une mise à jour OTA en cours avec Zigbee2MQTT ?

Oui, depuis la version 2.12.0. Publiez un message sur le topic zigbee2mqtt/bridge/request/device/ota_update/update/abort avec l'identifiant de l'appareil. Avant cette version, il fallait laisser la mise à jour aller à son terme ou échouer d'elle-même — aucun moyen propre n'existait pour l'interrompre en cours de route.

Zigbee2MQTT ou ZHA : lequel gère le mieux les mises à jour OTA ?

Les deux supportent l'OTA nativement depuis plusieurs années. ZHA affiche un simple bouton Mettre à jour dans l'interface Home Assistant ; Zigbee2MQTT expose en plus les topics MQTT bruts — annulation, planification, downgrade —, plus flexibles pour scripter ou automatiser, au prix d'une configuration initiale légèrement plus technique.

Conclusion

L'OTA Zigbee via Zigbee2MQTT n'a plus grand-chose à envier aux mises à jour Wi-Fi classiques : activation en une ligne de configuration, suivi de progression en temps réel, et désormais la possibilité d'annuler une mise à jour qui tourne mal. Deux réserves comptent vraiment au quotidien : un réseau Zigbee mal maillé sabote plus de mises à jour qu'un firmware capricieux, et les ampoules Philips Hue restent le cas particulier à traiter à part, en amont, via l'application du fabricant plutôt que par Zigbee2MQTT. Si vous construisez vos propres appareils Zigbee en DIY, gardez aussi à l'esprit que l'OTA n'est pas encore au rendez-vous côté ESPHome, comme détaillé dans notre guide sur les devices Zigbee natifs ESP32-C6/H2.