IoT Plug-and-Play dans Azure Device Update pour IoT Hub
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. Cet article décrit comment le service Device Update envoie à des appareils et reçoit de ceux-ci des propriétés et des messages à l’aide d’interfaces IoT Plug-and-Play.
Pour plus d’informations, consultez le Guide du développeur d’appareils IoT Plug-and-Play et Comment créer l’agent Device Update.
Modèles Device Update
Les smart devices utilisent des ID de modèle IoT Plug-and-Play pour publier leurs fonctionnalités auprès d’applications Azure IoT. Device Update exige que le smart device IoT Plug-and-Play annonce un ID de modèle dans le cadre de la connexion de l’appareil. Pour plus d’informations, consultez Annonce de l’ID de modèle.
Device Update offre plusieurs modèles IoT Plug-and-Play définis qui prennent en charge les fonctionnalités de Device Update. Le modèle Device Update **dtmi:azure:iot:deviceUpdateContractModel;3** prend en charge les fonctionnalités de base de Device Update et utilise l’interface de base de Device Update pour envoyer des métadonnées et des actions de mise à jour aux appareils et recevoir de ces derniers l’état des mises à jour.
L’autre modèle pris en charge est **dtmi:azure:iot:deviceUpdateModel;3**, qui étend **deviceUpdateContractModel;3** et utilise également des interfaces IoT Plug-and-Play qui envoient des informations sur les propriétés des appareils et activent des fonctionnalités de diagnostic. Pour ces versions et d’autres, consultez Modèles Device Update Azure IoT Plug-and-Play.
L’agent Device Update utilise **dtmi:azure:iot:deviceUpdateModel;3** qui prend en charge toutes les dernières fonctionnalités de la version 1.1.0 de Device Update. Ce modèle prend en charge la version 5.0 du manifeste d’importation. Les manifestes plus anciens fonctionnent avec les derniers agents, mais les nouvelles fonctionnalités nécessitent la dernière version du manifeste.
Métadonnées de l’agent
L’agent Device Update utilise les champs de métadonnées d’agent suivants pour envoyer des informations aux services Device Update.
| Nom | schéma | Sens | Description |
|---|---|---|---|
| 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 Propriétés de l’appareil. |
| compatPropertyNames | Chaîne (valeurs séparées par des virgules) | appareil à cloud | Jusqu’à cinq propriétés utilisées pour vérifier la compatibilité de l’appareil afin de cibler le déploiement de la mise à jour. Exemple : "compatPropertyNames": "manufacturer,model" |
| lastInstallResult | Mappage | appareil à cloud | Résultat signalé par l’agent contenant le code résultat, le code résultat étendu et les détails du résultat pour la mise à jour principale et les 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. Exemple : 700 |
| extendedResultCode | entier | appareil à cloud | Code contenant plus d’informations sur le résultat. Peut être renseigné pour la réussite ou l’échec. Exemple : 0x80004005 |
| resultDetails | string | appareil à cloud | Chaîne de forme libre fournie par l’utilisateur pour détailler davantage les résultats. Retournée au jumeau sans analyse. |
| stepResults | carte | appareil à cloud | Résultat signalé par l’agent contenant le code résultat, le code résultat étendu et les détails du résultat pour les mises à jour par étapes. Exemple : "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""} |
| state | entier | appareil à cloud | Un entier indiquant l’état actuel de l’agent Device Update. Pour plus d’informations, consultez État. |
| workflow | complex | appareil à cloud | Ensemble de valeurs indiquant sur quel déploiement l’agent travaille actuellement, l’ID du déploiement actuellement installé et la reconnaissance de toute demande de nouvelle tentative envoyée à l’agent par le service. L’ID workflow signale une valeur "nodeployment" une fois qu’un déploiement est annulé. Exemple : "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"} |
| installedUpdateId | string | appareil à cloud | ID du déploiement Device Update actuellement installé. Cette valeur capture le JSON de l’ID de la mise à jour ou null pour un appareil qui n’a jamais reçu de mise à jour via Device Update. Exemple : "installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}" |
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.
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.L’interface DeviceUpdateCore tente d’abord de lire la valeur aduc_manufacturer à partir du fichier de configuration. Si la valeur n’est pas renseignée dans le fichier de configuration, l’interface signale 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' |
| modèle | string | appareil à cloud | Modèle d’appareil de l’appareil, signalé par deviceProperties. L’interface DeviceUpdateCore tente d’abord de lire la valeur aduc_model à partir du fichier de configuration. Si la valeur n’est pas renseignée dans le fichier de configuration, l’interface signale 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 | Propriété utilisée par le service pour identifier la version du modèle de base dont se sert l’agent Device Update pour gérer et communiquer avec l’agent. Valeur : dtmi:azure:iot:deviceUpdateContractModel;3 pour les appareils utilisant l’agent Device Update version 1.1.0. Remarque : les agents utilisant dtmi:azure:iot:deviceUpdateModel;2 doivent signaler contractModelId en tant que dtmi:azure:iot:deviceUpdateContractModel;3, car deviceUpdateModel;3 est une extension de 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 uniquement si ENABLE_ADU_TELEMETRY_REPORTING est défini sur 1 (true) au moment de la compilation. Vous pouvez choisir de refuser la création de rapports de version en définissant la valeur sur 0 (false). Pour plus d’informations, consultez Comment créer 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 uniquement si ENABLE_ADU_TELEMETRY_REPORTING est défini sur 1 (true) au moment de la compilation. Vous pouvez choisir de refuser la création de rapports de version en définissant la valeur sur 0 (false). Pour plus d’informations, consultez Comment personnaliser les propriétés de l’agent Optimisation de la distribution. |
| Propriétés de compatibilité personnalisées | Défini par l’utilisateur | appareil à cloud | Autres propriétés d’appareil définies par l’utilisateur à utiliser pour la vérification de la compatibilité lors du ciblage du déploiement de la mise à jour. |
État
Le champ state correspond à l’état signalé par l’agent Device Update en réponse à une 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 workflow de l’agent.
| 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 revient à 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 | Un téléchargement a réussi. Seuls les appareils disposant de la version 0.7.0 ou antérieure de l’agent signalent cet état. |
| InstallSucceeded | 4 | Une installation a réussi. Seuls les appareils disposant de la version 0.7.0 ou antérieure de l’agent signalent cet état. |
Action
Le champ action représente l’action que l’agent Device Update doit effectuer conformément aux instructions du service Device Update. L’agent Device Update signale un état (state) pour le traitement de l’action qu’il reçoit. Pour plus d’informations sur les requêtes qui circulent entre le service Device Update et l’agent Device Update, consultez le workflow de l’agent.
| Nom | Valeur | Description |
|---|---|---|
| applyDeployment | 3 | Appliquer la mise à jour déployée. |
| cancel | 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 disposant de la version 0.7.0 ou antérieure de l’agent. |
| install | 1 | Installer le contenu ou la mise à jour, généralement pour appeler le programme d’installation du contenu ou de la mise à jour. Device Update envoie cette action uniquement aux appareils disposant de la version 0.7.0 ou antérieure de l’agent. |
| apply | 2 | Finaliser la mise à jour en redémarrant si nécessaire. Device Update envoie cette action uniquement aux appareils disposant de la version 0.7.0 ou antérieure de l’agent. |
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 Action. |
| updateManifest | string | cloud à appareil | Décrit le contenu d’une mise à jour. Généré à partir du Manifeste d’importation. |
| updateManifestSignature | Objet JSON | cloud à appareil | Signature web JSON (JWS) avec des clés web JSON à utiliser pour la vérification de la source. |
| fileUrls | Mappage | cloud à appareil | Mappage de FileID à DownloadUrl. Indique à l’agent les fichiers à télécharger et le hachage à utiliser pour vérifier que les fichiers ont été téléchargés correctement. |
Interface d’informations sur l’appareil
L’interface d’informations sur l’appareil est un concept utilisé dans l’architecture IoT Plug-and-Play. L’interface contient des propriétés appareil-à-cloud qui fournissent des informations sur le matériel et le système d’exploitation de l’appareil. Device Update utilise les propriétés DeviceInformation.manufacturer et DeviceInformation.model pour la télémétrie et les diagnostics. Pour obtenir un exemple d’interface d’informations sur l’appareil, consultez https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json.
Quand vous implémentez cette interface, le nom du composant attendu dans votre modèle est deviceInformation. Pour plus d’informations, consultez le Guide de modélisation d’IoT Plug-and-Play.
| Nom | Type | schéma | Sens | Description | Exemple |
|---|---|---|---|---|---|
| manufacturer | Propriété | string | appareil à cloud | Nom de l’entreprise du fabricant de l’appareil. Le fabricant peut avoir le même nom que le fabricant d’ordinateurs (OEM). | 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 |