Device Update pour IoT Hub et IoT Plug-and-Play
Device Update pour IoT Hub utilise IoT Plug-and-Play pour détecter et gérer les appareils prenant en charge la mise à jour OTA. Le service Device Update envoie et reçoit des propriétés et des messages vers et à partir des appareils à l’aide d’interfaces IoT Plug-and-Play.
Pour plus d'informations :
- Comprendre le client d’appareil IoT Plug-and-Play.
- Découvrir comment l'agent Device Update est implémenté.
Modèles des mises à jour d’appareil
L’ID de modèle est la manière dont les appareils intelligents publient leurs fonctionnalités dans les applications Azure IoT avec IoT Plug-and-Play. Pour en apprendre davantage sur la façon de créer des appareils intelligents pour publier ces fonctionnalités dans les applications Azure IoT, reportez-vous au Guide du développeur d’appareils IoT Plug-and-Play.
Device Update pour IoT Hub nécessite le smart device IoT Plug-and-Play pour annoncer un ID de modèle dans le cadre de la connexion de l’appareil. Découvrez comment annoncer un ID de modèle.
Device Update a défini plusieurs modèles PnP qui prennent en charge les fonctionnalités DU. Le modèle Device Update, « dtmi:azure:iot:deviceUpdateContractModel;3 », prend en charge la fonctionnalité de base et utilise l’interface Device Update Core pour envoyer des actions de mise à jour et des métadonnées aux appareils et recevoir l’état de la mise à jour de la part des appareils.
L’autre modèle pris en charge est dtmi:azure:iot:deviceUpdateModel;3, qui étend le modèle deviceUpdateContractModel;3 et utilise également d’autres interfaces PnP qui envoient des propriétés et des informations sur l’appareil et activent des fonctions de diagnostic. En savoir plus sur les [versions des modèles et interfaces de mises à jour d’appareil] (https://github.com/Azure/iot-plugandplay-models/tree/main/dtmi/azure/iot).
L’agent Device Update utilise le modèle dtmi:azure:iot:deviceUpdateModel;3 qui prend en charge toutes les dernières fonctionnalités de la version 1.1.0. Ce modèle prend en charge la version V5 du manifeste. Les manifestes plus anciens fonctionneront avec les agents les plus récents, mais les nouvelles fonctionnalités requièrent l’utilisation de la dernière version du manifeste.
Métadonnées de l’agent
L’agent Device Update utilise les champs de métadonnées de l’agent pour envoyer des informations aux services Device Update.
| Nom | schéma | Sens | Description | Exemple |
|---|---|---|---|---|
| deviceProperties | Mappage | appareil à cloud | Ensemble de propriétés incluant le fabricant, le modèle et d’autres informations sur l’appareil. | Pour plus d’informations, consultez la section Propriétés de l’appareil. |
| compatPropertyNames | Chaîne (valeurs séparées par des virgules) | appareil à cloud | Propriétés indiquées par l’appareil, utilisées pour vérifier la compatibilité de l’appareil afin de cibler le déploiement des mises à jour. Limitées à cinq propriétés d’appareil. | "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Mappage | appareil à cloud | Résultat indiqué par l’agent. Il contient le code de résultat, le code de résultat étendu et les détails du résultat de la mise à jour principale et des autres mises à jour par étapes. | |
| resultCode | entier | appareil à cloud | Code qui contient des informations sur le résultat de la dernière action de mise à jour. Peut être renseigné pour la réussite ou l’échec. | 700 |
| extendedResultCode | entier | appareil à cloud | Code qui contient des informations supplémentaires sur le résultat. Peut être renseigné pour la réussite ou l’échec. | 0x80004005 |
| resultDetails | string | appareil à cloud | Chaîne de forme libre définie par le client pour fournir des détails supplémentaires sur le résultat. Retournée au jumeau sans analyse. | |
| stepResults | carte | appareil à cloud | Résultat indiqué par l’agent incluant le code de résultat, le code de résultat étendu et les détails du résultat des mises à jour par étapes. | "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| state | entier | appareil à cloud | Un entier indiquant l’état actuel de l’agent Device Update. | Consultez la section État pour plus d’informations. |
| flux de travail | complex | appareil à cloud | Un ensemble de valeurs indiquant sur quel déploiement l’agent travaille actuellement, l’ID du déploiement actuel et les informations confirmant toute demande de nouvelle tentative envoyée à l’agent par le service. Notez que l’ID de workflow indique une valeur « nodeployment » une fois le déploiement annulé. | "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"} |
| installedUpdateId | string | appareil à cloud | ID de la mise à jour actuellement installée (via Device Update). Cette valeur est une chaîne qui capture le JSON d’ID de mise à jour ou null pour un appareil qui n’a jamais effectué une mise à jour via Device Update. | installedUpdateID{"provider":"contoso","name":"image-update","version":"1.0.0"}" |
Propriétés d’appareil
Le champ deviceProperties contient les informations de fabricant et de modèle d’un appareil.
| Nom | schéma | Sens | Description |
|---|---|---|---|
| manufacturer | string | appareil à cloud | Fabricant d’appareil de l’appareil, signalé par deviceProperties. Cette propriété est lue à partir de l’un ou de l’autre emplacement - l’interface DeviceUpdateCore tente d’abord de lire la valeur « aduc_manufacturer » à partir du fichier de configuration. Si cette valeur n’est pas renseignée dans le fichier de configuration, elle signalera par défaut la définition de ADUC_DEVICEPROPERTIES_MANUFACTURER au moment de la compilation. Cette propriété est signalée uniquement au moment du démarrage. Valeur par défaut « Contoso ». |
| model | string | appareil à cloud | Modèle d’appareil de l’appareil, signalé par deviceProperties. Cette propriété est lue à partir de l’un ou de l’autre emplacement - l’interface DeviceUpdateCore tente d’abord de lire la valeur « aduc_model » à partir du fichier de configuration. Si cette valeur n’est pas renseignée dans le fichier de configuration, elle signalera par défaut la définition de ADUC_DEVICEPROPERTIES_MODEL au moment de la compilation. Cette propriété est signalée uniquement au moment du démarrage. Valeur par défaut : « Video » |
| contractModelId | string | appareil à cloud | Cette propriété est utilisée par le service pour identifier la version du modèle de base utilisée par l’agent Device Update pour gérer et communiquer avec l’agent. Valeur : « dtmi:azure:iot:deviceUpdateContractModel;3 » pour les appareils qui utilisent la version 1.1.0 de l’agent DU. Remarque : Les agents qui utilisent le modèle « dtmi:azure:iot:deviceUpdateModel;2 » doivent indiquer le contractModelId sous la forme « dtmi:azure:iot:deviceUpdateContractModel;3 », car le modèle deviceUpdateModel;3 est une extension du modèle deviceUpdateContractModel;3 |
| aduVer | string | appareil à cloud | Version de l’agent Device Update en cours d’exécution sur l’appareil. Cette valeur est lue à partir de la build seulement si, au moment de la compilation, ENABLE_ADU_TELEMETRY_REPORTING a la valeur 1 (true). Les clients peuvent choisir de refuser la création de rapports de version en définissant cette valeur sur 0 (false). Comment personnaliser les propriétés de l’agent Device Update. |
| doVer | string | appareil à cloud | Version de l’agent d’optimisation de la distribution en cours d’exécution sur l’appareil. La valeur est lue à partir de la build seulement si, au moment de la compilation, ENABLE_ADU_TELEMETRY_REPORTING a la valeur 1 (true). Les clients peuvent choisir de refuser la création de rapports de version en définissant cette valeur sur 0 (false). Comment personnaliser les propriétés de l’agent d’optimisation de la distribution. |
| Propriétés de compatibilité personnalisées | Définis par l'utilisateur | appareil à cloud | Le responsable de l’implémentation peut définir d’autres propriétés d’appareil à utiliser pour le contrôle de compatibilité lors du ciblage du déploiement de la mise à jour. |
Exemple de jumeau d’appareil IoT Hub :
"deviceUpdate": {
"__t": "c",
"agent": {
"deviceProperties": {
"manufacturer": "contoso",
"model": "virtual-vacuum-v1",
"contractModelId": "dtmi:azure:iot:deviceUpdateContractModel;3",
"aduVer": "DU;agent/1.1.0",
},
"compatPropertyNames": "manufacturer,model",
"lastInstallResult": {
"resultCode": 700,
"extendedResultCode": 0,
"resultDetails": "",
"stepResults": {
"step_0": {
"resultCode": 700,
"extendedResultCode": 0,
"resultDetails": ""
}
}
},
"state": 0,
"workflow": {
"action": 3,
"id": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01",
"retryTimestamp": "2022-01-26T11:33:29.9680598Z"
},
"installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"Virtual-Vacuum\",\"version\":\"5.0\"}"
},
Notes
L’appareil ou le module doit ajouter le marqueur {"__t": "c"} pour indiquer que l’élément fait référence à un composant. Pour plus d’informations, consultez les Conventions d’IoT Plug-and-Play.
State
Le champ État indique l’état signalé par l’agent DU (Device Update) après avoir reçu une action du service Device Update. L’état est signalé en réponse à une action (consultez la section Action) envoyée à l’agent Device Update à partir du service Device Update. Pour plus d’informations sur les requêtes qui circulent entre le service Device Update et l’agent Device Update, consultez le flux de travail de vue d’ensemble.
| Nom | Valeur | Description |
|---|---|---|
| Idle | 0 | L’appareil est prêt à recevoir une action du service Device Update. Après une mise à jour réussie, l’état est rétabli à l’état Idle. |
| DeploymentInprogress | 6 | Un déploiement est en cours. |
| Échec | 255 | Une défaillance est survenue au cours de la mise à jour. |
| DownloadSucceeded | 2 | Téléchargement réussi. Cet état est signalé uniquement par les appareils avec une version d’agent 0.7.0 ou antérieure. |
| InstallSucceeded | 4 | Installation réussie. Cet état est signalé uniquement par les appareils avec une version d’agent 0.7.0 ou antérieure. |
Métadonnées de service
Les métadonnées de service contiennent des champs que le service Device Update utilise pour communiquer des actions et des données à l’agent Device Update.
| Nom | schéma | Sens | Description |
|---|---|---|---|
| action | entier | cloud à appareil | Un entier qui correspond à une action que l’agent doit effectuer. Pour plus d’informations, consultez la section Action. |
| updateManifest | string | cloud à appareil | Utilisé pour décrire le contenu d’une mise à jour. Généré à partir du Manifeste d’importation. |
| updateManifestSignature | Objet JSON | cloud à appareil | Signature web JSON (au JWS) avec clés web JSON utilisées pour la vérification de la source. |
| fileUrls | Mappage | cloud à appareil | Mappage de FileID à DownloadUrl. Indique à l’agent quels fichiers télécharger et le hachage à utiliser pour vérifier que les fichiers ont été téléchargés correctement. |
Action
Le champ action représente les actions effectuées par l’agent Device Update selon les instructions données par le service Device Update. L’agent Device Update signale un état pour le traitement de l’action reçue. Pour plus d’informations sur les requêtes qui circulent entre le service Device Update et l’agent Device Update, consultez le flux de travail de vue d’ensemble.
| Nom | Valeur | Description |
|---|---|---|
| applyDeployment | 3 | Appliquer la mise à jour. Cette action indique à l’appareil qu’il doit appliquer la mise à jour déployée. |
| annuler | 255 | Arrêtez le traitement de l’action actuelle et revenez à Idle, ou indiquez à un agent dans l’état Failed de revenir à Idle. |
| télécharger | 0 | Télécharger le contenu publié ou la mise à jour ainsi que tout autre contenu requis. Cette action est envoyée uniquement aux appareils avec une version d’agent 0.7.0 ou antérieure. |
| installer | 1 | Installez le contenu ou la mise à jour. En général, cette action a pour but d’appeler le programme d’installation pour le contenu ou la mise à jour. Cette action est envoyée uniquement aux appareils avec une version d’agent 0.7.0 ou antérieure. |
| apply | 2 | Finalisez la mise à jour. Cela signale au système de redémarrer si nécessaire. Cette action est envoyée uniquement aux appareils avec une version d’agent 0.7.0 ou antérieure. |
Interface d’informations sur l’appareil
L’interface d’informations sur l’appareil est un concept utilisé dans l’architecture IoT Plug-and-Play. Elle contient des propriétés d’appareil vers le cloud qui fournissent des informations sur le matériel et le système d’exploitation de l’appareil. Device Update for IoT Hub utilise les propriétés DeviceInformation.manufacturer et DeviceInformation.model pour la télémétrie et les diagnostics. Pour plus d’informations, consultez cet exemple d’interface d’informations sur l’appareil.
Le nom de composant attendu dans votre modèle est deviceInformation quand cette interface est implémentée. Découvrir les composants Azure IoT Plug-and-Play
| Name | Type | schéma | Sens | Description | Exemple |
|---|---|---|---|---|---|
| manufacturer | Propriété | string | appareil à cloud | Nom de l’entreprise du fabricant de l’appareil. Cette propriété peut correspondre au nom du fabricant OEM (Original Equipment Manufacturer). | Contoso |
| model | Propriété | string | appareil à cloud | ID ou nom du modèle d’appareil. | Appareil IoT Edge |
| swVersion | Propriété | string | appareil à cloud | Version du logiciel sur votre appareil. swVersion peut être la version de votre microprogramme. | 4.15.0-122 |
| osName | Propriété | string | appareil à cloud | Nom du système d’exploitation sur l’appareil. | Ubuntu Server 18.04 |
| processorArchitecture | Propriété | string | appareil à cloud | Architecture du processeur sur l’appareil. | ARM64 |
| processorManufacturer | Propriété | string | appareil à cloud | Nom du fabricant du processeur sur l’appareil. | Microsoft |
| totalStorage | Propriété | string | appareil à cloud | Stockage total disponible sur l’appareil, en kilo-octets. | 2 048 |
| totalMemory | Propriété | string | appareil à cloud | Quantité totale de mémoire disponible sur l’appareil, en kilo-octets. | 256 |