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

Articolo
10/16/2024

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 presenti solo poche modifiche tra l'origine e gli aggiornamenti 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 SWUpdate (SWU).
All'interno di ogni file SWUpdate deve essere presente un'immagine non elaborata che usa il file system Ext2, Ext3 o Ext4.
Il processo di generazione differenziale comprime l'aggiornamento SWU di destinazione usando la compressione gzip per produrre un delta ottimale. Importare questo aggiornamento SWU di destinazione ricompresso nel servizio Aggiornamento dispositivi insieme al file di aggiornamento differenziale generato.

Configurare un dispositivo con l'agente di Aggiornamento dispositivi e il componente del 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. Usare la versione dell'agente 1.0 o successiva. Per istruzioni, vedere Provisioning dell'agente di Aggiornamento dispositivi.

Gestore di aggiornamenti

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

Processore differenziale

Il processore differenziale ricrea 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. Il processore delta è disponibile nel repository GitHub Azure/iot-hub-device-update-delta.

Per aggiungere il componente del processore delta all'immagine del dispositivo e configurarlo per l'uso, è possibile scaricare un pacchetto .deb supportato in Ubuntu 20.04 e versioni successive. Se si usa un'altra distribuzione, 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 directory /usr/lib:

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, deve essere confrontato con un file SWU di origine valido memorizzato nella cache del dispositivo. Questo processo è necessario affinché l'aggiornamento differenziale possa ricreare l'immagine di destinazione 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). Se il dispositivo è configurato con l'agente di Aggiornamento dispositivi (versione 1.0 o successiva) e il processore differenziale, l'agente di Aggiornamento dispositivi memorizza automaticamente nella cache il file SWU installato per un uso successivo dell'aggiornamento differenziale.

Se invece si vuole prepopolare 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 valore [provider] è la parte Provider di updateId per il file SWU di origine.

ENCODED_HASH è la stringa esadecimale base64 di SHA256 del file binario, ma dopo la codifica in 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 con 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 sottosistema Windows per Linux se in modalità nativa in Windows).

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

Nome del file binario	Dove acquisire	Modalità di installazione
DiffGen	Repository GitHub Azure/iot-hub-device-update-delta	Scaricare la versione corrispondente al sistema operativo/alla distribuzione nel computer che verrà usato per generare aggiornamenti differenziali.
Runtime .NETCore, versione 8.0.0	Tramite Terminal/Gestione pacchetti	Istruzioni per Linux. È necessario solo il runtime.

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 gzip.

Se i file SWU sono firmati (opzione probabile), è 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, fornendo un parametro della 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 della chiave privata, quindi salvarlo. Vedere la sezione degli esempi per consultare esempi di utilizzo.

Nella tabella seguente vengono descritti in dettaglio gli argomenti:

Argomento	Descrizione
[source_archive]	Questa è l'immagine sulla quale si basa il delta durante la sua creazione. 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 su cui il delta aggiorna il dispositivo.
[output_path]	Il 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, lo strumento lo crea.
[log_folder]	Il 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, lo strumento lo crea.
[working_folder]	Il 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, lo strumento lo crea.
[recompressed_target_archive]	Il percorso nel computer host in cui viene creato il file di destinazione ricompresso. Questo file viene usato al posto di <target_archive> come file di destinazione per la generazione differenziale. 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)	Un 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 di 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

In questi esempi viene eseguita la directory /mnt/o/temp (in WSL):

Creazione differenziale 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. Innanzitutto, aprire lo script e modificarlo per aggiungere il percorso al file della chiave privata. Salvare lo script, quindi eseguire DiffGen come segue:

Creazione differenziale 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 di importazione di un aggiornamento nel servizio Aggiornamento dispositivi è invariato per gli aggiornamenti differenziali, quindi, se non è già stato fatto, assicurarsi di esaminare questa pagina: Come preparare un aggiornamento da importare in Aggiornamento dispositivi per hub IoT di Azure

Generare il manifesto di importazione

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

L'immagine SWU di destinazione ricompressa creata durante l'esecuzione dello strumento DiffGen.
Il file differenziale creato durante l'esecuzione dello strumento DiffGen.

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

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

Usare l'oggetto relatedFiles per specificare informazioni sul file di aggiornamento differenziale, inclusi il nome file, le dimensioni del file e l'hash sha256. Da ricordare è che è necessario anche specificare due proprietà univoche per la funzionalità di aggiornamento differenziale:

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

Entrambe le proprietà sono specifiche del 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 differenziali nel dispositivo usano questi metadati sull'immagine di origine per individuare l'immagine nel dispositivo dopo il download del delta.

Usare l'oggetto downloadHandler per specificare il modo in cui l'agente di Aggiornamento dispositivi 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 solo questo downloadHandler:

"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 in precedenza non è stata usata l'interfaccia della riga di comando di Azure per creare un manifesto di importazione, 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 JSON del manifesto di importazione generato in un file con estensione .importmanifest.json

Importare con il Portale di Azure

Dopo aver creato il manifesto di importazione, si è pronti per importare l'aggiornamento differenziale. Per eseguire l'importazione, seguire le istruzioni in Aggiungere un aggiornamento ad Aggiornamento dispositivi per hub IoT. È necessario includere questi elementi durante l'importazione:

Il file .JSON del manifesto di importazione creato nel passaggio precedente.
L'immagine SWU di destinazione ricompressa creata durante l'esecuzione dello strumento DiffGen.
Il file differenziale creato durante l'esecuzione dello strumento DiffGen.

Distribuire l'aggiornamento differenziale nei dispositivi

Quando si distribuisce un aggiornamento differenziale, l'esperienza nel portale di Azure è identica alla distribuzione di un aggiornamento standard delle immagini. Per altre informazioni sulla distribuzione degli aggiornamenti, vedere Distribuire un aggiornamento usando Aggiornamento dispositivi per hub IoT di Azure.

Dopo aver creato la distribuzione per l'aggiornamento differenziale, il servizio Aggiornamento dispositivi e il client identificano automaticamente se è presente un aggiornamento differenziale valido per ogni dispositivo in cui si esegue la distribuzione. Se viene trovato un delta valido, l'aggiornamento differenziale viene scaricato e installato nel dispositivo. Se non viene trovato alcun aggiornamento differenziale valido, l'aggiornamento completo dell'immagine (immagine SWU di destinazione ricompressa) viene scaricato come fallback. Questo approccio garantisce che tutti i dispositivi in cui si distribuisce l'aggiornamento passino alla versione appropriata.

Esistono tre possibili risultati per una distribuzione di aggiornamento differenziale:

Aggiornamento differenziale installato correttamente. Il dispositivo è in una nuova versione.
L'aggiornamento differenziale non era disponibile o non è riuscito a eseguire l'installazione, ma si è verificato un fallback corretto dell'immagine completa. Il dispositivo è in una nuova versione.
Non è stato possibile eseguire né il delta, né il fallback per l'immagine completa. Il dispositivo è ancora nella 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 un qualsiasi dispositivo in stato di errore. È anche possibile raccogliere i log da più dispositivi con aggiornamento non andato a buon fine, se necessario.

Se l'aggiornamento differenziale è riuscito, il dispositivo visualizza lo stato "Operazione completata".

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

resultCode: [valore maggiore di 0]
extendedResultCode: [diverso da zero]

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

Iniziare con gli errori dell'agente di Aggiornamento dispositivi in result.h.

Gli errori dell'agente di Aggiornamento dispositivi specifici della funzionalità Gestore download usati per gli aggiornamenti differenziali iniziano con 0x9:

Componente	Decimale	Hex	Nota
EXTENSION_MANAGER	0	0x00	Indica errori di logica nel gestore download di Gestione estensioni. Esempio: 0x900XXXXX
PLUG-IN	1	0x01	Indica errori nell'utilizzo delle librerie condivise dei plug-in del gestore download. Esempio: 0x901XXXXX
RISERVATO	2 - 7	0x02 - 0x07	Riservato per Gestore download. Esempio: 0x902XXXXX
COMUNE	8	0x08	Indica errori nella logica principale dell'estensione di Gestore download delta. Esempio: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Indica errori nella cache di aggiornamento dell'origine dell'estensione Gestore download delta. Esempio: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Codice di errore per gli errori dell'API processore differenziale. Esempio: 0x90AXXXXX

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

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

Passaggi successivi

Risolvere i problemi comuni

Condividi tramite