Comment utiliser des commandes dans une solution Azure IoT Central

Ce guide pratique vous montre comment utiliser des commandes définies dans un modèle d’appareil.

Un opérateur peut utiliser l’interface utilisateur IoT Central pour appeler une commande sur un appareil. Les commandes contrôlent 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épondez immédiatement à une commande.
• Répondez à IoT Central lorsqu’il reçoit la commande, puis informez Ultérieurement IoT Central lorsque la commande de longue durée est terminée.

Par défaut, les commandes s’attendent à ce qu’un appareil soit connecté et échoue si l’appareil ne peut pas être atteint. Si vous sélectionnez l’option Mettre en file d'attente si hors ligne dans l’interface utilisateur du modèle d’appareil, une commande peut être mise en file d’attente jusqu’à ce qu’un appareil soit en ligne. Ces commandes hors connexion sont décrites dans une section distincte plus loin dans cet article.

Pour en savoir plus sur les conventions de commande IoT Pug et Play, consultez les conventions IoT Plug-and-Play.

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

Pour savoir comment gérer les commandes à l’aide de l’API REST IoT Central, consultez 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 SDK d’appareil, consultez Communiquer avec un hub IoT à l’aide du protocole MQTT.

Définir vos commandes

Les commandes standard sont envoyées à un appareil pour indiquer à l’appareil de faire quelque chose. Une commande peut inclure des paramètres avec des informations supplémentaires. Par exemple, une commande permettant d’ouvrir une vanne sur un appareil peut avoir un paramètre qui spécifie la quantité d’ouverture de la vanne. Les commandes peuvent également recevoir une valeur de retour lorsque l’appareil termine la commande. Par exemple, une commande qui demande à un appareil d’exécuter certains diagnostics peut recevoir un rapport de diagnostic en tant que valeur de retour.

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

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

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 les commandes des conventions > IoT Plug-and-Play.

Les champs facultatifs, tels que le nom d’affichage et la description, vous permettent d’ajouter plus de 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 le Kit de développement logiciel (SDK) d’appareil Azure IoT pour gérer les commandes standard appelées par votre application IoT Central.

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

La capture d’écran suivante montre comment la réponse de commande réussie s’affiche dans l’interface utilisateur IoT Central :

Commandes à longue exécution

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.

Cette section vous montre comment un appareil peut retarder l’envoi d’une confirmation de la fin de la commande.

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

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. Utilise sendCommandResponse pour renvoyer la réponse vers IoT Central. Cette réponse inclut le 202 code de réponse pour indiquer les résultats en attente.
3. Termine l’opération de longue durée.
4. Utilise une propriété signalée portant le même nom que la commande pour indiquer à IoT Central que la commande s’est terminée.

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

Commandes hors connexion

Cette section vous montre comment un appareil gère une commande hors connexion. Si un appareil est en ligne, il peut gérer la commande hors connexion dès qu’il est reçu. Si un appareil est hors connexion, il gère la commande hors connexion quand il se connecte ensuite à IoT Central. Les appareils ne peuvent pas envoyer de valeur de retour en réponse à une commande hors connexion.

La capture d’écran suivante montre une commande hors connexion appelée GenerateDiagnostics. Le paramètre de requête est un objet avec la propriété datetime appelée StartTime et une propriété d’énumération entière appelée Bank :

L’extrait de code suivant montre comment un client peut écouter les commandes hors connexion et afficher le contenu du message :

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 affiche la charge utile avec les valeurs StartTime et Bank . La liste de propriétés inclut le nom de la commande dans l’élément de liste nom de méthode :

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

Commandes sur les appareils non attribué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 attribué, 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 :

Étapes suivantes

Maintenant que vous savez comment utiliser des commandes dans votre application Azure IoT Central, consultez télémétrie, propriété et charges utiles de commande pour en savoir plus sur les paramètres de commande et créer et connecter une application cliente à votre application Azure IoT Central pour afficher des exemples de code complets dans différents langages.