Que sont les modèles d’appareils ?

Un modèle d’appareil dans Azure IoT Central est un blueprint qui définit les caractéristiques et comportements d’un type d’appareil se connectant à votre application. Par exemple, le modèle d’appareil définit la télémétrie qu’un appareil envoie afin qu’IoT Central puisse créer des visualisations qui utilisent les unités et types de données appropriés.

Un générateur de solutions ajoute des modèles d’appareils à une application IoT Central. Un développeur d’appareils écrit le code d’appareil qui implémente les comportements définis dans le modèle d’appareil. Pour en savoir plus sur les données qu’un appareil échange avec IoT Central, consultez Charges utiles de télémétrie, de propriétés et de commandes.

Un modèle d’appareil comprend les sections suivantes :

  • Un modèle d’appareil. Cette partie du modèle d’appareil définit la manière dont l’appareil interagit avec votre application. Chaque modèle d’appareil possède un ID unique. Un développeur d’appareils implémente les comportements définis dans le modèle.
    • Composant racine. Chaque modèle d’appareil possède un composant racine. L’interface du composant racine décrit les capacités spécifiques au modèle d’appareil.
    • Composants. En plus du composant racine, un modèle d’appareil peut inclure des composants pour décrire les capacités de l’appareil. Chaque composant inclut une interface qui décrit ses fonctionnalités. Les interfaces de composant peuvent être réutilisées dans d’autres modèles d’appareils. Par exemple, plusieurs modèles d’appareil téléphonique peuvent utiliser la même interface de caméra.
    • Interfaces héritées. Un modèle d’appareil contient une ou plusieurs interfaces qui étendent les capacités du composant racine.
  • Affichages. Cette partie du modèle d’appareil permet au développeur de solutions de définir des visualisations pour afficher les données de l’appareil, ainsi que des formulaires pour gérer et contrôler un appareil. Les affichages n’affectent pas le code qu’un développeur d’appareils a écrit pour implémenter le modèle d’appareil.

Affecter un appareil à un modèle d’appareil

Pour qu’un appareil puisse interagir avec IoT Central, il doit être affecté à un modèle d’appareil. Cette affectation peut s’effectuer de quatre manières :

  • Lorsque vous inscrivez un appareil dans la page Appareils, vous pouvez identifier le modèle à utiliser par l’appareil.
  • Quand vous importez en bloc une liste d’appareils, vous pouvez choisir le modèle d’appareil que tous les appareils de la liste devront utiliser.
  • Une fois qu’un appareil non affecté s’est connecté, vous pouvez l’affecter manuellement à un modèle d’appareil.
  • Vous pouvez affecter automatiquement un appareil à un modèle d’appareil en envoyant un ID de modèle au moment où l’appareil se connecte pour la première fois à votre application.

Attribution automatique

IoT Central peut affecter automatiquement un appareil à un modèle d’appareil lors de la connexion de l’appareil. Un appareil doit envoyer un ID de modèle lorsqu’il se connecte. IoT Central utilise l’ID de modèle pour identifier le modèle d’appareil correspondant à ce modèle d’appareil spécifique. Le processus de détection fonctionne comme suit :

  1. Si le modèle d’appareil est déjà publié dans l’application IoT Central, l’appareil est affecté au modèle d’appareil.

  2. Si le modèle d’appareil n’est pas encore publié dans l’application IoT Central, cette dernière le recherche dans le référentiel de modèles public. Si IoT Central trouve le modèle, il l’utilise pour générer un modèle d’appareil de base.

  3. Si IoT Central ne trouve pas le modèle dans le référentiel de modèles public, l’appareil est marqué comme Non affecté. Un opérateur peut :

    • Créez un modèle d’appareil pour l’appareil, puis migrez l’appareil non attribué vers le nouveau modèle d’appareil.
    • Générer automatiquement un modèle d’appareil en fonction des données envoyées par l’appareil.

La capture d’écran suivante montre comment afficher l’ID d’un modèle d’appareil dans IoT Central. Dans un modèle d’appareil, sélectionnez un composant, puis Modifier l’identité :

Screenshot showing model ID in thermostat device template.

Le modèle Thermostat apparaît dans le référentiel de modèles public. La définition de l’ID de modèle se présente ainsi :

"@id": "dtmi:com:example:Thermostat;1"

Utilisez la charge utile DPS suivante pour affecter l’appareil à un modèle d’appareil :

{
  "modelId":"dtmi:com:example:TemperatureController;2"
}

Pour en savoir plus sur la charge utile DPS, consultez l’exemple de code utilisé dans le tutoriel : Créer et connecter une application cliente à votre application Azure IoT Central.

Modèles d’appareils

Un modèle d’appareil définit la manière dont un appareil interagit avec votre application IoT Central. Le développeur de l’appareil doit s’assurer que l’appareil implémente les comportements définis dans le modèle d’appareil afin qu’IoT Central puisse surveiller et gérer l’appareil. Un modèle d’appareil est constitué d’une ou plusieurs interfaces pouvant chacune définir une collection de types de télémétries, des propriétés d’appareil et des commandes. Un développeur de solutions peut :

  • Importez un fichier JSON qui définit un modèle d’appareil complet ou une interface individuelle dans un modèle d’appareil.
  • Utilisez l’interface utilisateur web dans IoT Central pour créer ou modifier un modèle d’appareil.

Remarque

IoT Central accepte toute charge utile JSON valide à partir d’un appareil, mais elle ne peut utiliser les données que pour les visualisations si elle correspond à une définition dans le modèle d’appareil. Pour exporter des données qui ne correspondent pas à une définition, consultez Exporter des données IoT vers des destinations cloud dans le Stockage Blob.

Pour en savoir plus sur la modification d’un modèle d’appareil, consultez Modifier un modèle d’appareil existant

Un développeur de solutions peut également exporter un fichier JSON à partir du modèle d’appareil qui contient un modèle d’appareil complet ou une interface individuelle. Un développeur d’appareils peut utiliser ce document JSON pour comprendre comment l’appareil doit communiquer avec l’application IoT Central.

Le fichier JSON qui définit le modèle d’appareil utilise le langage DTDL (Digital Twin Definition Language) v2. IoT Central s’attend à ce que le fichier JSON contienne le modèle d’appareil avec les interfaces définies incluses plutôt que dans des fichiers distincts. Les modèles créés dans IoT Central ont le contexte dtmi:iotcentral:context;2 défini pour indiquer que le modèle a été créé dans IoT Central :

"@context": [
  "dtmi:iotcentral:context;2",
  "dtmi:dtdl:context;2"
]

Pour en savoir plus sur les modèles DTDL, consultez le guide de modélisation IoT Plug-and-Play.

Remarque

IoT Central définit certaines extensions au langage DTDL v2. Pour en savoir plus, consultez l’extension IoT Central.

Propriétés

Par défaut, les propriétés sont en lecture seule. Les propriétés en lecture seule signifient que l’appareil signale des mises à jour de valeurs de propriété à votre application IoT Central. Votre application IoT Central ne peut pas définir la valeur d’une propriété en lecture seule.

Vous pouvez également marquer une propriété comme étant accessible en écriture sur une interface. Un appareil peut recevoir une mise à jour vers une propriété accessible en écriture à partir de votre application IoT Central et des mises à jour de la valeur de propriété de rapport vers votre application.

Les appareils n’ont pas besoin d’être connectés pour définir des valeurs de propriété. Les valeurs mises à jour sont transférées quand l’appareil se connecte ensuite à l’application. Ce comportement s’applique aux propriétés en lecture seule et accessibles en écriture.

N’utilisez pas de propriétés pour envoyer des données de télémétrie à partir de votre appareil. Par exemple, une propriété en lecture seule telle que temperatureSetting=80 doit signifier que la température de l’appareil a été définie sur 80 et que l’appareil tente d’atteindre cette température ou d’y rester.

Pour les propriétés accessibles en écriture, l’application d’appareil retourne un code d’état, une version et une description de l’état souhaité pour indiquer si elle a reçu et appliqué la valeur de la propriété.

Propriétés cloud

Vous pouvez également ajouter des propriétés cloud au composant racine du modèle. Les propriétés cloud vous permettent de spécifier les métadonnées d’appareil à stocker dans l’application IoT Central. Les valeurs de propriété cloud sont stockées dans l’application IoT Central et ne sont jamais synchronisées avec un appareil. Les propriétés Cloud n’affectent pas le code écrit par un développeur d’appareils pour implémenter le modèle d’appareil.

Un développeur de solutions peut ajouter des propriétés du cloud à des affichages et des formulaires d’appareil, en même temps que des propriétés de l’appareil pour permettre à un opérateur de gérer les appareils connectés à l’application. Un développeur de solutions peut également utiliser des propriétés Cloud dans le cadre d’une définition de règle pour rendre une valeur de seuil modifiable par un opérateur.

L’extrait de code DTDL suivant montre un exemple de définition de propriété cloud :

{
    "@id": "dtmi:azureiot:Thermostat:CustomerName",
    "@type": [
        "Property",
        "Cloud",
        "StringValue"
    ],
    "displayName": {
        "en": "Customer Name"
    },
    "name": "CustomerName",
    "schema": "string"
}

Télémétrie

IoT Central vous permet d’afficher la télémétrie dans des affichages et des graphiques d’appareil, ainsi que d’utiliser des règles pour déclencher des actions quand certains seuils sont atteints. IoT Central utilise les informations du modèle d’appareil, telles que les types de données, les unités et les noms d’affichage, pour déterminer la manière d’afficher les valeurs de télémétrie. Vous pouvez également afficher des valeurs de télémétrie sur des tableaux de bord d’application et des tableaux de bord personnels.

La fonctionnalité d’exportation de données d’IoT Central permet de diffuser en continu la télémétrie vers d’autres destinations, telles que le stockage ou Event Hubs.

Commandes

Une commande doit être exécutée dans un délai de 30 secondes par défaut, et l’appareil doit être connecté quand la commande arrive. Si l’appareil ne répond pas à temps ou qu’il n’est pas connecté, la commande échoue.

Les commandes peuvent avoir des paramètres de requête et retourner une réponse.

Commandes hors connexion

Vous pouvez choisir des commandes de mise en file d’attente si un appareil est actuellement hors connexion en activant l’option Mettre en file d’attente si hors connexion pour une commande dans le modèle d’appareil.

Les commandes hors connexion représentent des notifications unidirectionnelles de votre solution vers l’appareil. Les commandes hors connexion peuvent avoir des paramètres de requête, mais elles ne renvoient pas de réponse.

Remarque

Les commandes hors connexion sont marquées comme durable si vous exportez le modèle en tant que DTDL.

Les commandes hors connexion utilisent des message cloud-à-appareil IoT Hub pour envoyer la commande et la charge utile à l’appareil.

La charge utile du message reçu par l'appareil est la valeur brute du paramètre. Une propriété personnalisée appelée method-name stocke le nom de la commande IoT Central. Le tableau suivant présente quelques exemples de charges utiles :

Schéma de requête IoT Central Exemple de charge utile reçue par l'appareil
Aucun paramètre de requête @
Double 1.23
Chaîne sample string
Object {"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

L’extrait de code suivant d’un modèle d’appareil illustre la définition d’une commande. La commande possède un paramètre d’objet avec un champ d’horodatage et une énumération :

{
  "@type": "Command",
  "displayName": {
    "en": "Generate Diagnostics"
  },
  "name": "GenerateDiagnostics",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "Payload"
    },
    "name": "Payload",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "StartTime"
          },
          "name": "StartTime",
          "schema": "dateTime"
        },
        {
          "displayName": {
            "en": "Bank"
          },
          "name": "Bank",
          "schema": {
            "@type": "Enum",
            "displayName": {
              "en": "Enum"
            },
            "enumValues": [
              {
                "displayName": {
                  "en": "Bank 1"
                },
                "enumValue": 1,
                "name": "Bank1"
              },
              {
                "displayName": {
                  "en": "Bank2"
                },
                "enumValue": 2,
                "name": "Bank2"
              },
              {
                "displayName": {
                  "en": "Bank3"
                },
                "enumValue": 3,
                "name": "Bank3"
              }
            ],
            "valueSchema": "integer"
          }
        }
      ]
    }
  }
}

Si vous activez l’option Mettre en file d’attente si hors connexion dans l’interface utilisateur du modèle d’appareil pour la commande de l’extrait de code précédent, le message reçu par l’appareil comprend les propriétés suivantes :

Nom de la propriété Exemple de valeur
custom_properties {'method-name': 'GenerateDiagnostics'}
data {"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}

Vues

Un développeur de solutions crée des affichages permettant aux opérateurs de surveiller et de gérer les appareils connectés. Les affichage faisant partie du modèle d’appareil, ils sont associés à un type d’appareil spécifique. Un affichage peut inclure les éléments suivants :

  • Graphiques pour tracer la télémétrie.
  • Vignettes pour afficher les propriétés d’appareil en lecture seule.
  • Vignettes pour permettre à l’opérateur de modifier des propriétés d’appareil accessibles en écriture.
  • Vignettes pour permettre à l’opérateur de modifier des propriétés cloud.
  • Vignettes pour permettre à l’opérateur d’appeler des commandes, y compris des commandes qui attendent une charge utile.
  • Vignettes pour afficher des étiquettes, des images ou un texte Markdown.

Étapes suivantes

Maintenant que vous avez découvert les modèles d’appareil, une étape suivante suggérée consiste à lire les charges utiles de télémétrie, de propriété et de commande pour en savoir plus sur les données qu’un appareil échange avec IoT Central.