SNZB-02DR2 OTA Sorununu Düzeltme: Telink OTA için Home Assistant Desteğini Geliştirme

Özet

Eylül 2025'te, yeni çıkan SNZB-02DR2, SONOFF'un kendi ağ geçidinde beklendiği gibi çalıştı, ancak Home Assistant'ta OTA sorunları ortaya çıkmaya başladı. Bildirilen belirtiler arasında güncelleme kontrolü hataları, yüklü firmware sürümü değişmeden %100'e ulaşan yükseltmeler ve eksik firmware bildirimleri vardı. Sorun hem Zigbee2MQTT hem de ZHA'da görüldü.
SNZB-02DR2, Telink SoC üzerine inşa edilmiştir. Kayıtlar, firmware görüntü yapısı ve platform davranışı incelendikten sonra, SONOFF ekibi sorunu Telink SDK'da kullanılan OTA şifreleme formatındaki değişikliklere bağladı; bu da mevcut OTA ayrıştırma mantığıyla uyumluluk açığı yarattı. Düzeltmeler iki aşamada yapıldı: önce Zigbee2MQTT tarafında Telink 0xf000 satıcıya özel şifreli paketleme için, sonra ZHA / zigpy tarafında şifreli Telink OTA ayrıştırması için. Topluluk katkıcıları daha sonra OTA blok boyutu, şema ve sağlayıcı güncellemeleri ile çalışmayı genişletti.

Maruz Kalma ve Belirtiler

Eylül 2025'te, yeni çıkan SNZB-02DR2, SONOFF'un kendi ağ geçidinde normal çalışırken, Home Assistant'ta OTA ile ilgili hatalar ortaya çıktı. Ana belirtiler şunlardı:

• güncelleme kontrolü hataları
• OTA aktarımının zaman aşımına uğraması veya duraklaması
• firmware sürümü değişmeden yükseltme ilerlemesinin %100'e ulaşması
• Firmware: Bilinmiyor gösteren cihazlar
• güncelleme beklenirken eksik firmware bildirimleri

Bu belirtiler hem Zigbee2MQTT hem de ZHA'da ortaya çıktı. Kayıtlar, firmware görüntüleri ve çalışma zamanı davranışına dayanarak, SONOFF ekibi sorunu Telink SDK şifreleme formatı etrafındaki OTA uyumluluğuna indirgedi.

OTA Hata Türleri

Bu sorun üç kategoriye ayrılır:

Birincisi kablosuz taşıma hatasıdır; genellikle zaman aşımı, duraklama veya aşırı yeniden iletim olarak görülür. Yaygın nedenler arasında 2.4 GHz paraziti, zayıf sinyal gücü ve cihaz ile koordinatör arasındaki uzun mesafe bulunur.

İkincisi OTA görüntü ayrıştırma hatasıdır. Bu durumda, güncelleme kontrolleri erken başarısız olur veya görüntü aktarılır ancak daha sonra ayrıştırma, dilimleme veya doğrulama sırasında başarısız olur.

Üçüncüsü sürüm ve yapılandırma uyumsuzluğudur. Tipik örnekler arasında hala eski görüntüleri çalıştıran konteynerler, OTA sağlayıcı ayarlarının yüklü sürümle uyuşmaması veya yanlış indeks meta verisi bulunur. Yaygın belirti, ortamın güncellenmiş olması ancak düzeltmenin etkili olmamasıdır.

Telink OTA Paketleme ve Ayrıştırma Uyumsuzluğu

Sorunun kökeni, Telink SDK tarafından kullanılan OTA şifreleme formatındaki değişikliklere kadar izlenmiştir.

Standart bir Zigbee OTA alt öğesi şu şekilde basitleştirilebilir:

Standart düzen içinde, Uzunluk Alanı yalnızca takip eden Verinin boyutunu tanımlar. Etiket ID veya Uzunluk Alanının kendisini içermez.

Telink OTA şifrelenmiş paketlemede, özellikle 0xf000 gibi satıcıya özel öğelerde, düzen ekstra bir alan içerir:

Eklenen Etiket Bilgisi, veri akışının fiziksel düzenini değiştirirken, Uzunluk'un anlamı hala standart yolu izleyen ayrıştırıcılar tarafından doğru yorumlanmaz. Bu, ofset uyumsuzluğuna neden olur.

Bir ayrıştırıcı görüntüyü hala standart ZCL OTA olarak okursa, ofset hesaplaması, uzunluk işlemi ve veri dilimleme yanlış olur. Tipik sonuçlar şunlardır:

• OTA görüntü incelemesi sırasında ofset veya sınır hataları
• bozuk bir bellek içi görüntünün başarılı aktarımı
• cihaz tarafından son doğrulama aşamasında reddedilme

Sorun, bu nedenle Telink SDK'daki güncellenmiş OTA şifreleme formatından kaynaklanan bir ayrıştırma uyumsuzluğudur.

Zigbee2MQTT: Teşhis ve Düzeltme

sorun #9963

9 Eylül 2025'te, zigbee-herdsman-converters altında Some questions about the OTA encryption method başlıklı #9963 numaralı sorun açıldı (https://github.com/Koenkk/zigbee-herdsman-converters/issues/9963).

Sorun zaten temel hatayı gösteriyordu: OTA güncelleme kontrolleri sırasında, ayrıştırma tagID:0xf000'a ulaştı ve ardından aralık dışı ofset hatasıyla başarısız oldu. Ayrıca SONOFF ekibinin sonuçları belgelendi:
• sorun Telink SDK'daki OTA şifreleme paketlemesi ile ilgiliydi
• görüntü yapısı ekstra bir Etiket Bilgisi alanı içeriyordu
• parseSubElement değiştirilerek ayrıştırma düzeltmesi doğrulanabilir
• Ayrıştırıcı ayarından sonra OTA başarıyla tamamlandı

PR #9984

Sorundaki analiz temel alınarak, SONOFF ekibi telink ota ile ota işleme kodu ekleyen PR #9984'ü (https://github.com/Koenkk/zigbee-herdsman-converters/pull/9984) sundu.

PR, 2025-09-13 tarihinde, 6cb56489bc9e9ea4c2df99f9499d61d9c10671f0 birleştirme commit'i ile birleştirildi.
Düzeltme, tek bir ürün için cihaz özelinde bir dal eklemedi. Telink OTA paketleme için ayrıştırma uyumluluğu ekledi. Bu nedenle kapsam, bir modelden daha genişti ve Telink SDK'daki OTA şifreleme formatı değişikliklerinin getirdiği uyumluluk etkisini kapsıyordu.

Sürüm 25.25.0

zigbee-herdsman-converters için Sürüm PR #10005 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/10005), 2025-09-13 tarihinde birleştirildi ve 25.25.0 sürümüne karşılık geliyor.

Sürüm notlarında açıkça şunlar yer aldı:
• Telink şifreli OTA'lar için destek (#9984)

Bu, Telink şifreli OTA'ların Zigbee2MQTT ana hattının bir parçası olmasını sağladı.

ZHA / zigpy İlerleyişi

Sorun Zigbee2MQTT tarafında teşhis edilip düzeltildikten sonra, problemin tek bir entegrasyon yoluna bağlı olmadığı anlaşıldı. Bu, Home Assistant'ın Telink OTA'yı nasıl ele aldığına dair daha geniş bir uyumluluk açığıydı.

ZHA, OTA işlemleri için zigpy'ye dayanır, bu yüzden Zigbee2MQTT'de doğrulanan temel neden aynı zamanda zigpy OTA ayrıştırıcısında da ele alınmak zorundaydı.

PR #1734

Zigbee2MQTT'de ortaya çıkan Telink OTA yapı sorunu temel alınarak, SONOFF ekibi zigpy'ye PR #1734 (https://github.com/zigpy/zigpy/pull/1734) gönderdi. Öneri, Telink OTA için özel ayrıştırma desteği ekledi ve ilgili şifreleme bayrağını yaydı.

PR #1736

#1734 etrafındaki tartışmadan sonra, zigpy PR #1736'da (https://github.com/zigpy/zigpy/pull/1736) farklı bir uygulama benimsedi, başlığı Şifrelenmiş Telink OTA dosyalarını ayrıştır.

PR, 2026-01-03 tarihinde, 78a0b4da658deef0e7e88ec3bad0c80f20a19ea9 birleştirme commit'i ile birleştirildi.

#1736'daki ana değişiklikler şunlardı:
• Şifrelenmiş Telink OTA görüntülerinin doğrudan tespiti ve ayrıştırılması
• Telink şifreli görüntüleri tanımlamak için dış meta verilere olan sıkı bağımlılığın kaldırılması
• Ayrıştırıcı içinde Telink OTA'nın yerel tanınması

Bu, ayrıştırıcının bu görüntüleri yalnızca dış koşullara bağlı kalmadan doğrudan tanımlamasına olanak sağladı.

zigpy 0.90.0 Sürümü

zigpy 0.90.0, 2026-01-03 tarihinde yayınlandı ve sürüm notlarında açıkça şunlar yer aldı:
• @puddly tarafından #1736 numaralı sürümde şifrelenmiş Telink OTA dosyalarını ayrıştırma Yayın bağlantısı: zigpy 0.90.0 (https://github.com/zigpy/zigpy/releases/tag/0.90.0) 0.90.0, ZHA / zigpy'de şifrelenmiş Telink OTA ayrıştırmasının kullanılabilir hale geldiği ana sürümdür.

Topluluk Takip Çalışmaları

0.90.0, şifreli Telink OTA için temel ayrıştırma sorununu çözdü, ancak tüm uyumluluk detaylarını kapsamadı. Topluluk takip eden düzeltmelerle devam etti.

OTA Blok Boyutu Düzeltmesi

PR #1781 (https://github.com/zigpy/zigpy/pull/1781) içinde topluluk katkıcıları OTA blok boyutu uyumluluğunu ele aldı.
“OTA blok boyutu sınırını artır” başlıklı PR, 2026-03-02’de birleştirildi. Bazı Telink cihazları 48 baytlık OTA bloğu isterken, önceki sınır sadece 40 bayttı. Doğru imaj ayrıştırma olsa bile, istenen ve teslim edilen blok boyutları eşleşmezse yükseltme başarısız olabilir.
Bu, Telink OTA uyumluluğunun sadece imaj ayrıştırmayla ilgili olmadığını gösterir. Aynı zamanda taşıma parametrelerinin eşleşmesini de içerir.

OTA Şeması ve Sağlayıcı Hizalaması

PR #1782 (https://github.com/zigpy/zigpy/pull/1782) ardından zigpy-ota şemasını v2’ye yükseltti.

Çerçeve Telink OTA ayrıştırmasını zaten desteklese bile, kullanıcılar bilinmeyen ürün yazılımı, eksik bildirimler veya etkili değişiklik görmeyebilir; eğer OTA meta verisi, sağlayıcı yapılandırması ve yüklü zigpy sürümü senkronize değilse.

• 0.90.0, şifreli Telink OTA ayrıştırma sorununu çözdü

• sonraki topluluk değişiklikleri blok boyutu, şema ve OTA dağıtım detaylarını tamamladı

• ZHA desteği Telink OTA için tek bir yamada değil, aşamalar halinde olgunlaştı

Düzeltmenin Hâlâ Etkili Olmamasının Yaygın Nedenleri

“Desteklenen yukarı akış” yerel ortamın hemen doğru davranacağı anlamına gelmez. En yaygın son aşama nedenleri aşağıdadır.

1. Çalışma zamanı sürümü, kullanıcının beklediği sürüm değil

Bu, Docker dağıtımlarında yaygındır. Bir kullanıcı ana makinedeki dosyaları güncelleyebilir veya kodun zaten güncellendiğini düşünebilir, ancak konteyner hala eski paket sürümlerini çalıştırıyor olabilir. Çalışma zamanı zigpy veya ilgili paket değişmemişse, yukarı akıştaki düzeltme yerel olarak görünmez.

2. Yalnızca yığının bir kısmı güncellendi

Örneğin, Home Assistant yükseltilirken zigpy hala gereken sürümün altında olabilir veya yerel OTA dosyaları ve sağlayıcı yapılandırması eski yolu takip ediyor olabilir. Bu durumda, ortam hala düzeltmenin eksikmiş gibi davranır.

3. OTA sağlayıcı veya indeks meta verileri hala yanlış

Platform sürümleri doğru olsa bile, manufacturerCode, imageType, fileVersion, sha veya index.json içindeki dosya yolları tutarsızsa platform firmware'i tanımlayamayabilir veya gönderemeyebilir.

4. Cihaz yeni bir OTA sorgusu göndermedi

Sunucu tarafı hazırlığı, cihazın hemen yeni bir imaj talep edeceği anlamına gelmez. Cihaz Query Next Image Request'i tekrar göndermezse, firmware gönderimi hala eksik görünebilir.

5. Kablosuz taşıma sorunları hala var

Ayrıştırma uyumluluğu düzeltildikten sonra bile zayıf sinyal, uzun mesafe, parazit ve aşırı yeniden iletimler OTA'yı bozabilir. Bunlar ayrı taşıma sorunlarıdır ve ayrıştırma sorunu düzeltildiğinde ortadan kalkmaz.

Yukarı akış desteği, OTA başarısı için gerekli bir koşuldur. Düzeltmenin sahada gerçekten işe yarayıp yaramadığı, sürüm zinciri, yapılandırma zinciri, konteyner durumu ve kablosuz koşullara bağlıdır.

Kullanıcı Tarafı Sorun Giderme

SNZB-02DR2 ortamı ilgili düzeltmeleri içeren sürümlere zaten yükseltildiyse ancak OTA hala başarısız oluyorsa, firmware hala gönderilmiyorsa, yükseltmeler hala takılıyorsa veya sürüm güncellemeden sonra değişmiyorsa, aşağıdaki kontroller sırasıyla yapılmalıdır:

1. Gerçek platform ve bileşen sürümlerini doğrulayın

• Zigbee2MQTT en az 25.25.0 olmalıdır

• ZHA / zigpy en az 0.90.0 olmalıdır

2. Konteyner imajının veya çalışma zamanı ortamının gerçekten güncellendiğini doğrulayın

3. OTA sağlayıcı ayarlarının, yerel OTA indeks verilerinin ve firmware meta verilerinin tutarlı olduğunu doğrulayın

4. Cihazdan yeni bir OTA sorgusu tetikleyin, örneğin cihazı güç döngüsüne sokarak Query Next Image Request göndermesini sağlayın

5. Sinyal gücünü, mesafeyi ve 2.4 GHz parazitini kontrol edin

Sonuç

SNZB-02DR2 etrafındaki OTA düzeltmesi, gerçek dağıtımlarda gözlemlenen başarısızlıklarla başladı. Sorunun kök nedeni, Telink SDK'daki OTA şifreleme formatı değişiklikleri ile mevcut ayrıştırıcı davranışı arasındaki uyumluluk boşluğuna indirgenmiştir.

Zigbee2MQTT #9963 -> #9984 -> 25.25.0'dan, ZHA / zigpy #1734 -> #1736 -> 0.90.0'a ve ardından OTA blok boyutu, şema ve sağlayıcı yönetimi üzerine sonraki topluluk çalışmalarına kadar, sonuç Home Assistant genelinde daha geniş ve daha kararlı Telink OTA desteğidir.

Cihaz satıcıları için uyumluluk desteği sadece geçici bir çözüm sağlamakla ilgili değildir. Aynı zamanda sorunu yukarı akış ekosistemine taşımayı ve böylece düzeltmenin platformun kendisinin bir parçası haline gelmesini gerektirir.