Scénario : envoi de données structurées dans un format par défaut à l'aide de MQTT

Passez en revue ce scénario pour découvrir comment créer un modèle de jumeau numérique pour recevoir des données de télémétrie historiques à partir d'un oxymètre d'impulsion à l'aide de MQTT et comment afficher les données IoT dans APEX.

Création de spécifications DTDL pour un modèle de jumeau numérique
Créer un modèle de jumeau numérique pour un oxymètre d'impulsion
Créer un adaptateur de jumeau numérique par défaut
Création d'une instance de jumeau numérique
Publier des données à l'aide de MQTTX
Affichage de vos données IoT dans APEX
Publier les messages avec MQTTX
Interroger les données de cliché IoT dans APEX

Étape 1 : Créer des spécifications DTDL pour un modèle de jumeau numérique

Définissez une spécification de modèle de jumeau numérique où seul l'oxymètre d'impulsion est marqué comme historique.

Enregistrez-le en tant que fichier texte à référencer à l'étape suivante pour créer le modèle de jumeau numérique en fonction de ces spécifications.

en fonction des spécifications DTDL v3.

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1"
  ],
  "@id": "dtmi:com:oracle:example:health:po;1",
  "@type": "Interface",
  "displayName": "Pulse Oximeter",
  "description": "This is digital twin model for pulse oximeter",
  "contents": [
    {
      "name": "pulse",
      "displayName": "Heart Rate",
      "@type": [
        "Telemetry",
        "Historized"
      ],
      "schema": "integer"
    },
    {
      "name": "so2",
      "displayName": "Oxygen Saturation",
      "@type": "Telemetry",
      "schema": "integer"
    }
  ]
}

Étape 2 : Créer un modèle de jumeau numérique pour un oxymètre d'impulsion

Créez un modèle de jumeau numérique pour un oxymètre d'impulsion et remplacez <path-to-definition-file> par l'emplacement du fichier qui définit les spécifications du modèle numérique d'oxymètre d'impulsion de l'étape précédente.

Pour plus d'informations sur le référencement de fichiers, reportez-vous à la section Using a JSON File for Complex Input.

oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec <path-to-definition-file>

Exemple de réponse :

{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-17T14:23:03.379Z"
      }
    },
    "description": "This is digital twin model for pulse oximeter",
    "display-name": "Pulse Oximeter",
    "freeform-tags": {},
    "id": "<digital-twin-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:health:po;1",
    "system-tags": {},
    "time-created": "2025-08-17T14:23:03.449000+00:00",
    "time-updated": "2025-08-17T14:23:03.449000+00:00"
  },
  "etag": "<unique-id>"
}

Etape 3 : création d'un adaptateur jumeau numérique par défaut

Utilisez la commande oci iot digital-twin-adapter create pour créer un adaptateur jumeau numérique par défaut pour le modèle jumeau numérique oxymètre d'impulsion. Cet exemple montre comment créer un adaptateur jumeau numérique par défaut qui ne spécifie pas le sans spécifier inbound-envelope ou envelope-mapping. Par conséquent, les données sont envoyées au format par défaut de l'appareil.

Si le mapping d'enveloppe n'est pas spécifié et contient une valeur timeObserved, receivedTime est utilisé comme valeur timeObserved.

oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri "dtmi:com:oracle:example:health:po;1" --display-name "<your-pulse-oximeter-name>" --description "<this-is-digital-twin-adapter-for-pulse-oximeter>"

Exemple de réponse qui affiche les valeurs de la charge utile du périphérique et du domaine IoT associé, du modèle de jumeau numérique, de l'adaptateur de jumeau numérique et de l'URI DTMI.

{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-17T14:25:51.190Z"
      }
    },
    "description": "<this-is-digital-twin-adapter-for-pulse-oximeter>"
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:health:po;1",
    "display-name": "Pulse Oximeter",
    "freeform-tags": {},
    "id": "<iot-digital-twin-adapter-OCID>",
    "inbound-envelope": {
      "envelope-mapping": {
        "time-observed": "$.time"
      },
      "reference-endpoint": "/",
      "reference-payload": {
        "data": {
          "pulse": 0,
          "so2": 0,
          "time": "2025-08-17T14:25:52.184012284Z"
        },
        "data-format": "JSON"
      }
    },
    "inbound-routes": [
      {
        "condition": "*",
        "description": "Default condition",
        "payload-mapping": {
          "$.pulse": "$.pulse",
          "$.so2": "$.so2"
        },
        "reference-payload": null
      }
    ],
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-17T14:25:52.186000+00:00",
    "time-updated": "2025-08-17T14:25:52.186000+00:00"
  },
  "etag": "<unique-id>"
}

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

Utilisez cette commande oci iot digital-twin-instance create pour créer une instance de jumeau numérique.

Remplacez <iot-domain-OCID> et <iot-digital-twin-adapter-OCID> pour associer cette instance de jumeau numérique aux ressources IoT associées créées aux étapes précédentes.

Remplacez <vault-secret-OCID> par une clé secrète de coffre créée dans la même région que l'instance de jumeau numérique. Pour plus d'informations, reportez-vous à Création d'une clé secrète.

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --digital-twin-adapter-id <iot-digital-twin-adapter-OCID> --auth-id <vault-secret-OCID> --display-name "<Pulse Oximeter 1>"

Cet exemple de réponse montre une instance de jumeau numérique avec l'adaptateur de jumeau numérique associé, le modèle de jumeau numérique, y compris l'URI DTMI.

{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-17T14:39:44.292Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": "<iot-digital-twin-adapter-OCID>",
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:health:po;1",
    "display-name": "Pulse Oximeter 1",
    "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-17T14:39:45.238000+00:00",
    "time-updated": "2025-08-17T14:39:45.238000+00:00"
  },
  "etag": "<unique-id>"
}

Etape 5 : Publier des données à l'aide de MQTTX

Installez MQTTX.

https://mqttx.app/docs/cli/downloading-and-installation

Configurez MQTTX.

Remplacez <device-host-from-iot-domain>.

Remplacez <external-key> par la réponse de l'instance de jumeau numérique.

mqttx init
? Select MQTTX CLI output mode Text
? Select the default MQTT protocol MQTTS
? Enter the default MQTT broker host <device-host-from-iot-domain>
? Enter the default MQTT port 8883
? Enter the maximum reconnect times for MQTT connection 10
? Enter the default username for MQTT connection authentication <external-key>
? Enter the default password for MQTT connection authentication <auth-id-secret-value>
Configuration file created/updated at /Users/<user-name>/.mqttx-cli/config

Valider la connexion.

mqttx conn -h <data-host> -u <external-key> -P '<vault-secret-value>'

Publiez les données échantillon.
Remarque

-u et -P ne sont requis que si ceux-ci sont définis comme valeur par défaut dans mqtt init.

Etape 6 : visualisation des données IoT dans APEX

Pour afficher vos données IoT dans APEX, vous devez configurer la connexion à APEX.

Une fois la configuration configurée, vous pouvez suivre les étapes suivantes pour afficher le schéma de base de données IoT dans APEX :

Accédez à l'URL APEX avec l'ID abrégé du groupe de domaines à partir de l'hôte de données :

https://<domain-group-short-id-from-data-host>.data.iot.<region>.oci.oraclecloud.com/ords/r/apex

Utilisez l'ID abrégé de domaine provenant de l'hôte de périphérique pour vous connecter à APEX :
```
device-host:<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com
```
Connectez-vous à APEX à l'aide des éléments suivants :
- Base de données : <domain-short-id-from-device-host>__WKSP
- Nom d'utilisateur :<domain-short-id-from-device-host>__WKSP
- Mot de passe initial défini lorsque vous utilisez la commande de l'interface de ligne de commande pour configurer l'accès aux données d'un domaine IoT pour APEX : <initial-apex-password>

Accédez à SQL Workshop. Utilisez les commandes SQL pour interroger les données IoT.

select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-OCID>';


DIGITAL_TWIN_INSTANCE_ID	        CONTENT_PATH	VALUE	TIME_OBSERVED
<iot-digital-twin-instance-OCID>	so2	           95	  17-AUG-25 03.15.56.000205 PM
<iot-digital-twin-instance-OCID>	pulse	        75	  17-AUG-25 03.15.56.000205 PM

select * from <iot-domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_instance_id='ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';


ID	DIGITAL_TWIN_INSTANCE_ID	        CONTENT_PATH	VALUE	TIME_OBSERVED
87	<iot-digital-twin-instance-OCID>	pulse	        75	  17-AUG-25 03.15.56.000205 PM

Etape 7 : Publier des messages à l'aide de MQTTX

Publier à nouveau pour confirmer qu'il est connecté et que le message a été publié.

Lorsque vous avez créé l'instance de jumeau numérique à l'étape précédente, si vous avez indiqué la clé secrète de coffre comme ID d'authentification, vous pouvez obtenir le contenu de cette clé secrète stockée dans un coffre OCI et remplacer <vault-secret-content> par le contenu de la clé secrète.

mqttx pub -t "/data" -m '{ "pulse": 76, "so2": 94}' -u <external-key> -P '<vault-secret-content>'

Etape 8 : interrogation des données de cliché IoT dans APEX

Dans APEX, utilisez cette instruction pour interroger les données de cliché. Notez les deux traits de soulignement dans le nom du schéma.

select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-ocid>';

Affichez les dernières valeurs connues mises à jour pour chaque instance de jumeau numérique.

DIGITAL_TWIN_INSTANCE_ID	CONTENT_PATH	VALUE	TIME_OBSERVED
ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	so2	  94	17-AUG-25 03.22.34.000753 PM
ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	pulse	76	17-AUG-25 03.22.34.000753 PM

Dans APEX, utilisez cette interrogation d'instruction avec des données historiques.

select * from <iot-domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_instance_id='<iot-digital-twin-instance-OCID>';

N'observez que l'oxymètre de pouls affiche des données historiques de séries temporelles, en raison uniquement de l'oxymètre de pouls marqué comme historique dans le modèle jumeau numérique de l'étape précédente.


ID	DIGITAL_TWIN_INSTANCE_ID              CONTENT_PATH	VALUE	TIME_OBSERVED
87	<iot-digital-twin-instance-OCID>	pulse	       75	   17-AUG-25 03.15.56.000205 PM
88	<iot-digital-twin-instance-OCID>	pulse	       76	   17-AUG-25 03.22.34.000753 PM

Etape 9 : Utilisation du kit SDK

Vérifiez cette simulation avancée des données que vous pouvez utiliser en tant que fichier JavaScript dans le kit SDK Internet of Things.

/**
 * MQTTX Scenario file example
 *
 * This script generates random pulse and so2 to simulate pulse oximeter.
 */
function generator(faker, options) {
  return {
    // If no topic is returned, use the topic in the command line parameters.
    // Topic format: 'mqttx/simulate/myScenario/' + clientId,
    message: JSON.stringify({
      pulse: faker.number.int({ min: 60, max: 120 }), // Generate a random pulse between 60 and 120.
      so2: faker.number.int({ min: 90, max: 100 }), // Generate a random so2 between 90 and 100.
    })
  }
}
// Export the scenario module
module.exports = {
  name: 'Pulse Oximeter Scenario', // Name of the scenario
  generator, // Generator function
}

Exemple d'utilisation de la commande mqttx simulate et référencement du fichier.

mqttx simulate --file <path-to-above-script-file>  -u <external-key> -P '<vault-secret-content>'
❯  Starting publish simulation, scenario: Pulse Oximeter Scenario, connections: 1, req interval: 10ms, message interval: 1000ms
✔  [1/1] - Connected
✔  Created 1 connections in 1.198s
Published total: 10, message rate: 1/s
^C after 10 (or how much every you want)

Etape 10 : interrogation des données IoT dans APEX

Dans APEX, vous pouvez désormais interroger les données d'instantané pour l'oxymètre d'impulsion.

select * from <iot-domain-short-id>__IOT.SNAPSHOT_DATA where digital_twin_instance_id  = 'ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';

ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	so2	90	17-AUG-25 03.29.19.000429 PM
ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	       pulse	90	17-AUG-25 03.29.19.000429 PM

Requête sur données historiques.

select * from <iot-domain-short-id>__IOT.HISTORIZED_DATA where digital_twin_instance_id  = 'ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';

Observez les données de séries temporelles pour l'oxymètre de pouls.


ID	DIGITAL_TWIN_INSTANCE_ID	        CONTENT_PATH	VALUE	TIME_OBSERVED
94	<iot-digital-twin-instance-OCID>	pulse	       81	 17-AUG-25 03.29.15.000424 PM
96	<iot-digital-twin-instance-OCID>	pulse	       116	17-AUG-25 03.29.17.000430 PM
92	<iot-digital-twin-instance-OCID>	pulse	       105	17-AUG-25 03.29.13.000416 PM
89	<iot-digital-twin-instance-OCID>	pulse	       87	 17-AUG-25 03.29.10.000409 PM
97	<iot-digital-twin-instance-OCID>	pulse	       112	17-AUG-25 03.29.18.000429 PM
91	<iot-digital-twin-instance-OCID>	pulse	       73	 17-AUG-25 03.29.12.000411 PM
93	<iot-digital-twin-instance-OCID>	pulse	       70	 17-AUG-25 03.29.14.000413 PM
87	<iot-digital-twin-instance-OCID>	pulse	       75	 17-AUG-25 03.15.56.000205 PM
88	<iot-digital-twin-instance-OCID>	pulse	       76	 17-AUG-25 03.22.34.000753 PM
90	<iot-digital-twin-instance-OCID>	pulse	       74	 17-AUG-25 03.29.11.000409 PM

Documentation Oracle Cloud Infrastructure