Het SNZB-02DR2 OTA-probleem oplossen: Verbetering van de Home Assistant-ondersteuning voor Telink OTA

Samenvatting

In september 2025 werkte de nieuw uitgebrachte SNZB-02DR2 zoals verwacht op de eigen gateway van SONOFF, maar begonnen OTA-problemen te verschijnen in Home Assistant. Gerapporteerde symptomen waren onder andere mislukte updatecontroles, upgrades die 100% bereikten zonder de geïnstalleerde firmwareversie te veranderen, en ontbrekende firmware pushmeldingen. Het probleem deed zich voor in zowel Zigbee2MQTT als ZHA.
SNZB-02DR2 is gebouwd op een Telink SoC. Na het bekijken van logs, firmware-image structuur en platformgedrag, traceerde het SONOFF-team het probleem naar wijzigingen in het OTA-encryptieformaat dat wordt gebruikt in de Telink SDK, wat een compatibiliteitskloof introduceerde met de bestaande OTA-parsinglogica. De oplossingen werden in twee fasen doorgevoerd: eerst aan de Zigbee2MQTT-kant voor de Telink 0xf000 vendor-specifieke versleutelde verpakking, daarna aan de ZHA / zigpy-kant voor versleutelde Telink OTA-parsing. Communitybijdragers breidden het werk later uit met OTA-blokgrootte, schema en provider updates.

Blootstelling en Symptomen

In september 2025 werkte de nieuw uitgebrachte SNZB-02DR2 normaal op de eigen gateway van SONOFF, maar traden OTA-gerelateerde fouten op in Home Assistant. De belangrijkste symptomen waren:

• mislukkingen bij updatecontroles
• OTA-overdrachten die time-outs krijgen of vastlopen
• upgrade voortgang die 100% bereikt terwijl de firmwareversie ongewijzigd blijft
• apparaten die Firmware: Onbekend tonen
• ontbrekende firmware pushmeldingen wanneer een update werd verwacht

Deze symptomen verschenen zowel in Zigbee2MQTT als ZHA. Op basis van logs, firmware-images en runtime-gedrag beperkte het SONOFF-team het probleem tot OTA-compatibiliteit rond het Telink SDK-encryptieformaat.

Soorten OTA-fouten

Dit probleem valt in drie categorieën:

De eerste is draadloze transportfout, meestal zichtbaar als time-outs, vastlopen of overmatige hertransmissies. Veelvoorkomende oorzaken zijn 2,4 GHz interferentie, zwak signaal en grote afstand tussen apparaat en coördinator.

De tweede is het falen van het parsen van de OTA-image. In dit geval falen updatecontroles vroegtijdig, of wordt de image overgedragen maar faalt later tijdens het parsen, slicen of valideren.

De derde is versie- en configuratie-onverenigbaarheid. Typische voorbeelden zijn containers die nog oudere images draaien, OTA-providerinstellingen die niet overeenkomen met de geïnstalleerde versie, of onjuiste indexmetadata. Het gebruikelijke symptoom is dat de omgeving is bijgewerkt, maar de oplossing lijkt niet te werken.

Telink OTA Verpakking en Parsing Niet-op-een-lijn

De hoofdoorzaak werd teruggevoerd op wijzigingen in het OTA-encryptieformaat dat wordt gebruikt door de Telink SDK.

Een standaard Zigbee OTA subelement kan worden vereenvoudigd als:

In de standaardindeling beschrijft het Lengteveld alleen de grootte van de volgende Data. Het omvat niet Tag ID of het Lengteveld zelf.

In Telink OTA-versleutelde verpakking, vooral in leverancier-specifieke elementen zoals 0xf000, bevat de indeling een extra veld:

De ingevoegde Tag Info verandert de fysieke indeling van de datastroom, terwijl de betekenis van Lengte niet correct wordt geïnterpreteerd door parsers die nog steeds het standaardpad volgen. Dat veroorzaakt de offset-mismatch.

Als een parser de afbeelding nog steeds leest als standaard ZCL OTA, zullen offset-berekening, lengteverwerking en data-slicing verkeerd zijn. Typische resultaten zijn:

• offset- of grensfouten tijdens inspectie van OTA-afbeeldingen
• succesvolle overdracht van een beschadigd in-memory image
• afwijzing door het apparaat tijdens de laatste validatiefase

Het probleem is dus een parsing-mismatch veroorzaakt door het bijgewerkte OTA-encryptieformaat in de Telink SDK.

Zigbee2MQTT: Diagnose en Oplossing

issue #9963

Op 9 september 2025 werd issue #9963 (https://github.com/Koenkk/zigbee-herdsman-converters/issues/9963) geopend in zigbee-herdsman-converters met de titel Enkele vragen over de OTA-encryptiemethode.

Het probleem toonde al de kernfout: tijdens OTA-updatecontroles bereikte de parsing tagID:0xf000, waarna het mislukte met een out-of-range offset-fout. Het documenteerde ook de conclusies van het SONOFF-team:
• het probleem hield verband met OTA-encryptieverpakking in de Telink SDK
• de afbeeldingsstructuur bevatte een extra Tag Info-veld
• de parsing-fix kon worden geverifieerd door parseSubElement te wijzigen
• OTA succesvol voltooid na de aanpassing van de parser

PR #9984

Op basis van de analyse in het issue diende het SONOFF-team PR #9984 in (https://github.com/Koenkk/zigbee-herdsman-converters/pull/9984), getiteld voeg ota-handle-code toe met telink ota.

De PR werd samengevoegd op 2025-09-13, met merge commit 6cb56489bc9e9ea4c2df99f9499d61d9c10671f0.
De oplossing voegde geen apparaat-specifieke tak toe voor een enkel product. Het voegde compatibiliteit voor parsing toe voor Telink OTA-verpakking. De reikwijdte was daarom breder dan één model en omvatte de compatibiliteitsimpact die werd geïntroduceerd door de wijzigingen in het OTA-encryptieformaat in de Telink SDK.

Release 25.25.0

Release PR #10005 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/10005) voor zigbee-herdsman-converters werd samengevoegd op 2025-09-13, overeenkomend met versie 25.25.0.

De release-opmerkingen bevatten expliciet:
• Ondersteuning voor Telink-geëncrypteerde OTA's (#9984)

Dit maakte Telink-geëncrypteerde OTA's onderdeel van de Zigbee2MQTT hoofdlijn.

ZHA / zigpy Voortgang

Zodra het probleem was gediagnosticeerd en opgelost aan de Zigbee2MQTT-kant, werd duidelijk dat het probleem niet gebonden was aan één integratiepad. Het was een bredere compatibiliteitskloof in hoe Home Assistant Telink OTA afhandelde.

ZHA vertrouwt op zigpy voor OTA-verwerking, dus de hoofdoorzaak bevestigd in Zigbee2MQTT moest ook worden aangepakt in de zigpy OTA-parser.

PR #1734

Gebaseerd op het Telink OTA-structuurprobleem dat aan het licht kwam in Zigbee2MQTT, diende het SONOFF-team PR #1734 (https://github.com/zigpy/zigpy/pull/1734) in bij zigpy. Het voorstel voegde speciale parsingondersteuning toe voor Telink OTA en verspreidde de gerelateerde encryptievlag.

PR #1736

Na de discussie rond #1734 nam zigpy een andere implementatie aan in PR #1736 (https://github.com/zigpy/zigpy/pull/1736), getiteld Parse encrypted Telink OTA files.

De PR werd samengevoegd op 2026-01-03, met merge commit 78a0b4da658deef0e7e88ec3bad0c80f20a19ea9.

De belangrijkste wijzigingen in #1736 waren:
• directe detectie en parsing van geëncrypteerde Telink OTA-afbeeldingen
• verwijdering van strikte afhankelijkheid van externe metadata om Telink-geëncrypteerde afbeeldingen te identificeren
• native herkenning van Telink OTA binnen de parser

Dit stelde de parser in staat om deze afbeeldingen direct te identificeren in plaats van alleen te vertrouwen op externe voorwaarden.

zigpy 0.90.0 Release

zigpy 0.90.0 werd uitgebracht op 2026-01-03, en de release-opmerkingen bevatten expliciet:
• Geëncrypteerde Telink OTA-bestanden parseren door @puddly in #1736 Release link: zigpy 0.90.0 (https://github.com/zigpy/zigpy/releases/tag/0.90.0) 0.90.0 is de belangrijkste release waarin het parseren van geëncrypteerde Telink OTA beschikbaar werd in ZHA / zigpy.

Vervolgwerk van de community

0.90.0 loste het kernprobleem op met het ontcijferen van versleutelde Telink OTA, maar behandelde niet alle compatibiliteitsdetails. De community ging door met vervolgfixes.

Fix voor OTA-blokgrootte

In PR #1781 (https://github.com/zigpy/zigpy/pull/1781) hebben community-bijdragers de compatibiliteit van de OTA-blokgrootte aangepakt.
De PR, getiteld Increase OTA block size cap, werd samengevoegd op 2026-03-02. Sommige Telink-apparaten vragen om een OTA-blok van 48 bytes, terwijl de eerdere limiet slechts 40 bytes was. Zelfs met correcte image-parsing kan de upgrade mislukken als de gevraagde en geleverde blokgroottes niet overeenkomen.
Dit laat zien dat Telink OTA-compatibiliteit niet alleen over image-parsing gaat. Het omvat ook het afstemmen van transportparameters.

OTA-schema en providerafstemming

PR #1782 (https://github.com/zigpy/zigpy/pull/1782) heeft toen het zigpy-ota schema geüpgraded naar v2.

Zelfs wanneer het framework al Telink OTA-parsing ondersteunt, kunnen gebruikers nog onbekende firmware, ontbrekende pushmeldingen of geen effectieve verandering zien als OTA-metadata, providerconfiguratie en de geïnstalleerde zigpy-versie niet synchroon lopen.

• 0.90.0 loste het kernprobleem op met het ontcijferen van Telink OTA

• latere community-wijzigingen hebben de blokgrootte, het schema en de OTA-distributiedetails afgerond

• ZHA-ondersteuning voor Telink OTA is in fasen volwassen geworden in plaats van in één patch

Veelvoorkomende redenen waarom de fix nog niet werkt

“Ondersteund upstream” betekent niet dat de lokale omgeving zich direct correct gedraagt. De meest voorkomende oorzaken in de laatste fase staan hieronder.

1. De runtime-versie is niet de versie die de gebruiker verwacht

Dit komt vaak voor bij Docker-implementaties. Een gebruiker kan bestanden op de host bijwerken of denken dat de code al is bijgewerkt, terwijl de container nog oudere pakketversies draait. Als de runtime zigpy of gerelateerd pakket niet is veranderd, zal de upstream-fix lokaal niet zichtbaar zijn.

2. Alleen een deel van de stack is bijgewerkt

Bijvoorbeeld, Home Assistant kan worden bijgewerkt terwijl zigpy nog onder de vereiste versie zit, of lokale OTA-bestanden en providerconfiguratie kunnen nog het oude pad volgen. In dat geval gedraagt de omgeving zich nog alsof de oplossing ontbreekt.

3. OTA-provider of indexmetadata is nog steeds onjuist

Zelfs wanneer platformversies correct zijn, kan het platform falen in het identificeren of pushen van firmware als manufacturerCode, imageType, fileVersion, sha of bestandslocaties in index.json inconsistent zijn.

4. Het apparaat heeft geen nieuwe OTA-query verzonden

Servergereedheid betekent niet dat het apparaat onmiddellijk een nieuwe afbeelding opvraagt. Als het apparaat geen Query Next Image Request opnieuw verzendt, kan het lijken alsof de firmware-push ontbreekt.

5. Draadloze transportproblemen blijven bestaan

Zelfs nadat de parsercompatibiliteit is opgelost, kunnen zwak signaal, grote afstand, interferentie en te veel hertransmissies OTA nog steeds verstoren. Dit zijn aparte transportproblemen en verdwijnen niet wanneer het parserprobleem is opgelost.

Upstream-ondersteuning is een noodzakelijke voorwaarde voor OTA-succes. Of de oplossing daadwerkelijk werkt in de praktijk hangt af van de versieketen, configuratieketen, containerstatus en draadloze omstandigheden.

Probleemoplossing aan gebruikerszijde

Als de SNZB-02DR2-omgeving al is bijgewerkt naar versies die de relevante oplossingen bevatten, maar OTA nog steeds faalt, firmware niet wordt gepusht, upgrades vastlopen of de versie na update niet verandert, moeten de volgende controles in volgorde worden uitgevoerd:

1. Bevestig de daadwerkelijke platform- en componentversies

• Zigbee2MQTT moet minimaal versie 25.25.0 zijn

• ZHA / zigpy moet minimaal versie 0.90.0 zijn

2. Bevestig dat de containerafbeelding of runtime-omgeving daadwerkelijk is bijgewerkt

3. Bevestig dat de OTA-providerinstellingen, lokale OTA-indexgegevens en firmwaremetadata consistent zijn

4. Start een nieuwe OTA-query vanaf het apparaat, bijvoorbeeld door het apparaat uit en aan te zetten zodat het een Query Next Image Request verzendt

5. Controleer signaalsterkte, afstand en 2,4 GHz-interferentie

Conclusie

De OTA-oplossing rond SNZB-02DR2 begon met fouten die werden waargenomen in echte implementaties. De hoofdoorzaak werd vervolgens teruggebracht tot een compatibiliteitskloof tussen OTA-encryptieformaatwijzigingen in de Telink SDK en het bestaande parsergedrag.

Van Zigbee2MQTT #9963 -> #9984 -> 25.25.0, naar ZHA / zigpy #1734 -> #1736 -> 0.90.0, en vervolgens naar later gemeenschapswerk aan OTA-blokgrootte, schema en providerafhandeling, is het resultaat een bredere en stabielere Telink OTA-ondersteuning binnen Home Assistant.

Voor apparaatfabrikanten gaat compatibiliteitsondersteuning niet alleen over het bieden van een tijdelijke oplossing. Het vereist ook dat het probleem wordt doorgegeven aan het upstream-ecosysteem zodat de oplossing onderdeel wordt van het platform zelf.