Scenario: invio di dati strutturati in un formato predefinito mediante MQTT

Esamina questo scenario per scoprire come creare un modello gemello digitale per ricevere dati di telemetria istorizzati da un pulsossimetro utilizzando MQTT e come visualizzare i dati IoT in APEX.

Crea specifiche DTDL per un modello Digital Twin
Creare un modello gemello digitale per un ossimetro a impulsi
Crea un adattatore Digital Twin predefinito
Creare un'istanza Digital Twin
Pubblica dati mediante MQTTX
Visualizza i dati IoT in APEX
Pubblica messaggi mediante MQTTX
Esegui query sui dati di snapshot IoT in APEX

Passo 1: Creare le specifiche DTDL per un modello Digital Twin

Definire una specifica di modello gemello digitale in cui solo l'ossimetro a impulsi è contrassegnato come istorizzato.

Salvare questo file come file di testo a cui fare riferimento nel passo successivo per creare il modello gemello digitale in base a queste specifiche.

basato sulle specifiche 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"
    }
  ]
}

Passaggio 2: creare un modello gemello digitale per un ossimetro a impulsi

Creare un modello gemello digitale per un ossimetro a impulsi e sostituire <path-to-definition-file> con la posizione del file che definisce le specifiche del modello digitale dell'ossimetro a impulsi del passo precedente.

Per ulteriori informazioni sui file di riferimento, vedere Uso di un file JSON per l'input complesso.

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

Risposta di esempio:

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

Passo 3: Creare un adattatore Digital Twin predefinito

Utilizzare il comando oci iot digital-twin-adapter create per creare un adattatore digital twin predefinito per il modello digital twin pulsossimetro. Questo esempio mostra come creare un adattatore digital twin predefinito che non lo specifichi senza specificare inbound-envelope o envelope-mapping. Di conseguenza i dati vengono inviati nel formato predefinito del dispositivo.

Se il mapping dell'envelope non viene specificato e contiene un valore timeObserved, receivedTime viene utilizzato come valore 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>"

Risposta di esempio che mostra i valori per il payload del dispositivo e il dominio IoT associato, il modello gemello digitale, l'adattatore gemello digitale e 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>"
}

Passo 4: Creare un'istanza Digital Twin

Utilizzare questo comando oci iot digital-twin-instance create per creare un'istanza gemella digitale.

Sostituire <iot-domain-OCID> e <iot-digital-twin-adapter-OCID> per associare questa istanza di gemello digitale alle risorse IoT correlate create nei passi precedenti.

Sostituire <vault-secret-OCID> con un segreto vault creato nella stessa area dell'istanza del gemello digitale. Per informazioni, vedere Creazione di un segreto.

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

Questa risposta di esempio mostra l'istanza digital twin con l'adattatore digital twin associato, il modello digital twin, incluso 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>"
}

Passo 5: pubblicare i dati utilizzando MQTTX

Installare MQTTX.

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

Configurare MQTTX.

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

Sostituire il file <external-key> dalla risposta dell'istanza gemello digitale.

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

Convalida la connessione.

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

Pubblicare i dati di esempio.
Nota

-u e -P sono obbligatori solo se sono impostati come predefiniti in mqtt init.

Passo 6: visualizzare i dati IoT in APEX

Se si desidera visualizzare i dati IoT in APEX, è necessario configurare la connessione ad APEX.

Dopo aver impostato la configurazione, è possibile effettuare le operazioni riportate di seguito per visualizzare lo schema di database IoT in APEX.

Andare all'URL APEX con l'ID breve del gruppo di domini dell'host dati:

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

Utilizzare l'ID breve del dominio proveniente dall'host del dispositivo per eseguire il login ad APEX:
```
device-host:<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com
```
In APEX eseguire il login utilizzando:
- Database: <domain-short-id-from-device-host>__WKSP
- Nome utente:<domain-short-id-from-device-host>__WKSP
- Password iniziale impostata quando si usa il comando CLI per configurare l'accesso ai dati di un dominio IoT per APEX: <initial-apex-password>

Vai a Workshop su SQL. Utilizzare Comandi SQL per eseguire una query sui dati 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

Passo 7: Pubblica i messaggi utilizzando MQTTX

Pubblica di nuovo per confermare la connessione e la pubblicazione del messaggio.

Quando hai creato l'istanza digital twin nel passo precedente, se hai specificato il segreto vault come ID di autenticazione, puoi ottenere il contenuto di tale segreto memorizzato in un vault OCI e sostituire <vault-secret-content> con il contenuto del segreto.

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

Passo 8: eseguire una query sui dati di snapshot IoT in APEX

In APEX, utilizzare questa istruzione per eseguire una query sui dati dello snapshot. Osservare i due caratteri di sottolineatura nel nome dello schema.
```
select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-ocid>';
```

Visualizza gli ultimi valori noti aggiornati per ogni istanza digital twin.

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

In APEX, utilizzare questa istruzione per interrogare i dati storici.

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

Osservare solo l'ossimetro a impulsi mostra i dati storici delle serie temporali, come risultato solo dell'ossimetro a impulsi contrassegnato come istorizzato nel modello gemello digitale dal passo precedente.


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

Passo 9: Utilizzo dell'SDK

Esaminare questa simulazione avanzata di dati, che è possibile utilizzare come file JavaScript nell'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
}

Esempio che utilizza il comando mqttx simulate e fa riferimento al 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)

Passo 10: eseguire una query sui dati IoT in APEX

In APEX, ora è possibile eseguire una query sui dati dello snapshot per l'ossimetro a impulsi.

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

Query dati cronologici.

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

Osservare i dati della serie temporale per l'ossimetro a impulsi.


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

Documentazione dell'infrastruttura Oracle Cloud