Tutoriel : Ajouter un appareil réel à votre application Azure IoT CentralTutorial: Add a real device to your Azure IoT Central application

Ce didacticiel vous indique comment ajouter et configurer un appareil réel dans votre application Microsoft Azure IoT Central.This tutorial shows you how to add and configure a real device to your Microsoft Azure IoT Central application.

Le didacticiel se déroule en deux parties :This tutorial is made up of two parts:

  1. En tant qu’opérateur, vous commencez par apprendre à ajouter et configurer un appareil réel dans votre application Azure IoT Central.First, as an operator, you learn how to add and configure a real device in your Azure IoT Central application. À la fin de cette partie, vous récupérez une chaîne de connexion à utiliser dans la seconde partie.At the end of this part, you retrieve a connection string to use in the second part.
  2. Puis, en tant que développeur d’appareils, vous vous familiarisez avec le code dans votre appareil réel.Then, as a device developer, you learn about the code in your real device. Vous ajoutez alors à l’exemple de code la chaîne de connexion récupérée dans la première partie.You add the connection string from the first part to the sample code.

Ce tutoriel vous montre comment effectuer les opérations suivantes :In this tutorial, you learn how to:

  • Ajouter un appareil réelAdd a new real device
  • Configurer le nouvel appareilConfigure the new device
  • Obtenir la chaîne de connexion de l’appareil réel à partir de l’applicationGet connection string for real device from the application
  • Comprendre la façon dont le code client est mappé sur l’applicationUnderstand how client code maps to the application
  • Configurer le code client pour l’appareil réelConfigure client code for the real device

PrérequisPrerequisites

Avant de commencer, le générateur doit suivre au minimum le premier des trois didacticiels pour générateur ci-après afin de créer l’application Azure IoT Central :Before you begin, the builder should complete at least the first builder tutorial to create the Azure IoT Central application:

Ajouter un appareil réelAdd a real device

Pour ajouter un appareil réel à votre application, vous utilisez le modèle d’appareil Climatiseur connecté que vous avez créé dans le didacticiel Définir un nouveau type d’appareil.To add a real device to your application, you use the Connected Air Conditioner device template you created in the Define a new device type tutorial.

  1. Pour ajouter un appareil en tant qu’opérateur, choisissez Device Explorer dans le menu de navigation gauche :To add a new device as an operator choose Device Explorer in the left navigation menu:

    Page Device Explorer affichant le modèle de climatiseur connecté

    L’outil Device Explorer affiche le modèle d’appareil Climatiseur connecté, ainsi que l’appareil simulé qui a été automatiquement créé lorsque le générateur a créé le modèle d’appareil.The Device Explorer shows the Connected Air Conditioner device template and the simulated device that was automatically created when the builder created the device template.

  2. Pour démarrer la connexion d’un climatiseur connecté réel, choisissez Nouveau, puis Réel :To start connecting a real connected air conditioner device, choose New, then Real:

    Début de l’ajout d’un nouveau climatiseur connecté réel

  3. Si vous le souhaitez, vous pouvez renommer votre nouvel appareil en choisissant le nom de l’appareil et en modifiant la valeur correspondante :Optionally, you can rename your new device by choosing the device name and editing the value:

    Changement du nom de l’appareil

Configurer un appareil réelConfigure a real device

L’appareil réel est créé à partir du modèle d’appareil Climatiseur connecté.The real device is created from the Connected Air Conditioner device template. En tant que générateur, vous pouvez utiliser la page Settings (Paramètres) pour configure votre appareil et pour définir les valeurs de propriété afin d’enregistrer les informations concernant votre appareil.As a builder, you can use Settings to configure your device and set property values to record information about your device.

  1. Sur la page Settings (Paramètres), notez que le paramètre Température réglée présente l’état no update (aucune mise à jour).On the Settings page, notice that the Set Temperature setting status is no update. Il conserve cet état jusqu’à ce que l’appareil réel soit connecté et qu’il confirme la prise en compte du paramètre :It stays in this state until the real device connects and acknowledges that it has acted on the setting:

    Page de paramètres indiquant l’état de synchronisation

  2. Sur la page Propriétés de votre nouveau climatiseur connecté réel, définissez Numéro de série sur rcac0010, et Version du microprogramme sur 9.75.On the Properties page for your new, real connected air conditioner device, set Serial Number to rcac0010, and Firmware version to 9.75. Puis choisissez Enregistrer :Then choose Save:

    Définition des propriétés de l’appareil réel

  3. En tant que générateur, vous pouvez visualiser les pages Measurements (Mesures), Règles et Dashboard (Tableau de bord) de votre appareil réel.As a builder, you can view the Measurements, Rules, and Dashboard pages for your real device.

Obtenir la chaîne de connexion de l’appareil réel à partir de l’applicationGet connection string for real device from application

Un développeur d’appareils doit incorporer la chaîne de connexion de votre appareil réel dans le code qui s’exécute sur l’appareil.A device developer needs to embed the connection string for your real device in the code that runs on the device. La chaîne de connexion permet à l’appareil de se connecter en toute sécurité à votre application Azure IoT Central.The connection string enables the device to connect securely to your Azure IoT Central application. Chaque instance d’appareil possède une chaîne de connexion unique.Every device instance has a unique connection string. La procédure ci-après vous indique comment rechercher la chaîne de connexion pour une instance d’appareil dans votre application :The following steps show you how to find the connection string for a device instance in your application:

  1. Sur l’écran Appareil de votre climatiseur connecté réel, choisissez Connect this device (Connecter cet appareil) :On the Device screen for your real connected air conditioner device, choose Connect this device:

    Page Appareil affichant le lien d’accès aux informations de connexion

  2. Sur la page Connect this device (Connecter cet appareil), copiez la valeur du champ Chaîne de connexion principale, puis enregistrez-la.On the Connect page, copy the Primary connection string, and save it. Vous utiliserez cette valeur dans la seconde moitié de ce didacticiel.You use this value in the second half of this tutorial. Un développeur d’appareils utilise cette valeur dans l’application cliente qui s’exécute sur l’appareil :A device developer uses this value in the client application that runs on the device:

    Valeurs de chaîne de connexion

Préparer le code clientPrepare the client code

L’exemple de code fourni dans cet article est écrit en Node.js et présente juste assez de code pour :The example code in this article is written in Node.js and shows just enough code to:

  • se connecter en tant qu’appareil à votre application Azure IoT Central ;Connect as a device to your Azure IoT Central application.
  • envoyer les données de télémétrie de température en tant que climatiseur connecté ;Send temperature telemetry as a connected air conditioner device.
  • répondre à un opérateur qui utilise le paramètre Température réglée.Respond to an operator who uses the Set Temperature setting.

Les articles de procédure référencés à la section Étapes suivantes fournissent des exemples plus complets et illustrent l’utilisation d’autres langages de programmation.The "How to" articles referenced in the Next Steps section provide more complete samples and show the use of other programming languages. Pour plus d’informations sur la connexion d’appareils à Azure IoT Central, consultez l’article Connectivité des appareils.For more information about how devices connect to Azure IoT Central, see the Device connectivity article.

La procédure ci-après vous indique comment préparer l’exemple Node.js :The following steps show how to prepare the Node.js sample:

  1. Installez Node.js 4.0.x ou une version ultérieure sur votre machine.Install Node.js version 4.0.x or later in your machine. Node.js est disponible pour un large éventail de systèmes d’exploitation.Node.js is available for a wide variety of operating systems.

  2. Sur votre machine, créez un dossier nommé connectedairconditioner.Create a folder called connectedairconditioner on your machine.

  3. Dans votre environnement de ligne de commande, accédez au dossier connectedairconditioner que vous venez de créer.In your command-line environment, navigate to the connectedairconditioner folder you created.

  4. Pour initialiser votre projet Node.js, exécutez la commande ci-après en acceptant toutes les valeurs par défaut :To initialize your Node.js project, run the following command accepting all the defaults:

    npm init
    
  5. Pour installer les packages nécessaires, exécutez la commande suivante :To install the necessary packages, run the following command:

    npm install azure-iot-device azure-iot-device-mqtt --save
    
  6. À l’aide d’un éditeur de texte, créez un fichier appelé ConnectedAirConditioner.js dans le dossier connectedairconditioner.Using a text editor, create a file called ConnectedAirConditioner.js in the connectedairconditioner folder.

  7. Ajoutez les instructions require ci-après au début du fichier ConnectedAirConditioner.js :Add the following require statements at the start of the ConnectedAirConditioner.js file:

    'use strict';
    
    var clientFromConnectionString = require('azure-iot-device-mqtt').clientFromConnectionString;
    var Message = require('azure-iot-device').Message;
    var ConnectionString = require('azure-iot-device').ConnectionString;
    
  8. Ajoutez les déclarations de variable ci-après au fichier :Add the following variable declarations to the file:

    var connectionString = '{your device connection string}';
    var targetTemperature = 0;
    var client = clientFromConnectionString(connectionString);
    

    Note

    Vous mettrez à jour l’espace réservé {your device connection string} dans le cadre d’une étape ultérieure.You update the placeholder {your device connection string} in a later step.

  9. Enregistrez les modifications que vous venez d’effectuer, mais ne fermez pas le fichier.Save the changes you have made so far, but keep the file open.

Comprendre la façon dont le code client est mappé sur l’applicationUnderstand how client code maps to the application

À la section précédente, vous avez créé un projet Node.js squelette pour une application qui se connecte à votre application Azure IoT Central.In the previous section, you created a skeleton Node.js project for an application that connects to your Azure IoT Central application. Dans cette section, vous allez ajouter du code pour :In this section, you add the code to:

  • vous connecter à votre application Azure IoT Central ;Connect to your Azure IoT Central application.
  • envoyer des données de télémétrie à votre application Azure IoT Central ;Send telemetry to your Azure IoT Central application.
  • recevoir des paramètres de votre application Azure IoT Central.Receive settings from your Azure IoT Central application.
  1. Pour envoyer les données de télémétrie de température à votre application Azure IoT Central, ajoutez le code ci-après au fichier ConnectedAirConditioner.js :To send temperature telemetry to your Azure IoT Central application, add the following code to the ConnectedAirConditioner.js file:

    // Send device telemetry.
    function sendTelemetry() {
      var temperature = targetTemperature + (Math.random() * 15);
      var data = JSON.stringify({ temperature: temperature });
      var message = new Message(data);
      client.sendEvent(message, (err, res) => console.log(`Sent message: ${message.getData()}` +
        (err ? `; error: ${err.toString()}` : '') +
        (res ? `; status: ${res.constructor.name}` : '')));
    }
    

    Le nom du champ dans le code JSON que vous envoyez doit correspondre à celui que vous avez spécifié pour les données de télémétrie de température dans votre modèle d’appareil.The name of the field in the JSON you send must match the name of the field you specified for temperature telemetry in your device template. Dans cet exemple, le nom du champ est temperature.In this example, the name of the field is temperature.

  2. Pour définir les paramètres pris en charge par votre appareil, tels que setTemperature, ajoutez la définition suivante :To define the settings your device supports, such as setTemperature, add the following definition:

    // Add any settings your device supports
    // mapped to a function that is called when the setting is changed.
    var settings = {
      'setTemperature': (newValue, callback) => {
        // Simulate the temperature setting taking two steps.
        setTimeout(() => {
          targetTemperature = targetTemperature + (newValue - targetTemperature) / 2;
          callback(targetTemperature, 'pending');
          setTimeout(() => {
            targetTemperature = newValue;
            callback(targetTemperature, 'completed');
          }, 5000);
        }, 5000);
      }
    };
    
  3. Pour gérer les paramètres envoyés par Azure IoT Central, ajoutez la fonction ci-après qui localise et exécute le code d’appareil approprié :To handle settings sent from Azure IoT Central, add the following function that locates and executes the appropriate device code:

    // Handle settings changes that come from Azure IoT Central via the device twin.
    function handleSettings(twin) {
      twin.on('properties.desired', function (desiredChange) {
        for (let setting in desiredChange) {
          if (settings[setting]) {
            console.log(`Received setting: ${setting}: ${desiredChange[setting].value}`);
            settings[setting](desiredChange[setting].value, (newValue, status, message) => {
              var patch = {
                [setting]: {
                  value: newValue,
                  status: status,
                  desiredVersion: desiredChange.$version,
                  message: message
                }
              }
              twin.properties.reported.update(patch, (err) => console.log(`Sent setting update for ${setting}; ` +
                (err ? `error: ${err.toString()}` : `status: success`)));
            });
          }
        }
      });
    }
    

    Cette fonction :This function:

    • surveille l’envoi par Azure IoT Central d’une propriété requise ;Watches for Azure IoT Central sending a desired property.
    • localise la fonction à appeler pour gérer la modification du paramètre ;Locates the appropriate function to call to handle the setting change.
    • renvoie un accusé de réception à votre application Azure IoT Central.Sends an acknowledgement back to your Azure IoT Central application.
  4. Ajoutez le code ci-après pour effectuer la connexion à Azure IoT Central et raccorder les fonctions dans le code client :Add the following code to complete the connection to Azure IoT Central and hook up the functions in the client code:

    // Handle device connection to Azure IoT Central.
    var connectCallback = (err) => {
      if (err) {
        console.log(`Device could not connect to Azure IoT Central: ${err.toString()}`);
      } else {
        console.log('Device successfully connected to Azure IoT Central');
         // Send telemetry measurements to Azure IoT Central every 1 second.
        setInterval(sendTelemetry, 1000);
         // Get device twin from Azure IoT Central.
        client.getTwin((err, twin) => {
          if (err) {
            console.log(`Error getting device twin: ${err.toString()}`);
          } else {
            // Apply device settings and handle changes to device settings.
            handleSettings(twin);
          }
        });
      }
    };
    
    client.open(connectCallback);
    
  5. Enregistrez les modifications que vous venez d’effectuer, mais ne fermez pas le fichier.Save the changes you have made so far, but keep the file open.

Configurer le code client pour l’appareil réelConfigure client code for the real device

Pour configurer votre code client pour la connexion à votre application Azure IoT Central, vous devez ajouter la chaîne de connexion de votre appareil réel que vous avez notée au cours d’une étape précédente de ce didacticiel.To configure your client code to connect to your Azure IoT Central application, you need to add the connection string for your real device that you noted earlier in this tutorial.

  1. Dans le fichier ConnectedAirConditioner.js, recherchez la ligne de code suivante :In the ConnectedAirConditioner.js file, find the following line of code:

    var connectionString = '{your device connection string}';
    
  2. Remplacez {your device connection string} par la chaîne de connexion de votre appareil réel.Replace {your device connection string} with the connection string of your real device. Vous avez noté la chaîne de connexion à la fin de la section « Obtenir la chaîne de connexion de l’appareil réel à partir de l’application ».You made a note of the connection string at the end of the "Get connection string for real device from application" section.

  3. Enregistrez les modifications apportées au fichier ConnectedAirConditioner.js.Save the changes to the ConnectedAirConditioner.js file.

  4. Pour exécuter l’exemple, entrez la commande ci-après dans votre environnement de ligne de commande :To run the sample, enter the following command in your command-line environment:

    node ConnectedAirConditioner.js
    

    Note

    Vérifiez que vous exécutez cette commande à partir du dossier connectedairconditioner.Make sure you are in the connectedairconditioner folder when you run this command.

  5. L’application affiche la sortie sur la console :The application prints output to the console:

    Sortie de l’application cliente

  6. Au bout de 30 secondes environ, vous voyez les données de télémétrie apparaître sur la page Measurements (Mesures) de l’appareil :After about 30 seconds, you see the telemetry on the device Measurements page:

    Télémétrie réelle

  7. Sur la page Settings (Paramètres), vous pouvez constater que le paramètre est à présent synchronisé.On the Settings page, you can see the setting is now synchronized. Lorsque l’appareil s’est connecté pour la première fois, il a reçu la valeur du paramètre et a accusé réception de sa modification :When the device first connected, it received the setting value and acknowledged the change:

    Paramètre synchronisé

  8. Sur la page Settings (Paramètres), définissez la température de l’appareil sur 95, puis choisissez Update device (Mettre à jour l’appareil).On the Settings page, set the device temperature to 95 and choose Update device. Votre exemple d’application reçoit et traite cette modification :Your sample application receives and processes this change:

    Réception et traitement du paramètre

    Note

    Il existe deux types de messages « setting update » :There are two "setting update" messages. l’un lorsque l’état pending est envoyé, et l’autre lors de l’envoi de l’état completed.One when the pending status is sent and one when the completed status is sent.

  9. Sur la page Measurements (Mesures), vous pouvez constater que l’appareil envoie des valeurs de température plus élevées :On the Measurements page you can see that the device is sending higher temperature values:

    Données de télémétrie de température plus élevées

Étapes suivantesNext steps

Dans ce didacticiel, vous avez appris à :In this tutorial, you learned how to:

  • Ajouter un appareil réelAdd a new real device
  • Configurer le nouvel appareilConfigure the new device
  • Obtenir la chaîne de connexion de l’appareil réel à partir de l’applicationGet connection string for real device from the application
  • Comprendre la façon dont le code client est mappé sur l’applicationUnderstand how client code maps to the application
  • Configurer le code client pour l’appareil réelConfigure client code for the real device

Maintenant que vous avez connecté un appareil réel à votre application Azure IoT Central, voici les prochaines étapes suggérées :Now that you have connected a real device to your Azure IoT Central application, here are the suggested next steps:

En tant qu’opérateur, vous pouvez apprendre à :As an operator, you can learn how to:

En tant que développeur d’appareils, vous pouvez apprendre à :As a device developer, you can learn how to: