Sdílet prostřednictvím

Rozdílové aktualizace (Preview)

  • Článek

Rozdílové aktualizace umožňují generovat malé aktualizace, které představují pouze změny mezi dvěma úplnými aktualizacemi, zdrojovou imagí a 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 ve službě Azure Device Update pro IoT Hub 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.

Proces rozdílové generace rekomprimuje cílovou aktualizaci SWU pomocí komprese gzip k vytvoření optimálního rozdílu. Rekomprimovanou cílovou aktualizaci SWU naimportujete do služby Device Update spolu s vygenerovaným rozdílovým souborem aktualizace.

Konfigurace agenta aktualizace zařízení pro komponentu rozdílového procesoru

Pokud chcete stáhnout a nainstalovat rozdílové aktualizace ze služby Device Update, potřebuje vaše zařízení agenta Device Update s aktualizační obslužnou rutinou a komponentou delta procesoru, která je k dispozici a nakonfigurována.

Agent aktualizace zařízení

Agent aktualizace zařízení orchestruje proces aktualizace na zařízení, včetně akcí stahování, instalace a restartování. Pokud chcete přidat agenta Device Update do zařízení a nakonfigurovat ho pro použití, přečtěte si téma Zřizování agenta služby Device Update. Použijte agenta verze 1.0 nebo novější.

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.

Rozdílový procesor

Rozdílový procesor v Azure/iot-hub-device-update-delta znovu vytvoří původní soubor image SWU na vašem zařízení po stažení rozdílového souboru, aby obslužná rutina aktualizace mohl nainstalovat soubor SWU. Pokud chcete přidat komponentu rozdílového procesoru do image zařízení a nakonfigurovat ji pro použití, můžete si stáhnout balíček Debian pro Ubuntu 20.04 a novější z https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Pokud používáte jinou distribuci, postupujte podle pokynů README.md k vytvoření rozdílového procesoru ze zdroje pomocí CMAKE. Odtud nainstalujte sdílený objekt libadudiffapi.so přímo tak, že ho zkopírujete do adresáře /usr/lib následujícím způsobem:

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ého aktualizačního souboru do zařízení se porovná s platným <source_archive> dříve uloženým v mezipaměti zařízení. Tento proces umožňuje rozdílové aktualizaci znovu vytvořit úplnou cílovou image.

Nejjednodušší způsob, jak tuto image v mezipaměti naplnit, je importovat a nasadit úplnou aktualizaci image do zařízení prostřednictvím služby Device Update. Pokud je zařízení nakonfigurované s agentem Device Update verze 1.0 nebo novějším a rozdílovým procesorem, agent 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 předem naplníte, je <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>cesta, ve které se očekává obrázek. Ve výchozím nastavení <BASE_SOURCE_DOWNLOAD_CACHE_PATH> je cesta /var/lib/adu/sdc/<provider>. Hodnota provider je provider 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í aktualizace Delta pomocí nástroje DiffGen

Rozdílové aktualizace můžete vytvořit pomocí nástroje Diff Generation (DiffGen).

Požadavky na prostředí

Než začnete vytvářet rozdíly pomocí diffGen, musíte si na počítač s prostředím stáhnout a nainstalovat několik věcí. V ideálním případě použijte linuxové prostředí Ubuntu 20.04 nebo Subsystém Windows pro Linux, pokud používáte Windows.

Následující tabulka ukazuje potřebný obsah, kde ho získat, 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 Stáhněte si verzi odpovídající operačnímu systému nebo distribuci na počítači, která se má použít k vygenerování rozdílových aktualizací.
. NetCore runtime, verze 8.0.0 Prostřednictvím správce terminálů nebo balíčků Nainstalujte .NET v Linuxu. Vyžaduje se pouze modul runtime.

Rozdílové vytváření aktualizací pomocí DiffGen

Nástroj DiffGen se spustí s následujícími povinnými argumenty a syntaxí:

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive>

Předchozí příkaz spustí recompress_tool.py skript, který vytvoří <recompressed_target_file>. DiffGen pak použije <recompressed_target_file>místo <target_archive> jako cílový soubor pro vytvoření rozdílu. Soubory obrázků v rámci souboru <recompressed_target_archive> jsou komprimovány pomocí gzip.

Pokud jsou soubory SWU podepsané, vyžadují <signing_command> také argument v příkazu DiffGen:

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive> "<signing_command>"

DiffGenTool s podpisovým parametrem řetězce příkazu spustí recompress_and_sign_tool.py skript. Tento skript vytvoří .<recompressed_target_file> Kromě toho tento skript také podepíše soubor sw-description v archivu a vytvoří soubor sw-description.sig .

Pomocí ukázkového skriptu sign_file.sh z úložiště Azure/iot-hub-device-update-delta GitHubu můžete vytvořit rozdíl mezi vstupním zdrojovým souborem a rekomprimovaným cílovým souborem a opětovně podepsaným cílovým souborem. Otevřete skript, upravte ho a přidejte cestu k souboru privátního klíče a uložte ho. Ukázkové využití najdete v části Příklady .

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

Argument Popis
<source_archive> Základní image, kterou DiffGen používá jako výchozí bod k vytvoř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> Obrázek, na který rozdílový rozdíl aktualizuje zařízení.
<output_path> Cesta na hostitelském počítači, do které se má po vytvoření umístit rozdílový soubor, včetně požadovaného názvu vygenerovaného rozdílového souboru. Pokud cesta neexistuje, nástroj ji vytvoří.
<log_folder> Cesta na hostitelském počítači pro vytvoření protokolů. Nejlepší je definovat toto umístění jako podsložku výstupní cesty. Pokud cesta neexistuje, nástroj ji vytvoří.
<working_folder> Cesta na počítači k umístění zajištění a dalších pracovních souborů během rozdílové generace. Nejlepší je definovat toto umístění jako podsložku výstupní cesty. Pokud cesta neexistuje, nástroj ji vytvoří.
<recompressed_target_archive> Cesta na hostitelském počítači, ve které se má vytvořit <recompressed_target_file> Použije <recompressed_target_file> se místo cílového <target_archive> souboru pro diff generování. Pokud tato cesta existuje před voláním nástroje DiffGen, je přepsána. Nejlepší je definovat tento soubor v podsložce výstupní cesty.
"<signing_command>" (volitelné) Přizpůsobitelný příkaz pro podepsání souboru sw-description v souboru <recompressed_target_archive>. Soubor sw-description v rekomprimované archivu se používá jako vstupní parametr pro podpisový příkaz. DiffGen očekává, že podpisový příkaz vytvoří nový soubor podpisu pomocí názvu vstupu s připojeným souborem .sig .

Parametr musíte ohraničit dvojitými uvozovkami, aby se celý příkaz předal jako jediný parametr. Nepoužívejte ~ také znak v cestě 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

Následující příklady fungují mimo adresář /mnt/o/temp v Subsystém Windows pro Linux.

Následující kód vytvoří rozdíl 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 create>
/mnt/o/temp/logs
/mnt/o/temp/working
/mnt/o/temp/<recompressed target file to create>.swu

Pokud používáte také podpisový parametr, který musíte použít, pokud je soubor SWU podepsaný, můžete použít ukázkový sign_file.sh skript uvedený dříve. Otevřete skript, 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.

Následující kód vytvoří rozdíl mezi vstupním zdrojovým souborem a rekomprimovaným a znovu podepsaný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 create>  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/<recompressed target file to create>.swu  
/mnt/o/temp/<path to script>/<sign_file>.sh

Vygenerovaný rozdílový import aktualizace

Základní proces importu rozdílové aktualizace do služby Device Update je stejný jako u jakékoli jiné aktualizace. Pokud jste to ještě neudělali, přečtěte si, jak připravit aktualizaci, která se má naimportovat do služby Azure Device Update pro IoT Hub.

Vygenerování manifestu importu

Pokud chcete importovat aktualizaci do služby Device Update, musíte mít nebo vytvořit soubor manifestu importu. Další informace najdete v tématu Import aktualizací do služby Device Update.

Soubory manifestu importu pro rozdílové aktualizace musí odkazovat na následující soubory, které nástroj DiffGen vytvořil:

  • Obrázek <recompressed_target_file> SWU
  • <delta file>

Funkce rozdílové aktualizace používá funkci označovanou jako související soubory , které vyžadují manifest importu verze 5 nebo novější. Pokud chcete použít funkci souvisejících souborů, musíte do manifestu importu zahrnout 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. Nejdůležitější je, že musíte také zadat následující dvě vlastnosti, které jsou jedinečné pro funkci rozdílové aktualizace:

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "<source SWU image file hash>"
}

Obě vlastnosti jsou specifické pro <source image file> nástroj DiffGen, který jste použili jako vstup při vytváření rozdílové aktualizace. Manifest importu potřebuje informace o zdrojové imagi SWU, i když zdrojovou image ve skutečnosti neimportujete. Rozdílové komponenty v zařízení používají tato metadata o zdrojové imagi k vyhledání této image na zařízení po stažení rozdílové aktualizace.

Pomocí objektu downloadHandler určete, jak agent Device Update orchestruje rozdílovou aktualizaci pomocí funkce souvisejících souborů. Pokud si vlastní verzi agenta Device Update nevyužíváte pro rozdílové funkce, použijte následující downloadHandler:

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

K vygenerování manifestu importu pro rozdílovou aktualizaci můžete použít příkaz Azure CLI az iot du update init v5 . Další informace naleznete v tématu Vytvoření základního manifestu importu.

--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ý kód JSON manifestu importu s příponou souboru .importmanifest.json.

Import prostřednictvím portálu Azure Portal

Po vytvoření manifestu importu naimportujte rozdílovou aktualizaci podle pokynů v tématu Přidání aktualizace do služby Device Update pro IoT Hub. Do importu musíte zahrnout následující položky:

  • * importmanifest.json soubor, který jste dříve vytvořili v předchozích krocích
  • Obrázek <recompressed_target_file> SWU vytvořený nástroj DiffGen
  • Vytvořený <delta file> nástroj DiffGen

Rozdílové nasazení aktualizací do zařízení

Rozdílové nasazení aktualizací na webu Azure Portal je stejné jako nasazení běžné aktualizace image. Další informace najdete v tématu Nasazení aktualizace pomocí služby Device Update.

Jakmile vytvoříte nasazení pro rozdílovou aktualizaci, služba Device Update a klient automaticky určí, jestli je pro každé zařízení, do kterých nasazujete, platná rozdílová aktualizace. Pokud najdou platnou rozdílovou tabulku, stáhnutím a instalací rozdílové aktualizace na toto zařízení.

Pokud nenajde platnou rozdílovou aktualizaci, stáhne se úplná aktualizace image (rekomprimovaná cílová image SWU) jako záložní. 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:

  • Rozdílová aktualizace byla úspěšně nainstalována a zařízení je v nové verzi.
  • Rozdílová aktualizace nebyla k dispozici nebo se nepovedla nainstalovat, ale záložní instalace úplné image byla úspěšná a zařízení je v nové verzi.
  • Rozdílová i záložní instalace selhala a zařízení je stále ve staré verzi.

Pokud chcete zjistit, ke kterému výsledku selhání 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 několika neúspěšných zařízení.

  • Pokud byla rozdílová aktualizace úspěšná, zařízení zobrazí stav Úspěch .

  • Pokud se rozdílová aktualizace nezdařila, ale záložní aktualizace na celou image proběhla úspěšně, zobrazí se v zařízení následující stav chyby:

    • resultCode: <hodnota větší než 0>
    • extendedResultCode: <nenulová hodnota>

Řešení potíží s neúspěšnými aktualizacemi

Neúspěšné aktualizace zobrazují stav chyby, který můžete interpretovat pomocí následujících pokynů. Začněte s chybami agenta device Update ve výsledku.h.

Chyby z agenta služby Device Update, které jsou specifické pro funkci obslužné rutiny stahování rozdílových aktualizací, začínají na 0x9:

Komponenta Desetinné číslo Šestnáctkový Poznámka:
EXTENSION_MANAGER 0 0x00 Označuje chyby z logiky obslužné rutiny stahování správce rozšíření. Příklad: 0x900XXXXX
MODUL PLUG-IN 0 0x01 Označuje chyby při použití sdílených knihoven modulu plug-in obslužné rutiny stahování. Příklad: 0x901XXXXX
REZERVOVANÝ 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í rozšíření delta pro stahování. Příklad: 0x908XXXXX
SOURCE_UPDATE_CACHE 9 0x09 Indikuje chyby v mezipaměti aktualizace zdroje zdroje aktualizace rozšíření rozdílové obslužné rutiny stahování. 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, která je oddělená od agenta aktualizace zařízení. Pokud ano, extendedResultCode je záporná desetinná hodnota v šestnáctkovém formátu 0x90AXXXXX.

  • 9 is "Delta Facility"
  • 0A is "Delta Processor Component" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
  • XXXXX je 20bitový kód chyby z rozdílového procesoru Nástroje pro instalaci polí (FIT).

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

Související obsah