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

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.

Créer une instance de jumeau numérique
Etablir la session MQTT à l'aide des informations d'identification du broker
S'abonner à un thème pour recevoir des commandes
Définir la commande dans un fichier JSON
Appeler la commande JSON brute
Vérification dans MQTTX
Surveiller le statut de livraison de la commande dans APEX

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

Utilisation de l'interface de ligne de commande

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.

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 comment utiliser le paramètre d'ID d'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 du périphérique 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>"
}

Etape 2 : Etablir la session MQTT à l'aide des informations d'identification du broker

Utilisez tout client MQTT. Cet exemple utilise MQTTX avec les paramètres suivants.

Téléchargez et configurez MQTTX en suivant ces instructions. Reportez-vous à la rubrique Introduction à MQTTX. Ouvrez MQTTX.
Sélectionnez Nouveau point de connexion pour créer une connexion. Entrez un nom pour la connexion, évitez de saisir des informations confidentielles.
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>"
```
Saisissez le mot de passe du périphérique. Si vous utilisez une clé secrète de coffre, il doit s'agir de la clé secrète en texte brut ou vous pouvez utiliser un certificat MTLS.
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. Reportez-vous à Obtention des détails d'un domaine IoT.
Entrez le port (par exemple, 8883).
Remarque

Actuellement, MQTT Secure (MQTTS) est uniquement pris en charge à l'aide du port 8883.
Activez l'option SSL/TLS.
Activez l'option SSL Secure.
Pour le certificat, sélectionnez l'option Certificat du serveur signé par l'autorité de certification.
Lorsque vous configurez la connexion MQTTX, veillez à vous connecter à l'aide des éléments suivants :
- clean session : définissez l'option de session propre sur true. Lorsque la session clean est définie sur true, le broker ne conserve aucune information pour le client et rejette tout état précédent d'une session persistante. Toutes les données de session sont supprimées dès que la connexion réseau est fermée.
- Définissez l'option Last-Will-Retain sur false pour autoriser la conservation des abonnements client si le périphérique se déconnecte brièvement.
Définissez le dernier testament QoS sur 1. Définir la fiabilité de la livraison "Au moins une fois" pour votre notification de déconnexion.
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.

Etape 4 : définition de 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 ce fragment de code 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 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.
Si vous avez déjà une adresse dédiée aux réponses, par exemple : /endpoints/<external-id>/response, utilisez ce chemin dans responseEndpoint.
Vous pouvez également créer un élément endpoint/route pour l'instance de jumeau numérique dans les règles de routage entrantes de l'adaptateur jumeau numérique vers lesquelles l'appareil peut publier. Référencez ce chemin dans le fichier command.json. Conservez la cohérence du chemin d'adresse, quel que soit le chemin que vous définissez dans responseEndpoint, qui devient la rubrique MQTT à laquelle le client doit s'abonner à l'étape 3 afin que vous puissiez voir la réponse de la commande.
requestDuration : durée autorisée ou demandée pour la demande, au format de durée ISO 8601. Par exemple, PT3M é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 5 : 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.
Utilisez le fichier command.json de l'étape 2 précédente : définition de la commande dans un fichier JSON.
Remplacez /endpoints/1234 par la valeur définie dans le fichier command.json pour le paramètre --request-endpoint.

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 6 : Vérification 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 aux commandes

Scénario	Etat du périphérique	Etat de commande attendu	Commentaires
Non connecté	Non connecté non abonné	REFUSÉ	Echec immédiat de la livraison des commandes
Connecté mais non abonné	Connecté	REFUSÉ	Périphérique en ligne mais ne reçoit pas de commande
Abonné mais non connecté	Abonné uniquement	EN ATTENTE → EXPIRÉ	La commande attend ; expire après expiration
Abonné mais non connecté initialement et est connecté avant expiration	Initialement hors ligne	EN ATTENTE → ENVOYÉ	Commande reçue
Connecté et abonné	Connecté et abonné	SENT	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_RESPONDED	Le périphérique ne répond pas dans le délai d'expiration de la durée de réponse
Commande bidirectionnelle (réponse reçue)	Connecté et abonné	TERMINÉ	L'appareil envoie les données dans le délai d'expiration de la réponse et termine le flux

Etape 7 : 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.

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.
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>'
```
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.

Affichez les données de réponse de l'appareil dans APEX.

Documentation Oracle Cloud Infrastructure

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

Tâches

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

Utilisation de l'interface de ligne de commande

Etape 2 : Etablir la session MQTT à l'aide des informations d'identification du broker

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

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

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

Utilisation de l'interface de ligne de commande

Etape 6 : Vérification dans MQTTX

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