Risoluzione del problema OTA SNZB-02DR2: migliorare il supporto di Home Assistant per Telink OTA

Riepilogo

A settembre 2025, il nuovo SNZB-02DR2 ha funzionato come previsto sul gateway SONOFF, ma sono iniziati a comparire problemi OTA su Home Assistant. I sintomi segnalati includevano fallimenti nei controlli di aggiornamento, aggiornamenti che raggiungevano il 100% senza modificare la versione firmware installata e mancanza di notifiche push del firmware. Il problema si è manifestato sia in Zigbee2MQTT che in ZHA.
SNZB-02DR2 è basato su un SoC Telink. Dopo aver esaminato log, struttura dell'immagine firmware e comportamento della piattaforma, il team SONOFF ha ricondotto il problema a modifiche nel formato di crittografia OTA usato nel Telink SDK, che hanno introdotto una incompatibilità con la logica di parsing OTA esistente. Le correzioni sono state implementate in due fasi: prima su Zigbee2MQTT per il packaging crittografato specifico del vendor Telink 0xf000, poi su ZHA / zigpy per il parsing OTA crittografato Telink. Successivamente, contributori della community hanno esteso il lavoro con aggiornamenti su dimensione blocchi OTA, schema e provider.

Esposizione e sintomi

A settembre 2025, il nuovo SNZB-02DR2 ha funzionato normalmente sul gateway proprietario SONOFF, ma sono comparsi fallimenti OTA su Home Assistant. I sintomi principali erano:

• fallimenti nei controlli di aggiornamento
• trasferimenti OTA che scadono o si bloccano
• avanzamento dell'aggiornamento che raggiunge il 100% mentre la versione del firmware rimane invariata
• dispositivi che mostrano Firmware: Sconosciuto
• mancanza di notifiche push del firmware quando era previsto un aggiornamento

Questi sintomi sono apparsi sia in Zigbee2MQTT che in ZHA. Basandosi su log, immagini firmware e comportamento a runtime, il team SONOFF ha individuato il problema nella compatibilità OTA relativa al formato di crittografia del Telink SDK.

Tipi di fallimento OTA

Questo problema rientra in tre categorie:

Il primo è un fallimento nel trasporto wireless, tipicamente visibile come timeout, blocchi o ritrasmissioni eccessive. Cause comuni includono interferenze a 2,4 GHz, segnale debole e lunga distanza tra dispositivo e coordinatore.

Il secondo è un fallimento nel parsing dell'immagine OTA. In questo caso, i controlli di aggiornamento falliscono precocemente, oppure l'immagine viene trasferita ma poi fallisce durante il parsing, il taglio o la validazione.

Il terzo è un disallineamento di versione e configurazione. Esempi tipici includono contenitori che eseguono ancora immagini più vecchie, impostazioni del provider OTA non corrispondenti alla versione installata o metadati di indice errati. Il sintomo abituale è che l'ambiente è stato aggiornato, ma la correzione non sembra avere effetto.

Disallineamento nel packaging e parsing OTA di Telink

La causa principale è stata ricondotta a modifiche nel formato di crittografia OTA utilizzato dal Telink SDK.

Un sottoelemento standard Zigbee OTA può essere semplificato come:

Nella disposizione standard, il Campo Lunghezza descrive solo la dimensione dei Dati seguenti. Non include Tag ID o il Campo Lunghezza stesso.

Nel packaging crittografato Telink OTA, specialmente negli elementi specifici del fornitore come 0xf000, la disposizione contiene un campo extra:

Il Tag Info inserito cambia la disposizione fisica del flusso di dati, mentre il significato di Lunghezza non è interpretato correttamente dai parser che seguono ancora il percorso standard. Questo causa la discrepanza di offset.

Se un parser legge ancora l'immagine come OTA ZCL standard, il calcolo dell'offset, la gestione della lunghezza e il taglio dei dati saranno errati. I risultati tipici sono:

• errori di offset o limiti durante l'ispezione dell'immagine OTA
• trasferimento riuscito di un'immagine corrotta in memoria
• rifiuto da parte del dispositivo durante la fase finale di validazione

Il problema è quindi una discrepanza di parsing causata dal formato aggiornato di crittografia OTA nel SDK Telink.

Zigbee2MQTT: Diagnosi e Correzione

problema #9963

Il 9 settembre 2025, è stato aperto il problema #9963 (https://github.com/Koenkk/zigbee-herdsman-converters/issues/9963) in zigbee-herdsman-converters con il titolo Alcune domande sul metodo di crittografia OTA.

Il problema mostrava già il fallimento principale: durante i controlli di aggiornamento OTA, il parsing raggiungeva tagID:0xf000, poi falliva con un errore di offset fuori intervallo. Documentava anche le conclusioni del team SONOFF:
• il problema era legato al packaging di crittografia OTA nel SDK Telink
• la struttura dell'immagine conteneva un campo Tag Info extra
• la correzione del parsing poteva essere verificata modificando parseSubElement
• OTA completato con successo dopo la regolazione del parser

PR #9984

Basandosi sull'analisi nel problema, il team SONOFF ha presentato la PR #9984 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/9984), intitolata aggiungi codice di gestione ota con telink ota.

La PR è stata unita il 13-09-2025, con il commit di merge 6cb56489bc9e9ea4c2df99f9499d61d9c10671f0.
La correzione non ha aggiunto un ramo specifico per dispositivo per un singolo prodotto. Ha aggiunto la compatibilità di parsing per il packaging OTA Telink. L'ambito era quindi più ampio di un modello e copriva l'impatto sulla compatibilità introdotto dalle modifiche al formato di crittografia OTA nel SDK Telink.

Rilascio 25.25.0

La PR di rilascio #10005 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/10005) per zigbee-herdsman-converters è stata unita il 2025-09-13, corrispondente alla versione 25.25.0.

Le note di rilascio includevano esplicitamente:
• Supporto alle OTA Telink criptate (#9984)

Questo ha reso le OTA Telink criptate parte della linea principale di Zigbee2MQTT.

Progressione ZHA / zigpy

Una volta diagnosticato e risolto il problema sul lato Zigbee2MQTT, è stato chiaro che il problema non era legato a un solo percorso di integrazione. Era una lacuna di compatibilità più ampia nel modo in cui Home Assistant gestiva Telink OTA.

ZHA si affida a zigpy per l’elaborazione OTA, quindi la causa principale confermata in Zigbee2MQTT doveva essere affrontata anche nel parser OTA di zigpy.

PR #1734

Basandosi sul problema della struttura OTA Telink evidenziato in Zigbee2MQTT, il team SONOFF ha inviato la PR #1734 (https://github.com/zigpy/zigpy/pull/1734) a zigpy. La proposta ha aggiunto supporto dedicato all’analisi per Telink OTA e ha propagato il relativo flag di crittografia.

PR #1736

Dopo la discussione su #1734, zigpy ha adottato una diversa implementazione nella PR #1736 (https://github.com/zigpy/zigpy/pull/1736), intitolata Analisi dei file OTA Telink criptati.

La PR è stata unita il 2026-01-03, con commit di merge 78a0b4da658deef0e7e88ec3bad0c80f20a19ea9.

Le modifiche principali in #1736 sono state:
• rilevamento e analisi diretta delle immagini OTA Telink criptate
• rimozione della dipendenza rigida dai metadati esterni per identificare le immagini Telink criptate
• riconoscimento nativo di Telink OTA all’interno del parser

Questo ha permesso al parser di identificare direttamente queste immagini invece di fare affidamento solo su condizioni esterne.

Rilascio zigpy 0.90.0

zigpy 0.90.0 è stato rilasciato il 2026-01-03, e le note di rilascio includevano esplicitamente:
• Analisi dei file OTA Telink criptati da @puddly in #1736 Link rilascio: zigpy 0.90.0 (https://github.com/zigpy/zigpy/releases/tag/0.90.0) La versione 0.90.0 è il rilascio chiave in cui l’analisi dei file OTA Telink criptati è diventata disponibile in ZHA / zigpy.

Lavoro di follow-up della community

La versione 0.90.0 ha risolto il problema principale di parsing per OTA Telink criptato, ma non ha coperto tutti i dettagli di compatibilità. La community ha continuato con correzioni successive.

Correzione della dimensione del blocco OTA

Nella PR #1781 (https://github.com/zigpy/zigpy/pull/1781), i contributori della community hanno affrontato la compatibilità della dimensione del blocco OTA.
La PR, intitolata Aumento del limite di dimensione del blocco OTA, è stata unita il 2026-03-02. Alcuni dispositivi Telink richiedono un blocco OTA da 48 byte, mentre il limite precedente era solo di 40 byte. Anche con un parsing corretto dell'immagine, l'aggiornamento può ancora fallire se le dimensioni del blocco richieste e consegnate non corrispondono.
Questo dimostra che la compatibilità Telink OTA non riguarda solo il parsing dell'immagine. Include anche la corrispondenza dei parametri di trasporto.

Allineamento dello schema OTA e del provider

La PR #1782 (https://github.com/zigpy/zigpy/pull/1782) ha quindi aggiornato lo schema zigpy-ota alla versione 2.

Anche quando il framework supporta già il parsing OTA Telink, gli utenti possono ancora vedere firmware sconosciuti, notifiche push mancanti o nessun cambiamento efficace se i metadati OTA, la configurazione del provider e la versione installata di zigpy non sono sincronizzati.

• La versione 0.90.0 ha risolto il problema principale di parsing OTA Telink criptato

• modifiche successive della community hanno completato la dimensione del blocco, lo schema e i dettagli di distribuzione OTA

• Il supporto ZHA per Telink OTA è maturato a fasi piuttosto che in una singola patch

Motivi comuni per cui la correzione non ha ancora effetto

“Supportato a monte” non significa che l'ambiente locale si comporterà immediatamente correttamente. Le cause più comuni dell'ultimo miglio sono elencate di seguito.

1. La versione del runtime non è quella che l'utente si aspetta

Questo è comune nelle distribuzioni Docker. Un utente potrebbe aggiornare i file sull'host o credere che il codice sia già stato aggiornato, mentre il container sta ancora eseguendo versioni più vecchie dei pacchetti. Se il runtime di zigpy o il pacchetto correlato non è cambiato, la correzione a monte non apparirà localmente.

2. Solo una parte dello stack è stata aggiornata

Ad esempio, Home Assistant potrebbe essere aggiornato mentre zigpy è ancora sotto la versione richiesta, oppure i file OTA locali e la configurazione del provider potrebbero ancora seguire il vecchio percorso. In tal caso, l'ambiente si comporta ancora come se la correzione mancasse.

3. I metadati del provider OTA o dell'indice sono ancora errati

Anche quando le versioni della piattaforma sono corrette, la piattaforma potrebbe non riuscire a identificare o inviare il firmware se manufacturerCode, imageType, fileVersion, sha o i percorsi dei file in index.json non sono coerenti.

4. Il dispositivo non ha inviato una nuova richiesta OTA

La prontezza lato server non significa che il dispositivo richiederà immediatamente una nuova immagine. Se il dispositivo non invia nuovamente una Query Next Image Request, il push del firmware potrebbe sembrare mancante.

5. Persistono problemi di trasporto wireless

Anche dopo che la compatibilità del parser è stata risolta, segnale debole, distanza elevata, interferenze e ritrasmissioni eccessive possono ancora compromettere l'OTA. Questi sono problemi di trasporto separati e non scompaiono con la correzione del parsing.

Il supporto a monte è una condizione necessaria per il successo dell'OTA. Se la correzione funziona effettivamente sul campo dipende dalla catena di versioni, dalla configurazione, dallo stato del contenitore e dalle condizioni wireless.

Risoluzione dei problemi lato utente

Se l'ambiente SNZB-02DR2 è già stato aggiornato a versioni che includono le correzioni rilevanti, ma l'OTA continua a fallire, il firmware non viene ancora inviato, gli aggiornamenti si bloccano o la versione non cambia dopo l'aggiornamento, devono essere eseguiti i seguenti controlli in ordine:

1. Confermare le versioni effettive della piattaforma e del componente

• Zigbee2MQTT dovrebbe essere almeno alla versione 25.25.0

• ZHA / zigpy dovrebbe essere almeno alla versione 0.90.0

2. Confermare che l'immagine del contenitore o l'ambiente di runtime siano effettivamente stati aggiornati

3. Confermare che le impostazioni del provider OTA, i dati locali dell'indice OTA e i metadati del firmware siano coerenti

4. Attivare una nuova richiesta OTA dal dispositivo, ad esempio spegnendo e riaccendendo il dispositivo in modo che invii una Query Next Image Request

5. Controllare la potenza del segnale, la distanza e le interferenze a 2,4 GHz

Conclusione

La correzione OTA per SNZB-02DR2 è iniziata con fallimenti osservati in implementazioni reali. La causa principale è stata poi individuata in una lacuna di compatibilità tra le modifiche al formato di crittografia OTA nel Telink SDK e il comportamento del parser esistente.

Da Zigbee2MQTT #9963 -> #9984 -> 25.25.0, a ZHA / zigpy #1734 -> #1736 -> 0.90.0, e poi al lavoro successivo della community su dimensione del blocco OTA, schema e gestione del provider, il risultato è un supporto OTA Telink più ampio e stabile in Home Assistant.

Per i fornitori di dispositivi, il supporto alla compatibilità non riguarda solo la fornitura di una soluzione temporanea. Richiede anche di spingere il problema nell'ecosistema a monte affinché la correzione diventi parte integrante della piattaforma stessa.