Utilisation des commandes dans une solution Azure IoT Central

  • Article

Ce guide pratique explique comment utiliser les commandes définies dans un modèle d'appareil.

Un opérateur peut utiliser l'interface utilisateur d'IoT Central pour appeler une commande sur un appareil. Les commandes déterminent le comportement d'un appareil. Par exemple, un opérateur peut appeler une commande pour redémarrer un appareil ou collecter des données de diagnostic.

Un appareil peut :

  • répondre immédiatement à une commande ;
  • répondre à IoT Central lorsqu'il reçoit la commande, puis notifier IoT Central lorsque la commande de longue durée est terminée.

Par défaut, les commandes partent du principe qu'un appareil est connecté ; elles échouent si l'appareil est inaccessible. Si vous sélectionnez l'option Mettre en file d'attente si hors connexion dans l'interface utilisateur des modèles d'appareil, une commande peut être mise en file d'attente jusqu'à ce qu'un appareil se connecte. Ces commandes hors connexion sont décrites dans une section distincte plus loin dans cet article.

Pour en savoir plus sur les conventions de commandes IoT Plug-and-Play, consultez la rubrique Conventions IoT Plug-and-Play.

Pour en savoir plus sur les données de commandes qu’un appareil échange avec IoT Central, consultez la rubrique Charges utiles de télémétrie, de propriétés et de commandes.

Pour savoir comment gérer les commandes à l'aide de l'API REST IoT Central, consultez la rubrique Comment utiliser l'API REST IoT Central pour contrôler les appareils.

Pour savoir comment implémenter des commandes dans un appareil sans utiliser les kits de développement logiciel d’appareil, consultez la rubrique Communiquer avec un hub IoT à l’aide du protocole MQTT.

Définir vos commandes

Les commandes standard sont envoyées à un appareil pour lui demander d'effectuer une opération. Une commande peut inclure des paramètres spécifiant des informations supplémentaires. Par exemple, une commande permettant d'ouvrir une vanne sur un appareil peut inclure un paramètre qui spécifie de combien la vanne doit être ouverte. Les commandes peuvent également recevoir une « valeur renvoyée » obtenue au terme de leur exécution. Par exemple, une commande qui demande à un appareil d'exécuter des diagnostics peut recevoir un rapport de diagnostic comme valeur renvoyée.

Les commandes sont définies dans le cadre d'un modèle d'appareil. La capture d'écran suivante illustre la définition de la commande de rapport Get Max-Min dans le modèle d'appareil Thermostat. Cette commande contient à la fois des paramètres de requête et de réponse :

Screenshot showing Get Max Min Report command in Thermostat device template.

Le tableau suivant décrit les paramètres de configuration d’une fonctionnalité de commande :

Champ Description
Nom d’affichage Valeur de commande utilisée sur les mosaïques de tableaux de bord et formulaires d’appareil.
Nom Nom de la commande. IoT Central génère une valeur pour ce champ à partir du nom d’affichage, mais vous pouvez choisir votre propre valeur si nécessaire. Ce champ doit être alphanumérique. Le code de l’appareil utilise cette valeur Nom.
Type de fonctionnalité Commande.
Mettre en file d'attente si hors connexion Indique si cette commande doit être transformée en commande hors connexion.
Description Description de la fonctionnalité de commande.
Commentaire Commentaires sur la fonctionnalité de commande.
Requête Charge utile de la commande d'appareil.
Response Charge utile de la réponse à la commande d'appareil.

Pour en savoir plus sur le langage DTDL (Digital Twin Definition Language) utilisé par Azure IoT Central pour définir des commandes dans un modèle d’appareil, consultez la rubrique Conventions IoT Plug-and-Play > Commandes.

Des champs facultatifs, tels que le nom d’affichage et la description, vous permettent d’ajouter des détails à l’interface et aux fonctionnalités.

Commandes standard

Pour gérer une commande standard, un appareil envoie une valeur de réponse dès qu’il reçoit la commande d’IoT Central. Vous pouvez utiliser Azure IoT device SDK pour gérer les commandes standard appelées par votre application IoT Central.

Pour obtenir des exemples d’implémentations dans plusieurs langages, consultez la rubrique Créer et connecter une application cliente à votre application Azure IoT Central.

La capture d'écran suivante montre comment la réponse apparaît dans l'interface utilisateur d'IoT Central :

Screenshot showing how to view command payload for a standard command.

Remarque

Pour les commandes standard, le délai d’expiration est de 30 secondes. Si un appareil ne répond pas dans les 30 secondes, IoT Central suppose que la commande a échoué. Cette période d’expiration n’est pas configurable.

Commandes de longue durée

Dans une commande de longue durée, un appareil ne termine pas immédiatement la commande. Au lieu de cela, l’appareil accuse réception de la commande, puis confirme ultérieurement que la commande s’est terminée. Cette approche permet à un appareil d’effectuer une opération de longue durée sans maintenir la connexion à IoT Central ouverte.

Remarque

Les commandes de longue durée ne font pas partie des conventions IoT Plug-and-Play. IoT Central dispose de sa propre convention pour implémenter des commandes de longue durée.

Cette section montre la façon dont un appareil peut retarder l’envoi d’une confirmation de commande.

L'extrait de code suivant montre comment un appareil peut implémenter une commande de longue durée :

Remarque

Cet article utilise Node.js pour des raisons de simplicité.

client.onDeviceMethod('rundiagnostics', commandHandler);

// ...

const commandHandler = async (request, response) => {
  switch (request.methodName) {
  case 'rundiagnostics': {
    console.log('Starting long-running diagnostics run ' + request.payload);
    await sendCommandResponse(request, response, 202, 'Diagnostics run started');

    // Long-running operation here
    // ...

    const patch = {
      rundiagnostics: {
        value: 'Diagnostics run complete at ' + new Date().toLocaleString()
      }
    };

    deviceTwin.properties.reported.update(patch, function (err) {
      if (err) throw err;
      console.log('Properties have been reported for component');
    });
    break;
  }
  default:
    await sendCommandResponse(request, response, 404, 'unknown method');
    break;
  }
};

L'appel à onDeviceMethod configure la méthode commandHandler. Ce gestionnaire de commandes :

  1. vérifie le nom de la commande ;
  2. appelle sendCommandResponse pour renvoyer la réponse à IoT Central. Cette réponse comprend le code de réponse 202 qui indique que les résultats sont en attente ;
  3. termine l'opération de longue durée ;
  4. utilise une propriété rapportée qui porte le même nom que la commande pour indiquer à IoT Central que la commande est terminée.

La capture d'écran suivante présente l'interface utilisateur d'IoT Central lorsqu'elle reçoit la mise à jour de propriété qui indique que la commande est terminée :

Screenshot that shows long-running command finished.

Commandes hors connexion

Cette section montre comment un appareil gère une commande hors connexion. Si un appareil est connecté, il peut gérer la commande hors connexion dès sa réception. S'il est hors connexion, il gèrera la commande hors connexion lors de sa prochaine connexion à IoT Central. Les appareils ne peuvent pas transmettre de valeur renvoyée en réponse à une commande hors connexion.

Remarque

Les commandes hors connexion ne font pas partie des conventions IoT Plug-and-Play. IoT Central dispose de sa propre convention pour implémenter des commandes hors connexion.

Remarque

Cet article utilise Node.js pour des raisons de simplicité.

La capture d'écran suivante illustre une commande hors connexion appelée GenerateDiagnostics. Le paramètre de requête est un objet doté d'une propriété date/heure appelée StartTime et d'une propriété d'énumération d'entiers appelée Bank :

Screenshot that shows the UI for an offline command.

L'extrait de code suivant montre comment un client peut écouter les commandes hors connexion et afficher le contenu des messages :

client.on('message', function (msg) {
  console.log('Body: ' + msg.data);
  console.log('Properties: ' + JSON.stringify(msg.properties));
  client.complete(msg, function (err) {
    if (err) {
      console.error('complete error: ' + err.toString());
    } else {
      console.log('complete sent');
    }
  });
});

La sortie de l'extrait de code précédent montre la charge utile avec les valeurs StartTime et Bank. La liste des propriétés comprend le nom de la commande dans l'élément de liste method-name :

Body: {"StartTime":"2021-01-06T06:00:00.000Z","Bank":2}
Properties: {"propertyList":[{"key":"iothub-ack","value":"none"},{"key":"method-name","value":"GenerateDiagnostics"}]}

Remarque

La durée de vie par défaut des commandes hors connexion est de 24 heures, après quoi le message expire.

Commandes sur des appareils non affectés

Vous pouvez appeler des commandes sur un appareil qui n’est pas affecté à un modèle d’appareil. Pour appeler une commande sur un appareil non affecté, accédez à l’appareil dans la section Appareils, sélectionnez Gérer l’appareil, puis Commande. Entrez le nom de la méthode, la charge utile et toutes les autres valeurs requises. La capture d’écran suivante montre l’interface utilisateur que vous utilisez pour appeler une commande :

Screenshot that shows an example of calling a command on an unassigned device.

Étapes suivantes

Maintenant que vous avez appris à utiliser des commandes dans votre application Azure IoT Central, reportez-vous à Charges utiles de télémétrie, de propriétés et de commandes pour en savoir plus sur les paramètres des commandes, et à Créer une application cliente et la connecter à votre application IoT Central Azure pour bénéficier d'exemples de code complets dans différents langages.