Principy a používání rozdílových aktualizací ve službě Device Update pro IoT Hub (Preview)

Článek
03/05/2024

Rozdílové aktualizace umožňují vygenerovat malou aktualizaci, která představuje pouze změny mezi dvěma úplnými aktualizacemi – zdrojovou i cílovou imagí. Tento přístup je ideální pro snížení šířky pásma používané ke stažení aktualizace do zařízení, zejména pokud mezi zdrojovými a cílovými aktualizacemi existuje jen několik změn.

Poznámka:

Funkce rozdílové aktualizace je aktuálně ve verzi Public Preview.

Požadavky na používání rozdílových aktualizací ve službě Device Update pro IoT Hub

Zdrojové a cílové aktualizační soubory musí být ve formátu SWUpdate (SWU).
V každém souboru SWUpdate musí existovat nezpracovaná image, která používá systém souborů Ext2, Ext3 nebo Ext4. Tento obrázek lze komprimovat pomocí gzip nebo zstd.
Proces rozdílové generace rekomprimuje cílovou aktualizaci SWU pomocí komprese zstd, aby se vytvořil optimální rozdíl. Naimportujte tuto rekomprimovanou cílovou aktualizaci SWU do služby Device Update spolu s vygenerovaným rozdílovým aktualizačním souborem.
V rámci SWUpdate na zařízení musí být povolena také dekomprese zstd.
- Tento proces vyžaduje použití SWUpdate 2019.11 nebo novějšího.

Konfigurace zařízení s agentem Device Update a komponentou rozdílového procesoru

Aby vaše zařízení mohlo stahovat a instalovat rozdílové aktualizace ze služby Device Update, potřebujete několik součástí, které jsou přítomné a nakonfigurované.

Agent aktualizace zařízení

Agent aktualizace zařízení orchestruje proces aktualizace na zařízení, včetně akcí stahování, instalace a restartování. Přidejte agenta Device Update do zařízení a nakonfigurujte ho pro použití. Použijte agenta verze 1.0 nebo novější. Pokyny najdete v tématu Zřizování agenta služby Device Update.

Obslužná rutina aktualizace

Obslužná rutina aktualizace se integruje s agentem Device Update, aby se provedla skutečná instalace aktualizace. U rozdílových aktualizací začněte obslužnou rutinou aktualizace, pokud ještě nemáte vlastní obslužnou rutinu microsoft/swupdate:2 aktualizace SWUpdate, kterou chcete upravit. Pokud používáte vlastní obslužnou rutinu aktualizace, nezapomeňte povolit dekompresi zstd v SWUpdate.

Rozdílový procesor

Rozdílový procesor znovu vytvoří původní soubor obrázku SWU na vašem zařízení po stažení souboru delta, takže obslužná rutina aktualizace může nainstalovat soubor SWU. Kód rozdílového procesoru je k dispozici v úložišti Azure/iot-hub-device-update-delta Na GitHubu.

Pokud chcete přidat komponentu rozdílového procesoru do image zařízení a nakonfigurovat ji pro použití, postupujte podle pokynů README.md k sestavení rozdílového procesoru ze zdroje pomocí CMAKE. Odtud nainstalujte sdílený objekt (libadudiffapi.so) přímo tak, že ho /usr/lib zkopírujete do adresáře:

sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
sudo ldconfig

Přidání zdrojového obrázkového souboru SWU do zařízení

Po stažení rozdílové aktualizace do zařízení se musí porovnat s platným zdrojovým souborem SWU, který byl dříve uložen v mezipaměti zařízení. Tento proces je potřeba, aby rozdílová aktualizace znovu vytvořila úplnou cílovou image. Nejjednodušším způsobem, jak tuto image v mezipaměti naplnit, je nasadit úplnou aktualizaci image do zařízení prostřednictvím služby Device Update (pomocí existujících procesů importu a nasazení ). Pokud je zařízení nakonfigurované s agentem Aktualizace zařízení (verze 1.0 nebo novější) a rozdílovým procesorem, agent Device Update ukládá nainstalovaný soubor SWU automaticky do mezipaměti pro pozdější použití rozdílové aktualizace.

Pokud chcete zdrojovou image na svém zařízení přímo naplníte, cesta, ve které se očekává obrázek, je následující:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

Ve výchozím nastavení BASE_SOURCE_DOWNLOAD_CACHE_PATH je cesta /var/lib/adu/sdc/[provider]. Hodnota [provider] je Zprostředkovatel součástí updateId zdrojového souboru SWU.

ENCODED_HASH je šestnáctkový řetězec SHA256 binárního souboru base64, ale po kódování do šestnáctkového řetězce base64 kóduje znaky následujícím způsobem:

+ zakódováno jako octets _2B
/ zakódováno jako octets _2F
= zakódováno jako octets _3D

Generování rozdílových aktualizací pomocí nástroje DiffGen

Požadavky na prostředí

Před vytvořením rozdílových hodnot pomocí diffGen je potřeba na počítači prostředí stáhnout a/nebo nainstalovat několik věcí. Doporučujeme linuxové prostředí a konkrétně Ubuntu 20.04 (nebo Subsystém Windows pro Linux nativně ve Windows).

Následující tabulka obsahuje seznam potřebných obsahu, kde je načíst, a v případě potřeby doporučenou instalaci:

Binární název	Kde získat	Postup instalace
DiffGen	Azure/iot-hub-device-update-delta úložiště GitHub	V kořenové složce vyberte Microsoft.Azure.DeviceUpdate.Diffs.[ version].nupkg file. Přečtěte si další informace o balíčcích NuGet.
. NETCore Runtime, verze 6.0.0	Přes terminál / Správce balíčků	Pokyny pro Linux. Vyžaduje se pouze modul runtime.

Závislosti

Zstd_compression_tool slouží k dekomprimování souborů obrázků archivu a jejich rekomprimování pomocí zstd. Tento proces zajišťuje, že všechny soubory archivu používané pro generování rozdílů mají stejný algoritmus komprese pro obrázky uvnitř archivů.

Příkazy pro instalaci požadovaných balíčků/knihoven:

sudo apt update  
sudo apt-get install -y python3 python3-pip  
sudo pip3 install libconf zstandard

Vytvoření rozdílové aktualizace pomocí diffGen

Nástroj DiffGen se spustí s několika argumenty. Všechny argumenty jsou povinné a celková syntaxe je následující:

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive]

Skript recompress_tool.py spustí vytvoření souboru [recompressed_target_archive], který se pak použije místo [target_archive] jako cílový soubor pro vytvoření rozdílu.
Soubory obrázků v rámci [recompressed_target_archive] se komprimují pomocí zstd.

Pokud jsou vaše soubory SWU podepsané (pravděpodobně), potřebujete také další argument:

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive] "[signing_command]"

Kromě použití [recompressed_target_archive] jako cílového souboru poskytuje parametr řetězce podpisového příkazu spuštění recompress_and_sign_tool.py k vytvoření souboru [recompressed_target_archive] a mít soubor sw-description v archivu podepsaný (což znamená, že soubor sw-description.sig je k dispozici). Ukázkový sign_file.sh skript můžete použít z úložiště Azure/iot-hub-device-update-delta Na GitHubu. Otevřete skript, upravte ho a přidejte cestu k souboru privátního klíče a pak ho uložte. Ukázkové využití najdete v části s příklady.

Následující tabulka popisuje argumenty podrobněji:

Argument	Popis
[source_archive]	Toto je obrázek, proti kterému je rozdíl založený při vytváření rozdílu. Důležité: Tento obrázek musí být shodný s obrázkem, který už je na zařízení (například uložený v mezipaměti z předchozí aktualizace).
[target_archive]	Toto je obrázek, na který delta aktualizuje zařízení.
[output_path]	Cesta (včetně požadovaného názvu vygenerovaného rozdílového souboru) na hostitelském počítači, kde se po vytvoření umístí rozdílový soubor. Pokud cesta neexistuje, nástroj ji vytvoří.
[log_folder]	Cesta na hostitelském počítači, kde se vytvoří protokoly. Toto umístění doporučujeme definovat jako podsložku výstupní cesty. Pokud cesta neexistuje, nástroj ji vytvoří.
[working_folder]	Cesta na počítači, kde jsou během generování rozdílu umístěné doprovodné materiály a další pracovní soubory. Toto umístění doporučujeme definovat jako podsložku výstupní cesty. Pokud cesta neexistuje, nástroj ji vytvoří.
[recompressed_target_archive]	Cesta na hostitelském počítači, kde se vytvoří rekomprimovaný cílový soubor. Tento soubor se používá místo <target_archive> jako cílový soubor pro generování rozdílů. Pokud tato cesta existuje před voláním DiffGenTool, cesta se přepíše. Tuto cestu doporučujeme definovat jako soubor v podsložce výstupní cesty.
"[signing_command]" (volitelné)	Přizpůsobitelný příkaz použitý k podepsání souboru sw-description v souboru rekomprimovaného archivu. Soubor sw-description v rekomprimované archivu se používá jako vstupní parametr pro podpisový příkaz; DiffGenTool očekává, že podpisový příkaz vytvoří nový soubor podpisu pomocí názvu vstupu s připojeným kódem `.sig` . Obklopuje parametr v dvojitých uvozovkách, aby se celý příkaz předal jako jediný parametr. Nepoužívejte také znak ~do cesty ke klíči, který se používá k podepisování, a místo toho použijte úplnou domovskou cestu (například místo ~/keys/priv.pem použijte /home/USER/keys/priv.pem).

Příklady diffGen

V těchto příkladech pracujeme mimo adresář /mnt/o/temp (ve WSL):

Vytvoření rozdílu mezi vstupním zdrojovým souborem a rekomprimovaným cílovým souborem:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]  
/mnt/o/temp/[target file.swu]  
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]

Pokud používáte také podpisový parametr (potřebný v případě podepsání souboru SWU), můžete použít ukázkový sign_file.sh skript, na který jste odkazovali dříve. Nejprve otevřete skript a upravte ho a přidejte cestu k souboru privátního klíče. Uložte skript a spusťte DiffGen následujícím způsobem:

Vytvoření rozdílu mezi vstupním zdrojovým souborem a rekomprimovaným/rekompresovaným cílovým souborem:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]
/mnt/o/temp/[target file.swu]   
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]  
/mnt/o/temp/[path to script]/sign_file.sh

Import vygenerované rozdílové aktualizace

Základní proces importu aktualizace do služby Device Update se u rozdílových aktualizací nezmění, takže pokud jste to ještě neudělali, nezapomeňte si projít tuto stránku: Jak připravit aktualizaci pro import do služby Azure Device Update pro IoT Hub.

Generování manifestu importu

Prvním krokem při importu aktualizace do služby Device Update je vždy vytvoření manifestu importu, pokud ho ještě nemáte. Další informace o importu manifestů najdete v tématu Import aktualizací do služby Device Update. V případě rozdílových aktualizací musí manifest importu odkazovat na dva soubory:

Recompressed target SWU image created when you ran the DiffGen tool.
Rozdílový soubor vytvořený při spuštění nástroje DiffGen.

Funkce rozdílové aktualizace používá funkci označovanou jako související soubory, která vyžaduje manifest importu verze 5 nebo novější.

Pokud chcete vytvořit manifest importu pro rozdílovou aktualizaci pomocí funkce souvisejících souborů, musíte do manifestu importu přidat objekty relatedFiles a downloadHandler .

Pomocí objektu relatedFiles můžete zadat informace o rozdílovém aktualizačním souboru, včetně názvu souboru, velikosti souboru a hodnoty hash sha256. Důležité je také zadat dvě vlastnosti, které jsou jedinečné pro funkci rozdílové aktualizace:

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "[insert the source SWU image file hash]"
}

Obě tyto vlastnosti jsou specifické pro váš zdrojový soubor image SWU, který jste použili jako vstup pro nástroj DiffGen při vytváření rozdílové aktualizace. Informace o zdrojové imagi SWU jsou potřeba v manifestu importu, i když zdrojovou image ve skutečnosti neimportujete. Rozdílové komponenty v zařízení používají tato metadata o zdrojové imagi k vyhledání obrázku v zařízení po stažení rozdílu.

Pomocí objektu downloadHandler určete, jak agent Device Update orchestruje rozdílovou aktualizaci pomocí funkce souvisejících souborů. Pokud neukončíte vlastní verzi agenta Device Update pro rozdílové funkce, měli byste použít jenom tuto obslužnou rutinu stahování:

"downloadHandler": {
  "id": "microsoft/delta:1"
}

K vygenerování manifestu importu pro rozdílovou aktualizaci můžete použít rozhraní příkazového řádku Azure (CLI). Pokud jste k vytvoření manifestu importu ještě nepoužívali Azure CLI, přečtěte si téma Vytvoření základního manifestu importu.

az iot du update init v5
--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}'

Uložte vygenerovaný json manifestu importu do souboru s příponou. .importmanifest.json

Import prostřednictvím portálu Azure Portal

Po vytvoření manifestu importu jste připraveni naimportovat rozdílovou aktualizaci. Pokud chcete provést import, postupujte podle pokynů v tématu Přidání aktualizace do služby Device Update pro IoT Hub. Při importu musíte zahrnout tyto položky:

Manifest importu .json souboru, který jste vytvořili v předchozím kroku.
Recompressed target SWU image created when you ran the DiffGen tool.
Rozdílový soubor vytvořený při spuštění nástroje DiffGen.

Nasazení rozdílové aktualizace do zařízení

Když nasadíte rozdílovou aktualizaci, prostředí na webu Azure Portal vypadá stejně jako při nasazování běžné aktualizace image. Další informace o nasazení aktualizací najdete v tématu Nasazení aktualizace pomocí služby Device Update pro Azure IoT Hub.

Jakmile vytvoříte nasazení pro rozdílovou aktualizaci, služba Device Update a klient automaticky zjistí, jestli pro každé zařízení, které nasazujete, existuje platná rozdílová aktualizace. Pokud se najde platný rozdíl, aktualizace delta se stáhne a nainstaluje na toto zařízení. Pokud se nenajde žádná platná rozdílová aktualizace, stáhne se jako záložní aktualizace úplná aktualizace image (rekomprimovaná cílová image SWU). Tento přístup zajišťuje, že se všechna zařízení, která nasazujete, dostanou k příslušné verzi.

Existují tři možné výsledky nasazení rozdílové aktualizace:

Aktualizace Delta byla úspěšně nainstalována. Zařízení je na nové verzi.
Rozdílová aktualizace nebyla k dispozici nebo se nepodařilo nainstalovat, ale místo toho došlo k úspěšné záložní instalaci úplné image. Zařízení je na nové verzi.
Rozdílové i záložní image selhaly. Zařízení je stále ve staré verzi.

Pokud chcete zjistit, ke kterým z výše uvedených výsledků došlo, můžete zobrazit výsledky instalace s kódem chyby a rozšířeným kódem chyby výběrem libovolného zařízení, které je ve stavu selhání. V případě potřeby můžete také shromažďovat protokoly z více zařízení, která selhala.

Pokud rozdílová aktualizace proběhla úspěšně, zobrazí se u zařízení stav Úspěch.

Pokud rozdílová aktualizace selhala, ale proběhla úspěšná záložní aktualizace na celou image, zobrazí se následující stav chyby:

resultCode: [hodnota větší než 0]
extendedResultCode: [non-zero]

Pokud aktualizace nebyla úspěšná, zobrazí se stav chyby, který lze interpretovat pomocí těchto pokynů:

Začněte s chybami agenta device Update ve výsledku.h.

Chyby z agenta aktualizace zařízení, které jsou specifické pro funkci obslužné rutiny stahování používané pro rozdílové aktualizace začínají 0x9:

Komponenta	Desetinné číslo	Hex	Poznámka:
EXTENSION_MANAGER	0	0x00	Označuje chyby z logiky obslužné rutiny stahování správce rozšíření. Příklad: 0x900XXXXX
PLUGIN	0	0x01	Označuje chyby při použití sdílených knihoven modulu plug-in obslužné rutiny stahování. Příklad: 0x901XXXXX
VYHRAZENA	2 - 7	0x02 – 0x07	Vyhrazeno pro obslužnou rutinu stahování. Příklad: 0x902XXXXX
BĚŽNÉ	8	0x08	Označuje chyby v logice nejvyšší úrovně rozšíření delta download obslužné rutiny. Příklad: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Označuje chyby v rozšíření aktualizace zdrojové aktualizace mezipaměti obslužné rutiny delta ke stažení. Příklad: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Kód chyby z rozhraní DELTA PROCESSOR API Příklad: 0x90AXXXXX

Pokud kód chyby není ve výsledku.h, pravděpodobně se jedná o chybu v komponentě rozdílového procesoru (odděleně od agenta device Update). Pokud ano, extendedResultCode je záporná desetinná hodnota následujícího šestnáctkového formátu: 0x90AXXXXX
- 9 je "Delta Facility"
- 0A je komponenta Delta Processor (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX je 20bitový kód chyby z procesoru FIT Delta.

Pokud se vám nedaří problém vyřešit na základě informací o kódu chyby, vytvořte problém GitHubu a získejte další pomoc.

Další kroky

Řešení běžných potíží

Share via