Utiliser les modèles IoT Plug-and-Play dans une solution IoT

Article
03/30/2024

Cet article explique comment, dans une solution IoT, vous pouvez identifier l’ID de modèle d’un appareil IoT Plug-and-Play, puis récupérer sa définition de modèle.

Il existe deux grandes catégories de solutions IoT :

Une solution spécialisée fonctionne avec un ensemble connu de modèles pour les appareils IoT Plug-and-Play qui se connecteront à la solution. Vous utilisez ces modèles lorsque vous développez la solution.
Une solution pilotée par modèle peut fonctionner avec le modèle de n’importe quel appareil IoT Plug-and-Play. La création d’une solution pilotée par modèle est plus complexe, mais ce type de solution présente l’avantage de fonctionner avec tous les appareils susceptibles d’être ajoutés à l’avenir. Une solution IoT pilotée par modèle récupère un modèle et l’utilise pour déterminer les données de télémétrie, les propriétés et les commandes implémentées par l’appareil.

Pour utiliser un modèle IoT Plug-and-Play, une solution IoT :

Identifie l’ID de modèle du modèle implémenté par l’appareil IoT Plug-and-Play, module ou module IoT Edge connecté à la solution.
Utilise cet ID de modèle pour récupérer la définition de modèle de l’appareil connecté à partir d’un référentiel de modèles ou d’un magasin personnalisé.

Identifier l’ID de modèle

Lorsqu’un appareil IoT Plug-and-Play se connecte à IoT Hub, il inscrit l’ID de modèle du modèle qu’il implémente avec IoT Hub.

IoT Hub notifie la solution avec l’ID de modèle d’appareil dans le cadre du processus de connexion de l’appareil.

Une solution peut obtenir l’ID de modèle de l’appareil IoT Plug-and-Play à l’aide de l’une des trois méthodes suivantes :

API Obtenir un jumeau d’appareil

La solution peut utiliser l’API Obtenir un jumeau d’appareil pour récupérer l’ID de modèle de l’appareil IoT Plug-and-Play.

Conseil

Pour les modules et les modules IoT Edge, utilisez ModuleClient. getTwin.

Dans l’extrait de code suivant de réponse de jumeau d’appareil, modelId contient l’ID de modèle d’un appareil IoT Plug-and-Play :

{
    "deviceId": "sample-device",
    "etag": "AAAAAAAAAAc=",
    "deviceEtag": "NTk0ODUyODgx",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00Z",
    "connectionState": "Disconnected",
    "lastActivityTime": "2020-07-17T06:12:26.8402249Z",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "modelId": "dtmi:com:example:TemperatureController;1",
    "version": 15,
    "properties": {...}
    }
}

API Obtenir le jumeau numérique

La solution peut utiliser l’API Obtenir le jumeau numérique pour récupérer l’ID de modèle du modèle implémenté par l’appareil IoT Plug-and-Play.

Dans l’extrait de code suivant de réponse de jumeau numérique, $metadata.$model contient l’ID de modèle d’un appareil IoT Plug-and-Play :

{
    "$dtId": "sample-device",
    "$metadata": {
        "$model": "dtmi:com:example:TemperatureController;1",
        "serialNumber": {
            "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
        }
    }
}

Notification d’événement de changement du jumeau numérique

Une connexion d’appareil génère une notification Événement de changement du jumeau numérique. Une solution doit s’abonner à cette notification d’événement. Pour savoir comment activer l’acheminement des événements des jumeaux numériques, consultez Envoi de messages appareil-à-cloud à différents points de terminaison à l’aide de l’acheminement des messages IoT Hub.

La solution peut utiliser l’événement illustré dans l’extrait de code suivant pour en savoir plus sur l’appareil IoT Plug-and-Play qui se connecte et obtenir son ID de modèle :

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/22/2020 8:02:27 PM
iothub-message-source:digitalTwinChangeEvents
correlation-id:100f322dc2c5
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:com:example:TemperatureController;1"
  }
]

Récupérer une définition de modèle

Une solution utilise l’ID de modèle identifié ci-dessus pour récupérer la définition de modèle correspondante.

Une solution peut obtenir la définition de modèle en utilisant l’une des options suivantes :

Référentiel de modèles

Des solutions peuvent récupérer des modèles DTDL à partir du référentiel de modèles d’appareil (DMR). Le DMR est un référentiel public, hébergé par Microsoft, qui contient une collection de modèles DTDL organisés. Tous les utilisateurs peuvent accéder aux modèles d’appareil publics stockés dans le DMR pour les utiliser et les intégrer à leurs applications à partir du point de terminaison public https://devicemodels.azure.com.

Une fois que vous avez identifié l’ID de modèle pour une nouvelle connexion d’appareil, procédez comme suit :

Récupérez la définition de modèle à l’aide de l’ID de modèle à partir du référentiel de modèles. Pour découvrir plus d’informations, consultez Résoudre des modèles.
Avec la définition de modèle de l’appareil connecté, vous pouvez énumérer les fonctionnalités de l’appareil.
Avec les fonctionnalités énumérées de l’appareil, vous pouvez autoriser les utilisateurs à interagir avec l’appareil.

Résoudre des modèles

Les conventions de DMR incluent d’autres artefacts pour simplifier la consommation des modèles hébergés. Ces fonctionnalités sont facultatives pour les référentiels personnalisés ou privés.

Index. Tous les DTMI disponibles sont exposés via un index composé d’une séquence de fichiers JSON, par exemple : https://devicemodels.azure.com/index.page.2.json
Développé. Un fichier avec toutes les dépendances est disponible pour chaque interface, par exemple : https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
Métadonnées. Ce fichier expose les attributs clés d’un référentiel, et est actualisé régulièrement à l’aide du dernier instantané des modèles publiés. Il comprend des fonctionnalités qu’un référentiel implémente, par exemple si l’index de modèle ou les fichiers de modèle développés sont disponibles. Vous pouvez accéder aux métadonnées DMR à l’adresse https://devicemodels.azure.com/metadata.json

Pour accéder par programme aux modèles DTDL dans le DMR, vous pouvez utiliser le ModelsRepositoryClient disponible dans le package NuGet Azure.IoT.ModelsRepository. Ce client est configuré par défaut pour interroger le DMR public disponible sur devicemodels.azure.com et peut être configuré sur n’importe quel référentiel personnalisé.

Le client accepte un DTMI comme entrée et retourne un dictionnaire avec toutes les interfaces requises :

using Azure.IoT.ModelsRepository;

var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

La sortie attendue doit afficher le DTMI des trois interfaces trouvées dans la chaîne de dépendance :

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

Le ModelsRepositoryClient peut être configuré pour interroger un DMR personnalisé, disponible via HTTP(S), et pour spécifier la résolution de dépendance en utilisant le drapeau ModelDependencyResolution :

Désactivé. Retourne l’interface spécifiée uniquement, sans aucune dépendance.
Activé. Retourne toutes les interfaces dans la chaîne de dépendance

Conseil

Les dépôts personnalisés peuvent ne pas exposer le fichier .expanded.json. Lorsque ce fichier n’est pas disponible, le client est de secours pour traiter chaque dépendance localement.

L’exemple de code suivant montre comment initialiser le ModelsRepositoryClient en utilisant une URL de base de référentiel personnalisé, en utilisant dans ce cas les URL raw de l’API GitHub sans utiliser le formulaire expanded, car il n’est pas disponible dans le point de terminaison raw. Le AzureEventSourceListener est initialisé pour inspecter la requête HTTP effectuée par le client :

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

var client = new ModelsRepositoryClient(
    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));

ModelResult model = await client.GetModelAsync(
    "dtmi:com:example:TemperatureController;1", 
    dependencyResolution: ModelDependencyResolution.Enabled);

model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

D’autres exemples sont disponibles dans le référentiel GitHub du Kit de développement logiciel (SDK) Azure : Azure.Iot.ModelsRepository/samples.

Magasin personnalisé

Les solutions peuvent stocker ces définitions de modèle dans un système de fichiers local ou un magasin de fichiers public, ou encore utiliser une implémentation personnalisée.