Documentation sur Oracle Cloud Infrastructure

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

Pour effectuer les étapes ci-dessous, vous pouvez utiliser un domaine IoT et un groupe de domaines IoT existants ou créer un groupe de domaines IoT et un domaine IoT, puis effectuer les étapes suivantes.

  1. Créer une instance de jumeau numérique
  2. Établir la session MQTT à l'aide des données d'identification du broker
  3. S'abonner à un sujet pour recevoir des commandes
  4. Définir la commande dans un fichier JSON
  5. Appeler une commande JSON brute
  6. Vérification dans MQTTX
  7. Surveiller le statut de transmission de la commande dans APEX

É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 et, pour la production, l'instance de jumeau numérique doit utiliser un certificat mTLS pour l'authentification.

  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 indiquant comment utiliser le paramètre d'ID authentification avec le paramètre de domaine IoT requis pour associer le domaine IoT à l'instance de jumeau numérique :

    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, notez la clé externe qui est le nom d'utilisateur de l'appareil que vous pouvez utiliser à l'étape suivante :

    "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 : Établir la session MQTT à l'aide des informations d'identification et de connexion du broker

Utilisez un 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. Entrez un nom pour la connexion, évitez d'entrer des informations confidentielles.
  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. Si vous utilisez une clé secrète de chambre forte, celle-ci doit être en texte brut ou vous pouvez utiliser un certificat mTLS.
  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, voir Obtention des détails d'un domaine IoT.
  6. Entrez le port, par exemple : 8883
    Note

    Actuellement, MQTT Secure (MQTTS) n'est pris en charge qu'avec le port 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, assurez-vous de vous connecter en utilisant :
    • clean session : Réglez l'option de nettoyage de session à true. Lorsque l'option Clean Session est réglée à Vrai, le broker ne conserve aucune information pour le client et rejette tout état antérieur d'une session persistante. Toutes les données de session sont supprimées dès que la connexion réseau est fermée.
    • Réglez l'option Last-Will-Retain à false pour permettre la conservation des abonnements de client si l'appareil se déconnecte brièvement.
  11. Réglez la valeur de Dernière volonté QoS à 1. Pour définir la fiabilité de la livraison "Au moins une fois" pour votre notification de déconnexion.
  12. Sélectionnez Connexion.

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

Dans les paramètres MQTTX pour appeler une commande.

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

Lorsqu'un système externe ou un périphérique IoT publie un message pour le sujet auquel vous êtes abonné, dans MQTTX, vous voyez les messages entrants 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 approprié.

Définissez responseEndpoint à l'étape suivante lorsque vous définissez la commande dans un fichier JSON. La chaîne "responseEndpoint": "/endpoints/4321" représente le sujet ou le chemin du point d'extrémité où l'appareil doit publier sa réponse. Sélectionnez un chemin de point d'extrémité logique pour vos routes de jumeau numérique. Vous devez utiliser le même chemin à la fois du côté du nuage (lors de l'envoi de la commande) et du côté du périphérique (lors de la publication de la réponse).

  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 : your-client-ID
  • Nom d'utilisateur : ID externe.
  • Mot de passe : Entrez le mot de passe de l'appareil.
  • Entrez mqtts:// avec l'hôte d'appareil du domaine IoT et en utilisant le numéro de port 8883 :

    mqtts://<iot-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 4 : Définir la commande dans un fichier JSON

Vous pouvez définir les détails de la commande dans un fichier JSON et utiliser ce fichier à l'étape suivante pour Appeler une commande JSON brute sur un appareil.

Pour cet exemple, enregistrez cet extrait dans un fichier command.json afin de pouvoir l'utiliser 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.

    Si vous avez déjà un point d'extrémité dédié aux réponses, par exemple : /endpoints/<external-id>/response utilisez ce chemin dans responseEndpoint.

    Ou créez une nouvelle adresse endpoint/route pour l'instance de jumeau numérique dans les règles de routage entrant de l'adaptateur jumeau numérique vers lesquelles l'appareil peut publier. Référencez ce chemin dans le fichier command.json. Gardez le chemin du point d'extrémité cohérent, quel que soit le chemin que vous définissez dans responseEndpoint devient le sujet MQTT auquel votre client doit s'abonner à l'étape 3 pour que vous puissiez voir la réponse de la commande.

  • requestDuration : Durée autorisée ou demandée pour l'achèvement de la demande, au format de durée ISO 8601. Par exemple, PT3M est égal à 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 5 : 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. 

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 6 : Vérifier dans MQTTX

Dans MQTTX, observez les données appelées :
{
    "temp": 33
  }

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.

Cette image montre comment vérifier dans MQTTX.

Scénarios de réponse de commande
scénario;État de l'appareilÉtat de commande attenduCommentaires
Non connectéNon connecté non abonné REFUSÉE La livraison de commande échoue immédiatement
Connecté mais non abonnéConnecté REFUSÉEAppareil en ligne mais ne reçoit pas de commande
Abonné mais non connecté Abonné seulementEN ATTENTE → EXPIRÉLa commande attend; expire après la temporisation
Abonné mais non connecté initialement et connecté avant temporisation Initialement hors ligne EN ATTENTE → ENVOYÉCommande reçue
Connecté et abonnéConnecté et abonné ENVOYÉ Commande reçue
Commande unidirectionnelle (aucune réponse attendue)Connecté et abonné TERMINÉ Réponse non attendue et suivie
Commande bidirectionnelle (aucune réponse reçue)Connecté et abonné NOT_RESPONDEDL'appareil ne répond pas dans la temporisation de la durée de la réponse
Commande bidirectionnelle (réponse reçue) Connecté et abonné TERMINÉL'appareil envoie les données dans le délai de réponse et termine le flux

Étape 7 : 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.Voir les données de réponse de l'appareil dans APEX.