Corrigindo 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 funcionou como esperado no gateway próprio da SONOFF, mas problemas de OTA começaram a aparecer no Home Assistant. Os sintomas relatados incluíam falhas nas verificações de atualização, atualizações atingindo 100% sem alterar a versão do firmware instalado e notificações de push de firmware ausentes. O problema apareceu tanto no Zigbee2MQTT quanto no ZHA.
O SNZB-02DR2 é construído sobre um SoC Telink. Após revisar logs, estrutura da imagem de firmware e comportamento da plataforma, a equipe SONOFF rastreou o problema até mudanças no formato de criptografia OTA usado no SDK Telink, que introduziram uma lacuna de compatibilidade com a lógica de análise OTA existente. As correções foram aplicadas em duas etapas: primeiro no lado do Zigbee2MQTT para o empacotamento criptografado específico do fornecedor Telink 0xf000, depois no lado ZHA / zigpy para a análise OTA criptografada Telink. Contribuidores da comunidade posteriormente estenderam o trabalho com atualizações no tamanho do bloco OTA, esquema e provedor.

Exposição e Sintomas

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

• falhas nas verificações de atualização
• transferências OTA expirando ou travando
• progresso da atualização atingindo 100% enquanto a versão do firmware permanecia inalterada
• dispositivos mostrando Firmware: Desconhecido
• notificações de push de firmware ausentes quando uma atualização era esperada

Esses sintomas apareceram tanto no Zigbee2MQTT quanto no ZHA. Com base em logs, imagens de firmware e comportamento em tempo de execução, a equipe SONOFF restringiu o problema à compatibilidade OTA em torno do formato de criptografia do SDK Telink.

Tipos de Falha OTA

Esse problema se enquadra em três categorias:

O primeiro é falha no transporte sem fio, tipicamente vista como tempos limite, travamentos ou retransmissões excessivas. Causas comuns incluem interferência em 2,4 GHz, sinal fraco e longa distância entre o dispositivo e o coordenador.

O segundo é falha na análise da imagem OTA. Nesse 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 é incompatibilidade de versão e configuração. Exemplos típicos incluem dispositivos ainda executando imagens antigas, configurações do provedor OTA que não correspondem à versão instalada ou metadados de índice incorretos. O sintoma usual é 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 rastreada até mudanças no formato de criptografia OTA usado pelo SDK Telink.

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

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

No empacotamento criptografado OTA da Telink, 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 é o que causa a incompatibilidade de deslocamento.

Se um parser ainda lê a imagem como OTA ZCL padrão, o cálculo de deslocamento, o manuseio 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 na memória
• rejeição pelo dispositivo durante a etapa final de validação

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

Zigbee2MQTT: Diagnóstico e Correção

problema #9963

Em 9 de setembro de 2025, o problema #9963 (https://github.com/Koenkk/zigbee-herdsman-converters/issues/9963) foi aberto no zigbee-herdsman-converters com o título Algumas perguntas sobre o método de criptografia OTA.

O problema já mostrava a falha principal: durante as verificações de atualização OTA, a análise alcançou tagID:0xf000, depois falhou com um erro de deslocamento fora do intervalo. Também documentou as conclusões da equipe SONOFF:
• o problema estava relacionado ao empacotamento de criptografia 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 equipe 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 mesclado em 13-09-2025, com o commit de mesclagem 6cb56489bc9e9ea4c2df99f9499d61d9c10671f0.
A correção não adicionou um ramo específico para um único produto. Ela adicionou compatibilidade de análise para o empacotamento OTA da Telink. Portanto, o escopo foi mais amplo do que um modelo e cobriu o impacto de compatibilidade introduzido pelas mudanças no formato de criptografia 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 mesclado em 2025-09-13, correspondendo à versão 25.25.0.

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

Isso tornou as OTAs Telink criptografadas parte da linha principal do Zigbee2MQTT.

Progressão ZHA / zigpy

Uma vez que o problema foi diagnosticado e corrigido 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 em como o Home Assistant lidava com OTA Telink.

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

PR #1734

Baseado na questão da estrutura OTA Telink exposta no Zigbee2MQTT, a equipe SONOFF submeteu o PR #1734 (https://github.com/zigpy/zigpy/pull/1734) para o zigpy. A proposta adicionou suporte dedicado para análise de OTA Telink e propagou a flag de criptografia 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 arquivos OTA Telink criptografados.

O PR foi mesclado em 2026-01-03, com o commit de mesclagem 78a0b4da658deef0e7e88ec3bad0c80f20a19ea9.

As principais mudanças no #1736 foram:
• detecção e análise direta de imagens OTA Telink criptografadas
• remoção da dependência estrita de metadados externos para identificar imagens Telink criptografadas
• reconhecimento nativo de OTA Telink dentro do analisador

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

Lançamento zigpy 0.90.0

zigpy 0.90.0 foi lançado em 2026-01-03, e suas notas de lançamento incluíram explicitamente:
• Analisar arquivos OTA Telink criptografados por @puddly no #1736 Link do 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 criptografada se tornou disponível no ZHA / zigpy.

Trabalho de Acompanhamento da Comunidade

A versão 0.90.0 resolveu o problema central de análise para OTA Telink criptografado, 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), colaboradores da comunidade abordaram a 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 ainda pode falhar se os tamanhos de bloco solicitados e entregues não coincidirem.
Isso mostra que a compatibilidade Telink OTA não é apenas sobre a análise da imagem. Também inclui o ajuste dos parâmetros de transporte.

Alinhamento do Esquema OTA e do Provedor

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

Mesmo quando o framework já suporta a análise do OTA Telink, os usuários ainda podem ver firmware desconhecido, notificações push ausentes ou nenhuma mudança efetiva se os metadados OTA, a configuração do provedor e a versão instalada do zigpy estiverem fora de sincronia.

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

• mudanças posteriores da comunidade completaram o tamanho do bloco, esquema e detalhes da distribuição OTA

• O suporte ZHA para Telink OTA amadureceu em etapas, e não em um único patch

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

“Suportado upstream” não significa que o ambiente local se comportará corretamente imediatamente. 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 usuário espera

Isso é comum em implantações Docker. Um usuário pode atualizar arquivos no host ou acreditar que o código já foi atualizado, enquanto o contêiner ainda está executando versões 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 arquivos OTA locais e a configuração do provedor ainda podem seguir o caminho antigo. Nesse caso, o ambiente ainda se comporta como se a correção estivesse ausente.

3. Metadados do provedor OTA ou 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 caminhos de arquivo no index.json estiverem inconsistentes.

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

A prontidão do servidor não significa que o dispositivo solicitará imediatamente uma nova imagem. Se o dispositivo não enviar novamente a solicitação Query Next Image Request, o envio do firmware ainda pode parecer ausente.

5. Problemas de transporte sem fio ainda existem

Mesmo após a correção da compatibilidade do parser, sinal fraco, longa distância, interferência e retransmissões excessivas ainda podem interromper o OTA. Estes são problemas separados de transporte 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 realmente funciona no campo depende da cadeia de versões, cadeia de configuração, estado do container e condições sem fio.

Solução de problemas pelo usuário

Se o ambiente SNZB-02DR2 já foi atualizado para versões que incluem as correções relevantes, mas o OTA ainda está falhando, 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 na ordem:

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

• Zigbee2MQTT deve estar pelo menos na versão 25.25.0

• ZHA / zigpy deve estar pelo menos na versão 0.90.0

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

3. Confirme que as configurações do provedor OTA, os dados locais do índice OTA e os metadados do firmware estão consistentes

4. Acione uma nova consulta OTA a partir do dispositivo, por exemplo, desligando e ligando o dispositivo para que ele envie a solicitação Query Next Image Request

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

Conclusão

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

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

Para fornecedores de dispositivos, o suporte à compatibilidade não é apenas 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.