Escenario: Envío de datos estructurados en un formato predeterminado usando MQTTs

Revise este escenario para aprender a crear un modelo gemelo digital para recibir datos de telemetría historizados de un oxímetro de pulso mediante MQTT y a ver los datos de IoT en APEX.

Crear especificaciones DTDL para un modelo gemelo digital
Crear un modelo gemelo digital para un oxímetro de pulso
Crear un adaptador gemelo digital por defecto
Creación de una instancia gemela digital
Publicación de datos mediante MQTTX
Vea sus datos IoT en APEX
Publicación de mensajes usando MQTTX
Consultar datos de instantáneas de IoT en APEX

Paso 1: Crear especificaciones DTDL para un modelo gemelo digital

Defina una especificación de modelo gemelo digital donde solo el oxímetro de pulso esté marcado como historizado.

Guarde esto como un archivo de texto al que hacer referencia en el siguiente paso para crear el modelo de gemelo digital basado en estas especificaciones.

según las especificaciones de 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"
    }
  ]
}

Paso 2: Crear un modelo gemelo digital para un oxímetro de pulso

Cree un modelo gemelo digital para un oxímetro de pulso y sustituya el <path-to-definition-file> por la ubicación del archivo que define las especificaciones del modelo digital del oxímetro de pulso del paso anterior.

Para obtener más información sobre la referencia a archivos, consulte Uso de un archivo de JSON para una entrada compleja.

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

Ejemplo de respuesta:

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

Paso 3: Crear un adaptador gemelo digital predeterminado

Utilice el comando oci iot digital-twin-adapter create para crear un adaptador gemelo digital predeterminado para el modelo gemelo digital de oxímetro de pulso. En este ejemplo se muestra cómo crear un adaptador gemelo digital por defecto que no especifique el sin especificar inbound-envelope o envelope-mapping. Como resultado, los datos se envían en el formato predeterminado del dispositivo.

Si no se especifica la asignación de sobre y contiene un valor timeObserved, receivedTime se utiliza como valor 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>"

Ejemplo de respuesta que muestra los valores para la carga útil del dispositivo y el dominio IoT asociado, el modelo gemelo digital, el adaptador gemelo digital y el URI de 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>"
}

Paso 4: Crear una instancia gemela digital

Utilice este comando oci iot digital-twin-instance create para crear una instancia de gemelo digital.

Sustituya <iot-domain-OCID> y <iot-digital-twin-adapter-OCID> para asociar esta instancia de gemelo digital a los recursos IoT relacionados creados en los pasos anteriores.

Sustituya <vault-secret-OCID> por un secreto de almacén creado en la misma región que la instancia de gemelo digital. Para obtener información, consulte Creación de un secreto.

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

Esta respuesta de ejemplo muestra la instancia de gemelo digital con el adaptador de gemelo digital asociado, el modelo de gemelo digital, incluido el URI de 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>"
}

Paso 5: Publicar datos con MQTTX

Instale MQTTX.

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

Configurar MQTTX.

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

Sustituya <external-key> de la respuesta de instancia de gemelo digital.

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

Validar la conexión.

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

Publique los datos de ejemplo.
Nota

-u y -P solo son necesarios si se definen como valores por defecto en mqtt init.

Paso 6: Vea sus datos IoT en APEX

Si desea ver los datos de IoT en APEX, debe configurar la conexión a APEX.

Después de configurar la configuración, puede seguir estos pasos para ver el esquema de base de datos IoT en APEX:

Vaya a la URL de APEX con el identificador corto de grupo de dominios desde el host de datos:

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

Utilice el domain short id que proviene del host de dispositivo para iniciar sesión en APEX:
```
device-host:<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com
```
En APEX, conéctese mediante:
- Base de datos: <domain-short-id-from-device-host>__WKSP
- Nombre de usuario:<domain-short-id-from-device-host>__WKSP
- Contraseña inicial definida al usar el comando de la CLI para configurar el acceso a datos de un dominio IoT para APEX: <initial-apex-password>

Vaya a SQL Workshop. Utilice Comandos SQL para consultar los datos 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

Paso 7: Publicar mensajes usando MQTTX

Vuelva a publicar para confirmar que está conectado y que se ha publicado el mensaje.

Cuando ha creado la instancia de gemelo digital en el paso anterior, si ha especificado el secreto de almacén como el ID de autenticación, puede obtener el contenido de ese secreto almacenado en un almacén de OCI y sustituir <vault-secret-content> por el contenido del secreto.

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

Paso 8: Consulta de datos de instantáneas IoT en APEX

En APEX, utilice esta sentencia para consultar los datos de la instantánea. Observe los dos caracteres de subrayado en el nombre del esquema.
```
select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-ocid>';
```

Vea los últimos valores conocidos que se han actualizado para cada instancia de gemelo digital.

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

En APEX, utilice esta sentencia para consultar datos históricos.

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

Observe solo el oxímetro de pulso muestra datos históricos de series temporales, como resultado de solo el oxímetro de pulso marcado como historizado en el modelo gemelo digital del paso anterior.


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

Paso 9: Uso del SDK

Revise esta simulación avanzada de datos, que puede utilizar como archivo JavaScript en el SDK de 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
}

Ejemplo con el comando mqttx simulate y haciendo referencia al archivo.

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)

Paso 10: Consulta de datos IoT en APEX

En APEX, ahora puede consultar los datos de la instantánea para el oxímetro de pulso.

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

Consulta de datos históricos.

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

Observe los datos de la serie temporal para el oxímetro de pulso.


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

Documentación de Oracle Cloud Infrastructure