Förstå och använda deltauppdateringar i Enhetsuppdatering för IoT Hub (förhandsversion)

Artikel
03/08/2024

Med deltauppdateringar kan du generera en liten uppdatering som endast representerar ändringarna mellan två fullständiga uppdateringar – en källbild och en målbild. Den här metoden är perfekt för att minska den bandbredd som används för att ladda ned en uppdatering till en enhet, särskilt om det bara finns några få ändringar mellan käll- och måluppdateringarna.

Kommentar

Deltauppdateringsfunktionen är för närvarande i offentlig förhandsversion.

Krav för att använda deltauppdateringar i Enhetsuppdatering för IoT Hub

Käll- och måluppdateringsfilerna måste vara SWUpdate-format (SWU).
I varje SWUpdate-fil måste det finnas en råbild som använder filsystemet Ext2, Ext3 eller Ext4. Den bilden kan komprimeras med gzip eller zstd.
Deltagenereringsprocessen komprimerar mål-SWU-uppdateringen med hjälp av zstd-komprimering för att skapa ett optimalt delta. Importera den här komprimerade SWU-måluppdateringen till enhetsuppdateringstjänsten tillsammans med den genererade deltauppdateringsfilen.
Inom SWUpdate på enheten måste även zstd-dekomprimering vara aktiverat.
- Den här processen kräver att du använder SWUpdate 2019.11 eller senare.

Konfigurera en enhet med enhetsuppdateringsagenten och deltaprocessorkomponenten

För att enheten ska kunna ladda ned och installera deltauppdateringar från enhetsuppdateringstjänsten behöver du flera komponenter som finns och konfigurerats.

Enhetsuppdateringsagent

Enhetsuppdateringsagenten samordnar uppdateringsprocessen på enheten, inklusive åtgärder för att ladda ned, installera och starta om. Lägg till enhetsuppdateringsagenten på en enhet och konfigurera den för användning. Använd agentversion 1.0 eller senare. Anvisningar finns i Enhetsuppdateringsagentetablering.

Uppdateringshanterare

En uppdateringshanterare integreras med enhetsuppdateringsagenten för att utföra den faktiska uppdateringsinstallationen. För deltauppdateringar börjar du med microsoft/swupdate:2 uppdateringshanteraren om du inte redan har en egen SWUpdate-uppdateringshanterare som du vill ändra. Om du använder din egen uppdateringshanterare måste du aktivera zstd-dekomprimering i SWUpdate.

Delta-processor

Delta-processorn återskapar den ursprungliga SWU-avbildningsfilen på enheten efter att deltafilen har laddats ned, så att uppdateringshanteraren kan installera SWU-filen. Deltaprocessorkoden är tillgänglig på GitHub-lagringsplatsen Azure/iot-hub-device-update-delta .

Om du vill lägga till deltaprocessorkomponenten i din enhetsbild och konfigurera den för användning följer du README.md instruktioner för att använda CMAKE för att skapa deltaprocessorn från källan. Därifrån installerar du det delade objektet (libadudiffapi.so) direkt genom att kopiera det till /usr/lib katalogen:

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

Lägga till en käll-SWU-avbildningsfil på enheten

När en deltauppdatering har laddats ned till en enhet måste den jämföras med en giltig SWU-källfil som tidigare cachelagrades på enheten. Den här processen krävs för att deltauppdateringen ska kunna återskapa den fullständiga målbilden. Det enklaste sättet att fylla i den här cachelagrade avbildningen är att distribuera en fullständig avbildningsuppdatering till enheten via enhetsuppdateringstjänsten (med hjälp av befintliga import- och distributionsprocesser ). Så länge enheten har konfigurerats med enhetsuppdateringsagenten (version 1.0 eller senare) och deltaprocessorn cachelagrar Enhetsuppdateringsagenten den installerade SWU-filen automatiskt för senare användning av deltauppdatering.

Om du i stället vill fylla i källbilden direkt på enheten är sökvägen där avbildningen förväntas:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

Som standard BASE_SOURCE_DOWNLOAD_CACHE_PATH är sökvägen /var/lib/adu/sdc/[provider]. Värdet [provider] är providerdelen av updateId för käll-SWU-filen.

ENCODED_HASH är base64-hexsträngen i SHA256 för binärfilen, men efter kodning till base64 hexsträng kodas tecknen enligt följande:

+ kodad som octets _2B
/ kodad som octets _2F
= kodad som octets _3D

Generera deltauppdateringar med verktyget DiffGen

Miljökrav

Innan du skapar delta med DiffGen måste flera saker laddas ned och/eller installeras på miljödatorn. Vi rekommenderar en Linux-miljö och specifikt Ubuntu 20.04 (eller Windows-undersystem för Linux om den är inbyggd i Windows).

Följande tabell innehåller en lista över det innehåll som behövs, var de ska hämtas och den rekommenderade installationen om det behövs:

Binärt namn	Var du ska förvärva	Så här installerar du
DiffGen	GitHub-lagringsplats för Azure/iot-hub-device-update-delta	I rotmappen väljer du Microsoft.Azure.DeviceUpdate.Diffs.[ version].nupkg-fil . Läs mer om NuGet-paket.
. NETCore Runtime, version 6.0.0	Via terminal/pakethanterare	Instruktioner för Linux. Endast Körning krävs.

Beroenden

Den zstd_compression_tool används för att dekomprimera ett arkivs bildfiler och komprimera dem med zstd. Den här processen säkerställer att alla arkivfiler som används för diffgenerering har samma komprimeringsalgoritm för bilderna i arkiven.

Kommandon för att installera nödvändiga paket/bibliotek:

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

Skapa en deltauppdatering med DiffGen

Verktyget DiffGen körs med flera argument. Alla argument krävs och den övergripande syntaxen är följande:

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

Skriptet recompress_tool.py körs för att skapa filen [recompressed_target_archive], som sedan används i stället för [target_archive] som målfil för att skapa diffet.
Bildfilerna i [recompressed_target_archive] komprimeras med zstd.

Om dina SWU-filer är signerade (troligen) behöver du också ett annat argument:

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

Förutom att använda [recompressed_target_archive] som målfil körs en signeringskommandosträngsparameter recompress_and_sign_tool.py för att skapa filen [recompressed_target_archive] och ha sw-description-filen i arkivet signerad (vilket innebär att en sw-description.sig-fil finns). Du kan använda exempelskriptet sign_file.sh från GitHub-lagringsplatsen Azure/iot-hub-device-update-delta . Öppna skriptet, redigera det för att lägga till sökvägen till din privata nyckelfil och spara den. Se exempelavsnittet för exempelanvändning.

I följande tabell beskrivs argumenten mer detaljerat:

Argument	beskrivning
[source_archive]	Det här är den bild som deltat baseras på när deltat skapas. Viktigt: Den här avbildningen måste vara identisk med den avbildning som redan finns på enheten (till exempel cachelagrad från en tidigare uppdatering).
[target_archive]	Det här är den bild som deltat uppdaterar enheten till.
[output_path]	Sökvägen (inklusive det önskade namnet på deltafilen som genereras) på värddatorn där deltafilen placeras när den har skapats. Om sökvägen inte finns skapar verktyget den.
[log_folder]	Sökvägen på värddatorn där loggarna skapas. Vi rekommenderar att du definierar den här platsen som en undermapp för utdatasökvägen. Om sökvägen inte finns skapar verktyget den.
[working_folder]	Sökvägen på datorn där säkerheter och andra arbetsfiler placeras under deltagenereringen. Vi rekommenderar att du definierar den här platsen som en undermapp för utdatasökvägen. Om sökvägen inte finns skapar verktyget den.
[recompressed_target_archive]	Sökvägen på värddatorn där den komprimerade målfilen skapas. Den här filen används i stället för <target_archive> som målfil för diffgenerering. Om den här sökvägen finns innan DiffGenTool anropas skrivs sökvägen över. Vi rekommenderar att du definierar den här sökvägen som en fil i undermappen för utdatasökvägen.
"[signing_command]" (valfritt)	Ett anpassningsbart kommando som används för att signera sw-description-filen i den komprimerade arkivfilen. Sw-description-filen i det komprimerade arkivet används som indataparameter för signeringskommandot. DiffGenTool förväntar sig att signeringskommandot skapar en ny signaturfil med hjälp av namnet på indata med `.sig` tillagd. Att omge parametern med dubbla citattecken behövs så att hela kommandot skickas in som en enda parameter. Undvik också att placera "~"-tecknet i en nyckelsökväg som används för signering och använd den fullständiga hemsökvägen i stället (använd till exempel /home/USER/keys/priv.pem i stället för ~/keys/priv.pem).

DiffGen-exempel

I de här exemplen fungerar vi från katalogen /mnt/o/temp (i WSL):

Skapa ett bråk mellan indatakällans fil och den återkomprimerade målfilen:

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]

Om du också använder signeringsparametern (behövs om din SWU-fil är signerad) kan du använda exempelskriptet sign_file.sh som refererades tidigare. Öppna först skriptet och redigera det för att lägga till sökvägen till din privata nyckelfil. Spara skriptet och kör sedan DiffGen på följande sätt:

Skapa en diff mellan indatakällfilen och den återkomprimerade/återsignerade målfilen:

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

Importera den genererade deltauppdateringen

Den grundläggande processen för att importera en uppdatering till enhetsuppdateringstjänsten är oförändrad för deltauppdateringar, så om du inte redan har gjort det bör du gå igenom den här sidan: Så här förbereder du en uppdatering som ska importeras till Azure Device Update för IoT Hub

Generera importmanifest

Det första steget för att importera en uppdatering till enhetsuppdateringstjänsten är alltid att skapa ett importmanifest om du inte redan har ett. Mer information om importmanifest finns i Importera uppdateringar till Enhetsuppdatering. För deltauppdateringar måste importmanifestet referera till två filer:

Den återkomprimerade mål-SWU-avbildningen som skapades när du körde verktyget DiffGen.
Deltafilen som skapades när du körde verktyget DiffGen.

Funktionen deltauppdatering använder en funktion som kallas relaterade filer, vilket kräver ett importmanifest som är version 5 eller senare.

Om du vill skapa ett importmanifest för din deltauppdatering med hjälp av funktionen relaterade filer måste du lägga till relatedFiles och downloadHandler-objekt i importmanifestet.

Använd objektet relatedFiles för att ange information om deltauppdateringsfilen, inklusive filnamnet, filstorleken och sha256-hashen. Viktigt är att du också måste ange två egenskaper som är unika för deltauppdateringsfunktionen:

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

Båda dessa egenskaper är specifika för din SWU-källavbildningsfil som du använde som indata till verktyget DiffGen när du skapade deltauppdateringen. Informationen om käll-SWU-avbildningen behövs i importmanifestet även om du inte importerar källbilden. Deltakomponenterna på enheten använder dessa metadata om källbilden för att hitta avbildningen på enheten när deltat har laddats ned.

Använd - downloadHandler objektet för att ange hur enhetsuppdateringsagenten samordnar deltauppdateringen med hjälp av funktionen relaterade filer. Såvida du inte anpassar din egen version av enhetsuppdateringsagenten för deltafunktioner bör du bara använda den här downloadHandler:

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

Du kan använda Azure-kommandoradsgränssnittet (CLI) för att generera ett importmanifest för deltauppdateringen. Om du inte har använt Azure CLI för att skapa ett importmanifest tidigare kan du läsa Skapa ett grundläggande importmanifest.

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>"}'

Spara din genererade JSON-importmanifest till en fil med tillägget .importmanifest.json

Importera med hjälp av Azure-portalen

När du har skapat importmanifestet är du redo att importera deltauppdateringen. Om du vill importera följer du anvisningarna i Lägg till en uppdatering i Enhetsuppdatering för IoT Hub. Du måste inkludera dessa objekt när du importerar:

Importmanifestet .json fil som du skapade i föregående steg.
Den återkomprimerade mål-SWU-avbildningen som skapades när du körde verktyget DiffGen.
Deltafilen som skapades när du körde verktyget DiffGen.

Distribuera deltauppdateringen till dina enheter

När du distribuerar en deltauppdatering ser upplevelsen i Azure-portalen ut att vara identisk med distributionen av en vanlig avbildningsuppdatering. Mer information om hur du distribuerar uppdateringar finns i Distribuera en uppdatering med hjälp av Enhetsuppdatering för Azure IoT Hub.

När du har skapat distributionen för deltauppdateringen identifierar enhetsuppdateringstjänsten och klienten automatiskt om det finns en giltig deltauppdatering för varje enhet som du distribuerar till. Om ett giltigt delta hittas laddas deltauppdateringen ned och installeras på enheten. Om det inte finns någon giltig deltauppdatering hämtas den fullständiga avbildningsuppdateringen (den återkomprimerade mål-SWU-avbildningen) i stället som en reserv. Den här metoden säkerställer att alla enheter som du distribuerar uppdateringen för att komma till rätt version.

Det finns tre möjliga resultat för en deltauppdateringsdistribution:

Deltauppdateringen har installerats. Enheten har en ny version.
Deltauppdateringen var inte tillgänglig eller kunde inte installeras, men en lyckad återställningsinstallation av den fullständiga avbildningen inträffade i stället. Enheten har en ny version.
Både delta och återställning till fullständig avbildning misslyckades. Enheten är fortfarande i gammal version.

För att avgöra vilket av ovanstående resultat som har inträffat kan du visa installationsresultatet med felkod och utökad felkod genom att välja alla enheter som är i ett feltillstånd. Du kan också samla in loggar från flera misslyckade enheter om det behövs.

Om deltauppdateringen lyckades visar enheten statusen "Lyckades".

Om deltauppdateringen misslyckades men gjorde en lyckad återställning till den fullständiga avbildningen visas följande felstatus:

resultCode: [värde större än 0]
extendedResultCode: [icke-noll]

Om uppdateringen misslyckades visas en felstatus som kan tolkas med hjälp av följande instruktioner:

Börja med felen för enhetsuppdateringsagenten i result.h.

Fel från enhetsuppdateringsagenten som är specifika för nedladdningshanterarens funktioner som används för deltauppdateringar börjar med 0x9:

Komponent	Decimal	Hex	Kommentar
EXTENSION_MANAGER	0	0x00	Anger fel från tilläggshanterarens nedladdningshanterarlogik. Exempel: 0x900XXXXX
PLUGIN	1	0x01	Anger fel med användning av delade bibliotek för nedladdningshanterarens plugin-program. Exempel: 0x901XXXXX
RESERVERADE	2 - 7	0x02 - 0x07	Reserverad för nedladdningshanteraren. Exempel: 0x902XXXXX
GEMENSAM	8	0x08	Anger fel i Delta Download Handler-tilläggets logik på den översta nivån. Exempel: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Anger fel i Delta Download-hanteringstillägget Source Update Cache. Exempel: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Felkod för fel från DELTA-processor-API:et. Exempel: 0x90AXXXXX

Om felkoden inte finns i result.h är det troligtvis ett fel i deltaprocessorkomponenten (separat från enhetsuppdateringsagenten). I så fall är extendedResultCode ett negativt decimalvärde för följande hexadecimala format: 0x90AXXXXX
- 9 är "Delta Facility"
- 0A är "Delta Processor Component" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX är 20-bitars felkoden från FIT Delta-processorn

Om du inte kan lösa problemet baserat på felkodsinformationen kan du skicka in ett GitHub-problem för att få ytterligare hjälp.

Nästa steg

Felsök vanliga problem

Dela via