Scénario : réception de commandes et envoi de réponses à l'aide de MQTT

Utilisez ce scénario pour recevoir des commandes dans le cloud et envoyer des réponses à un appareil à l'aide du protocole MQTTs afin d'interagir avec vos appareils Internet of Things (IoT).

Tâches

Etape 1 : création d'une instance de jumeau numérique

Utilisation de l'interface de ligne de commande

  1. Lorsque vous créez une instance de jumeau numérique, utilisez une clé secrète ou un certificat afin que l'instance de jumeau numérique puisse s'authentifier en toute sécurité. Vous devez créer une clé secrète ou créer un certificat pour terminer ce scénario. Oracle recommande d'utiliser une clé secrète pour chaque instance de jumeau numérique.
  2. Utilisez la commande oci iot digital-twin-instance create et les paramètres requis pour créer un jumeau numérique. L'exemple suivant illustre la commande avec les paramètres de nom d'affichage et d'ID d'authentification :

    oci iot digital-twin-instance create --auth-id <vault-secret-or-client-certificate-id> --iot-domain-id <iot-domain-OCID>

    Dans cet exemple de réponse, notez la valeur de la clé externe. Utilisez la valeur de clé externe suivante dans Etape 3 : Utilisation de MQTTX pour la connexion à l'aide d'un ID externe :

    "external-key": "<unique-id>"
    {
      "data": {
        "auth-id": "<vault-secret-or-certificate-OCID>",
        "defined-tags": {
          "Oracle-Tags": {
            "CreatedBy": "default/user@oracle.com",
            "CreatedOn": "2025-08-05T18:03:15.264Z"
          }
        },
        "description": null,
        "digital-twin-adapter-id": null,
        "digital-twin-model-id": null,
        "digital-twin-model-spec-uri": null,
        "display-name": "HVAC-instance",
        "external-key": "<unique-id>",
        "freeform-tags": {},
        "id": "<iot-digital-twin-instance-OCID>",
        "iot-domain-id": "<iot-domain-OCID>",
        "lifecycle-state": "ACTIVE",
        "system-tags": {},
        "time-created": "2025-08-05T18:03:15.870000+00:00",
        "time-updated": "2025-08-05T18:03:15.870000+00:00"
      },
      "etag": "<unique-id>"
    }

Etape 2 : définition de la commande dans un fichier JSON

Vous pouvez définir la commande dans un fichier JSON et l'utiliser à l'étape suivante.

Dans cet exemple, le fichier command.json contient les commandes suivantes permettant d'appeler la commande et de traiter la réponse conformément aux instructions du fichier.

{
  "requestEndpoint": "/endpoints/1234",
  "requestDuration": "PT3M",
  "requestDataFormat": "JSON",
  "requestData": {
    "temp": 33
  },
  "requestDataContentType": "application/json",
  "responseEndpoint": "/endpoints/4321",
  "responseDuration": "PT3M"
}
  • requestEndpoint : chemin d'URL /endpoints/1234 vers lequel la demande sera envoyée. Il s'agit généralement d'une adresse d'API ou d'une adresse où la plate-forme IoT écoute les commandes.
  • requestDuration : durée autorisée ou demandée pour la demande, au format de durée ISO 8601. PT3M qui équivaut à 3 minutes.
  • requestDataFormat : indique le format de date des données envoyées dans la demande JSON.
  • requestData : charge utile JSON envoyée avec une paire de valeurs de clé pour définir une valeur de température sur l'appareil :
    "temp": 33
Pour plus d'informations sur les emplacements de fichier et les types de chemin, reportez-vous à Utilisation d'un fichier JSON pour une entrée complexe.

Etape 3 : Appel d'une commande JSON brute sur un appareil

Vous pouvez utiliser l'interface de ligne de commande ou l'API pour appeler une commande sur un périphérique. L'exemple suivant utilise l'interface de ligne de commande.

Utilisation de l'interface de ligne de commande

Utilisez la commande oci iot digital-twin-instance invoke-raw-json-command et les paramètres pour appeler une commande JSON brute sur un dispositif.

Remplacez <digital-twin-instance-OCID> par l'OCID d'instance de jumeau numérique de l'étape 1 : création d'une instance de jumeau numérique. Cet exemple illustre une demande de valeur de température à partir du périphérique à l'aide de la commande JSON brute définie dans le fichier command.json défini à l'étape 2 : définition de la commande dans un fichier JSON.

oci iot digital-twin-instance invoke-raw-json-command --digital-twin-instance-id <digital-twin-instance-OCID> --request-endpoint "/endpoints/1234" --from-json --file://command.json
Pour plus d'informations sur les autres types de commande, reportez-vous à Envoi d'une commande brute à partir d'une instance de jumeau numérique.

Etape 4 : utilisation de MQTTX pour la connexion à l'appareil à l'aide d'un ID externe

Utilisez n'importe quel client MQTT, cet exemple utilise MQTTX avec les paramètres suivants.
  1. Téléchargez et configurez MQTTX en suivant ces instructions. Reportez-vous à la rubrique Introduction à MQTTX. Ouvrez MQTTX.
  2. Sélectionnez + Nouvelle connexion pour créer une connexion.
  3. Entrez la valeur <unique-id> de la clé externe en tant que nom utilisateur. La clé externe se trouve dans la réponse oci iot digital-twin-instance create, à partir de l'étape 1 précédente : création d'une instance de jumeau numérique :
    "external-key": "<unique-id>"
  4. Saisissez le mot de passe du périphérique.
  5. Entrez l'hôte. Sélectionnez le protocole mqtts:// dans la liste déroulante des hôtes et entrez l'hôte de périphérique : <domain-short-id>.device.iot.<region>.oci.oraclecloud.com à partir du domaine IoT.
  6. Entrez le port (par exemple, 8883).
  7. Activez l'option SSL/TLS.
  8. Activez l'option SSL Secure.
  9. Pour le certificat, sélectionnez l'option Certificat du serveur signé par l'autorité de certification.
  10. Lorsque vous configurez la connexion MQTTX, veillez à vous connecter à l'aide d'un élément clean session et définissez l'option Last-Will-Retain sur false pour permettre la conservation des abonnements client si le périphérique se déconnecte brièvement.
  11. Définissez le dernier testament QoS sur 1.
  12. Sélectionnez Connexion.

Cette image montre les paramètres de MQTTX, cliquez avec le bouton droit de la souris et ouvrez-la dans un nouvel onglet pour afficher une capture d'écran plus grande.

Dans les paramètres MQTTX pour appeler une commande.

Pour afficher une capture d'écran plus grande, cliquez avec le bouton droit de la souris et ouvrez-la dans un nouvel onglet.

Dans MQTTX, sélectionnez connect.

Etape 5 : S'abonner à un sujet pour recevoir des réponses dans MQTTX

Lorsque le système externe ou le périphérique IoT publie un message sur la rubrique abonnée, vous visualisez les messages entrants dans MQTTX sous cette rubrique. Si vous attendez une réponse d'une commande précédente, assurez-vous que vous êtes abonné au sujet de réponse correct qui est défini dynamiquement dans la réponse d'instance de jumeau numérique en tant que valeur <external-id>.

  1. Dans MQTTX, sélectionnez + Nouvel abonnement.
  2. Entrez l'adresse en tant que sujet.
  3. Dans le menu déroulant QoS, sélectionnez 1 au moins une fois.
  4. Sélectionnez Confirmer.
Utilisez les paramètres de connexion suivants pour recevoir les messages publiés vers une adresse d'appareil pour l'instance de jumeau numérique avec un ID externe spécifique :
  • ID client : oracle-test-user-42
  • Nom utilisateur : ID externe.
  • Mot de passe : saisissez le mot de passe du périphérique.
  • Entrez mqtts:// avec l'hôte du périphérique et le numéro de port :

    mqtts://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com:8883

Pour afficher une capture d'écran plus grande, cliquez avec le bouton droit de la souris et ouvrez-la dans un nouvel onglet.Dans MQTTX, entrez l'adresse comme sujet et confirmez l'abonnement.

Etape 6 : surveillance du statut de transmission de la commande dans APEX

Pour afficher vos données IoT dans APEX, la configuration de l'accès à vos données est nécessaire. Une fois cette configuration terminée, vous pouvez utiliser APEX pour utiliser vos données IoT.

  1. Dans APEX, connectez-vous à l'espace de travail du domaine IoT spécifique en utilisant les éléments suivants comme nom d'espace de travail et nom utilisateur de base de données. Notez les deux traits de soulignement du nom de schéma de base de données :
    <domain-short-id-from-device-host>__IOT 
    Accédez à SQL Workshop et sélectionnez Commandes SQL pour interroger les données IoT.
  2. Entrez la commande suivante, remplacez <digital-twin-instance-OCID> par l'OCID de jumeau numérique et sélectionnez Exécuter pour interroger les données de commande brutes :
    select * from raw_command_data
    where digital_twin_instance_id='<digital-twin-instance-OCID>'
  3. Dans Résultats, affichez le fichier RESPONSE_DATA :
    {"test":1}
Pour afficher une capture d'écran plus grande, cliquez avec le bouton droit de la souris et ouvrez-la dans un nouvel onglet.Affichez les données de réponse de l'appareil dans APEX.

Etape 7 : Affichage de la réponse de la commande dans MQTTX

Dans MQTTX, sélectionnez connect pour afficher la réponse :
{
    "test": 1
  }

Pour afficher une capture d'écran plus grande, cliquez avec le bouton droit de la souris et ouvrez-la dans un nouvel onglet.

Dans MQTTX, affichez les données de réponse de la commande.