Resolvendo o Problema OTA do SNZB-02DR2: Melhorando o Suporte do Home Assistant para Telink OTA

Resumo

Em setembro de 2025, o recém-lançado SNZB-02DR2 funcionava como esperado na gateway própria da SONOFF, mas começaram a surgir problemas OTA no Home Assistant. Os sintomas reportados incluíam falhas nas verificações de atualização, atualizações a atingir 100% sem alterar a versão do firmware instalado e notificações de push de firmware em falta. O problema apareceu tanto no Zigbee2MQTT como no ZHA.
O SNZB-02DR2 é construído com um SoC Telink. Após rever registos, estrutura da imagem de firmware e comportamento da plataforma, a equipa SONOFF identificou o problema nas alterações do formato de encriptação OTA usado no SDK Telink, que introduziu uma lacuna de compatibilidade com a lógica de análise OTA existente. As correções foram implementadas em duas fases: primeiro no lado do Zigbee2MQTT para o empacotamento encriptado específico do fornecedor Telink 0xf000, depois no lado ZHA / zigpy para a análise OTA encriptada Telink. Contribuidores da comunidade estenderam posteriormente o trabalho com atualizações no tamanho do bloco OTA, esquema e fornecedor.

Exposição e Sintomas

Em setembro de 2025, o recém-lançado SNZB-02DR2 operava normalmente na gateway própria da SONOFF, mas surgiram falhas relacionadas com OTA no Home Assistant. Os principais sintomas foram:

• falhas nas verificações de atualização
• transferências OTA a expirar ou a bloquear
• progresso da atualização a atingir 100% enquanto a versão do firmware permanecia inalterada
• dispositivos a mostrar Firmware: Desconhecido
• notificações de push de firmware em falta quando se esperava uma atualização

Estes sintomas apareceram tanto no Zigbee2MQTT como no ZHA. Com base em registos, imagens de firmware e comportamento em tempo de execução, a equipa SONOFF restringiu o problema à compatibilidade OTA em torno do formato de encriptação do SDK Telink.

Tipos de Falhas OTA

Este problema enquadra-se em três categorias:

O primeiro é a falha no transporte sem fios, normalmente vista como tempos de espera, bloqueios ou retransmissões excessivas. Causas comuns incluem interferência a 2,4 GHz, sinal fraco e longa distância entre o dispositivo e o coordenador.

O segundo é a falha na análise da imagem OTA. Neste caso, as verificações de atualização falham cedo, ou a imagem é transferida mas falha posteriormente durante a análise, divisão ou validação.

O terceiro é a incompatibilidade de versão e configuração. Exemplos típicos incluem dispositivos ainda a executar imagens antigas, configurações do fornecedor OTA que não correspondem à versão instalada ou metadados de índice incorretos. O sintoma habitual é que o ambiente foi atualizado, mas a correção não parece surtir efeito.

Desalinhamento na Empacotamento e Análise OTA da Telink

A causa raiz foi atribuída a alterações no formato de encriptação OTA usado pelo SDK Telink.

Um subelemento padrão Zigbee OTA pode ser simplificado como:

No layout padrão, o Campo de Comprimento descreve apenas o tamanho dos Dados seguintes. Não inclui o ID da Tag nem o próprio Campo de Comprimento.

No empacotamento encriptado Telink OTA, especialmente em elementos específicos do fornecedor como 0xf000, o layout contém um campo extra:

O Tag Info inserido altera o layout físico do fluxo de dados, enquanto o significado do Comprimento não é interpretado corretamente por parsers que ainda seguem o caminho padrão. É isso que causa a incompatibilidade de deslocamento.

Se um parser ainda ler a imagem como OTA ZCL padrão, o cálculo do deslocamento, o tratamento do comprimento e a divisão dos dados estarão errados. Resultados típicos são:

• erros de deslocamento ou limites durante a inspeção da imagem OTA
• transferência bem-sucedida de uma imagem corrompida em memória
• rejeição pelo dispositivo durante a fase final de validação

O problema é, portanto, uma incompatibilidade de análise causada pelo formato atualizado de encriptação OTA no SDK da Telink.

Zigbee2MQTT: Diagnóstico e Correção

problema #9963

A 9 de setembro de 2025, o problema #9963 (https://github.com/Koenkk/zigbee-herdsman-converters/issues/9963) foi aberto no zigbee-herdsman-converters sob o título Algumas questões sobre o método de encriptação OTA.

O problema já mostrava a falha principal: durante as verificações de atualização OTA, a análise atingiu tagID:0xf000, depois falhou com um erro de deslocamento fora do intervalo. Também documentou as conclusões da equipa SONOFF:
• o problema estava relacionado com o empacotamento de encriptação OTA no SDK da Telink
• a estrutura da imagem continha um campo extra Tag Info
• a correção da análise pôde ser verificada alterando parseSubElement
• OTA concluído com sucesso após o ajuste do parser

PR #9984

Com base na análise do problema, a equipa SONOFF submeteu o PR #9984 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/9984), intitulado adicionar código de manipulação OTA com Telink OTA.

O PR foi integrado em 2025-09-13, com o commit de integração 6cb56489bc9e9ea4c2df99f9499d61d9c10671f0.
A correção não adicionou um ramo específico para um único produto. Adicionou compatibilidade de análise para o empacotamento OTA da Telink. O âmbito foi, portanto, mais amplo do que um modelo e cobriu o impacto da compatibilidade introduzido pelas alterações no formato de encriptação OTA no SDK da Telink.

Lançamento 25.25.0

O PR de lançamento #10005 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/10005) para zigbee-herdsman-converters foi integrado a 2025-09-13, correspondendo à versão 25.25.0.

As notas de lançamento incluíram explicitamente:
• Suporte para OTAs Telink encriptadas (#9984)

Isto tornou as OTAs Telink encriptadas parte da linha principal do Zigbee2MQTT.

Progressão ZHA / zigpy

Uma vez diagnosticado e corrigido o problema no lado do Zigbee2MQTT, ficou claro que o problema não estava ligado a um único caminho de integração. Era uma lacuna de compatibilidade mais ampla na forma como o Home Assistant lidava com OTA Telink.

O ZHA depende do zigpy para o processamento OTA, por isso a causa raiz confirmada no Zigbee2MQTT também teve de ser resolvida no analisador OTA do zigpy.

PR #1734

Com base no problema da estrutura OTA Telink exposto no Zigbee2MQTT, a equipa SONOFF submeteu o PR #1734 (https://github.com/zigpy/zigpy/pull/1734) ao zigpy. A proposta adicionou suporte dedicado para análise de OTA Telink e propagou a bandeira de encriptação relacionada.

PR #1736

Após a discussão em torno do #1734, o zigpy adotou uma implementação diferente no PR #1736 (https://github.com/zigpy/zigpy/pull/1736), intitulado Analisar ficheiros OTA Telink encriptados.

O PR foi integrado a 2026-01-03, com o commit de integração 78a0b4da658deef0e7e88ec3bad0c80f20a19ea9.

As principais alterações no #1736 foram:
• deteção e análise direta de imagens OTA Telink encriptadas
• remoção da dependência estrita de metadados externos para identificar imagens Telink encriptadas
• reconhecimento nativo de OTA Telink dentro do analisador

Isto permitiu que o analisador identificasse estas imagens diretamente em vez de depender apenas de condições externas.

Lançamento zigpy 0.90.0

zigpy 0.90.0 foi lançado a 2026-01-03, e as suas notas de lançamento incluíram explicitamente:
• Analisar ficheiros OTA Telink encriptados por @puddly no #1736 Lançamento: zigpy 0.90.0 (https://github.com/zigpy/zigpy/releases/tag/0.90.0) A versão 0.90.0 é o lançamento chave onde a análise de OTA Telink encriptada ficou disponível no ZHA / zigpy.

Trabalho de Seguimento da Comunidade

A versão 0.90.0 resolveu o problema central de análise para o OTA Telink encriptado, mas não cobriu todos os detalhes de compatibilidade. A comunidade continuou com correções subsequentes.

Correção do Tamanho do Bloco OTA

No PR #1781 (https://github.com/zigpy/zigpy/pull/1781), os colaboradores da comunidade trataram da compatibilidade do tamanho do bloco OTA.
O PR, intitulado Aumentar o limite do tamanho do bloco OTA, foi mesclado em 2026-03-02. Alguns dispositivos Telink solicitam um bloco OTA de 48 bytes, enquanto o limite anterior era apenas 40 bytes. Mesmo com a análise correta da imagem, a atualização pode falhar se os tamanhos do bloco solicitado e entregue não coincidirem.
Isto mostra que a compatibilidade Telink OTA não é apenas sobre a análise da imagem. Inclui também a correspondência dos parâmetros de transporte.

Alinhamento do Esquema OTA e do Fornecedor

O PR #1782 (https://github.com/zigpy/zigpy/pull/1782) atualizou então o esquema zigpy-ota para a versão 2.

Mesmo quando o framework já suporta a análise do OTA Telink, os utilizadores ainda podem ver firmware desconhecido, notificações push em falta ou nenhuma alteração efetiva se os metadados OTA, a configuração do fornecedor e a versão instalada do zigpy estiverem fora de sincronização.

• A versão 0.90.0 resolveu o problema central de análise do OTA Telink encriptado

• alterações comunitárias posteriores completaram o tamanho do bloco, esquema e detalhes da distribuição OTA

• O suporte ZHA para Telink OTA amadureceu em fases, em vez de numa única correção

Razões Comuns pelas Quais a Correção Ainda Não Tem Efeito

“Suportado upstream” não significa que o ambiente local se comportará imediatamente de forma correta. As causas mais comuns na última etapa estão abaixo.

1. A versão em tempo de execução não é a versão que o utilizador espera

Isto é comum em implementações Docker. Um utilizador pode atualizar ficheiros no host ou acreditar que o código já foi atualizado, enquanto o contentor ainda está a executar versões mais antigas dos pacotes. Se o zigpy em tempo de execução ou o pacote relacionado não mudou, a correção upstream não aparecerá localmente.

2. Apenas parte da pilha foi atualizada

Por exemplo, o Home Assistant pode ser atualizado enquanto o zigpy ainda está abaixo da versão necessária, ou os ficheiros OTA locais e a configuração do fornecedor podem ainda seguir o caminho antigo. Nesse caso, o ambiente ainda se comporta como se a correção estivesse em falta.

3. O fornecedor OTA ou os metadados do índice ainda estão incorretos

Mesmo quando as versões da plataforma estão corretas, a plataforma pode falhar em identificar ou enviar o firmware se manufacturerCode, imageType, fileVersion, sha ou os caminhos dos ficheiros no index.json forem inconsistentes.

4. O dispositivo não enviou uma nova consulta OTA

A prontidão do servidor não significa que o dispositivo irá imediatamente solicitar uma nova imagem. Se o dispositivo não enviar novamente o Pedido de Próxima Imagem, o envio do firmware pode ainda parecer ausente.

5. Problemas de transporte sem fios ainda existem

Mesmo depois de corrigida a compatibilidade do parser, sinal fraco, longa distância, interferência e retransmissões excessivas ainda podem interromper o OTA. Estes são problemas de transporte separados e não desaparecem quando o problema do parser é corrigido.

O suporte upstream é uma condição necessária para o sucesso do OTA. Se a correção funciona realmente no campo depende da cadeia de versões, cadeia de configuração, estado do contentor e condições sem fios.

Resolução de problemas pelo utilizador

Se o ambiente SNZB-02DR2 já foi atualizado para versões que incluem as correções relevantes, mas o OTA ainda falha, o firmware ainda não é enviado, as atualizações ainda travam ou a versão não muda após a atualização, as seguintes verificações devem ser feitas por ordem:

1. Confirme as versões reais da plataforma e do componente

• Zigbee2MQTT deve ser pelo menos 25.25.0

• ZHA / zigpy deve ser pelo menos 0.90.0

2. Confirme que a imagem do contentor ou o ambiente de execução foi realmente atualizado

3. Confirme que as definições do fornecedor OTA, os dados locais do índice OTA e os metadados do firmware são consistentes

4. Dispare uma nova consulta OTA a partir do dispositivo, por exemplo, desligando e ligando o dispositivo para que envie o Pedido de Próxima Imagem

5. Verifique a intensidade do sinal, a distância e a interferência a 2,4 GHz

Conclusão

A correção OTA para o SNZB-02DR2 começou com falhas observadas em implementações reais. A causa raiz foi então reduzida a uma lacuna de compatibilidade entre as alterações do formato de encriptação OTA no SDK Telink e o comportamento do parser existente.

Desde Zigbee2MQTT #9963 -> #9984 -> 25.25.0, até ZHA / zigpy #1734 -> #1736 -> 0.90.0, e depois para trabalhos comunitários posteriores sobre tamanho do bloco OTA, esquema e gestão do fornecedor, o resultado é um suporte Telink OTA mais amplo e estável no Home Assistant.

Para os fornecedores de dispositivos, o suporte à compatibilidade não se trata apenas de fornecer uma solução temporária. Também requer levar o problema para o ecossistema upstream para que a correção faça parte da própria plataforma.