Creating a Digital Twin Adapter

Create a digital twin adapter to convert raw data payloads coming to and from a physical device or an external system to normalized telemetry data based on the digital twin model.

The data is passed to the digital twin adapter as a JSON object containing the data and mapping.

A digital twin adapter is required when working with structured data. There are two ways to use a digital twin adapter, depending on if the device you are working with can be programmed to send data:

Default adapter format: If the device can be programmed to send data in the format you want to work with, then create a digital twin adapter 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. For a specific example, see Scenario: Sending Structured Data in a Default Format using HTTPs.
Custom adapter format: For devices that can not be programmed to send data, you can create a custom digital twin adapter by defining a custom inbound-envelope and envelope-mapping transforming the payload and metadata to get the output you want to work with. For a specific example, see Scenario: Sending Structured Data in a Custom Format using HTTPs.

Note

Limit: Maximum number of inbound routes is 128.

Device payload JSON example:

{ "time": "<timestamp>", "temp": 65, "hum": 55 }

Use JQ expressions or JsonPath, to create an adapter payload JSON mapping.

This example uses JQ:

{ "temperature": .temp, "humidity": .hum, "timeObserved": .time }

Transformed output result:

{ "temperature": 65, "humidity": 55, "timeObserved": "<timestamp>" }

You can try adapter mapping in JQ Playground by pasting the payload as the query input, adding the JSON mapping in the JSON section and then view the output result.

The following examples uses the DTMI URI parameter to associate the digital twin model. Alternatively, you can use the --digital-twin-model-id parameter with the <digital-twin-model-OCID> for the digital twin model you want to associate to this digital twin adapter.
To create a digital twin adapter for structured data in a default format:
Use the oci iot digital-twin-adapter create command and required parameters to create a digital twin adapter. Replace <digital-twin-model-spec-uri> with the DTMI for your associated digital twin model. For structured data, if the device can be programmed, then you create a digital twin adapter without specifying the inbound-envelope or the envelope-mapping to accept the data that comes from the device in the response.
```
oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>'
```
To create a digital twin adapter for structured data in a custom format:
Use the oci iot digital-twin-adapter create command and required parameters to create a custom digital twin adapter to inbound-envelope or the envelope-mapping values to get the output you want to work with in Oracle services and applications. Define your inbound envelope and inbound route payload mapping for your digital twin using a <file://envelope-mapping.json> file and a <file://inbound-routes.json> file using JQ expressions. Replace <digital-twin-model-spec-uri> with the DTMI URI for your associated digital twin model and replace the <iot-domain-OCID> with the IoT domain OCID you want to associate to this digital twin adapter:
```
oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>' --inbound-envelope <file://inbound-envelope.json> --inbound-routes <file://inbound-routes.json>
```
For a complete list of parameters and values for CLI commands, see CLI Command Reference.
Run the CreateDigitalTwinAdapter operation to create a digital twin adapter in the specified IoT domain.

Oracle Cloud Infrastructure Documentation

Creating a Digital Twin Adapter