Résolution du problème OTA du SNZB-02DR2 : amélioration du support Telink OTA dans Home Assistant

Résumé

En septembre 2025, le SNZB-02DR2 nouvellement sorti fonctionnait comme prévu sur la passerelle SONOFF, mais des problèmes OTA ont commencé à apparaître sur Home Assistant. Les symptômes signalés comprenaient des échecs de vérification de mise à jour, des mises à niveau atteignant 100 % sans changement de la version du firmware installé, et des notifications push de firmware manquantes. Le problème est apparu à la fois dans Zigbee2MQTT et ZHA.
Le SNZB-02DR2 est basé sur un SoC Telink. Après examen des journaux, de la structure de l'image du firmware et du comportement de la plateforme, l'équipe SONOFF a retracé le problème à des changements dans le format de chiffrement OTA utilisé dans le SDK Telink, qui ont introduit un écart de compatibilité avec la logique d'analyse OTA existante. Les corrections ont été déployées en deux étapes : d'abord côté Zigbee2MQTT pour l'emballage chiffré spécifique au fournisseur Telink 0xf000, puis côté ZHA / zigpy pour l'analyse OTA chiffrée Telink. Des contributeurs de la communauté ont ensuite étendu le travail avec des mises à jour de la taille des blocs OTA, du schéma et du fournisseur.

Exposition et symptômes

En septembre 2025, le SNZB-02DR2 nouvellement sorti fonctionnait normalement sur la passerelle SONOFF, mais des échecs liés à l'OTA sont apparus sur Home Assistant. Les principaux symptômes étaient :

• échecs des vérifications de mise à jour
• transferts OTA expirant ou se bloquant
• progression de la mise à jour atteignant 100 % alors que la version du firmware restait inchangée
• appareils affichant Firmware : Inconnu
• notifications push de firmware manquantes alors qu'une mise à jour était attendue

Ces symptômes sont apparus à la fois dans Zigbee2MQTT et ZHA. D'après les journaux, les images du firmware et le comportement en temps réel, l'équipe SONOFF a identifié le problème comme étant une incompatibilité OTA liée au format de chiffrement du SDK Telink.

Types d'échecs OTA

Ce problème se divise en trois catégories :

Le premier est un échec du transport sans fil, généralement visible sous forme de délais d'attente, de blocages ou de retransmissions excessives. Les causes courantes incluent les interférences à 2,4 GHz, une faible intensité du signal et une longue distance entre l'appareil et le coordinateur.

Le second est un échec d'analyse de l'image OTA. Dans ce cas, les vérifications de mise à jour échouent tôt, ou l'image est transférée mais échoue ensuite lors de l'analyse, du découpage ou de la validation.

Le troisième est un décalage de version et de configuration. Des exemples typiques incluent des conteneurs fonctionnant encore avec d'anciennes images, des paramètres du fournisseur OTA ne correspondant pas à la version installée, ou des métadonnées d'index incorrectes. Le symptôme habituel est que l'environnement a été mis à jour, mais que la correction ne semble pas prendre effet.

Désalignement de l'emballage et de l'analyse OTA Telink

La cause principale a été attribuée à des changements dans le format de chiffrement OTA utilisé par le SDK Telink.

Un sous-élément OTA Zigbee standard peut être simplifié comme suit :

Dans la disposition standard, le champ Longueur décrit seulement la taille des données suivantes. Il n'inclut pas l'ID de Tag ni le champ Longueur lui-même.

Dans le packaging chiffré OTA Telink, surtout dans les éléments spécifiques au fournisseur comme 0xf000, la disposition contient un champ supplémentaire :

Le Tag Info inséré modifie la disposition physique du flux de données, tandis que la signification de la Longueur n'est pas interprétée correctement par les parseurs qui suivent encore le chemin standard. C'est ce qui cause le décalage.

Si un parseur lit encore l'image comme un OTA ZCL standard, le calcul du décalage, la gestion de la longueur et le découpage des données seront erronés. Les résultats typiques sont :

• erreurs de décalage ou de limites lors de l'inspection de l'image OTA
• transfert réussi d'une image corrompue en mémoire
• rejet par l'appareil lors de la phase finale de validation

Le problème est donc un décalage d'analyse causé par le format de chiffrement OTA mis à jour dans le SDK Telink.

Zigbee2MQTT : Diagnostic et correction

problème #9963

Le 9 septembre 2025, le problème #9963 (https://github.com/Koenkk/zigbee-herdsman-converters/issues/9963) a été ouvert dans zigbee-herdsman-converters sous le titre Quelques questions sur la méthode de chiffrement OTA.

Le problème montrait déjà l'échec principal : lors des vérifications de mise à jour OTA, l'analyse atteignait tagID : 0xf000, puis échouait avec une erreur de décalage hors limites. Il documentait aussi les conclusions de l'équipe SONOFF :
• le problème était lié au packaging de chiffrement OTA dans le SDK Telink
• la structure de l'image contenait un champ Tag Info supplémentaire
• la correction de l'analyse pouvait être vérifiée en modifiant parseSubElement
• OTA complété avec succès après l'ajustement du parseur

PR #9984

Basé sur l'analyse dans le problème, l'équipe SONOFF a soumis la PR #9984 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/9984), intitulée ajout du code de gestion OTA avec Telink OTA.

La PR a été fusionnée le 13-09-2025, avec le commit de fusion 6cb56489bc9e9ea4c2df99f9499d61d9c10671f0.
La correction n'a pas ajouté une branche spécifique à un appareil pour un seul produit. Elle a ajouté la compatibilité de l'analyse pour le packaging OTA Telink. La portée était donc plus large qu'un seul modèle et couvrait l'impact de compatibilité introduit par les changements du format de chiffrement OTA dans le SDK Telink.

Version 25.25.0

La PR de version #10005 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/10005) pour zigbee-herdsman-converters a été fusionnée le 13-09-2025, correspondant à la version 25.25.0.

Les notes de version incluaient explicitement :
• Prise en charge des OTA Telink chiffrés (#9984)

Cela a fait des OTA Telink chiffrés une partie de la branche principale de Zigbee2MQTT.

Progression ZHA / zigpy

Une fois le problème diagnostiqué et corrigé côté Zigbee2MQTT, il était clair que le problème n’était pas lié à un seul chemin d’intégration. C’était un écart de compatibilité plus large dans la façon dont Home Assistant gérait les OTA Telink.

ZHA s’appuie sur zigpy pour le traitement OTA, donc la cause racine confirmée dans Zigbee2MQTT devait aussi être traitée dans le parseur OTA de zigpy.

PR #1734

Basé sur le problème de structure OTA Telink exposé dans Zigbee2MQTT, l’équipe SONOFF a soumis la PR #1734 (https://github.com/zigpy/zigpy/pull/1734) à zigpy. La proposition ajoutait un support d’analyse dédié pour les OTA Telink et propageait le drapeau de chiffrement associé.

PR #1736

Après la discussion autour de la PR #1734, zigpy a adopté une implémentation différente dans la PR #1736 (https://github.com/zigpy/zigpy/pull/1736), intitulée Analyse des fichiers OTA Telink chiffrés.

La PR a été fusionnée le 03-01-2026, avec le commit de fusion 78a0b4da658deef0e7e88ec3bad0c80f20a19ea9.

Les principaux changements dans la version #1736 étaient :
• détection et analyse directe des images OTA Telink chiffrées
• suppression de la dépendance stricte aux métadonnées externes pour identifier les images Telink chiffrées
• reconnaissance native des OTA Telink dans le parseur

Cela a permis au parseur d’identifier ces images directement au lieu de se fier uniquement à des conditions externes.

Version zigpy 0.90.0

zigpy 0.90.0 a été publié le 03-01-2026, et ses notes de version incluaient explicitement :
• Analyse des fichiers OTA Telink chiffrés par @puddly dans la version #1736 Lien de la version : zigpy 0.90.0 (https://github.com/zigpy/zigpy/releases/tag/0.90.0) La version 0.90.0 est la version clé où l’analyse des OTA Telink chiffrés est devenue disponible dans ZHA / zigpy.

Travail de suivi communautaire

La version 0.90.0 a résolu le problème principal d'analyse pour l'OTA Telink chiffrée, mais elle ne couvrait pas tous les détails de compatibilité. La communauté a poursuivi avec des corrections complémentaires.

Correction de la taille des blocs OTA

Dans la PR #1781 (https://github.com/zigpy/zigpy/pull/1781), des contributeurs communautaires ont traité la compatibilité de la taille des blocs OTA.
La PR, intitulée Augmentation de la taille maximale des blocs OTA, a été fusionnée le 2026-03-02. Certains appareils Telink demandent un bloc OTA de 48 octets, alors que la limite précédente était de seulement 40 octets. Même avec une analyse d'image correcte, la mise à jour peut échouer si les tailles de bloc demandées et livrées ne correspondent pas.
Cela montre que la compatibilité Telink OTA ne concerne pas seulement l'analyse d'image. Elle inclut aussi la correspondance des paramètres de transport.

Alignement du schéma OTA et du fournisseur

La PR #1782 (https://github.com/zigpy/zigpy/pull/1782) a ensuite mis à jour le schéma zigpy-ota en version 2.

Même lorsque le framework prend déjà en charge l'analyse OTA Telink, les utilisateurs peuvent encore voir un firmware inconnu, des notifications push manquantes ou aucun changement effectif si les métadonnées OTA, la configuration du fournisseur et la version installée de zigpy ne sont pas synchronisées.

• la version 0.90.0 a résolu le problème principal d'analyse OTA Telink chiffrée

• des modifications communautaires ultérieures ont complété la taille des blocs, le schéma et les détails de distribution OTA

• Le support ZHA pour Telink OTA a mûri par étapes plutôt que par un seul correctif

Raisons courantes pour lesquelles la correction ne prend toujours pas effet

« Pris en charge en amont » ne signifie pas que l'environnement local se comportera immédiatement correctement. Les causes les plus courantes en dernière étape sont ci-dessous.

1. La version d'exécution n'est pas celle attendue par l'utilisateur

C'est courant dans les déploiements Docker. Un utilisateur peut mettre à jour des fichiers sur l'hôte ou croire que le code a déjà été mis à jour, alors que le conteneur exécute encore des versions plus anciennes des paquets. Si le zigpy d'exécution ou le paquet associé n'a pas changé, la correction en amont n'apparaîtra pas localement.

2. Seule une partie de la pile a été mise à jour

Par exemple, Home Assistant peut être mis à jour alors que zigpy est encore en dessous de la version requise, ou les fichiers OTA locaux et la configuration du fournisseur peuvent encore suivre l'ancien chemin. Dans ce cas, l'environnement se comporte toujours comme si la correction manquait.

3. Les métadonnées du fournisseur OTA ou de l'index sont toujours incorrectes

Même lorsque les versions de la plateforme sont correctes, la plateforme peut ne pas identifier ou pousser le firmware si manufacturerCode, imageType, fileVersion, sha ou les chemins de fichiers dans index.json sont incohérents.

4. L'appareil n'a pas envoyé de nouvelle requête OTA

La préparation côté serveur ne signifie pas que l'appareil demandera immédiatement une nouvelle image. Si l'appareil n'envoie pas à nouveau une requête Query Next Image, la poussée du firmware peut sembler absente.

5. Des problèmes de transport sans fil subsistent

Même après correction de la compatibilité du parseur, un signal faible, une longue distance, des interférences et des retransmissions excessives peuvent toujours interrompre l'OTA. Ce sont des problèmes de transport distincts qui ne disparaissent pas avec la correction du parseur.

Le support en amont est une condition nécessaire au succès de l'OTA. Que la correction fonctionne réellement sur le terrain dépend de la chaîne de versions, de la configuration, de l'état du conteneur et des conditions sans fil.

Dépannage côté utilisateur

Si l'environnement SNZB-02DR2 a déjà été mis à jour vers des versions incluant les corrections pertinentes, mais que l'OTA échoue toujours, que le firmware n'est pas poussé, que les mises à jour restent bloquées ou que la version ne change pas après la mise à jour, les vérifications suivantes doivent être effectuées dans l'ordre :

1. Confirmez les versions réelles de la plateforme et des composants

• Zigbee2MQTT doit être au moins en version 25.25.0

• ZHA / zigpy doit être au moins en version 0.90.0

2. Confirmez que l'image du conteneur ou l'environnement d'exécution a bien été mis à jour

3. Confirmez que les paramètres du fournisseur OTA, les données locales de l'index OTA et les métadonnées du firmware sont cohérents

4. Déclenchez une nouvelle requête OTA depuis l'appareil, par exemple en coupant puis rétablissant l'alimentation pour qu'il envoie une requête Query Next Image

5. Vérifiez la puissance du signal, la distance et les interférences sur 2,4 GHz

Conclusion

La correction OTA concernant le SNZB-02DR2 a commencé avec des échecs observés lors de déploiements réels. La cause principale a ensuite été identifiée comme un écart de compatibilité entre les changements de format de chiffrement OTA dans le SDK Telink et le comportement du parseur existant.

De Zigbee2MQTT #9963 -> #9984 -> 25.25.0, à ZHA / zigpy #1734 -> #1736 -> 0.90.0, puis aux travaux communautaires ultérieurs sur la taille des blocs OTA, le schéma et la gestion des fournisseurs, le résultat est un support OTA Telink plus large et plus stable dans Home Assistant.

Pour les fournisseurs d'appareils, le support de compatibilité ne consiste pas seulement à fournir une solution temporaire. Il nécessite également de remonter le problème dans l'écosystème en amont afin que la correction fasse partie intégrante de la plateforme elle-même.