Oracle Cloud Infrastructure Documentation

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 inbound-routes. 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 use the DTMI URI parameter to associate the adapter to 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 a 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 URI 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 define specific inbound-envelope or the inbound-routes values to get the output you want to work with. Define your custom payload mapping for your digital twin by using a <file://inbound-envelope.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 more information about referencing files, see Using a JSON File for Complex Input.

    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.