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

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

Tâches

Étape 1 : Créer 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 montre la commande avec les paramètres de nom d'affichage et d'ID 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 cette valeur de clé externe à l'étape 3 : Utiliser 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>"
    }

Étape 2 : Définir la commande dans un fichier JSON

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

Le fichier command.json dans cet exemple contient les commandes suivantes pour appeler la commande et 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 de l'URL /endpoints/1234 où la demande sera envoyée. Il s'agit généralement d'un point d'extrémité d'API ou d'une adresse où la plate-forme IoT écoute les commandes.
  • requestDuration : Durée autorisée ou demandée pour l'achèvement de la demande, dans le format de durée ISO 8601. PT3M qui équivaut à 3 minutes.
  • requestDataFormat : Spécifie le format de date pour les données envoyées dans la demande JSON.
  • requestData : Données utiles JSON envoyées avec une paire clé-valeur pour définir une valeur de température sur l'appareil :
    "temp": 33
Pour plus d'informations, notamment sur les emplacements et les types de chemin d'accès, voir Utilisation d'un fichier JSON pour une entrée complexe.

Étape 3 : Appeler 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 appareil. L'exemple suivant utilise l'interface de ligne de commande.

Utilisation de l'interface de ligne de commande

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

Remplacez <digital-twin-instance-OCID> par l'OCID de l'instance de jumeau numérique à l'étape 1 : Créer une instance de jumeau numérique. Cet exemple présente une demande de valeur de température à partir de l'appareil à l'aide de la commande JSON brute définie dans le fichier command.json défini à l'étape 2 : Définir 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, voir Envoi d'une commande brute à partir d'une instance de jumeau numérique.

Étape 4 : Utilisez MQTTX pour vous connecter à l'appareil à l'aide d'un ID externe

Utilisez n'importe quel client MQTT, cet exemple utilise MQTTX avec les paramètres suivants.
  1. Pour télécharger et configurer MQTTX, suivez ces instructions, voir Introduction à MQTTX. Ouvrez MQTTX.
  2. Sélectionnez + Nouvelle connexion pour créer une nouvelle connexion.
  3. Entrez la valeur <unique-id> de la clé externe dans le champ Nom d'utilisateur. Vous pouvez trouver la clé externe dans la réponse oci iot digital-twin-instance create, à partir de l'étape 1 : Créer une instance de jumeau numérique précédente :
    "external-key": "<unique-id>"
  4. Entrez le mot de passe de l'appareil.
  5. Entrez l'hôte. Sélectionnez le protocole mqtts:// dans la liste déroulante des hôtes et entrez l'hôte de l'appareil : <domain-short-id>.device.iot.<region>.oci.oraclecloud.com dans le 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 de serveur signé par une autorité de certification.
  10. Lorsque vous configurez la connexion MQTTX, veillez à vous connecter à l'aide d'un clean session et réglez l'option Last-Will-Retain à false pour permettre la conservation des abonnements clients si l'appareil se déconnecte brièvement.
  11. Réglez Dernière volonté QoS à 1.
  12. Sélectionnez Connexion.

Cette image montre les paramètres dans 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.

Étape 5 : Abonnez-vous à un sujet pour recevoir des réponses dans MQTTX

Lorsque le système externe ou l'appareil IoT publie un message pour le sujet auquel vous êtes abonné, vous consultez les messages entrants dans MQTTX sous ce sujet. Si vous attendez une réponse d'une commande précédente, assurez-vous d'être 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 le point d'extrémité comme 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 un point d'extrémité d'appareil pour l'instance de jumeau numérique avec un ID externe spécifique :
  • ID client : oracle-test-user-42
  • Nom d'utilisateur : ID externe.
  • Mot de passe : Entrez le mot de passe de l'appareil.
  • Entrez mqtts:// avec l'hôte et le numéro de port de l'appareil :

    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 enpoint comme sujet et confirmez l'abonnement.

Étape 6 : Surveiller le statut de livraison de la commande dans APEX

Pour voir vos données IoT dans APEX, vous devez configurer l'accès à vos données. 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 en utilisant les informations suivantes comme nom de l'espace de travail et nom d'utilisateur de la base de données. Notez les deux traits de soulignement dans le nom du schéma de base de données :
    <domain-short-id-from-device-host>__IOT 
    Allez à Atelier SQL et sélectionnez Commandes SQL pour interroger les données IoT.
  2. Entrez la commande suivante, remplacez <digital-twin-instance-OCID> par l'OCID du jumeau numérique et sélectionnez Exécuter pour interroger les données de la commande brute :
    select * from raw_command_data
    where digital_twin_instance_id='<digital-twin-instance-OCID>'
  3. Dans Résultats, consultez 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.Consultez les données de réponse de l'appareil dans APEX.

Étape 7 : Afficher 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.