Guide de modélisation d’IoT Plug-and-Play
Au cœur d’IoT Plug-and-Play se trouve un modèle d’appareil qui décrit les capacités d’un appareil à une application IoT Plug-and-Play. Ce modèle est structuré sous la forme d’un ensemble d’interfaces qui définissent ce qui suit :
- Propriétés qui représentent l’état en lecture seule ou en écriture d’un appareil ou d’une autre entité. Par exemple, un numéro de série d’appareil peut être une propriété en lecture seule et une température cible sur un thermostat peut être une propriété en écriture.
- Les champs Télémétrie définissent les données émises par un appareil, qu’il s’agisse d’un flux régulier de relevés de capteurs, d’une erreur occasionnelle ou d’un message d’information.
- Commandes qui décrivent une fonction ou une opération qui peut être effectuée sur un appareil. Par exemple, une commande peut redémarrer une passerelle ou prendre une photo à l’aide d’une caméra distante.
Pour en savoir plus sur la façon dont IoT Plug-and-Play utilise les modèles d’appareils, consultez le Guide du développeur de l'appareil IoT Plug-and-Play et le Guide du développeur du service IoT Plug-and-Play.
Pour définir un modèle, vous utilisez le langage DTDL (Digital Twins Definition Language). DTDL utilise une variante JSON nommée JSON-LD. L’extrait suivant montre le modèle pour un appareil à thermostat qui :
- A un ID de modèle unique :
dtmi:com:example:Thermostat;1. - Envoie des données de télémétrie de température.
- A une propriété accessible en écriture pour définir la température cible.
- A une propriété en lecture seule pour indiquer la température maximale depuis le dernier redémarrage.
- Répond à une commande qui demande des températures maximale, minimale et moyenne sur une période.
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:Thermostat;1",
"@type": "Interface",
"displayName": "Thermostat",
"description": "Reports current temperature and provides desired temperature control.",
"contents": [
{
"@type": [
"Telemetry",
"Temperature"
],
"name": "temperature",
"displayName": "Temperature",
"description": "Temperature in degrees Celsius.",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": [
"Property",
"Temperature"
],
"name": "targetTemperature",
"schema": "double",
"displayName": "Target Temperature",
"description": "Allows to remotely specify the desired target temperature.",
"unit": "degreeCelsius",
"writable": true
},
{
"@type": [
"Property",
"Temperature"
],
"name": "maxTempSinceLastReboot",
"schema": "double",
"unit": "degreeCelsius",
"displayName": "Max temperature since last reboot.",
"description": "Returns the max temperature since last device reboot."
},
{
"@type": "Command",
"name": "getMaxMinReport",
"displayName": "Get Max-Min report.",
"description": "This command returns the max, min and average temperature from the specified time to the current time.",
"request": {
"name": "since",
"displayName": "Since",
"description": "Period to return the max-min report.",
"schema": "dateTime"
},
"response": {
"name": "tempReport",
"displayName": "Temperature Report",
"schema": {
"@type": "Object",
"fields": [
{
"name": "maxTemp",
"displayName": "Max temperature",
"schema": "double"
},
{
"name": "minTemp",
"displayName": "Min temperature",
"schema": "double"
},
{
"name": "avgTemp",
"displayName": "Average Temperature",
"schema": "double"
},
{
"name": "startTime",
"displayName": "Start Time",
"schema": "dateTime"
},
{
"name": "endTime",
"displayName": "End Time",
"schema": "dateTime"
}
]
}
}
}
]
}
Le modèle de thermostat a une interface unique. Les exemples ultérieurs dans cet article montrent des modèles plus complexes qui utilisent des composants et l’héritage.
Cet article explique comment concevoir et créer vos propres modèles et couvre des sujets tels que les types de données, la structure du modèle et les outils.
Pour en savoir plus, consultez la spécification Digital Twins Definition Language.
Remarque
IoT Central prend actuellement en charge DTDL v2 avec une extension IoT Central.
Structure du modèle
Les propriétés, les données de télémétrie et les commandes sont regroupées dans des interfaces. Cette section décrit comment vous pouvez utiliser des interfaces pour décrire des modèles simples et complexes à l’aide de composants et de l’héritage.
ID de modèle
Chaque interface possède un identificateur de modèle de jumeau numérique (DTMI) unique. Les modèles complexes utilisent des DTMI pour identifier des composants. Les applications peuvent utiliser les DTMI que les appareils envoient pour localiser des définitions de modèle dans un référentiel.
Les DTMIs doivent utiliser la convention d’affectation de noms suivante :
- Le préfixe DTMI est
dtmi:. - Le suffixe DTMI est le numéro de version du modèle, par exemple
;2. - Le corps du DTMI est mappé au dossier et au fichier dans le référentiel de modèles où le modèle est stocké. Le numéro de version fait partie du nom de fichier.
Par exemple, le modèle identifié par le DTMI dtmi:com:Example:Thermostat;2 est stocké dans le fichier dtmi/com/example/thermostat-2.json.
L’extrait de code suivant montre le plan d’une définition d’interface avec son DTMI unique :
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:Thermostat;2",
"@type": "Interface",
"displayName": "Thermostat",
"description": "Reports current temperature and provides desired temperature control.",
"contents": [
...
]
}
Aucun composant
Un modèle simple, tel que le thermostat présenté précédemment, n’utilise pas de composants incorporés ou en cascade. Les données de télémétrie, les propriétés et les commandes sont définies dans le nœud contents de l’interface.
L’exemple suivant montre une partie d’un modèle simple qui n’utilise pas de composants :
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:Thermostat;1",
"@type": "Interface",
"displayName": "Thermostat",
"description": "Reports current temperature and provides desired temperature control.",
"contents": [
{
"@type": [
"Telemetry",
"Temperature"
],
"name": "temperature",
"displayName": "Temperature",
"description": "Temperature in degrees Celsius.",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": [
"Property",
...
Des outils, tels que l’Explorateur Azure IoT et le concepteur de modèles d’appareils IoT Central étiquettent une interface autonome comme le thermostat en tant que composant par défaut.
La capture d’écran suivante montre la façon dont le modèle s’affiche dans l’outil Explorateur Azure IoT :
La capture d’écran suivante montre comment le modèle s’affiche en tant que composant par défaut dans le concepteur de modèles d’appareils IoT Central. Sélectionnez Afficher l’identité pour afficher le DTMI du modèle :
L’ID de modèle est stocké dans une propriété de jumeau d’appareil, comme le montre la capture d’écran suivante :
Un modèle DTDL sans composants est une simplification utile pour un appareil ou un module IoT Edge doté d’un ensemble de données de télémétrie, de propriétés et de commandes unique. Un modèle qui n’utilise pas de composants facilite la migration d’un appareil ou module existant en appareil IoT Plug-and-Play : vous créez un modèle DTDL qui décrit votre appareil ou module réel sans avoir à définir de composants.
Conseil
Un module peut être un module d’appareil ou un module IoT Edge.
Réutiliser
Deux méthodes permettent de réutiliser les définitions d’interface.
- Utilisez plusieurs composants dans un modèle pour référencer d’autres définitions d’interface.
- Utilisez l’héritage pour étendre les définitions d’interface existantes.
Plusieurs composants
Les composants vous permettent de créer une interface de modèle qui représente un assemblage d’autres interfaces.
Par exemple, l’interface Thermostat est définie comme modèle. Vous pouvez incorporer cette interface comme un ou plusieurs composants lorsque vous définissez le modèle Contrôleur de température. Dans l’exemple suivant, ces composants sont appelés thermostat1 et thermostat2.
Pour un modèle DTDL avec plusieurs composants, il y a deux ou plusieurs sections de composants. Chaque section a @type défini sur Component et fait explicitement référence à un schéma, comme indiqué dans l’extrait de code suivant :
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:TemperatureController;1",
"@type": "Interface",
"displayName": "Temperature Controller",
"description": "Device with two thermostats and remote reboot.",
"contents": [
{
"@type": [
"Telemetry",
"DataSize"
],
"name": "workingSet",
"displayName": "Working Set",
"description": "Current working set of the device memory in KiB.",
"schema": "double",
"unit": "kibibyte"
},
{
"@type": "Property",
"name": "serialNumber",
"displayName": "Serial Number",
"description": "Serial number of the device.",
"schema": "string"
},
{
"@type": "Command",
"name": "reboot",
"displayName": "Reboot",
"description": "Reboots the device after waiting the number of seconds specified.",
"request": {
"name": "delay",
"displayName": "Delay",
"description": "Number of seconds to wait before rebooting the device.",
"schema": "integer"
}
},
{
"@type" : "Component",
"schema": "dtmi:com:example:Thermostat;1",
"name": "thermostat1",
"displayName": "Thermostat One",
"description": "Thermostat One of Two."
},
{
"@type" : "Component",
"schema": "dtmi:com:example:Thermostat;1",
"name": "thermostat2",
"displayName": "Thermostat Two",
"description": "Thermostat Two of Two."
},
{
"@type": "Component",
"schema": "dtmi:azure:DeviceManagement:DeviceInformation;1",
"name": "deviceInformation",
"displayName": "Device Information interface",
"description": "Optional interface with basic device hardware information."
}
]
}
Ce modèle a trois composants définis dans la section de contenu : deux composants Thermostat et un composant DeviceInformation. La section de contenu comprend également les définitions de propriété, de télémétrie et de commande.
Les captures d’écran suivantes montrent comment ce modèle apparaît dans IoT Central. Les définitions de propriété, de télémétrie et de commande dans le contrôleur de température apparaissent dans le Composant par défaut de niveau supérieur. Les définitions de propriété, de télémétrie et de commande de chaque thermostat apparaissent dans les définitions de composant :
Pour savoir comment écrire le code de l’appareil qui interagit avec les composants, consultez le Guide du développeur d’appareils IoT Plug-and-Play.
Pour savoir comment écrire le code de service qui interagit avec des composants sur un appareil, consultez le Guide du développeur du service IoT Plug-and-Play.
Héritage
L’héritage vous permet de réutiliser des fonctionnalités dans des interfaces de base afin d’étendre les fonctionnalités d’une interface. Par exemple, plusieurs modèles d’appareils peuvent partager des fonctionnalités communes comme un numéro de série :
L’extrait de code suivant montre un modèle DTML qui utilise le mot clé extends pour définir la relation d’héritage présentée dans le diagramme précédent :
[
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:Thermostat;1",
"@type": "Interface",
"contents": [
{
"@type": "Telemetry",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": "Property",
"name": "targetTemperature",
"schema": "double",
"unit": "degreeCelsius",
"writable": true
}
],
"extends": [
"dtmi:com:example:baseDevice;1"
]
},
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:baseDevice;1",
"@type": "Interface",
"contents": [
{
"@type": "Property",
"name": "SerialNumber",
"schema": "double",
"writable": false
}
]
}
]
La capture d’écran suivante montre ce modèle dans l’environnement de modèle d’appareil IoT Central :
Lorsque vous écrivez du code d’appareil ou côté service, votre code n’a rien à faire de spécial pour gérer les interfaces héritées. Dans l’exemple présenté dans cette section, le code de votre appareil signale le numéro de série comme s’il faisait partie de l’interface de thermostat.
Conseils
Vous pouvez combiner des composants et l’héritage lorsque vous créez un modèle. Le diagramme suivant illustre un modèle thermostat qui hérite d’une interface baseDevice. L'interface baseDevice possède un composant, qui hérite lui-même d’une autre interface :
L’extrait de code suivant montre un modèle DTML qui utilise les mots clés extends et component pour définir la relation d’héritage et l’utilisation de composant présentées dans le diagramme précédent :
[
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:Thermostat;1",
"@type": "Interface",
"contents": [
{
"@type": "Telemetry",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
},
{
"@type": "Property",
"name": "targetTemperature",
"schema": "double",
"unit": "degreeCelsius",
"writable": true
}
],
"extends": [
"dtmi:com:example:baseDevice;1"
]
},
{
"@context": "dtmi:dtdl:context;2",
"@id": "dtmi:com:example:baseDevice;1",
"@type": "Interface",
"contents": [
{
"@type": "Property",
"name": "SerialNumber",
"schema": "double",
"writable": false
},
{
"@type" : "Component",
"schema": "dtmi:com:example:baseComponent;1",
"name": "baseComponent"
}
]
}
]
les types de données ;
Utilisez des types de données pour définir des paramètres de données de télémétrie, de propriétés et de commande. Les types de données peuvent être primitifs ou complexes. Les types de données complexes utilisent des primitives ou d’autres types complexes. La profondeur maximale pour les types complexes est de cinq niveaux.
Types primitifs
Le tableau suivant présente l’ensemble de types primitifs que vous pouvez utiliser :
| Type primitif | Description |
|---|---|
boolean |
Une valeur booléenne |
date |
Une date complète telle que définie dans la section 5.6 de la RFC 3339 |
dateTime |
Une date/heure telle que définie dans la RFC 3339 |
double |
Une virgule flottante IEEE sur 8 octets |
duration |
Une durée au format ISO 8601 |
float |
Une virgule flottante IEEE sur 4 octets |
integer |
Un entier signé sur 4 octets |
long |
Un entier signé sur 8 octets |
string |
Une chaîne UTF8 |
time |
Une heure complète telle que définie dans la section 5.6 de la RFC 3339 |
L’extrait de code suivant montre un exemple de définition de télémétrie qui utilise le type double dans le champ schema :
{
"@type": "Telemetry",
"name": "temperature",
"displayName": "Temperature",
"schema": "double"
}
Les types de données complexes
Les types de données complexes sont un tableau, une énumération, un mappage, un objet ou l’un des types géospatiaux.
Tableaux
Un tableau est un type de données indexable dans lequel tous les éléments sont du même type. Le type d’élément peut être primitif ou complexe.
L’extrait de code suivant montre un exemple de définition de télémétrie qui utilise le type Array dans le champ schema. Les éléments du tableau sont des valeurs booléennes :
{
"@type": "Telemetry",
"name": "ledState",
"schema": {
"@type": "Array",
"elementSchema": "boolean"
}
}
Énumérations
Une énumération décrit un type avec un ensemble d’étiquettes nommées qui mappent à des valeurs. Les valeurs peuvent être des entiers ou des chaînes, mais les étiquettes sont toujours des chaînes.
L’extrait de code suivant montre un exemple de définition de télémétrie qui utilise le type Enum dans le champ schema. Les valeurs de l’énumération sont des entiers :
{
"@type": "Telemetry",
"name": "state",
"schema": {
"@type": "Enum",
"valueSchema": "integer",
"enumValues": [
{
"name": "offline",
"displayName": "Offline",
"enumValue": 1
},
{
"name": "online",
"displayName": "Online",
"enumValue": 2
}
]
}
}
Maps
Un mappage est un type avec des paires clé-valeur où les valeurs ont toutes le même type. La clé d’un mappage doit être une chaîne. Les valeurs d’un mappage peuvent être de n’importe quel type, y compris un autre type complexe.
L’extrait de code suivant montre un exemple de définition de propriété qui utilise le type Map dans le champ schema. Les valeurs du mappage sont des chaînes :
{
"@type": "Property",
"name": "modules",
"writable": true,
"schema": {
"@type": "Map",
"mapKey": {
"name": "moduleName",
"schema": "string"
},
"mapValue": {
"name": "moduleState",
"schema": "string"
}
}
}
Objets
Un type d’objet est constitué de champs nommés. Les types des champs d’un mappage d’objets peuvent être primitifs ou complexes.
L’extrait de code suivant montre un exemple de définition de télémétrie qui utilise le type Object dans le champ schema. Les champs de l’objet sont dateTime, duration et string :
{
"@type": "Telemetry",
"name": "monitor",
"schema": {
"@type": "Object",
"fields": [
{
"name": "start",
"schema": "dateTime"
},
{
"name": "interval",
"schema": "duration"
},
{
"name": "status",
"schema": "string"
}
]
}
}
Types géospatiaux
DTDL fournit un ensemble de types géospatiaux, basés sur GeoJSON, pour la modélisation des structures de données géographiques : point, multiPoint, lineString, multiLineString, polygon et multiPolygon. Ces types sont des structures imbriquées prédéfinies de tableaux, d’objets et d’énumérations.
L’extrait de code suivant montre un exemple de définition de télémétrie qui utilise le type point dans le champ schema :
{
"@type": "Telemetry",
"name": "location",
"schema": "point"
}
Étant donné que les types géospatiaux sont basés sur un tableau, ils ne peuvent pas être utilisés actuellement dans des définitions de propriété.
Types de sémantiques
Le type de données d’une définition de propriété ou de télémétrie spécifie le format des données qu’un appareil échange avec un service. Le type de sémantique fournit des informations sur les données de télémétrie et les propriétés qu’une application peut utiliser pour déterminer comment traiter ou afficher une valeur. Une ou plusieurs unités sont associées à chaque type de sémantique. Par exemple, les degrés Celsius et Fahrenheit sont des unités pour le type de sémantique de température. Les tableaux de bord et l’analytique d’IoT Central peuvent utiliser les informations du type de sémantique pour déterminer comment tracer les valeurs de télémétrie ou de propriété et afficher les unités. Pour savoir comment vous pouvez utiliser l’analyseur de modèle pour lire les types de sémantiques, consultez Présentation de l’analyseur de modèle de jumeaux numériques.
L’extrait de code suivant montre un exemple de définition de télémétrie qui comprend des informations sur le type de sémantique. Le type de sémantique Temperature est ajouté au tableau @type, et la valeur de unit, degreeCelsius, est l’une des unités valides pour le type de sémantique :
{
"@type": [
"Telemetry",
"Temperature"
],
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
}
Localisation
Les applications, telles que IoT Central, utilisent les informations du modèle pour créer dynamiquement une interface utilisateur autour des données échangées avec un appareil IoT Plug-and-Play. Par exemple, les vignettes d’un tableau de bord peuvent afficher les noms et les descriptions des données de télémétrie, des propriétés et des commandes.
Les champs description et displayName facultatifs dans le modèle contiennent des chaînes destinées à être utilisées dans une interface utilisateur. Ces champs peuvent contenir des chaînes localisées qu’une application peut utiliser pour afficher une interface utilisateur localisée.
L’extrait de code suivant montre un exemple de définition de télémétrie de température qui comprend des chaînes localisées :
{
"@type": [
"Telemetry",
"Temperature"
],
"description": {
"en": "Temperature in degrees Celsius.",
"it": "Temperatura in gradi Celsius."
},
"displayName": {
"en": "Temperature",
"it": "Temperatura"
},
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
}
L’ajout de chaînes localisées est facultatif. L’exemple suivant n’a qu’une seule langue par défaut :
{
"@type": [
"Telemetry",
"Temperature"
],
"description": "Temperature in degrees Celsius.",
"displayName": "Temperature",
"name": "temperature",
"schema": "double",
"unit": "degreeCelsius"
}
Cycle de vie et outils
Les quatre phases du cycle de vie d’un modèle d’appareil sont la création, la publication, l’utilisation et le contrôle de version :
Auteur
Les modèles d’appareils DTML sont des documents JSON que vous pouvez créer dans un éditeur de texte. Toutefois, dans IoT Central, vous pouvez utiliser l’environnement de l’interface graphique utilisateur du modèle d’appareil pour créer un modèle DTML. Dans IoT Central vous pouvez :
- Créer des interfaces qui définissent des propriétés, des données de télémétrie et des commandes.
- Utiliser des composants pour assembler plusieurs interfaces.
- Définir des relations d’héritage entre les interfaces.
- Importer et exporter des fichiers de modèle DTML.
Pour en savoir plus, consultez Définir un nouveau type d’appareil IoT dans votre application Azure IoT Central.
Il existe une extension de création DTDL pour VS Code.
Pour installer l’extension DTDL pour VS Code, accédez à l’éditeur DTDL pour Visual Studio Code. Vous pouvez également rechercher DTDL dans l’affichage Extensions de VS Code.
Une fois l’extension installée, utilisez-la pour vous aider à créer des fichiers de modèle DTDL dans VS code :
L’extension fournit la validation de la syntaxe dans les fichiers de modèle DTDL, en mettant en surbrillance les erreurs comme indiqué sur la capture d’écran suivante :
Utilisez IntelliSense et l’autocomplétion lorsque vous modifiez des modèles DTDL :
Créez une nouvelle interface DTDL. La commande DTDL : Create Interface crée un fichier JSON avec une nouvelle interface. L’interface comprend des exemples de définitions de télémétrie, de propriété et de commande.
Utiliser
Les applications, telles que IoT Central, utilisent des modèles d’appareils. Dans IoT Central, un modèle fait partie du modèle d’appareil qui décrit les fonctionnalités de l’appareil. IoT Central utilise le modèle d’appareil pour créer dynamiquement une interface utilisateur pour l’appareil, y compris des tableaux de bord et des analyses.
Remarque
IoT Central définit certaines extensions au langage DTDL. Pour plus d’informations, consultez Extension IoT Central.
Une solution personnalisée peut utiliser l'analyseur de modèle de jumeaux numériques pour comprendre les fonctionnalités d’un appareil qui implémente le modèle. Pour en savoir plus, consultez Utiliser les modèles IoT Plug-and-Play dans une solution IoT.
Version
Pour garantir que les appareils et les solutions côté serveur qui utilisent des modèles continuent de fonctionner, les modèles publiés sont non modifiables.
Le DTMI contient un numéro de version que vous pouvez utiliser pour créer plusieurs versions d’un modèle. Les appareils et les solutions côté serveur peuvent utiliser la version spécifique pour lesquels ils ont été conçus.
IoT Central implémente davantage de règles de contrôle de version pour les modèles d’appareils. Si vous contrôlez la version d’un modèle d’appareil et son modèle dans IoT Central, vous pouvez migrer des appareils de versions précédentes vers des versions ultérieures. Toutefois, les appareils migrés ne peuvent pas utiliser les nouvelles fonctionnalités sans une mise à niveau du microprogramme. Pour en savoir plus, consultez Modifier un modèle d’appareil.
Publier
Depuis février 2024, le programme Azure Certified Device a été mis hors service. Par conséquent, Microsoft n’accepte plus les soumissions de modèles DTDL au référentiel de modèles plug and play Azure IoT.
Si vous souhaitez créer votre propre référentiel de modèles, vous pouvez utiliser le référentiel d’outils de modèles plug and play Azure IoT. Ce référentiel inclut le code de l’outil CLI dmr-client qui peut valider, importer et développer des modèles DTDL. Cet outil vous permet également d’indexer les référentiels de modèles qui suivent les conventions de référentiel de modèles d’appareils.
Limites et contraintes
La liste suivante résume certaines contraintes et limites principales sur les modèles :
- La profondeur maximale pour les tableaux, les mappages et les objets est actuellement de cinq niveaux.
- Vous ne pouvez pas utiliser de tableaux dans des définitions de propriété.
- Vous pouvez étendre les interfaces jusqu’à une profondeur de 10 niveaux.
- Une interface peut étendre au maximum deux autres interfaces.
- Un composant ne peut pas contenir un autre composant.
Étapes suivantes
Maintenant que vous avez découvert la modélisation d’appareil, voici quelques ressources supplémentaires :