Distribuzione di aggiornamenti differenziali ai dispositivi

Questo articolo illustra come generare file di aggiornamento delta, importarli in Aggiornamento dispositivi di Azure per l'hub IoT e distribuirli ai dispositivi. I file delta possono essere generati usando lo strumento DiffGen o come parte di una compilazione basata su Yocto. Per una panoramica, vedi Aggiornamenti delta di Azure Device Update for hub IoT.

Prerequisiti

• Aggiornamento del dispositivo Azure per hub IoT account e istanza.
• Un dispositivo o simulatore IoT sottoposto a provisioning per Device Update con l'implementazione di riferimento dell'agente integrata, versione 1.3.0 o successiva. Per le istruzioni, vedere provisioning dell'agente di Device Update.
• File di aggiornamento di origine e destinazione in formato SWUpdate (SWU), con un'immagine non elaborata all'interno. L'esempio di riferimento Microsoft usa il file system Ext4, ma Ext2 e Ext3 sono supportati anche.

Configurare il dispositivo

Per applicare gli aggiornamenti delta, nel dispositivo devono essere installati l'agente Device Update, un gestore di aggiornamento compatibile e l'estensione del processore delta. Le sezioni seguenti descrivono come configurare ogni componente.

Gestore di aggiornamenti

Il gestore di aggiornamento si integra con l'agente di Aggiornamento dispositivi per eseguire l'installazione effettiva dell'aggiornamento nel dispositivo.

Per gli aggiornamenti differenziali, iniziare con il gestore di aggiornamento microsoft/swupdate:2 se non si dispone già di un gestore di aggiornamento SWUpdate personalizzato.

Estensione del processore Delta

L'estensione del processore delta ricostruisce sul dispositivo l'aggiornamento di destinazione completo combinando l'aggiornamento delta scaricato con l'aggiornamento di origine già presente sul dispositivo. Il gestore dell'aggiornamento installa quindi l'aggiornamento ricostruito.

Esistono due modi per installare l'estensione del processore delta. Entrambe le opzioni comportano la disponibilità dell'estensione nel dispositivo: la differenza è se la si installa direttamente nel dispositivo o la si include durante la compilazione dell'immagine del dispositivo.

• Opzione 1: Installare l'estensione direttamente nel dispositivo. Questo è l'approccio più comune se si usa un sistema operativo predefinito o si usa un dispositivo esistente.
• Opzione 2: Includere l'estensione come parte della compilazione dell'immagine del dispositivo. Questa opzione si applica se si compilano e si gestiscono immagini del dispositivo personalizzate, ad esempio con Yocto.

Opzione 1: Installare l'estensione nel dispositivo

Usare questa opzione se si vuole installare l'estensione del processore delta in un dispositivo esistente. Questo approccio è consigliato se si usa un sistema operativo predefinito o se non si modifica l'immagine del dispositivo.

Scaricare l'estensione del processore delta dal repository Azure/iot-hub-device-update-delta.

I pacchetti predefiniti sono disponibili nella versione 3.0.0. Scegliere il pacchetto corrispondente al sistema operativo e all'architettura del dispositivo.

Per Ubuntu 20.04 e versioni successive, installare direttamente il pacchetto Debian.

Se un pacchetto predefinito non è disponibile per la piattaforma, seguire le istruzioni di compilazione e installazione nel repository README per compilare l'estensione dall'origine.

Dopo aver compilato la libreria, copiare l'oggetto libadudiffapi.so/usr/lib condiviso in e aggiornare la cache della libreria di sistema:

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

Opzione 2: Integrare con una compilazione Yocto

Usare questa opzione se si compila un'immagine del dispositivo personalizzata e si vuole includere l'estensione del processore delta come parte di tale immagine.

Con questo approccio, l'estensione viene installata durante la compilazione dell'immagine, quindi non è necessario installarla separatamente nel dispositivo.

Per integrare il supporto degli aggiornamenti differenziali nella compilazione, usare i livelli Yocto forniti nel repository iot-hub-device-update-yocto.

Per maggiori dettagli sui layer disponibili e su come includerli nella build, consulta la sezione layer Yocto forniti da Microsoft.

Per informazioni sul modo in cui i componenti delta vengono inseriti nel pacchetto e resi disponibili come parte dell'output di compilazione, vedere Distribuzione degli strumentiDelta.

Dopo aver compilato l'immagine con questi livelli inclusi, l'estensione del processore delta è già disponibile nel dispositivo e non sono necessari passaggi di installazione aggiuntivi.

Dopo aver completato una delle due opzioni, l'estensione del processore delta viene installata sul dispositivo ed è pronta per ricostruire gli aggiornamenti differenziali durante la distribuzione.

Preparare l'aggiornamento sorgente sul dispositivo

Un aggiornamento differenziale richiede che sul dispositivo sia disponibile un aggiornamento sorgente valido. Durante l'installazione, l'aggiornamento delta viene combinato con l'aggiornamento sorgente sul dispositivo per ricostruire l'aggiornamento di destinazione completo.

Il modo più semplice per rendere disponibile l'aggiornamento di origine nel dispositivo consiste nell'importare e distribuire un aggiornamento completo tramite il servizio Aggiornamento dispositivi. Quando il dispositivo installa l'aggiornamento, l'agente di Aggiornamento dispositivo lo salva automaticamente nella cache da usare con i futuri aggiornamenti differenziali.

Questo comportamento è lo stesso indipendentemente dalla modalità di installazione dell'estensione del processore delta. Ad esempio, se si usa un'immagine basata su Yocto, l'aggiornamento installato viene comunque memorizzato nella cache automaticamente dopo la distribuzione, quindi non sono necessari passaggi aggiuntivi.

Se è necessario pre-preparare manualmente l'aggiornamento di origine anziché basarsi sulla cache, posizionare l'immagine in: <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>

Where:

• <BASE_SOURCE_DOWNLOAD_CACHE_PATH> è il percorso della directory di base usato per gli aggiornamenti dell'origine memorizzati nella cache. Per impostazione predefinita, questo percorso è /var/lib/adu/sdc/<provider>.

• <provider> è il valore provider dell'identità di aggiornamento del file SWU di origine.

• <ENCODED_HASH> è l'hash SHA256 con codifica base64 dell'immagine di origine, con le sostituzioni seguenti:

Generare un file di aggiornamento differenziale

Generare file di aggiornamento differenziale usando DiffGen, uno strumento di riferimento fornito da Microsoft eseguito in un computer di compilazione.

DiffGen accetta un file SWU di origine e un file SWU di destinazione come input, ricomprime la destinazione usando gzip e produce un file di aggiornamento differenziale che contiene solo le differenze tra i due.

Esistono due modi per generare file di aggiornamento differenziale:

• Opzione 1: Scaricare ed eseguire DiffGen in un computer di compilazione
• Opzione 2: Usare gli strumenti di generazione differenziale da una compilazione Yocto

Opzione 1: Scaricare ed eseguire Manualmente DiffGen

Usare questa opzione se si sta generando aggiornamenti differenziali su una macchina di sviluppo o di build separata.

Scaricare lo strumento DiffGen dal repository Azure/iot-hub-device-update-delta.

I file binari predefiniti sono disponibili nella versione 3.0.0. Scegliere la versione corrispondente al sistema operativo e all'architettura del computer di compilazione.

Per altri dettagli sullo strumento DiffGen e sul relativo utilizzo, vedere la sezione Diff Generation (DiffGen) nel repository.

Eseguire DiffGen in un computer di compilazione. È consigliabile ubuntu 20.04 o 22.04 (o sottosistema Windows per Linux).

Prima di eseguire DiffGen, installare quanto segue nel computer di compilazione:

Opzione 2: Usare DiffGen da una compilazione Yocto

Usare questa opzione se si compila l'immagine del dispositivo con Yocto e si vogliono usare gli strumenti generati come parte di tale compilazione.

Durante una compilazione basata su Yocto, lo strumento DiffGen e i componenti correlati vengono prodotti insieme all'immagine del dispositivo. È possibile creare un pacchetto ed eseguire questi strumenti in un host di compilazione compatibile.

Per iniziare, vedere il repository iot-hub-device-update-yocto, che fornisce i livelli necessari e la configurazione della compilazione.

Per informazioni dettagliate su come creare un pacchetto e usare gli strumenti generati, vedere distribuzione degli strumenti Delta tools distribution.

Eseguire DiffGen

Dopo aver installato le dipendenze, eseguire DiffGen usando la sintassi seguente:

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

Questo comando esegue lo recompress_tool.py script , che crea l'oggetto <recompressed_target_archive>. DiffGen usa l'archivio ricompresso anziché <target_archive> quando si genera l'aggiornamento differenziale. I file di immagine all'interno dell'archivio ricompresso vengono compressi usando gzip.

Se i file SWU sono firmati, includete l'argomento <signing_command>:

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

Quando si fornisce un comando di firma, DiffGen esegue lo recompress_and_sign_tool.py script. Questo script crea e firma il <recompressed_target_archive>sw-description file all'interno di esso, producendo un sw-description.sig file.

Per generare un aggiornamento differenziale tra un file di origine e un file di destinazione ricompresso e nuovamente firmato, utilizzare lo script di esempio sign_file.sh nel repository Azure/iot-hub-device-update-delta. Aggiornare lo script per includere il percorso della chiave privata e quindi eseguirlo come parte del comando DiffGen. Vedere la sezione degli esempi per l'utilizzo.

Argomenti DiffGen

Esempi di DiffGen

Negli esempi seguenti si presuppone una directory di lavoro di /mnt/o/temp in sottosistema Windows per Linux.

Creare un aggiornamento differenziale:

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

Creare un aggiornamento differenziale con firma:

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

Importare l'aggiornamento differenziale

Il processo di base per l'importazione di un aggiornamento differenziale nel servizio Aggiornamento dispositivi equivale all'importazione di qualsiasi altro aggiornamento. Per informazioni generali, vedere Come preparare un aggiornamento da importare in Azure Aggiornamento dispositivi 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 Device Update.

Per gli aggiornamenti differenziali, il manifesto di importazione deve fare riferimento ai file seguenti creati dallo strumento DiffGen:

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

Gli aggiornamenti differenziali usano una funzionalità denominata file correlati, che richiede un manifest di importazione versione 5 o successivo. Per usare questa funzionalità, includere sia gli oggetti relatedFiles che downloadHandler nel manifesto.

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à univoche seguenti per la funzionalità di aggiornamento differenziale.

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

Entrambe le proprietà fanno riferimento all'aggiornamento di origine usato come input per lo strumento DiffGen durante la generazione dell'aggiornamento differenziale. Il manifesto di importazione richiede queste informazioni anche se il file SWU di origine non è incluso nell'importazione.

I componenti delta presenti nel dispositivo usano questi metadati relativi all'immagine di origine per individuare tale immagine sul dispositivo dopo aver scaricato l'aggiornamento delta.

Usare quanto segue downloadHandler a meno che l'implementazione dell'agente Device Update non sia stata modificata in modo tale da cambiare il comportamento previsto per il download e l'installazione differenziali:

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

Generare il manifesto di importazione usando il interfaccia della riga di comando di Azure

È possibile usare il comando az iot du update init v5 dell'interfaccia della riga di comando di Azure 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>"}' 

Salva il JSON del manifest di importazione generato con l'estensione di file *.importmanifest.json.

Importare con il Portale di Azure

Dopo aver creato il manifesto di importazione, importa l'aggiornamento delta seguendo le istruzioni in Aggiungere un aggiornamento a Device Update for hub IoT.

Includere gli elementi seguenti nell'importazione:

• Il *.importmanifest.json file
• Immagine <recompressed_target_file> SWU creata da DiffGen
• Oggetto <delta file> creato da DiffGen

Distribuisci l'aggiornamento delta

La distribuzione di un aggiornamento delta segue lo stesso processo della distribuzione di un aggiornamento completo dell'immagine. Per istruzioni dettagliate, vedere Distribuire un aggiornamento con Aggiornamento dispositivi.

Per supportare i dispositivi che eseguono versioni di partenza diverse, includere un aggiornamento differenziale per ogni versione di origine da supportare, insieme all'aggiornamento di destinazione completo.

Per esempio:

• Un aggiornamento delta v1 → v3
• Un aggiornamento delta da v2 a v3
• Aggiornamento completo della versione 3

Dopo aver creato una distribuzione, il servizio Device Update e il client determinano automaticamente se è disponibile un aggiornamento differenziale valido per ogni dispositivo.

• Se è disponibile un aggiornamento delta valido (ad esempio, per i dispositivi con v1 o v2), il dispositivo lo scarica e lo installa.
• Se non è disponibile alcun delta valido (ad esempio, dispositivi con v0), il dispositivo scarica e installa invece l'aggiornamento completo (l'immagine SWU di destinazione ricompressa).

Questo comportamento garantisce che tutti i dispositivi possano eseguire l'aggiornamento alla versione di destinazione, anche se non è disponibile un aggiornamento differenziale corrispondente.

Risultati della distribuzione

Dopo la distribuzione, si verifica uno dei risultati seguenti:

• L'aggiornamento delta viene installato correttamente e il dispositivo si aggiorna alla versione di destinazione.
• L'aggiornamento differenziale non è disponibile o non va a buon fine, ma l'aggiornamento completo di riserva si installa correttamente.
• Sia l'aggiornamento differenziale che l'aggiornamento completo del fallback hanno esito negativo e il dispositivo rimane nella versione precedente.

Per determinare il risultato di un dispositivo, visualizzare i risultati dell'installazione nel portale di Azure. Per gli aggiornamenti non riusciti, esaminare resultCode e extendedResultCode.

• Se l'aggiornamento differenziale ha esito positivo, il dispositivo visualizza lo stato Succeeded.

• Se l'aggiornamento differenziale ha esito negativo ma il fallback ha esito positivo, il dispositivo visualizza uno stato di errore con:

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

Se necessario, è anche possibile raccogliere i log dai dispositivi non riusciti. Per altre informazioni, vedere Raccogliere i log.

Risolvere i problemi relativi ad aggiornamenti non riusciti

Gli aggiornamenti non riusciti visualizzano uno stato di errore che è possibile interpretare usando le istruzioni seguenti.

Inizia con le definizioni degli errori dell'agente Device Update in result.h.

Gli errori dell'agente Aggiornamento dispositivi specifici per la funzionalità del gestore del download degli aggiornamenti differenziali iniziano con 0x9:

Se il codice di errore non è presente in result.h, è probabile che provenga dall'estensione del processore delta. In tal caso, extendedResultCode è un valore decimale negativo nel formato 0x90AXXXXXesadecimale , dove:

• 9 indica la struttura Delta
• 0A indica il componente del processore delta (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
• XXXXX è il codice di errore a 20 bit restituito dal processore delta

Se non è possibile risolvere il problema usando il codice di errore, raccogliere i log dal dispositivo e inviare un GitHub problema per ulteriore assistenza.

Contenuti correlati

• Aggiornamento del dispositivo Azure per gli aggiornamenti differenziali hub IoT
• Schema del manifesto di importazione per l'Aggiornamento dei Dispositivi di Azure per hub IoT
• Risolvere i problemi comuni