Guide pratique pour comprendre et utiliser les mises à jour delta dans Device Update pour IoT Hub (préversion)

Article
09/11/2023

Les mises à jour delta permettent de générer une petite mise à jour qui représente uniquement les changements apportés entre deux mises à jour complètes : une image source et une image cible. Cette approche est idéale pour réduire la bande passante consommée pour télécharger une mise à jour sur un appareil, en particulier si seules quelques modifications ont été effectuées entre les mises à jour source et cible.

Remarque

La fonctionnalité de mise à jour delta est actuellement en préversion publique.

Prérequis des mises à jour delta dans Device Update pour IoT Hub

Les fichiers des mises à jour source et cible doivent être au format SWUpdate (SWU).
Dans chaque fichier SWUpdate doit se trouver une image brute qui utilise le système de fichiers Ext2, Ext3 ou Ext4. Cette image peut être compressée avec Gzip ou Zstd.
Le processus de génération delta recompresse la mise à jour SWU cible avec Zstd afin de produire un delta optimal. Importez cette mise à jour SWU cible recompressée dans le service Device Update avec le fichier de mise à jour delta généré.
Dans SWUpdate, la décompression Zstd doit également être activée sur l’appareil,
- Ce processus implique d’utiliser SWUpdate 2019.11 ou une version plus récente.

Configuration d’un appareil avec l’agent Device Update et le composant processeur delta

Pour que votre appareil puisse télécharger et installer les mises à jour delta à partir du service Device Update, vous devez avoir configuré plusieurs composants.

Agent Device Update

L’agent Device Update orchestre le processus de mise à jour sur l’appareil, notamment les actions de téléchargement, d’installation et de redémarrage. Ajoutez-le à un appareil et configurez-le pour pouvoir l’utiliser. Utilisez la version 1.0 ou une version ultérieure de l’agent. Pour obtenir des instructions, consultez Approvisionnement de l’agent Device Update.

Gestionnaire de mises à jour

Un gestionnaire de mises à jour s’intègre à l’agent Device Update pour effectuer l’installation proprement dite des mises à jour. Dans le cas des mises à jour delta, commencez par le gestionnaire de mises à jour microsoft/swupdate:2 si vous ne possédez pas déjà votre propre gestionnaire de mises à jour SWUpdate que vous souhaitez modifier. Si vous utilisez votre propre gestionnaire de mises à jour, veillez à activer la décompression Zstd dans SWUpdate.

Processeur delta

Le processeur delta recrée le fichier image SWU d’origine sur votre appareil une fois le fichier delta téléchargé, afin que votre gestionnaire de mises à jour puisse installer le fichier SWU. Le code du processeur delta est disponible dans le dépôt GitHub Azure/iot-hub-device-update-delta.

Pour ajouter le composant processeur delta à votre image d’appareil et le configurer en vue de son utilisation, suivez les instructions sur README.md pour utiliser CMAKE et générer le processeur delta à partir de la source. À partir de là, installez l’objet partagé (libadudiffapi.so) directement en le copiant dans le répertoire /usr/lib :

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

Ajout d’un fichier image SWU source à l’appareil

Une fois qu’une mise à jour delta a été téléchargée sur un appareil, elle doit être comparée à un fichier SWU source valide précédemment mis en cache sur l’appareil. Ce processus est nécessaire pour que la mise à jour delta recrée l’image cible complète. Le moyen le plus simple de remplir cette image mise en cache consiste à déployer la mise à jour d’une image complète sur l’appareil avec le service Device Update (à l’aide des processus d’importation et de déploiement existants). Tant que l’appareil a été configuré avec l’agent Device Update (version 1.0 ou ultérieure) et le processeur delta, l’agent Device Update met automatiquement en cache le fichier SWU installé pour que la mise à jour delta puisse l’utiliser par la suite.

Si vous souhaitez plutôt préremplir directement l’image source sur votre appareil, l’image est attendue au chemin suivant :

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

Par défaut, BASE_SOURCE_DOWNLOAD_CACHE_PATH est le chemin /var/lib/adu/sdc/[provider]. La valeur [provider] est égale à la partie provider d’updateId dans le fichier SWU source.

ENCODED_HASH correspond à la chaîne hexadécimale base64 du fichier binaire SHA256. Après l’encodage en chaîne hexadécimale base64, elle encode toutefois les caractères comme suit :

+ encodé en tant que octets _2B
/ encodé en tant que octets _2F
= encodé en tant que octets _3D

Génération de mises à jour delta à l’aide de l’outil DiffGen

Environnement requis

Pour pouvoir créer des deltas avec DiffGen, vous devez télécharger ou installer plusieurs éléments sur l’ordinateur de l’environnement. Nous vous recommandons d’utiliser un environnement Linux, plus spécifiquement Ubuntu 20.04 (ou le Sous-système Windows pour Linux en mode natif sur Windows).

Le tableau suivant donne la liste du contenu nécessaire, l’emplacement où vous pouvez les récupérer et l’installation recommandée si besoin :

Nom binaire	Emplacement	Procédure d'installation
DiffGen	Référentiel GitHub Azure/iot-hub-device-update-delta	Dans le dossier racine, sélectionnez le fichier Microsoft.Azure.DeviceUpdate.Diffs.[version].nupkg. En savoir plus sur les packages NuGet.
Runtime .NETCore, version 6.0.0	Dans le terminal ou les gestionnaires de packages	Instructions pour Linux. Seul le runtime est requis.

Les dépendances

zstd_compression_tool permet de décompresser les fichiers image d’une archive et de les recompresser avec Zstd. Ce processus garantit que tous les fichiers d’archive utilisés pour la génération du différentiel suivent le même algorithme de compression pour les images figurant à l’intérieur des archives.

Voici les commandes permettant d’installer les packages et bibliothèques requis :

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

Création d’une mise à jour delta à l’aide de DiffGen

L’outil DiffGen est exécuté avec plusieurs arguments. Tous les arguments sont obligatoires. La syntaxe globale est la suivante :

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

Le script recompress_tool.py est exécuté pour créer le fichier [recompressed_target_archive], qui est ensuite utilisé comme fichier cible au lieu de [target_archive] pour créer le diff.
Les fichiers image figurant dans [recompressed_target_archive] sont compressés avec zstd.

Si vos fichiers SWU sont signés (ce qui est probable), vous avez également besoin d’un autre argument :

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

En plus d’utiliser [recompressed_target_archive] comme fichier cible, fournissez un paramètre de chaîne de commande de signature pour exécuter recompress_and_sign_tool.py afin de créer le fichier [recompressed_target_archive] et signer le fichier sw-description situé dans l’archive (ce qui suppose qu’un fichier sw-description.sig est présent). Vous pouvez utiliser l’exemple de script sign_file.sh du référentiel GitHub Azure/iot-hub-device-update-delta. Ouvrez le script et modifiez-le pour ajouter le chemin à votre fichier de clé privée, puis enregistrez-le. Consultez la section d’exemples pour obtenir des exemples d’utilisation.

Le tableau suivant décrit plus en détail les arguments :

Argument	Description
[source_archive]	Il s’agit de l’image sur laquelle le delta est basé quand il est créé. Important : cette image doit être identique à l’image déjà présente sur l’appareil (par exemple mise en cache à partir d’une mise à jour précédente).
[target_archive]	Il s’agit de l’image vers laquelle le delta met à jour l’appareil.
[output_path]	Chemin (y compris le nom souhaité du fichier delta généré) sur la machine hôte où placer le fichier delta après sa création. Si le chemin d’accès n’existe pas, l’outil le crée.
[log_folder]	Chemin sur la machine hôte où sont créés les journaux. Nous vous recommandons de définir comme emplacement un sous-dossier du chemin de sortie. Si le chemin d’accès n’existe pas, l’outil le crée.
[working_folder]	Chemin sur l’ordinateur où sont placés les fichiers d’accompagnement et autres fichiers de travail pendant la génération du delta. Nous vous recommandons de définir comme emplacement un sous-dossier du chemin de sortie. Si le chemin d’accès n’existe pas, l’outil le crée.
[recompressed_target_archive]	Chemin sur la machine hôte où est créé le fichier cible recompressé. Ce fichier est utilisé comme fichier cible au lieu de <target_archive> pour la génération du diff. Si ce chemin existe avant l’appel de DiffGenTool, il est remplacé. Nous vous recommandons de définir comme chemin un fichier dans le sous-dossier du chemin de sortie.
"[signing_command]" (facultatif)	Commande personnalisable permettant de signer le fichier sw-description dans le fichier d’archive recompressé. Le fichier sw-description figurant dans l’archive recompressée est utilisé comme paramètre d’entrée de la commande de signature. DiffGenTool impose que la commande de signature crée un fichier de signature, en utilisant le nom de l’entrée terminé par `.sig`. Il est nécessaire de mettre le paramètre entre des guillemets doubles afin que l’ensemble de la commande soit transmise comme un seul paramètre. En outre, évitez de placer le caractère « ~ » dans un chemin de clé utilisé pour la signature. Employez plutôt le chemin « home » complet à la place (par exemple, utilisez /home/USER/keys/priv.pem au lieu de ~/keys/priv.pem).

Exemples DiffGen

Dans ces exemples, nous opérons à partir du répertoire /mnt/o/temp (dans WSL) :

Création du différentiel entre le fichier source d’entrée et le fichier cible recompressé :

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]

Si vous utilisez également le paramètre de signature (nécessaire dans le cas où votre fichier SWU est signé), vous pouvez utiliser l’exemple de script sign_file.sh référencé précédemment. Tout d’abord, ouvrez le script et modifiez-le pour ajouter le chemin à votre fichier de clé privée. Enregistrez le script, puis exécutez DiffGen comme suit :

Création du différentiel entre le fichier source d’entrée et le fichier cible recompressé et resigné :

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

Importation de la mise à jour delta générée

Le processus de base d’importation d’une mise à jour dans le service Device Update reste inchangé pour les mises à jour delta. Si ce n’est déjà fait, veillez à consulter la page Guide pratique pour préparer une mise à jour à importer dans Azure Device Update pour IoT Hub.

Génération du manifeste d’importation

La première étape à suivre pour importer une mise à jour dans le service Device Update consiste toujours à créer un manifeste d’importation si vous n’en possédez pas déjà. Pour plus d’informations sur les manifestes d’importation, consultez Importation de mises à jour dans Device Update. Pour les mises à jour delta, votre manifeste d’importation doit référencer deux fichiers :

l’image SWU cible recompressée créée lors de l’exécution de l’outil DiffGen ;
le fichier delta créé lorsque vous avez exécuté l’outil DiffGen.

La fonctionnalité de mise à jour delta utilise une fonctionnalité appelée Fichiers associés, qui exige un manifeste d’importation version 5 ou plus récente.

Pour créer un manifeste d’importation pour votre mise à jour delta à l’aide de la fonctionnalité Fichiers associés, vous devez ajouter des objets relatedFiles et downloadHandler à votre manifeste d’importation.

Utilisez l’objet relatedFiles pour spécifier des informations sur le fichier de mise à jour delta, notamment le nom de fichier, la taille du fichier et le code de hachage sha256. Il est important de noter que vous devez également spécifier deux propriétés propres à la fonctionnalité de mise à jour delta :

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

Ces deux propriétés sont propres au fichier image SWU source que vous avez utilisé comme entrée dans l’outil DiffGen lors de la création de votre mise à jour delta. Les informations sur l’image SWU source sont nécessaires dans votre manifeste d’importation même si vous n’importez pas vraiment l’image source. Les composants delta présents sur l’appareil utilisent ces métadonnées relatives à l’image source pour localiser l’image sur l’appareil une fois le delta téléchargé.

Utilisez l’objet downloadHandler pour spécifier la façon dont l’agent Device Update doit orchestrer la mise à jour delta, en utilisant la fonctionnalité Fichiers associés. À moins de personnaliser votre propre version de l’agent Device Update pour la fonctionnalité delta, utilisez seulement le gestionnaire de téléchargement suivant :

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

Vous pouvez utiliser l’interface de ligne de commande (CLI) Azure pour générer le manifeste d’importation de votre mise à jour delta. Si vous n’avez pas encore utilisé Azure CLI pour créer un manifeste d’importation, consultez Créer un manifeste d’importation de 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>"}'

Enregistrez le fichier JSON de manifeste d’importation que vous avez généré dans un fichier portant l’extension .importmanifest.json.

Importer via le portail Azure

Maintenant que vous avez créé votre manifeste d’importation, vous pouvez importer la mise à jour delta. Pour ce faire, suivez les instructions fournies dans Ajout d’une mise à jour à Device Update pour IoT Hub. Vous devez inclure les éléments suivants lors de l’importation :

le fichier .json de manifeste d’importation que vous avez créé à l’étape précédente ;
l’image SWU cible recompressée créée lors de l’exécution de l’outil DiffGen ;
le fichier delta créé lorsque vous avez exécuté l’outil DiffGen.

Déploiement de la mise à jour delta sur les appareils

Lorsque vous déployez une mise à jour delta, l’expérience sur le Portail Azure est identique au déploiement d’une mise à jour d’image classique. Pour plus d’informations sur le déploiement de mises à jour, consultez Déployer une mise à jour à l’aide de Device Update pour Azure IoT Hub.

Une fois que vous avez créé le déploiement de votre mise à jour delta, le service Device Update et le client Device Update identifient automatiquement s’il existe une mise à jour delta valide pour chaque appareil sur lequel vous effectuez le déploiement. Si un delta valide est trouvé, la mise à jour delta est téléchargée et installée sur cet appareil. Dans le cas contraire, la mise à jour de l’image complète (l’image SWU cible recompressée) est téléchargée en remplacement. Cette approche permet de garantir que tous les appareils sur lesquels vous déployez la mise à jour récupèrent la bonne version.

Il existe trois issues possibles pour un déploiement de mise à jour delta :

La mise à jour delta est installée. L’appareil possède la nouvelle version.
La mise à jour delta n’était pas disponible ou n’a pas pu être installée, mais une installation de l’image complète s’est produite en remplacement. L’appareil possède la nouvelle version.
Le delta et le remplacement par l’image complète ont échoué. L’appareil se trouve toujours sur l’ancienne version.

Pour déterminer laquelle des issues ci-dessus s’est produite, vous pouvez afficher les résultats de l’installation avec le code d’erreur et le code d’erreur étendu. Pour cela, sélectionnez n’importe quel appareil en état d’échec. Si nécessaire, vous avez également la possibilité de collecter les journaux de plusieurs appareils ayant échoué.

En cas de réussite de la mise à jour delta, l’appareil affiche l’état « Réussite ».

Si la mise à jour delta a échoué, mais qu’elle a réussi à rétablir l’image complète, l’état d’erreur suivant s’affiche :

resultCode : [valeur supérieure à 0]
extendedResultCode : [valeur différente de 0]

Si la mise à jour a échoué, elle indique un état d’erreur pouvant être interprété à l’aide de ces instructions :

Commencez par les erreurs de l’agent Device Update dans result.h.

Les erreurs de l’agent Device Update propres à la fonctionnalité de gestionnaire de téléchargement utilisée pour les mises à jour delta commencent par 0x9 :

Composant	Decimal	Hex	Notes
EXTENSION_MANAGER	0	0x00	Indique des erreurs provenant de la logique de l’extension de gestionnaire de téléchargement. Exemple : 0x900XXXXX
PLUGIN	1	0x01	Indique des erreurs qui se sont produites lors de l’utilisation des bibliothèques partagées du plug-in de gestionnaire de téléchargement. Exemple : 0x901XXXXX
RÉSERVÉ	2 - 7	0x02 - 0x07	Réservé au gestionnaire de téléchargement. Exemple : 0x902XXXXX
COMMON	8	0x08	Indique des erreurs dans la logique de niveau supérieur de l’extension Delta Download Handler. Exemple : 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Indique des erreurs dans le cache de mise à jour source de l’extension Delta Download Handler. Exemple : 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Indique des erreurs provenant de l’API du processeur delta. Exemple : 0x90AXXXXX

Si le code d’erreur ne figure pas dans result.h, il s’agit probablement d’une erreur dans le composant de processeur delta (distinct de l’agent Device Update). Dans ce cas, extendedResultCode a une valeur décimale négative au format hexadécimal 0x90AXXXXX.
- 9 correspond à « Delta Facility ».
- 0A correspond à « Delta Processor Component » (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR).
- XXXXX correspond au code d’erreur 20 bits du processeur delta FIT.

Si vous ne parvenez pas à résoudre le problème à partir des informations du code d’erreur, créez un problème GitHub pour obtenir une aide supplémentaire.

Étapes suivantes

Résolution des problèmes courants

Partager via