Cenário: Enviando Dados Estruturados em um Formato Padrão usando MQTTs

Revise esse cenário para saber como criar um modelo de gêmeo digital para receber dados de telemetria historizados de um oxímetro de pulso usando MQTTs e como exibir dados IoT no APEX.

Criar Especificações DTDL para um Modelo Digital Twin
Crie um modelo gêmeo digital para um oxímetro de pulso
Criar um Adaptador Digital Twin Padrão
Criar uma Instância Digital Twin
Publicar Dados usando MQTTX
Exiba seus Dados IoT no APEX
Publicar Mensagens usando MQTTX
Consultar Dados de Snapshot IoT no APEX

Etapa 1: Criar Especificações DTDL para um Modelo Digital Twin

Defina uma especificação de modelo gêmeo digital em que apenas o oxímetro de pulso seja marcado como historizado.

Salve isso como um arquivo de texto para fazer referência na próxima etapa para criar o modelo de gêmeo digital com base nessas especificações.

com base nas especificações 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"
    }
  ]
}

Etapa 2: Criar um Modelo Digital Twin para um Oxímetro de Pulso

Crie um modelo de gêmeo digital para um oxímetro de pulso e substitua o <path-to-definition-file> pelo local do arquivo que define as especificações do modelo digital do oxímetro de pulso da etapa anterior.

Para obter mais informações sobre como referenciar arquivos, consulte Usando um Arquivo JSON para Entrada Complexa.

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

Exemplo de resposta:

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

Etapa 3: Criar um Adaptador Digital Twin Padrão

Use o comando oci iot digital-twin-adapter create para criar um adaptador de gêmeo digital padrão para o modelo de gêmeo digital de oxímetro de pulso. Este exemplo mostra como criar um adaptador de gêmeo digital padrão que não especifica o sem especificar o inbound-envelope ou o envelope-mapping. Como resultado, os dados são enviados no formato padrão do dispositivo.

Se o mapeamento de envelope não for especificado e contiver um timeObserved, receivedTime será usado 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>"

Exemplo de resposta que mostra os valores para o payload do dispositivo e o domínio IoT associado, o modelo de gêmeo digital, o adaptador de gêmeo digital e o 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>"
}

Etapa 4: Criar uma Instância Digital Twin

Use este comando oci iot digital-twin-instance create para criar uma instância de gêmeo digital.

Substitua o <iot-domain-OCID> e o <iot-digital-twin-adapter-OCID> para associar esta instância de gêmeo digital aos recursos IoT relacionados criados nas etapas anteriores.

Substitua <vault-secret-OCID> por um segredo do vault criado na mesma região que a instância do gêmeo digital. Para obter informações, consulte Criando um Segredo.

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

Este exemplo de resposta mostra a instância de gêmeo digital com o adaptador de gêmeo digital associado, o modelo de gêmeo digital, incluindo o 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>"
}

Etapa 5: Publicar Dados usando MQTTX

Instale o MQTTX.

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

Configurar MQTTX.

Substitua o <device-host-from-iot-domain>.

Substitua o <external-key> da resposta da instância do gêmeo 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 a conexão.

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

Publique os dados de amostra.
Observação

-u e -P só serão obrigatórios se forem definidos como padrão em mqtt init.

Etapa 6: Exibir seus Dados IoT no APEX

Se quiser exibir seus dados IoT no APEX, configure a conexão com o APEX.

Após a configuração ser configurada, você poderá seguir estas etapas para exibir seu esquema de banco de dados IoT no APEX:

Vá para o URL do APEX com o id curto do grupo de domínios do host de dados:

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

Use o id short de domínio proveniente do host do dispositivo para fazer log-in no APEX:
```
device-host:<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com
```
No APEX, faça log-in usando:
- Banco de Dados: <domain-short-id-from-device-host>__WKSP
- Nome de usuário:<domain-short-id-from-device-host>__WKSP
- Senha inicial definida quando você usar o comando da CLI para configurar o acesso aos dados de um domínio IoT para o APEX: <initial-apex-password>

Vá para SQL Workshop. Use Comandos SQL para consultar seus dados do 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

Etapa 7: Publicar Mensagens usando MQTTX

Publique novamente para confirmar que está conectado e a mensagem foi publicada.

Quando você criou a instância de gêmeo digital na etapa anterior, se especificou o segredo do vault como o ID de autenticação, poderá obter o conteúdo desse segredo armazenado em um vault do OCI e substituir o <vault-secret-content> pelo conteúdo do segredo.

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

Etapa 8: Consultar Dados de Snapshot IoT no APEX

No APEX, use esta instrução para consultar os dados de snapshot. Observe os dois sublinhados no nome do esquema.

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

Exiba os últimos valores conhecidos que foram atualizados para cada instância de gêmeo 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

No APEX, use esses dados históricos de consulta de instrução.

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

Observe apenas que o oxímetro de pulso mostra dados históricos de séries temporais, como resultado apenas do oxímetro de pulso marcado como historizado no modelo de gêmeo digital da etapa 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

Etapa 9: Usando o SDK

Revise essa simulação avançada de dados, que você pode usar como um arquivo JavaScript no 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
}

Exemplo de uso do comando mqttx simulate e referência ao arquivo.

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)

Etapa 10: Consultar Dados IoT no APEX

No APEX, agora você pode consultar os dados de snapshot do 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

Consultar dados históricos.

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

Observe os dados da série temporal para o 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

Documentação do Oracle Cloud Infrastructure