Naprawa problemu OTA w SNZB-02DR2: ulepszanie wsparcia Home Assistant dla Telink OTA

Podsumowanie

We wrześniu 2025 roku nowo wydany SNZB-02DR2 działał zgodnie z oczekiwaniami na własnej bramce SONOFF, ale na Home Assistant zaczęły pojawiać się problemy z OTA. Zgłaszane objawy obejmowały niepowodzenia w sprawdzaniu aktualizacji, osiąganie 100% postępu aktualizacji bez zmiany zainstalowanej wersji firmware oraz brak powiadomień push o firmware. Problem pojawił się zarówno w Zigbee2MQTT, jak i ZHA.
SNZB-02DR2 jest zbudowany na SoC Telink. Po przeanalizowaniu logów, struktury obrazu firmware i zachowania platformy, zespół SONOFF ustalił, że problem wynika ze zmian w formacie szyfrowania OTA używanym w Telink SDK, które wprowadziły lukę kompatybilności z istniejącą logiką parsowania OTA. Poprawki zostały wprowadzone w dwóch etapach: najpierw po stronie Zigbee2MQTT dla specyficznego dla dostawcy Telink 0xf000 szyfrowanego pakowania, a następnie po stronie ZHA / zigpy dla szyfrowanego parsowania OTA Telink. Wkład społecznościowy rozszerzył później prace o rozmiar bloków OTA, schemat i aktualizacje dostawcy.

Ekspozycja i objawy

We wrześniu 2025 roku nowo wydany SNZB-02DR2 działał normalnie na własnej bramce SONOFF, ale pojawiły się problemy z OTA na Home Assistant. Główne objawy to:

• niepowodzenia w sprawdzaniu aktualizacji
• przesyłanie OTA kończące się przekroczeniem limitu czasu lub zacięciami
• postęp aktualizacji osiągający 100%, podczas gdy wersja firmware pozostawała niezmieniona
• urządzenia pokazujące Firmware: Nieznany
• brak powiadomień push o firmware, gdy spodziewano się aktualizacji

Te objawy pojawiły się zarówno w Zigbee2MQTT, jak i ZHA. Na podstawie logów, obrazów firmware i zachowania w czasie działania, zespół SONOFF zawęził problem do niezgodności OTA związanej z formatem szyfrowania Telink SDK.

Rodzaje awarii OTA

Ten problem dzieli się na trzy kategorie:

Pierwszą przyczyną jest awaria transmisji bezprzewodowej, zwykle objawiająca się przekroczeniem limitu czasu, zacięciami lub nadmierną liczbą retransmisji. Częste przyczyny to zakłócenia na częstotliwości 2,4 GHz, słaby sygnał oraz duża odległość między urządzeniem a koordynatorem.

Drugą przyczyną jest błąd parsowania obrazu OTA. W takim przypadku kontrole aktualizacji kończą się niepowodzeniem na wczesnym etapie lub obraz jest przesyłany, ale później występuje błąd podczas parsowania, dzielenia na fragmenty lub walidacji.

Trzecią przyczyną jest niezgodność wersji i konfiguracji. Typowe przykłady to urządzenia nadal działające na starszych obrazach, ustawienia dostawcy OTA niezgodne z zainstalowaną wersją lub nieprawidłowe metadane indeksu. Zwykle objawia się to tym, że środowisko zostało zaktualizowane, ale poprawka nie zaczyna działać.

Niezgodność pakowania i parsowania OTA Telink

Przyczynę problemu zidentyfikowano jako zmiany w formacie szyfrowania OTA używanym przez Telink SDK.

Standardowy podelement Zigbee OTA można uprościć do:

W standardowym układzie pole Długość opisuje tylko rozmiar następujących danych. Nie obejmuje ID tagu ani samego pola Długość.

W szyfrowanym pakowaniu Telink OTA, szczególnie w elementach specyficznych dla dostawcy takich jak 0xf000, układ zawiera dodatkowe pole:

Wstawione Tag Info zmienia fizyczny układ strumienia danych, podczas gdy znaczenie pola Długość nie jest poprawnie interpretowane przez parsery, które nadal podążają standardową ścieżką. To powoduje niezgodność przesunięcia.

Jeśli parser nadal odczytuje obraz jako standardowy ZCL OTA, obliczanie przesunięcia, obsługa długości i wycinanie danych będą błędne. Typowe skutki to:

• błędy przesunięcia lub zakresu podczas inspekcji obrazu OTA
• pomyślne przesłanie uszkodzonego obrazu w pamięci
• odrzucenie przez urządzenie podczas końcowego etapu walidacji

Problem jest więc niezgodnością parsowania spowodowaną zaktualizowanym formatem szyfrowania OTA w SDK Telink.

Zigbee2MQTT: diagnoza i naprawa

zgłoszenie #9963

9 września 2025 otwarto zgłoszenie #9963 (https://github.com/Koenkk/zigbee-herdsman-converters/issues/9963) w zigbee-herdsman-converters pod tytułem Kilka pytań o metodę szyfrowania OTA.

Problem już pokazał podstawową usterkę: podczas sprawdzania aktualizacji OTA, parsowanie dotarło do tagID:0xf000, a następnie zakończyło się błędem przesunięcia poza zakres. Udokumentowano też wnioski zespołu SONOFF:
• problem dotyczył pakowania szyfrowania OTA w SDK Telink
• struktura obrazu zawierała dodatkowe pole Tag Info
• poprawkę parsowania można było zweryfikować przez zmianę parseSubElement
• OTA zakończone pomyślnie po dostosowaniu parsera

PR #9984

Na podstawie analizy w zgłoszeniu, zespół SONOFF zgłosił PR #9984 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/9984), zatytułowany dodanie kodu obsługi OTA z Telink OTA.

PR został scalony 13-09-2025, z commitem scalającym 6cb56489bc9e9ea4c2df99f9499d61d9c10671f0.
Poprawka nie dodała gałęzi specyficznej dla urządzenia dla pojedynczego produktu. Dodała kompatybilność parsowania dla pakowania OTA Telink. Zakres był więc szerszy niż jeden model i obejmował wpływ kompatybilności wprowadzony przez zmiany formatu szyfrowania OTA w SDK Telink.

Wydanie 25.25.0

PR wydania #10005 (https://github.com/Koenkk/zigbee-herdsman-converters/pull/10005) dla zigbee-herdsman-converters został scalony 2025-09-13, odpowiadający wersji 25.25.0.

Notatki do wydania wyraźnie zawierały:
• Wsparcie zaszyfrowanych OTA Telink (#9984)

To uczyniło zaszyfrowane OTA Telink częścią głównej linii Zigbee2MQTT.

Postęp ZHA / zigpy

Po zdiagnozowaniu i naprawieniu problemu po stronie Zigbee2MQTT było jasne, że problem nie dotyczył tylko jednej ścieżki integracji. Była to szersza luka kompatybilności w sposobie obsługi Telink OTA przez Home Assistant.

ZHA opiera się na zigpy do przetwarzania OTA, więc potwierdzona przyczyna w Zigbee2MQTT musiała zostać również rozwiązana w parserze OTA zigpy.

PR #1734

Na podstawie problemu ze strukturą Telink OTA ujawnionego w Zigbee2MQTT, zespół SONOFF zgłosił PR #1734 (https://github.com/zigpy/zigpy/pull/1734) do zigpy. Propozycja dodała dedykowane wsparcie parsowania Telink OTA i propagowała powiązany flagę szyfrowania.

PR #1736

Po dyskusji wokół #1734, zigpy przyjęło inną implementację w PR #1736 (https://github.com/zigpy/zigpy/pull/1736) zatytułowaną Parsowanie zaszyfrowanych plików Telink OTA.

PR został scalony 2026-01-03, z commitem scalającym 78a0b4da658deef0e7e88ec3bad0c80f20a19ea9.

Główne zmiany w #1736 to:
• bezpośrednie wykrywanie i parsowanie zaszyfrowanych obrazów Telink OTA
• usunięcie ścisłego uzależnienia od zewnętrznych metadanych do identyfikacji zaszyfrowanych obrazów Telink
• natywne rozpoznawanie Telink OTA wewnątrz parsera

Pozwoliło to parserowi na bezpośrednie rozpoznawanie tych obrazów zamiast polegać wyłącznie na warunkach zewnętrznych.

Wydanie zigpy 0.90.0

zigpy 0.90.0 zostało wydane 2026-01-03, a w notatkach do wydania wyraźnie zawarto:
• Parsowanie zaszyfrowanych plików Telink OTA przez @puddly w #1736 Link do wydania: zigpy 0.90.0 (https://github.com/zigpy/zigpy/releases/tag/0.90.0) Wersja 0.90.0 to kluczowe wydanie, w którym w ZHA / zigpy udostępniono możliwość parsowania zaszyfrowanych plików Telink OTA.

Dalsze prace społecznościowe

Wersja 0.90.0 rozwiązała podstawowy problem parsowania szyfrowanego Telink OTA, ale nie objęła wszystkich szczegółów kompatybilności. Społeczność kontynuowała prace nad kolejnymi poprawkami.

Poprawka rozmiaru bloku OTA

W PR #1781 (https://github.com/zigpy/zigpy/pull/1781) współtwórcy społeczności zajęli się kompatybilnością rozmiaru bloku OTA.
PR zatytułowany Increase OTA block size cap został scalony 2026-03-02. Niektóre urządzenia Telink żądają bloku OTA o rozmiarze 48 bajtów, podczas gdy wcześniejszy limit wynosił tylko 40 bajtów. Nawet przy poprawnym parsowaniu obrazu aktualizacja może się nie powieść, jeśli żądany i dostarczony rozmiar bloku się nie zgadzają.
To pokazuje, że kompatybilność Telink OTA to nie tylko parsowanie obrazu. Obejmuje także dopasowanie parametrów transportu.

Dostosowanie schematu OTA i dostawcy

PR #1782 (https://github.com/zigpy/zigpy/pull/1782) następnie zaktualizował schemat zigpy-ota do wersji v2.

Nawet gdy framework już obsługuje parsowanie Telink OTA, użytkownicy mogą nadal widzieć nieznane oprogramowanie układowe, brak powiadomień push lub brak skutecznej zmiany, jeśli metadane OTA, konfiguracja dostawcy i zainstalowana wersja zigpy nie są zsynchronizowane.

• Wersja 0.90.0 rozwiązała podstawowy problem z parsowaniem szyfrowanego Telink OTA

• późniejsze zmiany społeczności uzupełniły rozmiar bloku, schemat i szczegóły dystrybucji OTA

• Wsparcie ZHA dla Telink OTA rozwijało się etapami, a nie w jednej łatce

Typowe powody, dla których poprawka nadal nie działa

„Wsparcie upstream” nie oznacza, że lokalne środowisko od razu będzie działać poprawnie. Najczęstsze przyczyny na ostatnim etapie są poniżej.

1. Wersja runtime nie jest wersją, której oczekuje użytkownik

Jest to powszechne w wdrożeniach Docker. Użytkownik może zaktualizować pliki na hoście lub uważać, że kod został już zaktualizowany, podczas gdy kontener nadal działa na starszych wersjach pakietów. Jeśli runtime zigpy lub powiązany pakiet nie uległ zmianie, poprawka z repozytorium nie pojawi się lokalnie.

2. Zaktualizowano tylko część stosu

Na przykład Home Assistant może zostać zaktualizowany, podczas gdy zigpy nadal jest poniżej wymaganej wersji, lub lokalne pliki OTA i konfiguracja dostawcy mogą nadal korzystać ze starej ścieżki. W takim przypadku środowisko nadal zachowuje się tak, jakby poprawka nie została zastosowana.

3. Metadane dostawcy OTA lub indeksu nadal są niepoprawne

Nawet gdy wersje platformy są poprawne, platforma może nie rozpoznać lub nie przesłać oprogramowania, jeśli manufacturerCode, imageType, fileVersion, sha lub ścieżki plików w index.json są niespójne.

4. Urządzenie nie wysłało nowego zapytania OTA

Gotowość po stronie serwera nie oznacza, że urządzenie natychmiast wyśle nowe zapytanie o obraz. Jeśli urządzenie nie wyśle ponownie zapytania Query Next Image Request, przesyłanie oprogramowania może nadal nie działać.

5. Problemy z transmisją bezprzewodową nadal występują

Nawet po naprawieniu kompatybilności parsera, słaby sygnał, duża odległość, zakłócenia i nadmierne retransmisje mogą nadal powodować awarie OTA. To osobne problemy transportowe, które nie znikają po naprawieniu problemu z parsowaniem.

Wsparcie nadrzędne jest warunkiem koniecznym sukcesu OTA. To, czy poprawka faktycznie działa w praktyce, zależy od łańcucha wersji, konfiguracji, stanu kontenera i warunków bezprzewodowych.

Rozwiązywanie problemów po stronie użytkownika

Jeśli środowisko SNZB-02DR2 zostało już zaktualizowane do wersji zawierających odpowiednie poprawki, ale OTA nadal nie działa, oprogramowanie układowe nie jest przesyłane, aktualizacje zatrzymują się lub wersja nie zmienia się po aktualizacji, należy wykonać następujące kontrole w kolejności:

1. Potwierdź faktyczne wersje platformy i komponentów

• Zigbee2MQTT powinno mieć co najmniej wersję 25.25.0

• ZHA / zigpy powinny mieć co najmniej wersję 0.90.0

2. Potwierdź, że obraz kontenera lub środowisko uruchomieniowe faktycznie zostały zaktualizowane

3. Potwierdź, że ustawienia dostawcy OTA, lokalne dane indeksu OTA oraz metadane oprogramowania układowego są spójne

4. Wywołaj nowe zapytanie OTA z urządzenia, na przykład przez wyłączenie i ponowne włączenie zasilania, aby wysłało zapytanie Query Next Image Request

5. Sprawdź siłę sygnału, odległość i zakłócenia na 2,4 GHz

Wnioski

Poprawka OTA dotycząca SNZB-02DR2 zaczęła się od awarii zaobserwowanych w rzeczywistych wdrożeniach. Przyczynę źródłową zawężono do luki kompatybilności między zmianami formatu szyfrowania OTA w Telink SDK a istniejącym zachowaniem parsera.

Od Zigbee2MQTT #9963 -> #9984 -> 25.25.0, przez ZHA / zigpy #1734 -> #1736 -> 0.90.0, a następnie do późniejszych prac społeczności nad rozmiarem bloku OTA, schematem i obsługą dostawcy, efektem jest szersze i bardziej stabilne wsparcie Telink OTA w Home Assistant.

Dla dostawców urządzeń wsparcie kompatybilności to nie tylko zapewnienie tymczasowego obejścia. Wymaga to również przekazania problemu do ekosystemu nadrzędnego, aby poprawka stała się częścią samej platformy.