Oracle Cloud Infrastructure Documentation

Scenario: Sending Structured Data in a Default Format using MQTTs

Review this scenario to learn how to create a digital twin model to receive historized telemetry data from a pulse oximeter using MQTTs and how to view IoT data in APEX.

  1. Create DTDL Specifications for a Digital Twin Model
  2. Create a Digital Twin Model for a Pulse Oximeter
  3. Create a Default Digital Twin Adapter
  4. Create a Digital Twin Instance
  5. Publish Data using MQTTX
  6. View your IoT Data in APEX
  7. Publish Messages using MQTTX
  8. Query IoT Snapshot Data in APEX

Step 1: Create DTDL Specifications for a Digital Twin Model

Define a digital twin model specification where only the pulse oximeter is marked as historized.

Save this as a text file to reference in the next step to create the digital twin model based on these specifications.

based on the DTDL v3 specifications.

{
  "@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"
    }
  ]
}

Step 2: Create a Digital Twin Model for a Pulse Oximeter

Create digital twin model for a pulse oximeter and replace the <path-to-definition-file> with the location of the file that defines the pulse oximeter digital model specifications from the previous step.

For more information about referencing files, see Using a JSON File for Complex Input. 

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

Example response:

{
  "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>"
}

Step 3: Create a Default Digital Twin Adapter

Use the oci iot digital-twin-adapter create command to create a default digital twin adapter for the pulse oximeter digital twin model. This example shows how to create a default digital twin adapter that does not specify the without specifying the inbound-envelope or the envelope-mapping. As a result the data is sent in the device's default format.

If the envelope mapping is not specified and contains a timeObserved then receivedTime is used as timeObserved value. 

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>"
Example response that shows the values for the device's payload and associated IoT domain, digital twin model, digital twin adapter, and the DTMI URI.
{
  "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>"
}

Step 4: Create a Digital Twin Instance

Use this oci iot digital-twin-instance create command to create a digital twin instance.

Replace the <iot-domain-OCID> and the <iot-digital-twin-adapter-OCID> to associate this digital twin instance with the related IoT resources created in the previous steps.

Replace <vault-secret-OCID> with a vault secret created in the same region as the digital twin instance. For information, see Creating a Secret. 

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>"
This example response shows digital twin instance with the associated digital twin adapter, digital twin model, including the DTMI URI.
{
  "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>"
}

Step 5: Publish Data using MQTTX

  1. Install MQTTX.
    https://mqttx.app/docs/cli/downloading-and-installation
  2. Configure MQTTX.

    Replace the <device-host-from-iot-domain>.

    Replace the <external-key> from the digital twin instance response.

    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
  3. Validate the connection.
    mqttx conn -h <data-host> -u <external-key> -P '<vault-secret-value>'
  4. Publish the sample data.
    Note

    -u and -P are only required if these are set as the default in mqtt init.

Step 6: View your IoT Data in APEX

If you want to view your IoT data in APEX you must configure the connection to APEX.

After the configuration is set up, you can follow these steps to view your IoT database schema in APEX:

  1. Go to the APEX URL with the domain group short id from the data host: 
    https://<domain-group-short-id-from-data-host>.data.iot.<region>.oci.oraclecloud.com/ords/r/apex
  2. Use the domain short id that comes from the device host to log in to APEX: 
    device-host:<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com
    In APEX log in using:

  3. Go to SQL Workshop. Use SQL Commands to query your IoT data. 

    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

Step 7: Publish Messages using MQTTX

Publish again to confirm it's connected and the message published.

When you created the digital twin instance in the previous step, if you specified the vault secret as the authentication ID, then you can get the content of that secret stored in an OCI vault, and replace the <vault-secret-content> with the secret's contents.

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

Step 8: Query IoT Snapshot Data in APEX

  1. In APEX, use this statement to query the snapshot data. Notice the two underscores in the schema name.
    select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-ocid>';
  2. View the last known values that updated for each digital twin instance. 
    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
  3. In APEX, use this statement query historized data.
    select * from <iot-domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_instance_id='<iot-digital-twin-instance-OCID>';
  4. Observe only the pulse oximeter shows time series historized data, as a result of only the pulse oximeter marked as historized in the digital twin model from the previous step.
    
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

Step 9: Using the SDK

Review this advanced simulation of data, that you can use as a JavaScript file in the Internet of Things SDK.
/**
 * 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
}
Example using the mqttx simulate command and referencing the file.
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)

Step 10: Query IoT Data in APEX

  1. In APEX, now you can query the snapshot data for the pulse oximeter. 
    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
  2. Query historized data.
    select * from <iot-domain-short-id>__IOT.HISTORIZED_DATA where digital_twin_instance_id  = 'ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';
  3. Observe the time series data for the pulse oximeter.
    
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