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

Article
04/11/2023

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.
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. Ce tutoriel nécessite que l’appareil soit connecté via une connexion Ethernet.

Téléchargez des fichiers dans Ressources sur la page des versions GitHub de Device Update. Le Tutorial_RaspberryPi.zip contient tous les fichiers requis pour le tutoriel.

Créez un appareil dans IoT Hub et récupérez 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.

Sur le Portail Azure, accédez à votre hub IoT.
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.
Obtenez la chaîne de connexion de l’appareil en accédant à l’affichage de l’appareil, puis 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.

Notes

Ce tutoriel utilise une chaîne de connexion d’appareil pour s’authentifier et se connecter avec le IoT Hub afin de faciliter la configuration. Pour les scénarios de production, nous vous recommandons d’utiliser l’identité de module et de tirer parti d’AIS (service d'identité de l’IoT) pour configurer des appareils. En savoir plus

Installer Raspberry Pi

Nous fournissons des fichiers d’image de base et de mise à jour dans Ressources sur la page des versions GitHub de Device Update. Le Tutorial_RaspberryPi.zip contient tous les fichiers requis pour le tutoriel. Le fichier .gz est l’image de base que vous pouvez flasher sur une carte Raspberry Pi 3 B+. Le fichier swUpdate(.swu), le script swupdate personnalisé et le manifeste sont les fichiers de mise à jour que vous importeriez via Device Update pour IoT Hub.

Cette image de base utilise une build Yocto (basée sur la version 3.4.4) avec :

SWUpdate qui active la mise à jour de partition double avec DU
Agent Device Update

Pour en savoir plus sur les couches Yocto utilisées, reportez-vous à GitHub Device Update Yocto.

Vous pouvez utiliser 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+. Vous trouverez ci-dessous les instructions d’utilisation de bmaptool pour flasher sur la carte SD.

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.

Configuration de l’agent Devise Update sur Raspberry Pi

Vérifiez que l’appareil Raspberry Pi 3 est connecté au réseau.
SSH au Raspberry Pi 3 en utilisant la commande suivante dans la fenêtre PowerShell :
```
  ssh raspberrypi3 -l root
```
Les fichiers de configuration DU (du-config.json et du-diagnostics-config.json) doivent se trouver sur l’appareil afin que Device Update pour IoT Hub se configure correctement.
1. Pour créer ou ouvrir le fichier du-config.json pour modification à l’aide de :
```
  nano /adu/du-config.json
```
1. 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 ci-dessous 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.
  
  config_json
```
{
   "schemaVersion": "1.0",
   "aduShellTrustedUsers": [
      "adu",
      "do"
   ],
   "manufacturer": "contoso",
   "model": "virtual-vacuum-v2",
   "agents": [
      {
      "name": "main",
      "runas": "adu",
      "connectionSource": {
         "connectionType": "string",
         "connectionData": "HostName=<hub_name>.azure-devices.net;DeviceId=<device_id>;SharedAccessKey=<device_key>" 
      },
      "manufacturer": "contoso",
      "model": "virtual-vacuum-v2"
      }
   ]
}  
```
1. Une fois vos modifications terminées, sélectionnez Ctrl+X pour quitter l’éditeur. Entrez y ensuite pour enregistrer les modifications.
À présent, vous devez créer le fichier du-diagnostics-config.json à l’aide de commandes similaires.
1. Commencez par créer ou ouvrir le fichier du-diagnostics-config.json pour le modifier à l’aide de :
```
  nano /adu/du-diagnostics-config.json
```
1. Copiez le contenu du-diagnostics-config.json fourni ci-dessous 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 modifier ces valeurs par défaut si votre implémentation diffère.
du-diagnostics-config.json
```
{
   "logComponents":[
      {
         "componentName":"adu",
         "logPath":"/adu/logs/"
      },
      {
         "componentName":"do",
         "logPath":"/var/log/deliveryoptimization-agent/"
      }
   ],
   "maxKilobytesToUploadPerLogPath":50
}
```
1. Une fois vos modifications terminées, sélectionnez Ctrl+X pour quitter l’éditeur. Entrez y ensuite pour enregistrer les modifications.
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 deviceupdate-agent
```
Vérifiez que l’agent est actif à l’aide de la commande suivante :
```
  systemctl status deviceupdate-agent
```
Vous devez voir l’état devenir 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.
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 de groupe Device Update à votre appareil

Accédez à votre hub IoT dans le portail Azure.
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>"
            }
```
Cette capture d’écran montre la section dans laquelle la balise doit être ajoutée dans le jumeau.

Importer la mise à jour

Téléchargez l’échantillon de manifeste de didacticiel et l’échantillon de mise à jour (fichier .swu) et l’exemple de script A/B à partir de Tutorial_RaspberryPi.zip, sous 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. Pour le didacticiel, importez l’exemple de manifeste du didacticiel, l’exemple de mise à jour (fichier .swu) et l’exemple de script A/B téléchargé précédemment.
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.

Pour plus d’informations sur le processus d’importation, consultez Importer une mise à jour vers Device Update.

Afficher les groupes d’appareils

Device Update utilise des groupes pour organiser les appareils. Device Update trie automatiquement les appareils en groupes en fonction des étiquettes et des propriétés de compatibilité qui leur sont attribuées. Chaque appareil appartient à un seul groupe, mais les groupes peuvent avoir plusieurs sous-groupes pour trier différentes classes d’appareils.

Accédez à l’onglet Groupes et déploiements en haut de la page.
Affichez la liste des groupes et le graphique de conformité de mise à 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 devez voir un groupe d’appareils qui contient l’appareil simulé que vous avez configuré dans ce tutoriel, ainsi que toutes les mises à jour disponibles pour les appareils du 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.

Pour plus d’informations sur les balises et les groupes, consultez Gérer les groupes d’appareils.

Déployer la mise à jour

Une fois le groupe créé, vous devriez voir une nouvelle mise à jour disponible pour votre groupe d’appareils, avec un lien vers cette mise à jour sous Meilleure mise à jour. Vous devrez peut-être actualiser une fois.

Pour plus d’informations sur la conformité, consultez Conformité des mises à jour des appareils.
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 de déploiement à 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.

Conseil

Par défaut, la date et l’heure de Début est définie sur 24 heures à partir de votre heure actuelle. Veillez à sélectionner une autre date et heure si vous souhaitez que le déploiement commence plus tôt.
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.