Mises à jour Delta (préversion)

Les mises à jour delta permettent de générer de petites mises à jour qui représentent 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.

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

• Les fichiers des mises à jour source et cible doivent être dans le format SWUpdate (SWU).
• Dans chaque fichier SWUpdate doit se trouver une image brute qui utilise le système de fichiers Ext2, Ext3 ou Ext4.

Le processus de génération delta recompresse la mise à jour SWU cible avec gzip pour produire un delta optimal. Vous importez la mise à jour SWU cible recompressée dans le service Device Update avec le fichier de mise à jour delta généré.

Dispositif Configuration de l'agent de mise à jour pour le composant processeur delta

Pour télécharger et installer les mises à jour delta à partir du service Device Update, votre appareil doit disposer de l'agent Device Update avec le gestionnaire de mise à jour et le composant processeur delta présents et configurés.

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. Pour ajouter l’agent Device Update à un appareil et le configurez pour pouvoir l’utiliser, consultez Approvisionnement de l’agent Device Update. Utilisez la version 1.0 ou une version ultérieure de l’agent.

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.

Processeur delta

Le processeur delta sur Azure/iot-hub-device-update-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. Pour ajouter le composant de processeur delta à votre image d’appareil et le configurer pour une utilisation, vous pouvez télécharger un package Debian pour Ubuntu 20.04 et versions ultérieures depuis https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Si vous utilisez une autre distribution, suivez les instructions de README.md pour utiliser plutôt CMAKE afin de 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, comme suit :

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

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

Une fois le fichier de mise à jour delta téléchargé sur un appareil, il est comparé à un <source_archive> valide précédemment mis en cache sur l’appareil. Ce processus active la mise à jour delta pour recréer l’image cible complète.

Le moyen le plus simple de remplir cette image mise en cache consiste à importer et déployer la mise à jour d’une image complète sur l’appareil avec le service Device Update. Si l’appareil a été configuré avec l’agent Device Update version 1.0 ou ultérieure et le processeur delta, l’agent 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, le chemin où l’image est attendue est <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>. Par défaut, <BASE_SOURCE_DOWNLOAD_CACHE_PATH> est le chemin /var/lib/adu/sdc/<fournisseur>. La valeur provider est égale à la partie provider de 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 la mise à jour delta à l’aide de l’outil DiffGen

Vous pouvez créer des mises à jour delta à l’aide de l’outil Diff Generation (DiffGen).

Environnement requis

Avant de créer des deltas avec DiffGen, vous devez télécharger et installer plusieurs éléments sur la machine de l'environnement. Idéalement, utilisez un environnement Linux Ubuntu 20.04, ou Sous-système Windows pour Linux si vous êtes sous Windows.

Le tableau suivant affiche le contenu nécessaire, l’emplacement pour l’obtenir et l’installation recommandée si besoin.

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

L'outil DiffGen s'exécute avec les arguments et la syntaxe suivants :

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

La commande précédente exécute le script recompress_tool.py, qui crée le <recompressed_target_file>. DiffGen utilise ensuite la valeur <recompressed_target_file> au lieu de <target_archive> en tant que fichier cible pour créer le diff. Les fichiers image dans le <recompressed_target_archive> sont compressés avec gzip.

Si vos fichiers SWU sont signés, ils nécessitent également l’argument <signing_command> dans la commande DiffGen :

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

Le paramètre de chaîne de commande de signature DiffGenTool exécute le script recompress_and_sign_tool.py. Ce script crée le <recompressed_target_file>. En outre, ce script signe également le fichier sw-description dans l’archive pour créer un fichier sw-description.sig.

Vous pouvez utiliser l’exemple de script sign_file.sh à partir du dépôt GitHub Azure/iot-hub-device-update-delta pour créer un écart entre le fichier source d’entrée et un fichier cible re-compressé et re-signé. Ouvrez le script et modifiez-le pour ajouter le chemin à votre fichier de clé privée et enregistrez-le. Consultez la section Exemples pour obtenir des exemples d’utilisation.

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

Exemples DiffGen

Les exemples suivants fonctionnent à partir du répertoire /mnt/o/temp dans le sous-système Windows pour Linux.

Le code suivant crée une différence entre le fichier source d'entrée et un fichier cible recompressé :

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

Si vous utilisez également le paramètre de signature, que vous devez si votre fichier SWU est signé, vous pouvez utiliser l’exemple de script sign_file.sh mentionné précédemment. 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.

Le code suivant crée une différence entre le fichier source d'entrée et un fichier cible recompressé et re-signé :

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

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

La procédure d'importation d'une mise à jour delta dans le service Device Update est la même que pour toute autre mise à jour. Si vous ne l’avez pas encore fait, assurez-vous de consulter Guide pratique pour préparer l’importation d’une mise à jour dans Azure Device Update pour IoT Hub.

Générer le manifeste d’importation

Pour importer une mise à jour dans le service Device Update, vous devez disposer ou créer un fichier manifeste d'importation. Pour plus d’informations, consultez Importation de mises à jour dans Device Update.

Les fichiers manifestes d'importation pour les mises à jour delta doivent faire référence aux fichiers suivants créés par l'outil DiffGen :

• L’image SWU <recompressed_target_file>
• <delta file>.

La fonctionnalité de mise à jour delta utilise une fonctionnalité appelée fichiers associés, qui exige une version 5 ou plus récente du manifeste d’importation. Pour utiliser la fonctionnalité fichiers associés, vous devez inclure les objets relatedFiles et downloadHandler dans votre manifeste d’importation.

Vous 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. Plus important, vous devez également spécifier les deux propriétés suivantes qui sont propres à la fonctionnalité de mise à jour delta :

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

Les deux propriétés sont spécifiques au <source image file> que vous utilisez en tant qu’entrée de l’outil DiffGen lors de la création de votre mise à jour delta. Le manifeste d’importation a besoin des informations sur l’image SWU source 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 cette image sur l’appareil après avoir téléchargé la mise à jour delta.

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 le downloadHandler suivant :

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

Vous pouvez utiliser la commande az iot du update init v5 d’interface de ligne de commande Azure (CLI) pour générer le manifeste d’importation de votre mise à jour delta. Pour plus d’informations, consultez Créer un manifeste d’importation de 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>"}' 

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

Importer via le portail Azure

Une fois que vous avez créé votre manifeste d’importation, importez la mise à jour delta en suivant les instructions fournies dans Ajouter une mise à jour à Device Update pour IoT Hub. Vous devez inclure les éléments suivants dans l’importation :

• Le fichier *importmanifest.json que vous avez créé précédemment dans les étapes précédentes
• L’image SWU <recompressed_target_file> créée par l’outil DiffGen
• Le <delta file> créé par l’outil DiffGen

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

Le déploiement d'une mise à jour delta dans le portail Azure est identique à celui d'une mise à jour d'image normale. Pour plus d’informations, consultez Déployer une mise à jour en utilisant Device Update.

Une fois que vous avez créé le déploiement de votre mise à jour delta, le service Device Update et le client Device Update déterminent automatiquement s’il existe une mise à jour delta valide pour chaque appareil sur lequel vous effectuez le déploiement. S'ils trouvent un delta valide, ils téléchargent et installent la mise à jour delta sur cet appareil.

S’ils ne trouvent pas de mise à jour delta valide, 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 s'est installée avec succès et l'appareil est sur 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 et l’appareil est sur la nouvelle version.
• L'installation delta et l'installation de secours ont toutes deux échoué, et l'appareil fonctionne toujours avec l'ancienne version.

Pour déterminer laquelle des défaillances 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 d’une mise à jour delta, l’appareil affiche l’état Réussite.

• Si une mise à jour delta a échoué, mais que le rétablissement de l’image complète a réussi, l’appareil affiche l’état d’erreur suivant :

  • resultCode : <valeur supérieure à 0>
  • extendedResultCode : <valeur non nulle>

Résoudre les problèmes liés aux mises à jour

Les mises à jour non réussies affichent un état d'erreur que vous pouvez interpréter à l'aide des instructions suivantes. 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 des mises à jour delta commence avec 0x9 :

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, le extendedResultCode est 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 est le code d’erreur 20 bits du processeur delta FIT (Field Installation Tool)

Si vous ne pouvez 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.

Contenu connexe

• Schéma de manifeste d’importation Azure Device Update pour IoT Hub
• Résolution des problèmes courants