Didacticiel : Device Update pour Azure IoT Hub utilisant l’image de référence Raspberry Pi 3 B+

Article
1/26/2022

Device Update pour Azure IoT Hub prend en charge les mises à jour basées sur une image, un package et un script.

Les mises à jour basées sur une image offrent un niveau de confiance plus élevé pour l’état final de l’appareil. Il est généralement plus facile de répliquer les résultats d’une mise à jour basée sur une image entre un environnement de préproduction et un environnement de production, car cela ne présente pas les mêmes défis que les packages et leurs dépendances. En raison de sa nature atomique, le modèle de basculement A/B peut être adopté facilement.

Ce didacticiel vous guide tout au long de la procédure de mise à jour de bout en bout basée sur une image à l’aide du service Device Update pour IoT Hub sur une carte Raspberry Pi 3 B+.

Ce didacticiel vous montre comment effectuer les opérations suivantes :

Téléchargez une image.
Ajoutez une étiquette à votre appareil IoT.
Importez une mise à jour.
Créez un groupe d’appareils.
Déployez une mise à jour d’image.
Supervisez le déploiement de la mise à jour.

Notes

Les mises à jour basées sur l’image dans ce didacticiel ont été validées sur la carte Raspberry Pi B3.

Prérequis

Si ce n’est déjà fait, créez un compte et une instance Device Update, et configurez un hub IoT.

Télécharger l’image

Nous fournissons des exemples d’images dans les Ressources figurant sur la page des versions GitHub de Device Update. Le fichier .gz est l’image de base que vous pouvez flasher sur une carte Raspberry Pi 3 B+. Le fichier swUpdate est la mise à jour que vous importeriez via Device Update pour IoT Hub.

Flasher une carte SD avec l’image

Utilisez l’outil de flashage du système d’exploitation de votre choix pour installer l’image de base de Device Update (adu-base-image) sur la carte SD qui sera utilisée sur l’appareil Raspberry Pi 3 B+.

Utiliser bmaptool pour flasher la carte SD

Installez l’utilitaire bmaptool si ce n’est déjà fait.
```
sudo apt-get install bmap-tools
```
Recherchez le chemin de la carte SD dans /dev. Le chemin doit être similaire à /dev/sd* ou /dev/mmcblk*. Vous pouvez recourir à l’utilitaire dmesg pour rechercher le chemin correct.
Démontez toutes les partitions montées avant l’effectuer le flashage.
```
sudo umount /dev/<device>
```
Veillez à disposer des autorisations d’accès en écriture sur l’appareil.
```
sudo chmod a+rw /dev/<device>
```
Facultatif : Pour accélérer le flashage, téléchargez le fichier bimap avec le fichier image et placez-les dans le même répertoire.

Flashez la carte SD.

sudo bmaptool copy <path to image> /dev/<device>

Les logiciels de Device Update pour Azure IoT Hub sont soumis aux termes de contrat de licence suivants :

Lisez les termes de contrat de licence avant d’utiliser l’agent. Le fait de procéder à l’installation et à l’utilisation revient à accepter ces termes. Si vous n’acceptez pas les termes du contrat de licence, n’utilisez pas l’agent Device Update pour IoT Hub.

Créer un appareil ou module dans IoT Hub et récupérer une chaîne de connexion

À présent, ajoutez l’appareil à IoT Hub. Dans IoT Hub, une chaîne de connexion est générée pour l’appareil.

À partir du portail Azure, démarrez IoT Hub.
Créez un appareil.
Dans le volet gauche, sélectionnez Appareils. Sélectionnez ensuite Nouveau.
Sous ID de périphérique, entrez un nom pour l’appareil. Assurez-vous que la case Générer automatiquement les clés est cochée.
Sélectionnez Enregistrer. Sur la page Appareils, l’appareil que vous avez créé doit figurer dans la liste.
Récupérez la chaîne de connexion de l’appareil à l’aide de l’une des deux options suivantes :
- Option 1 : Utiliser l’agent Device Update avec une identité de module : Sur la même page Appareils, sélectionnez Ajouter une identité de module en haut. Créez un module Device Update intitulé IoTHubDeviceUpdate. Choisissez d’autres options telles qu’elles s’appliquent à votre cas d’usage, puis sélectionnez Enregistrer. Sélectionnez le module que vous venez de créer. Dans la vue du module, sélectionnez l’icône Copier en regard de Chaîne de connexion principale.
- Option 2 : Utiliser l’agent Device Update avec l’identité de l’appareil : Dans la vue de l’appareil, sélectionnez l’icône Copier en regard de Chaîne de connexion principale.
Collez les caractères copiés à un certain emplacement en vue d’une utilisation ultérieure lors des étapes suivantes :

Cette chaîne copiée est la chaîne de connexion de votre appareil.

Préparer les configurations sur l’appareil pour Device Update pour IoT Hub

Deux fichiers de configuration doivent se trouver sur l’appareil afin que Device Update pour IoT Hub soit configuré correctement. Le premier est le fichier du-config.json qui doit exister à l’emplacement /adu/du-config.json. Le deuxième est le fichier du-diagnostics-config.json qui doit exister à l’emplacement /adu/du-diagnostics-config.json.

Voici deux exemples pour les fichiers du-config.json et du-diagnostics-config.json :

Exemple de fichier du-config.json

   {
      "schemaVersion": "1.0",
      "aduShellTrustedUsers": [
         "adu",
         "do"
      ],
      "manufacturer": "fabrikam",
      "model": "vacuum",
      "agents": [
         {
         "name": "main",
         "runas": "adu",
         "connectionSource": {
            "connectionType": "string",
            "connectionData": "HostName=example-connection-string.azure-devices.net;DeviceId=example-device;SharedAccessKey=M5oK/rOP12aB5678YMWv5vFWHFGJFwE8YU6u0uTnrmU="
         },
         "manufacturer": "fabrikam",
         "model": "vacuum"
         }
      ]
   }

Exemple du fichier du-diagnostics-config.json

   {
      "logComponents":[
         {
               "componentName":"adu",
               "logPath":"/adu/logs/"
         },
         {
               "componentName":"do",
               "logPath":"/var/log/deliveryoptimization-agent/"
         }
      ],
      "maxKilobytesToUploadPerLogPath":50
   }

Configuration de l’agent Devise Update sur Raspberry Pi

Vérifiez que l’appareil Raspberry Pi 3 est connecté au réseau.
Suivez les instructions pour ajouter les détails de la configuration :
1. Tout d’abord, connectez-vous avec SSH à la machine à l’aide de la commande suivante dans la fenêtre PowerShell :
```
   ssh raspberrypi3 -l root
```
2. Créez ou ouvrez le fichier du-config.json pour le modifier à l’aide de :
```
   nano /adu/du-config.json
```
3. Après avoir exécuté la commande, vous devez voir un éditeur ouvert avec le fichier. Si vous n’avez jamais créé le fichier, il sera vide. À présent, copiez le contenu du-config.json de l’exemple précédent et remplacez-le par les configurations requises pour votre appareil. Remplacez ensuite l’exemple de chaîne de connexion par celle de l’appareil que vous avez créé dans les étapes précédentes.
4. Une fois vos modifications terminées, sélectionnez Ctrl + X pour quitter l’éditeur. Ensuite, entrez y pour enregistrer les modifications.
5. À présent, vous devez créer le fichier du-diagnostics-config.json à l’aide de commandes similaires. Commencez par créer ou ouvrir le fichier du-diagnostics-config.json pour le modifier à l’aide de :
```
   nano /adu/du-diagnostics-config.json
```
6. Copiez l’exemple précédent de contenu du-diagnostics-config.json et remplacez toutes les configurations qui diffèrent de la build par défaut. L’exemple de fichier du-diagnostics-config.json représente les emplacements par défaut des journaux pour Device Update pour IoT Hub. Vous devez uniquement les modifier si votre implémentation diffère.
7. Une fois vos modifications terminées, sélectionnez Ctrl + X pour quitter l’éditeur. Ensuite, entrez y pour enregistrer les modifications.
8. Utilisez la commande suivante pour afficher les fichiers situés dans le répertoire /adu/. Vous devez voir vos deux fichiers de configuration files.du-diagnostics-config.json pour les modifier à l’aide de la commande suivante :
```
   ls -la /adu/
```
Redémarrez le démon système Device Update pour garantir que les configurations ont été appliquées. Utilisez la commande suivante dans le terminal connecté à raspberrypi :
```
   systemctl start adu-agent
```
Vérifiez que l’agent est actif à l’aide de la commande suivante :
```
   systemctl status adu-agent
```
Vous devez voir l’état redevenir actif et vert.

Connecter l’appareil dans Device Update pour IoT Hub

Dans le volet gauche, sélectionnez Appareils.
Sélectionnez le lien comportant le nom de votre appareil.
En haut de la page, sélectionnez Jumeau d’appareil si vous vous connectez directement à Device Update à l’aide de l’identité de l’appareil IoT. Dans le cas contraire, sélectionnez le module que vous avez créé ci-dessus, puis cliquez sur son jumeau de module.
Dans la section Signalé des propriétés du Jumeau d’appareil, recherchez la version du noyau Linux. Pour un nouvel appareil qui n’a pas reçu de mise à jour du service Device Update, la valeur DeviceManagement:DeviceInformation:1.swVersion représente la version du microprogramme qui s’exécute sur l’appareil. Une fois qu’une mise à jour a été appliquée à un appareil, le service Device Update utilise la valeur de la propriété AzureDeviceUpdateCore:ClientMetadata:4.installedUpdateId pour représenter la version du microprogramme qui s’exécute sur l’appareil.
Les noms des fichiers image de base et de mise à jour comportent un numéro de version.
```
adu-<image type>-image-<machine>-<version number>.<extension>
```

Utilisez ce numéro de version dans la section ultérieure « Importer la mise à jour ».

Ajouter une étiquette à votre appareil

Connectez-vous au portail Azure et accédez à votre hub IoT.
Dans le volet gauche, sous Appareils, recherchez votre appareil IoT et accédez au jumeau d’appareil ou au jumeau de module.
Dans le jumeau de module du module d’agent Device Update, supprimez toutes les valeurs d’étiquette Device Update existantes en leur affectant la valeur Null. Si vous utilisez l’identité d’appareil avec l’agent Device Update, effectuez ces changements sur le jumeau d’appareil.
Ajoutez une nouvelle valeur d’étiquette Device Update comme indiqué ci-dessous :
```
    "tags": {
            "ADUGroup": "<CustomTagValue>"
            }
```

Importer la mise à jour

Téléchargez l’exemple de manifeste du didacticiel (Tutorial Import Manifest_PI.json) et l’exemple de mise à jour (adu-update-image-raspberrypi3-0.6.5073.1.swu) à partir des ressources de version pour l’agent le plus récent.
Connectez-vous au portail Azure et accédez à votre hub IoT avec Device Update. Dans le volet gauche, sous Gestion automatique des appareils, sélectionnez Mises à jour.
Sélectionnez l’onglet Mises à jour.
Sélectionnez + Importer une nouvelle mise à jour.
Sélectionnez + Sélectionner dans le conteneur de stockage. Sélectionnez un compte existant ou créez-en un en utilisant + Compte de stockage. Sélectionnez ensuite un conteneur existant ou créez-en un en utilisant + Conteneur. Ce conteneur sera utilisé pour préparer vos fichiers de mise à jour pour l’importation.

Notes

Nous vous recommandons d’utiliser un nouveau conteneur chaque fois que vous importez une mise à jour pour éviter d’importer accidentellement des fichiers à partir de mises à jour précédentes. Si vous n’utilisez pas un nouveau conteneur, veillez à supprimer tous les fichiers du conteneur existant avant de terminer cette étape.
Dans votre conteneur, sélectionnez Charger et accédez aux fichiers que vous avez téléchargés à l’étape 1. Une fois que vous avez sélectionné tous vos fichiers de mise à jour, sélectionnez Charger. Sélectionnez ensuite le bouton Sélectionner pour revenir à la page Importer la mise à jour.

Cette capture d’écran montre l’étape d’importation. Les noms de fichiers peuvent ne pas correspondre à ceux utilisés dans l’exemple.
Sur la page Importer la mise à jour, passez en revue les fichiers à importer. Sélectionnez ensuite Importer la mise à jour pour démarrer le processus d’importation.
Le processus d’importation commence et l’écran passe à la section Historique d’importation. Lorsque la colonne État indique que l’importation a réussi, sélectionnez l’en-tête Mises à jour disponibles. Vous devez maintenant voir votre mise à jour importée dans la liste.

En savoir plus sur l’importation des mises à jour.

Créer un groupe de mise à jour

Accédez à l’onglet Groupes et déploiements en haut de la page.
Sélectionnez Ajouter un groupe pour créer un groupe.
Sélectionnez une étiquette IoT Hub et une classe d’appareil dans la liste. Sélectionnez ensuite Créer un groupe.
Une fois que le groupe est créé, le graphique de conformité de mise à jour et la liste des groupes sont mis à jour. Le graphique de conformité des mises à jour montre le nombre d’appareils dans différents états de conformité : À la mise à jour la plus récente, Nouvelles mises à jour disponibles et Mises à jour en cours. En savoir plus sur la conformité des mises à jour.
Vous voyez maintenant le groupe que vous venez de créer ainsi que toutes les mises à jour disponibles pour les appareils dans le nouveau groupe. Si des appareils ne répondent pas aux exigences de classe d’appareil du groupe, ils apparaissent dans un groupe non valide correspondant. Pour déployer la meilleure mise à jour disponible sur le nouveau groupe défini par l’utilisateur à partir de cet affichage, sélectionnez Déployer à côté du groupe.

En savoir plus sur l’ajout d’étiquettes et la création de groupes de mises à jour.

Déployer la mise à jour

Une fois le groupe créé, vous devez voir une nouvelle mise à jour disponible pour votre groupe d’appareils. Un lien vers la mise à jour doit s’afficher sous Meilleure mise à jour. Vous devrez peut-être actualiser une fois. En savoir plus sur la conformité des mises à jour.
Sélectionnez le groupe cible en sélectionnant le nom du groupe. Vous êtes redirigé vers les détails du groupe sous Informations de base du groupe.
Pour démarrer le déploiement, accédez à l’onglet Déploiement actuel. Sélectionnez le lien Déployer à côté de la mise à jour souhaitée dans la section Mises à jour disponibles. La meilleure mise à jour disponible pour un groupe donné est indiquée par la mention Optimale.
Planifiez votre déploiement pour qu’il démarre immédiatement ou plus tard. Sélectionnez ensuite Créer.
Sous Détails du déploiement, État devient Actif. La mise à jour déployée est marquée avec la mention (déploiement en cours).
Affichez le graphique de conformité pour voir que la mise à jour est maintenant en cours.
Une fois votre appareil correctement mis à jour, vous voyez que votre graphique de conformité et les détails du déploiement sont mis à jour pour concorder.