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 passed to the digital twin adapter as a JSON object containing the data and mapping.

Key Concepts

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

For more examples, see Reference: JQ Expressions for Digital Twin Models and Adapters and Scenarios.

  • Authentication ID: When you create a digital twin adapter if you connect a device, then the associated digital twin instance must use an authentication ID parameter, with a certificate or secret to authenticate the device.
  • External key: After you create a digital twin adapter, you can update the digital twin adapter to change the external key to associate a device.
  • Limit: Maximum number of inbound routes for a digital twin adapter is 128.

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.

Device payload JSON example:

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

Use either a JQ expression or use JsonPath Notation to create an adapter payload JSON mapping output.

This example uses a JQ expression: 
{ "temperature": ".temp", "humidity": ".hum", "timeObserved": ".time" }
This example uses JsonPath Notation to create an adapter payload JSON mapping output:
{ "temperature": "$.temp", "humidity": "$.hum", "timeObserved": "$.time" }
Transformed output result:
{ "temperature": 65, "humidity": 55, "timeObserved": "<timestamp>" }

  • Use the oci iot digital-twin-adapter create command and required parameters to create a digital twin adapter.

    To create a digital twin adapter for structured data in a default format: If the device can be programmed, then you create a digital twin adapter without specifying the inbound-envelope or the envelope-mapping as a result the default data that comes from the device is accepted in the response.

    Two options for associating the digital twin model:

    • Using the DTMI:

      The following example uses the DTMI URI parameter to associate the adapter to the digital twin model. Replace <digital-twin-model-spec-uri> with the DTMI URI for your associated digital twin model. 
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>'
    • Using the digital twin model OCID:
      Alternatively, the following example uses 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:
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-id <digital-twin-model-OCID>

    To create a digital twin adapter for structured data in a custom format:

    Use the oci iot digital-twin-adapter create command and the required --iot-domain-id parameter. To create a custom digital twin adapter define a specific inbound-envelope or the inbound-route values to get the output you want to work with, to do that define 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.