Solucionando el problema OTA del SNZB-02DR2: Mejorando el soporte de Home Assistant para Telink OTA

Resumen

En septiembre de 2025, el recién lanzado SNZB-02DR2 funcionó como se esperaba en la propia pasarela de SONOFF, pero comenzaron a aparecer problemas OTA en Home Assistant. Los síntomas reportados incluían fallos en las comprobaciones de actualización, actualizaciones que alcanzaban el 100% sin cambiar la versión de firmware instalada y notificaciones push de firmware faltantes. El problema apareció tanto en Zigbee2MQTT como en ZHA.
SNZB-02DR2 está construido sobre un SoC Telink. Tras revisar registros, estructura de la imagen de firmware y comportamiento de la plataforma, el equipo de SONOFF rastreó el problema a cambios en el formato de cifrado OTA usado en el SDK de Telink, que introdujeron una brecha de compatibilidad con la lógica de análisis OTA existente. Las correcciones se implementaron en dos etapas: primero en el lado de Zigbee2MQTT para el empaquetado cifrado específico del proveedor Telink 0xf000, luego en el lado de ZHA / zigpy para el análisis OTA cifrado de Telink. Posteriormente, colaboradores de la comunidad ampliaron el trabajo con actualizaciones en el tamaño de bloque OTA, esquema y proveedor.

Exposición y síntomas

En septiembre de 2025, el recién lanzado SNZB-02DR2 funcionaba normalmente en la propia pasarela de SONOFF, pero aparecieron fallos relacionados con OTA en Home Assistant. Los síntomas principales fueron:

• fallos en las comprobaciones de actualización
• transferencias OTA que se agotan o se bloquean
• progreso de actualización alcanzando el 100% mientras la versión del firmware permanecía sin cambios
• dispositivos mostrando Firmware: Desconocido
• notificaciones push de firmware faltantes cuando se esperaba una actualización

Estos síntomas aparecieron tanto en Zigbee2MQTT como en ZHA. Basándose en registros, imágenes de firmware y comportamiento en tiempo de ejecución, el equipo de SONOFF redujo el problema a la compatibilidad OTA relacionada con el formato de cifrado del SDK de Telink.

Tipos de fallos OTA

Este problema se divide en tres categorías:

El primero es la falla en el transporte inalámbrico, típicamente vista como tiempos de espera, bloqueos o retransmisiones excesivas. Las causas comunes incluyen interferencia en 2.4 GHz, señal débil y larga distancia entre el dispositivo y el coordinador.

El segundo es la falla en el análisis de la imagen OTA. En este caso, las comprobaciones de actualización fallan temprano, o la imagen se transfiere pero luego falla durante el análisis, segmentación o validación.

El tercero es la incompatibilidad de versión y configuración. Ejemplos típicos incluyen contenedores que aún ejecutan imágenes antiguas, configuraciones del proveedor OTA que no coinciden con la versión instalada o metadatos de índice incorrectos. El síntoma habitual es que el entorno se ha actualizado, pero la corrección no parece surtir efecto.

Desalineación en el empaquetado y análisis OTA de Telink

La causa raíz se rastreó a cambios en el formato de cifrado OTA utilizado por el SDK de Telink.

Un subelemento estándar de OTA Zigbee se puede simplificar como:

En la disposición estándar, el Campo de Longitud describe solo el tamaño de los Datos siguientes. No incluye el ID de Etiqueta ni el Campo de Longitud en sí.

En el empaquetado cifrado OTA de Telink, especialmente en elementos específicos del proveedor como 0xf000, la disposición contiene un campo extra:

La Información de Etiqueta insertada cambia la disposición física del flujo de datos, mientras que el significado de Longitud no es interpretado correctamente por analizadores que aún siguen el camino estándar. Eso es lo que causa la descoordinación del desplazamiento.

Si un analizador aún lee la imagen como OTA estándar ZCL, el cálculo del desplazamiento, el manejo de la longitud y el corte de datos serán incorrectos. Los resultados típicos son:

• errores de desplazamiento o límites durante la inspección de la imagen OTA
• transferencia exitosa de una imagen corrupta en memoria
• rechazo por parte del dispositivo durante la etapa final de validación

Por lo tanto, el problema es una descoordinación en el análisis causada por el formato actualizado de cifrado OTA en el SDK de Telink.

Zigbee2MQTT: Diagnóstico y corrección

problema #9963

El 9 de septiembre de 2025, se abrió el problema #9963 (https://github.com/Koenkk/zigbee-herdsman-converters/issues/9963) en zigbee-herdsman-converters bajo el título Algunas preguntas sobre el método de cifrado OTA.

El problema ya mostraba la falla principal: durante las comprobaciones de actualización OTA, el análisis alcanzó tagID:0xf000, luego falló con un error de desplazamiento fuera de rango. También documentó las conclusiones del equipo SONOFF:
• el problema estaba relacionado con el empaquetado de cifrado OTA en el SDK de Telink
• la estructura de la imagen contenía un campo extra de Información de Etiqueta
• la corrección del análisis pudo verificarse cambiando parseSubElement
• OTA completado con éxito tras el ajuste del analizador

PR #9984

Basado en el análisis del problema, el equipo de SONOFF presentó la PR #9984 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/9984), titulada añadir código de manejo OTA con Telink OTA.

La PR se fusionó el 13-09-2025, con el commit de fusión 6cb56489bc9e9ea4c2df99f9499d61d9c10671f0.
La corrección no añadió una rama específica para un dispositivo para un solo producto. Añadió compatibilidad de análisis para el empaquetado OTA de Telink. Por lo tanto, el alcance fue más amplio que un modelo y cubrió el impacto de compatibilidad introducido por los cambios en el formato de cifrado OTA en el SDK de Telink.

Lanzamiento 25.25.0

El PR de lanzamiento #10005 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/10005) para zigbee-herdsman-converters fue fusionado el 2025-09-13, correspondiente a la versión 25.25.0.

Las notas de lanzamiento incluyeron explícitamente:
• Soporte para OTA cifrados de Telink (#9984)

Esto hizo que los OTA cifrados de Telink formaran parte de la línea principal de Zigbee2MQTT.

Progresión de ZHA / zigpy

Una vez diagnosticado y corregido el problema en el lado de Zigbee2MQTT, quedó claro que el problema no estaba ligado a una sola ruta de integración. Era una brecha de compatibilidad más amplia en cómo Home Assistant manejaba OTA de Telink.

ZHA depende de zigpy para el procesamiento de OTA, por lo que la causa raíz confirmada en Zigbee2MQTT también tuvo que ser abordada en el analizador OTA de zigpy.

PR #1734

Basado en el problema de la estructura OTA de Telink expuesto en Zigbee2MQTT, el equipo SONOFF presentó el PR #1734 (https://github.com/zigpy/zigpy/pull/1734) a zigpy. La propuesta añadió soporte dedicado para el análisis de OTA de Telink y propagó la bandera de cifrado relacionada.

PR #1736

Después de la discusión en #1734, zigpy adoptó una implementación diferente en el PR #1736 (https://github.com/zigpy/zigpy/pull/1736), titulado Analizar archivos OTA cifrados de Telink.

El PR fue fusionado el 2026-01-03, con el commit de fusión 78a0b4da658deef0e7e88ec3bad0c80f20a19ea9.

Los principales cambios en #1736 fueron:
• detección y análisis directo de imágenes OTA cifradas de Telink
• eliminación de la dependencia estricta de metadatos externos para identificar imágenes cifradas de Telink
• reconocimiento nativo de OTA de Telink dentro del analizador

Esto permitió que el analizador identificara estas imágenes directamente en lugar de depender solo de condiciones externas.

Lanzamiento de zigpy 0.90.0

zigpy 0.90.0 fue lanzado el 2026-01-03, y sus notas de lanzamiento incluyeron explícitamente:
• Analizar archivos OTA cifrados de Telink por @puddly en #1736 Enlace de la versión: zigpy 0.90.0 (https://github.com/zigpy/zigpy/releases/tag/0.90.0) 0.90.0 es la versión clave donde el análisis de OTA cifrados de Telink se hizo disponible en ZHA / zigpy.

Trabajo de seguimiento de la comunidad

La versión 0.90.0 resolvió el problema principal de análisis para OTA Telink cifrada, pero no cubrió todos los detalles de compatibilidad. La comunidad continuó con correcciones posteriores.

Corrección del tamaño de bloque OTA

En el PR #1781 (https://github.com/zigpy/zigpy/pull/1781), los colaboradores de la comunidad abordaron la compatibilidad del tamaño de bloque OTA.
El PR, titulado Aumentar el límite de tamaño de bloque OTA, fue fusionado el 2026-03-02. Algunos dispositivos Telink solicitan un bloque OTA de 48 bytes, mientras que el límite anterior era solo de 40 bytes. Incluso con un análisis correcto de la imagen, la actualización puede fallar si los tamaños de bloque solicitados y entregados no coinciden.
Esto muestra que la compatibilidad con OTA Telink no solo se trata del análisis de imágenes. También incluye la coincidencia de parámetros de transporte.

Alineación del esquema OTA y del proveedor

El PR #1782 (https://github.com/zigpy/zigpy/pull/1782) actualizó el esquema zigpy-ota a la versión 2.

Incluso cuando el framework ya soporta el análisis de OTA Telink, los usuarios pueden seguir viendo firmware desconocido, notificaciones push faltantes o ningún cambio efectivo si los metadatos OTA, la configuración del proveedor y la versión instalada de zigpy no están sincronizados.

• La versión 0.90.0 resolvió el problema principal de análisis de OTA Telink cifrada

• cambios posteriores de la comunidad completaron el tamaño del bloque, el esquema y los detalles de distribución OTA

• El soporte ZHA para Telink OTA maduró en etapas en lugar de en un solo parche

Razones comunes por las que la corrección aún no surte efecto

“Compatible con la versión original” no significa que el entorno local se comporte correctamente de inmediato. Las causas más comunes en la última etapa son las siguientes.

1. La versión en tiempo de ejecución no es la que el usuario espera

Esto es común en despliegues con Docker. Un usuario puede actualizar archivos en el host o creer que el código ya ha sido actualizado, mientras el contenedor sigue ejecutando versiones antiguas de los paquetes. Si la versión en tiempo de ejecución de zigpy o paquetes relacionados no ha cambiado, la corrección original no aparecerá localmente.

2. Solo una parte de la pila ha sido actualizada

Por ejemplo, Home Assistant puede actualizarse mientras zigpy aún está por debajo de la versión requerida, o los archivos OTA locales y la configuración del proveedor pueden seguir usando la ruta antigua. En ese caso, el entorno sigue comportándose como si la corrección no estuviera aplicada.

3. El proveedor OTA o los metadatos del índice aún son incorrectos

Incluso cuando las versiones de la plataforma son correctas, la plataforma puede fallar al identificar o enviar el firmware si manufacturerCode, imageType, fileVersion, sha o las rutas de archivo en index.json son inconsistentes.

4. El dispositivo no envió una nueva consulta OTA

La preparación del servidor no significa que el dispositivo solicitará inmediatamente una nueva imagen. Si el dispositivo no envía nuevamente la solicitud Query Next Image Request, el envío del firmware aún puede parecer ausente.

5. Aún existen problemas de transporte inalámbrico

Incluso después de corregir la compatibilidad del análisis, la señal débil, la larga distancia, la interferencia y las retransmisiones excesivas aún pueden interrumpir OTA. Estos son problemas de transporte separados y no desaparecen cuando se corrige el problema de análisis.

El soporte ascendente es una condición necesaria para el éxito de OTA. Si la corrección realmente funciona en el campo depende de la cadena de versiones, la cadena de configuración, el estado del contenedor y las condiciones inalámbricas.

Solución de problemas por parte del usuario

Si el entorno SNZB-02DR2 ya se ha actualizado a versiones que incluyen las correcciones relevantes, pero OTA sigue fallando, el firmware no se envía, las actualizaciones se detienen o la versión no cambia después de la actualización, se deben realizar las siguientes comprobaciones en orden:

1. Confirmar las versiones reales de la plataforma y del componente

• Zigbee2MQTT debe ser al menos 25.25.0

• ZHA / zigpy debe ser al menos 0.90.0

2. Confirmar que la imagen del contenedor o el entorno de ejecución realmente se haya actualizado

3. Confirmar que la configuración del proveedor OTA, los datos locales del índice OTA y los metadatos del firmware sean consistentes

4. Activar una nueva consulta OTA desde el dispositivo, por ejemplo, apagando y encendiendo el dispositivo para que envíe la solicitud Query Next Image Request

5. Verificar la intensidad de la señal, la distancia y la interferencia en 2.4 GHz

Conclusión

La corrección OTA para SNZB-02DR2 comenzó con fallos observados en implementaciones reales. La causa raíz se redujo a una brecha de compatibilidad entre los cambios en el formato de cifrado OTA en el SDK de Telink y el comportamiento del analizador existente.

Desde Zigbee2MQTT #9963 -> #9984 -> 25.25.0, hasta ZHA / zigpy #1734 -> #1736 -> 0.90.0, y luego al trabajo comunitario posterior sobre el tamaño del bloque OTA, esquema y manejo del proveedor, el resultado es un soporte OTA Telink más amplio y estable en Home Assistant.

Para los proveedores de dispositivos, el soporte de compatibilidad no solo consiste en proporcionar una solución temporal. También requiere impulsar el problema hacia el ecosistema ascendente para que la corrección forme parte de la plataforma misma.