Az SNZB-02DR2 OTA problémájának megoldása: A Home Assistant támogatásának fejlesztése a Telink OTA-hoz

Összefoglalás

2025 szeptemberében az újonnan kiadott SNZB-02DR2 a SONOFF saját átjáróján várakozás szerint működött, de OTA problémák kezdtek megjelenni a Home Assistant-on. Jelentett tünetek voltak a frissítés ellenőrzési hibák, a 100%-os frissítés elérése anélkül, hogy a telepített firmware verzió változott volna, valamint hiányzó firmware push értesítések. A probléma mind a Zigbee2MQTT-ben, mind a ZHA-ban megjelent.
Az SNZB-02DR2 egy Telink SoC-re épül. A naplók, firmware kép struktúra és platform viselkedés áttekintése után a SONOFF csapat a problémát a Telink SDK-ban használt OTA titkosítási formátum változásaira vezette vissza, amely kompatibilitási rést okozott a meglévő OTA elemzési logikával. A javításokat két lépésben vezették be: először a Zigbee2MQTT oldalán a Telink 0xf000 gyártóspecifikus titkosított csomagolásra, majd a ZHA / zigpy oldalon a titkosított Telink OTA elemzésre. A közösségi hozzájárulók később kiterjesztették a munkát OTA blokk méret, séma és szolgáltató frissítésekkel.

Kitettség és tünetek

2025 szeptemberében az újonnan kiadott SNZB-02DR2 normálisan működött a SONOFF saját átjáróján, de OTA-val kapcsolatos hibák jelentkeztek a Home Assistant-on. A fő tünetek a következők voltak:

• frissítés ellenőrzési hibák
• OTA átvitelek időtúllépése vagy megakadása
• a frissítés előrehaladása eléri a 100%-ot, miközben a firmware verzió nem változik
• eszközök, amelyek Firmware: Ismeretlen állapotot mutatnak
• hiányzó firmware push értesítések, amikor frissítésre számítottak

Ezek a tünetek mind a Zigbee2MQTT-ben, mind a ZHA-ban megjelentek. A naplók, firmware képek és futásidejű viselkedés alapján a SONOFF csapat az OTA kompatibilitási problémát azonosította a Telink SDK titkosítási formátumával kapcsolatban.

OTA hibák típusai

Ez a probléma három kategóriába sorolható:

Az első a vezeték nélküli átvitel hibája, amely általában időtúllépésként, megakadásként vagy túlzott újraküldésként jelentkezik. Gyakori okok: 2,4 GHz-es interferencia, gyenge jelerősség és hosszú távolság az eszköz és a koordinátor között.

A második az OTA kép elemzési hiba. Ebben az esetben a frissítés ellenőrzése korán meghiúsul, vagy a kép átvitele megtörténik, de később elemzés, szeletelés vagy érvényesítés közben hibát jelez.

A harmadik a verzió- és konfigurációs eltérés. Tipikus példák: konténerek, amelyek még régebbi képeket futtatnak, az OTA szolgáltató beállításai nem egyeznek a telepített verzióval, vagy helytelen index metaadatok. A szokásos tünet, hogy a környezet frissült, de a javítás nem lép életbe.

Telink OTA csomagolás és elemzés eltérései

A probléma gyökere a Telink SDK által használt OTA titkosítási formátum változásaira vezethető vissza.

Egy szabványos Zigbee OTA al-elemet egyszerűsítve így lehet leírni:

A szabványos elrendezésben a Hossz mező csak a következő Adat méretét írja le. Nem tartalmazza a Tag ID-t vagy magát a Hossz mezőt.

A Telink OTA titkosított csomagolásban, különösen a gyártóspecifikus elemekben, mint a 0xf000, az elrendezés egy extra mezőt tartalmaz:

A beillesztett Tag Info megváltoztatja az adatfolyam fizikai elrendezését, miközben a Hossz jelentését nem értelmezik helyesen azok az elemzők, amelyek még a szabványos utat követik. Ez okozza az eltolás eltérését.

Ha egy elemző még mindig standard ZCL OTA-ként olvassa a képet, az eltolás számítása, a hossz kezelése és az adatok szeletelése hibás lesz. Tipikus eredmények:

• eltolás vagy határérték hibák az OTA kép ellenőrzése során
• sikeres átvitel egy sérült memóriaképről
• az eszköz általi elutasítás a végső érvényesítési szakaszban

A probléma tehát egy elemzési eltérés, amelyet a Telink SDK frissített OTA titkosítási formátuma okoz.

Zigbee2MQTT: Diagnózis és javítás

issue #9963

2025. szeptember 9-én megnyílt a #9963-as issue (https://github.com/Koenkk/zigbee-herdsman-converters/issues/9963) a zigbee-herdsman-converters projektben, címe: Néhány kérdés az OTA titkosítási módszerrel kapcsolatban.

A probléma már mutatta a fő hibát: az OTA frissítés ellenőrzésekor az elemzés elérte a tagID:0xf000 értéket, majd hibát dobott a határon kívüli eltolás miatt. Dokumentálta továbbá a SONOFF csapat következtetéseit is:
• a probléma a Telink SDK OTA titkosítási csomagolásához kapcsolódott
• a képfájl struktúrája tartalmazott egy extra Tag Info mezőt
• az elemzési javítás ellenőrizhető volt a parseSubElement megváltoztatásával
• Az OTA sikeresen befejeződött az elemző módosítása után

PR #9984

A probléma elemzése alapján a SONOFF csapat benyújtotta a #9984-es PR-t (https://github.com/Koenkk/zigbee-herdsman-converters/pull/9984), címe: add ota handle code with telink ota.

A PR 2025-09-13-án került beolvasztásra, a beolvasztási commit azonosítója: 6cb56489bc9e9ea4c2df99f9499d61d9c10671f0.
A javítás nem adott hozzá eszközspecifikus ágat egyetlen termékhez sem. Hozzáadta a Telink OTA csomagolás elemzési kompatibilitását. Ezért a hatókör szélesebb volt egy modellnél, és lefedte az OTA titkosítási formátumváltozások által a Telink SDK-ban bevezetett kompatibilitási hatást.

25.25.0 kiadás

A zigbee-herdsman-converters 10005-ös PR-ja (https://github.com/Koenkk/zigbee-herdsman-converters/pull/10005) 2025-09-13-án került beolvasztásra, a 25.25.0 verzióval.

A kiadási megjegyzések kifejezetten tartalmazták:
• Telink titkosított OTA-k támogatása (#9984)

Ez a Telink titkosított OTA-kat a Zigbee2MQTT fő ágba emelte.

ZHA / zigpy fejlődés

Miután a problémát diagnosztizálták és javították a Zigbee2MQTT oldalán, világossá vált, hogy a gond nem egyetlen integrációs úthoz kötött. Szélesebb kompatibilitási hiányosság volt abban, ahogyan a Home Assistant kezelte a Telink OTA-t.

A ZHA a zigpy-ra támaszkodik az OTA feldolgozásban, így a Zigbee2MQTT-ben megerősített alapvető okot a zigpy OTA elemzőjében is kezelni kellett.

PR #1734

A Zigbee2MQTT-ben feltárt Telink OTA szerkezet problémája alapján a SONOFF csapat benyújtotta a #1734-es PR-t (https://github.com/zigpy/zigpy/pull/1734) a zigpy-hoz. A javaslat dedikált elemzési támogatást adott a Telink OTA-hoz, és továbbította a kapcsolódó titkosítási jelzőt.

PR #1736

A #1734 körüli vita után a zigpy egy másik megvalósítást vett át a #1736-os PR-ben (https://github.com/zigpy/zigpy/pull/1736), címe: Titkosított Telink OTA fájlok elemzése.

A PR 2026-01-03-án került beolvasztásra, a merge commit azonosítója: 78a0b4da658deef0e7e88ec3bad0c80f20a19ea9.

A #1736-os változtatások főbb pontjai:
• titkosított Telink OTA képek közvetlen észlelése és elemzése
• a szigorú külső metaadat-függőség eltávolítása a titkosított Telink képek azonosításához
• natív felismerés a Telink OTA-n belül az elemzőben

Ez lehetővé tette az elemző számára, hogy közvetlenül azonosítsa ezeket a képeket, ahelyett, hogy csak külső feltételekre támaszkodott volna.

zigpy 0.90.0 kiadás

A zigpy 0.90.0 2026-01-03-án jelent meg, és a kiadási megjegyzések kifejezetten tartalmazták:
• Titkosított Telink OTA fájlok elemzése @puddly által a #1736-os kiadásban Megjelenési link: zigpy 0.90.0 (https://github.com/zigpy/zigpy/releases/tag/0.90.0) A 0.90.0 a kulcsfontosságú kiadás, amelyben elérhetővé vált a titkosított Telink OTA elemzés a ZHA / zigpy számára.

Közösségi utómunka

A 0.90.0 megoldotta a titkosított Telink OTA alapvető elemzési problémáját, de nem fedte le az összes kompatibilitási részletet. A közösség további javításokkal folytatta.

OTA blokk méret javítás

A PR #1781-ben (https://github.com/zigpy/zigpy/pull/1781) a közösségi hozzájárulók az OTA blokk méret kompatibilitását javították.
A PR, amelynek címe „OTA blokk méret korlát növelése”, 2026-03-02-án lett egyesítve. Néhány Telink eszköz 48 bájtos OTA blokkot kér, míg a korábbi korlát csak 40 bájt volt. Még a helyes képfájl elemzés mellett is sikertelen lehet a frissítés, ha a kért és a szállított blokk mérete nem egyezik.
Ez azt mutatja, hogy a Telink OTA kompatibilitás nem csak a képfájl elemzéséről szól. Tartalmazza a szállítási paraméterek egyeztetését is.

OTA séma és szolgáltató összehangolása

A PR #1782 (https://github.com/zigpy/zigpy/pull/1782) frissítette a zigpy-ota sémát v2-re.

Még ha a keretrendszer már támogatja is a Telink OTA elemzést, a felhasználók még mindig találkozhatnak ismeretlen firmware-rel, hiányzó push értesítésekkel vagy hatástalan változással, ha az OTA metaadatok, a szolgáltató konfigurációja és a telepített zigpy verzió nincs szinkronban.

• a 0.90.0 megoldotta a titkosított Telink OTA elemzésének alapvető problémáját

• későbbi közösségi változtatások befejezték a blokk méretét, sémát és az OTA terjesztési részleteket

• A ZHA támogatás a Telink OTA-hoz fokozatosan érett, nem egyetlen javításban

Gyakori okok, amiért a javítás még mindig nem lép életbe

A „támogatott fejlesztői verzió” nem jelenti azt, hogy a helyi környezet azonnal helyesen fog működni. A leggyakoribb utolsó lépésbeli okok az alábbiak.

1. A futtatási verzió nem az, amit a felhasználó vár

Ez gyakori a Docker telepítések esetén. Egy felhasználó frissítheti a fájlokat a gazdagépen, vagy azt hiheti, hogy a kód már frissült, miközben a konténer még mindig régebbi csomagverziókat futtat. Ha a futtatási idejű zigpy vagy a kapcsolódó csomag nem változott, a fejlesztői javítás helyileg nem jelenik meg.

2. Csak a rendszer egy része lett frissítve

Például a Home Assistant frissülhet, miközben a zigpy még mindig az előírt verzió alatt van, vagy a helyi OTA fájlok és a szolgáltató konfigurációja még az régi útvonalat követi. Ilyen esetben a környezet még mindig úgy viselkedik, mintha a javítás hiányozna.

3. Az OTA szolgáltató vagy az index metaadatai még mindig helytelenek

Még ha a platform verziók helyesek is, a platform nem biztos, hogy felismeri vagy továbbítja a firmware-t, ha a manufacturerCode, imageType, fileVersion, sha vagy a file utak az index.json-ben nem konzisztenssek.

4. Az eszköz nem küldött új OTA lekérdezést

A szerveroldali készenlét nem jelenti azt, hogy az eszköz azonnal új képet kér. Ha az eszköz nem küldi el újra a Query Next Image Request-et, a firmware továbbítása még mindig hiányozhat.

5. Vezeték nélküli szállítási problémák továbbra is fennállnak

Még a feldolgozási kompatibilitás javítása után is a gyenge jel, a nagy távolság, az interferencia és a túlzott újraküldések megszakíthatják az OTA-t. Ezek különálló szállítási problémák, és nem szűnnek meg a feldolgozási probléma javításával.

Az upstream támogatás szükséges feltétele az OTA sikerének. Hogy a javítás valóban működik-e a gyakorlatban, az a verziólánctól, konfigurációs lánctól, konténer állapottól és vezeték nélküli körülményektől függ.

Felhasználói hibakeresés

Ha az SNZB-02DR2 környezet már frissült a releváns javításokat tartalmazó verziókra, de az OTA még mindig sikertelen, a firmware nem kerül továbbításra, a frissítések elakadnak, vagy a verzió nem változik a frissítés után, a következő ellenőrzéseket kell sorrendben elvégezni:

1. Erősítse meg a tényleges platform- és komponensverziókat

• A Zigbee2MQTT legalább 25.25.0 legyen

• A ZHA / zigpy legalább 0.90.0 legyen

2. Erősítse meg, hogy a konténerkép vagy a futtatókörnyezet valóban frissült

3. Erősítse meg, hogy az OTA szolgáltató beállításai, a helyi OTA index adatok és a firmware metaadatai konzisztenssek

4. Indítson új OTA lekérdezést az eszközről, például az eszköz áramtalanításával, hogy elküldje a Query Next Image Request-et

5. Ellenőrizze a jelerősséget, a távolságot és a 2,4 GHz-es interferenciát

Következtetés

Az SNZB-02DR2 körüli OTA javítás valós telepítéseken tapasztalt hibákkal kezdődött. A gyökérokot aztán egy kompatibilitási résre szűkítették le az OTA titkosítási formátumváltozások és a Telink SDK, valamint a meglévő elemző viselkedése között.

A Zigbee2MQTT #9963 -> #9984 -> 25.25.0-tól a ZHA / zigpy #1734 -> #1736 -> 0.90.0-ig, majd a későbbi közösségi munkákig az OTA blokk méret, séma és szolgáltató kezelés terén, az eredmény szélesebb és stabilabb Telink OTA támogatás a Home Assistantban.

Az eszközgyártók számára a kompatibilitás támogatása nem csupán egy ideiglenes megoldás biztosítását jelenti. Ez azt is megköveteli, hogy a problémát az upstream ökoszisztémába tolja, hogy a javítás maga a platform részévé váljon.