Come comprendere e usare gli aggiornamenti differenziali in Aggiornamento dispositivi per hub IoT (anteprima)

Articolo
09/08/2023

Gli aggiornamenti differenziali consentono di generare un piccolo aggiornamento che rappresenta solo le modifiche tra due aggiornamenti completi, ovvero un'immagine di origine e un'immagine di destinazione. Questo approccio è ideale per ridurre la larghezza di banda usata per scaricare un aggiornamento in un dispositivo, in particolare se sono state apportate solo alcune modifiche tra gli aggiornamenti di origine e di destinazione.

Nota

La funzionalità di aggiornamento differenziale è attualmente disponibile in anteprima pubblica.

Requisiti per l'uso degli aggiornamenti differenziali in Aggiornamento dispositivi per hub IoT

I file di aggiornamento di origine e di destinazione devono essere in formato SWU (SWUpdate).
All'interno di ogni file SWUpdate deve essere presente un'immagine non elaborata che usa il file system Ext2, Ext3 o Ext4. L'immagine può essere compressa con gzip o zstd.
Il processo di generazione differenziale ricomprime l'aggiornamento SWU di destinazione usando la compressione zstd per produrre un delta ottimale. Si importerà questo aggiornamento SWU di destinazione ricompresso nel servizio Aggiornamento dispositivi insieme al file di aggiornamento differenziale generato.
All'interno di SWUpdate nel dispositivo, è necessario abilitare anche la decompressione zstd.
- Ciò richiede l'uso di SWUpdate 2019.11 o versione successiva.

Configurare un dispositivo con l'agente di Aggiornamento dispositivi e il componente processore differenziale

Per consentire al dispositivo di scaricare e installare gli aggiornamenti differenziali dal servizio Aggiornamento dispositivi, sono necessari diversi componenti presenti e configurati.

Agente di aggiornamento dispositivi

L'agente di Aggiornamento dispositivi orchestra il processo di aggiornamento nel dispositivo, incluse le azioni di download, installazione e riavvio. Aggiungere l'agente di Aggiornamento dispositivi a un dispositivo e configurarlo per l'uso. Sarà necessaria la versione 1.0 o successiva dell'agente. Per istruzioni, vedere Provisioning dell'agente di Aggiornamento dispositivi.

Gestore di aggiornamento

Un gestore di aggiornamento si integra con l'agente di Aggiornamento dispositivi per eseguire l'installazione effettiva dell'aggiornamento. Per gli aggiornamenti differenziali, iniziare con il microsoft/swupdate:2 gestore di aggiornamento se non si ha già un gestore di aggiornamento SWUpdate che si vuole modificare. Se si usa il proprio gestore di aggiornamento, assicurarsi di abilitare la decompressione zstd in SWUpdate.

Processore Delta

Il processore delta crea nuovamente il file di immagine SWU originale nel dispositivo dopo il download del file delta, in modo che il gestore di aggiornamento possa installare il file SWU. Tutto il codice del processore differenziale è disponibile nel repository GitHub Azure/iot-hub-device-update-delta .

Per aggiungere il componente processore differenziale all'immagine del dispositivo e configurarlo per l'uso, seguire le istruzioni README.md per usare CMAKE per compilare il processore differenziale dall'origine. Da qui installare l'oggetto condiviso (libadudiffapi.so) direttamente copiandolo nella /usr/lib directory:

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

Aggiungere un file di immagine SWU di origine al dispositivo

Dopo il download di un aggiornamento differenziale in un dispositivo, è necessario confrontarlo con un file SWU di origine valido memorizzato nella cache nel dispositivo per poter essere ricreato in un'immagine completa. Il modo più semplice per popolare questa immagine memorizzata nella cache consiste nel distribuire un aggiornamento completo dell'immagine nel dispositivo tramite il servizio Aggiornamento dispositivi (usando i processi di importazione e distribuzione esistenti). Finché il dispositivo è stato configurato con l'agente di Aggiornamento dispositivi (versione 1.0 o successiva) e il processore differenziale, il file SWU installato viene memorizzato automaticamente nella cache dall'agente di Aggiornamento dispositivi per un uso successivo dell'aggiornamento differenziale.

Se invece si vuole precompilare direttamente l'immagine di origine nel dispositivo, il percorso in cui è prevista l'immagine è:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

Per impostazione predefinita, BASE_SOURCE_DOWNLOAD_CACHE_PATH è il percorso /var/lib/adu/sdc/[provider]. Il [provider] valore è la parte provider dell'updateId per il file SWU di origine.

ENCODED_HASH è la stringa esadecimale base64 dello SHA256 del file binario, ma dopo la codifica nella stringa esadecimale base64, codifica i caratteri come indicato di seguito:

+ codificato come octets _2B
/ codificato come octets _2F
= codificato come octets _3D

Generare aggiornamenti differenziali usando lo strumento DiffGen

Prerequisiti dell'ambiente

Prima di creare delta con DiffGen, è necessario scaricare e/o installare diversi elementi nel computer dell'ambiente. È consigliabile un ambiente Linux e in particolare Ubuntu 20.04 (o WSL se in modalità nativa in Windows).

La tabella seguente fornisce un elenco del contenuto necessario, dove recuperarli e l'installazione consigliata, se necessario:

Nome binario	Dove acquisire	Modalità di installazione
DiffGen	Azure/iot-hub-device-update-delta Repository GitHub	Nella cartella radice selezionare Microsoft.Azure.DeviceUpdate.Diffs.[ file version].nupkg . Altre informazioni sui pacchetti NuGet.
.NET (runtime)	Tramite Terminal/Gestione pacchetti	Istruzioni per Linux. È necessario solo il runtime.

Dipendenze

Il zstd_compression_tool viene usato per decomprimere i file di immagine di un archivio e ricomprimerli con zstd. Questo processo garantisce che tutti i file di archivio usati per la generazione diff abbiano lo stesso algoritmo di compressione per le immagini all'interno degli archivi.

Comandi per installare pacchetti/librerie necessari:

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

Creare un aggiornamento differenziale con DiffGen

Lo strumento DiffGen viene eseguito con diversi argomenti. Tutti gli argomenti sono obbligatori e la sintassi complessiva è la seguente:

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

Lo script recompress_tool.py viene eseguito per creare il file [recompressed_target_archive], che viene quindi usato invece di [target_archive] come file di destinazione per la creazione del diff.
I file di immagine all'interno di [recompressed_target_archive] vengono compressi con zstd.

Se i file SWU sono firmati (probabilmente), sarà necessario anche un altro argomento:

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

Oltre a usare [recompressed_target_archive] come file di destinazione, fornire un parametro di stringa di comando di firma viene eseguito recompress_and_sign_tool.py per creare il file [recompressed_target_archive] e avere il file sw-description all'interno dell'archivio firmato (ovvero è presente un file sw-description.sig). È possibile usare lo script di esempio sign_file.sh del repository GitHub Azure/iot-hub-device-update-delta . Aprire lo script, modificarlo per aggiungere il percorso al file di chiave privata, quindi salvarlo. Per informazioni sull'utilizzo di esempio, vedere la sezione degli esempi di seguito.

Nella tabella seguente vengono descritti in modo più dettagliato gli argomenti:

Argomento	Descrizione
[source_archive]	Si tratta dell'immagine su cui si basa il delta durante la creazione del delta. Importante: questa immagine deve essere identica all'immagine già presente nel dispositivo (ad esempio, memorizzata nella cache da un aggiornamento precedente).
[target_archive]	Questa è l'immagine a cui il delta aggiorna il dispositivo.
[output_path]	Percorso (incluso il nome desiderato del file differenziale generato) nel computer host in cui viene inserito il file differenziale dopo la creazione. Se il percorso non esiste, la directory viene creata dallo strumento .
[log_folder]	Percorso nel computer host in cui vengono creati i log. È consigliabile definire questo percorso come sottocartella del percorso di output. Se il percorso non esiste, viene creato dallo strumento .
[working_folder]	Percorso del computer in cui vengono inseriti i file collaterali e altri file di lavoro durante la generazione differenziale. È consigliabile definire questo percorso come sottocartella del percorso di output. Se il percorso non esiste, viene creato dallo strumento .
[recompressed_target_archive]	Percorso nel computer host in cui viene creato il file di destinazione ricompresso. Questo file viene usato invece di <target_archive> come file di destinazione per la generazione di differenze. Se questo percorso esiste prima di chiamare DiffGenTool, il percorso viene sovrascritto. È consigliabile definire questo percorso come file nella sottocartella del percorso di output.
"[signing_command]" (facoltativo)	Comando personalizzabile usato per firmare il file sw-description all'interno del file di archivio ricompresso. Il file sw-description nell'archivio ricompresso viene usato come parametro di input per il comando di firma; DiffGenTool prevede che il comando di firma crei un nuovo file di firma, usando il nome dell'input con `.sig` accodato. È necessario racchiudere il parametro tra virgolette doppie in modo che l'intero comando venga passato come singolo parametro. Evitare inoltre di inserire il carattere "~" in un percorso chiave usato per la firma e usare invece il percorso home completo (ad esempio, usare /home/USER/keys/priv.pem anziché ~/keys/priv.pem).

Esempi di DiffGen

Negli esempi seguenti viene eseguito il funzionamento della directory /mnt/o/temp (in WSL):

Creazione diff tra il file di origine di input e il file di destinazione ricompresso:

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]

Se si usa anche il parametro di firma (necessario se il file SWU è firmato), è possibile usare lo script di esempio sign_file.sh a cui si fa riferimento in precedenza. Aprire prima di tutto lo script e modificarlo per aggiungere il percorso al file di chiave privata. Salvare lo script e quindi eseguire DiffGen come segue:

Creazione diff tra il file di origine di input e il file di destinazione ricompresso/rifirmato:

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

Importare l'aggiornamento differenziale generato

Il processo di base per l'importazione di un aggiornamento al servizio Aggiornamento dispositivi è invariato per gli aggiornamenti differenziali, quindi, se non è già stato fatto, assicurarsi di rivedere questa pagina: Come preparare un aggiornamento da importare in Aggiornamento dispositivi di Azure per hub IoT

Generare un manifesto di importazione

Il primo passaggio per importare un aggiornamento nel servizio Aggiornamento dispositivi è sempre quello di creare un manifesto di importazione se non ne è già disponibile uno. Per altre informazioni sui manifesti di importazione, vedere Importazione di aggiornamenti nell'aggiornamento del dispositivo. Per gli aggiornamenti differenziali, il manifesto di importazione deve fare riferimento a due file:

L'immagine SWU di destinazione ricompressa creata quando si esegue lo strumento DiffGen.
Il file delta creato quando si esegue lo strumento DiffGen.

La funzionalità di aggiornamento delta usa una funzionalità denominata file correlati, che richiede un manifesto di importazione che è la versione 5 o successiva.

Per creare un manifesto di importazione per l'aggiornamento differenziale usando la funzionalità file correlati, è necessario aggiungere oggetti relatedFiles e downloadHandler al manifesto di importazione.

Usare l'oggetto per specificare informazioni sul file di aggiornamento delta, tra cui il nome del file, le dimensioni del file e l'hash relatedFiles sha256. Importante è anche necessario specificare due proprietà univoche per la funzionalità di aggiornamento delta:

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

Entrambe le proprietà precedenti sono specifiche per il file di immagine SWU di origine usato come input per lo strumento DiffGen durante la creazione dell'aggiornamento differenziale. Le informazioni sull'immagine SWU di origine sono necessarie nel manifesto di importazione anche se non si importa effettivamente l'immagine di origine. I componenti delta nel dispositivo usano questi metadati sull'immagine di origine per individuare l'immagine nel dispositivo dopo il download del delta.

Usare l'oggetto per specificare come l'agente downloadHandler di aggiornamento del dispositivo orchestra l'aggiornamento differenziale usando la funzionalità relativa ai file. A meno che non si stia personalizzando la propria versione dell'agente di aggiornamento dispositivi per la funzionalità delta, è consigliabile usare questo gestore download:

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

È possibile usare l'interfaccia della riga di comando di Azure per generare un manifesto di importazione per l'aggiornamento differenziale. Se l'interfaccia della riga di comando di Azure non è stata usata per creare un manifesto di importazione prima, vedere Creare un manifesto di importazione di base.

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

Salvare il file JSON del manifesto di importazione generato in un file con l'estensione .importmanifest.json

Importare con il Portale di Azure

Dopo aver creato il manifesto di importazione, è possibile importare l'aggiornamento differenziale. Per importare, seguire le istruzioni in Aggiungere un aggiornamento all'aggiornamento del dispositivo per hub IoT. È necessario includere questi elementi durante l'importazione:

File con estensione json del manifesto di importazione creato nel passaggio precedente.
L'immagine SWU di destinazione ricompressa creata quando si esegue lo strumento DiffGen.
Il file delta creato quando si esegue lo strumento DiffGen.

Distribuire l'aggiornamento differenziale nei dispositivi

Quando si distribuisce un aggiornamento differenziale, l'esperienza nell'portale di Azure sembra identica alla distribuzione di un aggiornamento regolare dell'immagine. Per altre informazioni sulla distribuzione degli aggiornamenti, vedere Distribuire un aggiornamento usando l'aggiornamento del dispositivo per hub IoT di Azure

Dopo aver creato la distribuzione per l'aggiornamento differenziale, il servizio Aggiornamento dispositivi e il client identificano automaticamente se è disponibile un aggiornamento differenziale valido per ogni dispositivo a cui si sta distribuendo. Se viene trovato un delta valido, l'aggiornamento differenziale verrà scaricato e installato nel dispositivo. Se non è stato trovato alcun aggiornamento differenziale valido, l'aggiornamento completo dell'immagine (immagine SWU di destinazione ricompressa) verrà scaricato invece come fallback. Questo approccio garantisce che tutti i dispositivi che si distribuiscono l'aggiornamento verranno visualizzati nella versione appropriata.

Esistono tre possibili risultati per una distribuzione di aggiornamenti differenziali:

Aggiornamento delta installato correttamente. Il dispositivo è in nuova versione.
L'aggiornamento delta non è disponibile o non è stato installato, ma si è verificato un fallback corretto dell'immagine completa. Il dispositivo è in nuova versione.
Non è riuscito sia il delta che il fallback all'immagine completa. Il dispositivo è ancora in versione precedente.

Per determinare quali dei risultati precedenti si sono verificati, è possibile visualizzare i risultati dell'installazione con il codice di errore e il codice di errore esteso selezionando qualsiasi dispositivo in uno stato non riuscito. È anche possibile raccogliere i log da più dispositivi non riusciti, se necessario.

Se l'aggiornamento differenziale ha avuto esito positivo, il dispositivo mostra uno stato "Successed".

Se l'aggiornamento differenziale non è riuscito ma ha eseguito un fallback riuscito nell'immagine completa, viene visualizzato lo stato di errore seguente:

resultCode: [valore maggiore di 0]
extendedResultCode: [non zero]

Se l'aggiornamento non è riuscito, viene visualizzato uno stato di errore che può essere interpretato usando le istruzioni seguenti:

Iniziare con gli errori dell'agente di aggiornamento del dispositivo in result.h.

Gli errori dell'agente di aggiornamento del dispositivo specifici della funzionalità Download Handler usati per gli aggiornamenti differenziali iniziano con 0x9:

Componente	Decimal	Hex	Nota
EXTENSION_MANAGER	0	0x00	Indica gli errori della logica di download del gestore estensioni. Esempio: 0x900XXXXX
PLUGIN	1	0x01	Indica gli errori relativi all'utilizzo delle librerie condivise del plug-in del gestore di download. Esempio: 0x901XXXXX
RISERVATO	2 - 7	0x02 - 0x07	Riservato per il gestore download. Esempio: 0x902XXXXX
COMUNE	8	0x08	Indica gli errori nella logica principale dell'estensione del gestore di download Delta. Esempio: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Indica gli errori nella cache dell'aggiornamento dell'estensione del gestore di download delta. Esempio: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Codice di errore per errori dall'API del processore delta. Esempio: 0x90AXXXXX

Se il codice di errore non è presente in result.h, è probabile che si verifichi un errore nel componente del processore delta (separato dall'agente di aggiornamento del dispositivo). In tal caso, extendedResultCode sarà un valore decimale negativo del formato esadecimale seguente: 0x90AXXXXX
- 9 è "Delta Facility"
- 0A è "Componente processore Delta" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX è il codice di errore a 20 bit dal processore delta FIT

Se non è possibile risolvere il problema in base alle informazioni sul codice di errore, inviare un problema di GitHub per ottenere ulteriore assistenza.

Passaggi successivi

Risolvere i problemi comuni

Share via