Condividi tramite

Aggiornamenti differenziali (anteprima)

  • Articolo

Gli aggiornamenti differenziali consentono di generare piccoli aggiornamenti che rappresentano solo le modifiche tra due aggiornamenti completi, 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, soprattutto se sono presenti solo alcune modifiche tra l'origine e gli aggiornamenti di destinazione.

Nota

La funzionalità di aggiornamento differenziale in Aggiornamento dispositivi di Azure per hub IoT è attualmente 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 ricomprime l'aggiornamento swU di destinazione usando la compressione gzip per produrre un delta ottimale. Importare l'aggiornamento SWU di destinazione ricompresso nel servizio Aggiornamento dispositivi insieme al file di aggiornamento differenziale generato.

Configurazione dell'agente di Aggiornamento dispositivi per il componente del processore differenziale

Per scaricare e installare gli aggiornamenti differenziali dal servizio Aggiornamento dispositivi, il dispositivo deve disporre dell'agente di Aggiornamento dispositivi con il gestore di aggiornamento e il componente processore delta 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. Per aggiungere l'agente di Aggiornamento dispositivi a un dispositivo e configurarlo per l'uso, vedere Provisioning dell'agente di Aggiornamento dispositivi. Usare la versione dell'agente 1.0 o successiva.

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 in Azure/iot-hub-device-update-delta crea nuovamente il file di immagine SWU originale nel dispositivo dopo il download del file differenziale, in modo che il gestore di aggiornamento possa installare il file SWU. Per aggiungere il componente processore delta all'immagine del dispositivo e configurarlo per l'uso, è possibile scaricare un pacchetto Debian per Ubuntu 20.04 e versioni successive da https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

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 , come indicato di seguito:

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 del file di aggiornamento differenziale in un dispositivo, viene confrontato con un file precedentemente memorizzato nella cache valido <source_archive> nel dispositivo. Questo processo consente all'aggiornamento differenziale di ricreare l'immagine di destinazione completa.

Il modo più semplice per popolare questa immagine memorizzata nella cache consiste nell'importare e distribuire un aggiornamento completo dell'immagine nel dispositivo tramite il servizio Aggiornamento dispositivi. Se il dispositivo è configurato con l'agente di Aggiornamento dispositivi versione 1.0 o successiva e il processore differenziale, l'agente memorizza nella cache automaticamente il file SWU installato per un uso successivo dell'aggiornamento differenziale.

Se invece si vuole prepopoulare 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 provider parte dell'updateIdper 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

Generazione di aggiornamenti differenziali con lo strumento DiffGen

È possibile creare aggiornamenti differenziali usando lo strumento Diff Generation (DiffGen).

Prerequisiti dell'ambiente

Prima di creare delta con DiffGen, è necessario scaricare e installare diversi elementi nel computer dell'ambiente. Idealmente, usare un ambiente Ubuntu 20.04 Linux o sottosistema Windows per Linux se si usa Windows.

La tabella seguente illustra il contenuto necessario, dove ottenerlo e l'installazione consigliata, se necessario.

Nome binario Dove acquisire Modalità di installazione
DiffGen Repository GitHub Azure/iot-hub-device-update-delta Scaricare la versione corrispondente al sistema operativo o alla distribuzione nel computer da usare per generare aggiornamenti differenziali.
. Runtime NETCore, versione 8.0.0 Tramite terminal o gestori pacchetti Installare .NET in Linux. È necessario solo il runtime.

Creazione di aggiornamenti differenziali con DiffGen

Lo strumento DiffGen viene eseguito con gli argomenti e la sintassi obbligatori seguenti:

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

Il comando precedente esegue lo script recompress_tool.py , che crea l'oggetto <recompressed_target_file>. DiffGen usa quindi invece <recompressed_target_file>di come file di <target_archive> 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, richiedono anche l'argomento <signing_command> nel comando DiffGen:

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

Il parametro DiffGenTool con la stringa di comando di firma esegue lo script recompress_and_sign_tool.py . Questo script crea l'oggetto <recompressed_target_file>. Inoltre, questo script firma anche il file sw-description all'interno dell'archivio per creare un file sw-description.sig .

È possibile usare lo script di esempio sign_file.sh dal repository GitHub Azure/iot-hub-device-update-delta per creare una differenza tra il file di origine di input e un file di destinazione ricompresso e rifirmato. Aprire lo script, modificarlo per aggiungere il percorso al file di chiave privata e salvarlo. Vedere la sezione Esempi per l'utilizzo di esempio.

Nella tabella seguente vengono descritti in dettaglio gli argomenti:

Argomento Descrizione
<source_archive> Immagine di base usata da DiffGen come punto di partenza per creare il delta. Importante: questa immagine deve essere identica all'immagine già presente nel dispositivo, ad esempio memorizzata nella cache da un aggiornamento precedente.
<target_archive> Immagine a cui il delta aggiorna il dispositivo.
<output_path> Percorso nel computer host in cui inserire il file differenziale dopo la creazione, incluso il nome desiderato del file differenziale generato. Se il percorso non esiste, lo strumento lo crea.
<log_folder> Percorso nel computer host in cui creare i log. È consigliabile definire questo percorso come sottocartella del percorso di output. Se il percorso non esiste, lo strumento lo crea.
<working_folder> Percorso nel computer in cui inserire 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> Percorso nel computer host in cui creare .<recompressed_target_file> Viene <recompressed_target_file> utilizzato anziché come file di destinazione per la generazione di <target_archive> differenze. Se questo percorso esiste prima di chiamare lo strumento DiffGen, viene sovrascritto. È consigliabile definire questo file in una sottocartella del percorso di output.
"<signing_command>" (facoltativo) Comando personalizzabile per firmare il file sw-description all'interno di <recompressed_target_archive>. Il file sw-description nell'archivio ricompresso viene usato come parametro di input per il comando di firma. DiffGen prevede che il comando di firma crei un nuovo file di firma, usando il nome dell'input con estensione sig accodato.

È necessario racchiudere il parametro tra virgolette doppie per passare l'intero comando come singolo parametro. Evitare inoltre di usare 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

Gli esempi seguenti escono dalla directory /mnt/o/temp in sottosistema Windows per Linux.

Il codice seguente crea una differenza tra il file di origine di input e un file di destinazione ricompresso:

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

Se si usa anche il parametro di firma, che è necessario se il file SWU è firmato, è possibile usare lo script di esempio sign_file.sh menzionato in precedenza. Aprire lo script, modificarlo per aggiungere il percorso al file di chiave privata, salvare lo script e quindi eseguire DiffGen come indicato di seguito.

Il codice seguente crea una differenza tra il file di origine di input e un file di destinazione ricompresso e rifirmato:

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

Importazione dell'aggiornamento differenziale generato

Il processo di base di importazione di un aggiornamento differenziale nel servizio Aggiornamento dispositivi è uguale a quello di qualsiasi altro aggiornamento. Se non è già stato fatto, vedere Come preparare un aggiornamento da importare in Aggiornamento dispositivi di Azure per hub IoT.

Generare il manifesto di importazione

Per importare un aggiornamento nel servizio Aggiornamento dispositivi, è necessario disporre o creare un file manifesto di importazione. Per altre informazioni, vedere Importazione di aggiornamenti in Aggiornamento dispositivi.

Importare i file manifesto per gli aggiornamenti differenziali deve fare riferimento ai file seguenti creati dallo strumento DiffGen:

  • Immagine <recompressed_target_file> SWU
  • Oggetto <delta file>

La funzionalità di aggiornamento differenziale usa una funzionalità denominata file correlati che richiede un manifesto di importazione versione 5 o successiva. Per usare la funzionalità relativa ai file, è necessario includere gli oggetti relatedFiles e downloadHandler nel 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. Soprattutto, è necessario specificare anche le due proprietà seguenti univoche per la funzionalità di aggiornamento differenziale:

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

Entrambe le proprietà sono specifiche dell'oggetto <source image file> usato come input per lo strumento DiffGen quando è stato creato l'aggiornamento differenziale. Il manifesto di importazione richiede le informazioni sull'immagine SWU di origine 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 dell'aggiornamento differenziale.

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 personalizza la propria versione dell'agente di Aggiornamento dispositivi per la funzionalità delta, usare quanto segue downloadHandler:

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

È possibile usare il comando dell'interfaccia della riga di comando di Azure az iot du update init v5 per generare un manifesto di importazione per l'aggiornamento differenziale. Per altre informazioni, vedere Creare un manifesto di importazione di base.

--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 con l'estensione del file .importmanifest.json.

Importare con il Portale di Azure

Dopo aver creato il manifesto di importazione, importare l'aggiornamento differenziale seguendo le istruzioni riportate in Aggiungere un aggiornamento a Aggiornamento dispositivi per hub IoT. È necessario includere gli elementi seguenti nell'importazione:

  • File *importmanifest.json creato in precedenza nei passaggi precedenti
  • Immagine <recompressed_target_file> SWU creata dallo strumento DiffGen
  • Lo <delta file> strumento DiffGen creato

Distribuzione degli aggiornamenti differenziali nei dispositivi

L'esperienza di distribuzione degli aggiornamenti differenziali nella portale di Azure equivale alla distribuzione di un normale aggiornamento delle immagini. Per altre informazioni, vedere Distribuire un aggiornamento tramite Aggiornamento dispositivi.

Dopo aver creato la distribuzione per l'aggiornamento differenziale, il servizio Aggiornamento dispositivi e il client determinano automaticamente se è presente un aggiornamento differenziale valido per ogni dispositivo in cui si esegue la distribuzione. Se trovano un delta valido, scaricano e installano l'aggiornamento differenziale nel dispositivo.

Se non trova un 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:

  • L'aggiornamento differenziale installato correttamente e il dispositivo si trova nella nuova versione.
  • L'aggiornamento differenziale non è disponibile o non è riuscito a eseguire l'installazione, ma un'installazione di fallback dell'immagine completa è riuscita e il dispositivo si trova nella nuova versione.
  • Le installazioni delta e fallback non sono riuscite e il dispositivo è ancora nella versione precedente.

Per determinare il risultato dell'errore, è possibile visualizzare i risultati dell'installazione con il codice di errore e il codice di errore esteso selezionando qualsiasi dispositivo in stato di errore. Se necessario, è anche possibile raccogliere i log da più dispositivi non riusciti.

  • Se un aggiornamento differenziale è riuscito, il dispositivo visualizza lo stato Succeeded .

  • Se un aggiornamento differenziale non è riuscito ma il fallback all'immagine completa è riuscito, il dispositivo mostra lo stato di errore seguente:

    • resultCode: <valore maggiore di 0>
    • extendedResultCode: <valore diverso da zero>

Risolvere i problemi relativi ad aggiornamenti non riusciti

Gli aggiornamenti non riusciti visualizzano uno stato di errore che è possibile interpretare usando le istruzioni seguenti. Iniziare con gli errori dell'agente di Aggiornamento dispositivi in result.h.

Gli errori dell'agente di Aggiornamento dispositivi specifici per la funzionalità del gestore di download degli 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 il gestore di 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 di aggiornamento dell'origine dell'estensione del 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, probabilmente si tratta di un errore nel componente processore differenziale, separato dall'agente di Aggiornamento dispositivi. In tal caso, extendedResultCode è un valore decimale negativo nel formato 0x90AXXXXXesadecimale .

  • 9 è "Delta Facility"
  • 0A è "Componente processore delta" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
  • XXXXX è il codice di errore a 20 bit del processore differenziale FIT (Field Installation Tool)

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

Contenuto correlato