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.

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. The response will contain data 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.
  • 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 either 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 for a device. When you send data, use the external key as the user name for the device.
  • Limit: Maximum number of inbound routes for a digital twin adapter is 128.
Example device payload input, JSON mapping, and transformed result

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

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

  • If the device sends or receives unstructured data, then you do not need to specify a digital twin adapter.

    1. On the IoT domains list page, select the IoT domain you want to work with. If you need help finding the IoT domains list page, see Listing IoT Domains.
    2. Select the Digital twin adapters tab, select Create.
    3. Enter a Name and optionally a Description. Avoid entering any confidential information.
    4. To find the digital twin model you want to associate:
      • Select model: To search for the digital twin model by name.
      • Select with model spec URI: To search for the digital twin model using the DTMI. For example, dtmi:com:example:iot:demo;1
    5. Depends if the device you are working with can be programmed to send data in specific formats:
      • If the device can be programmed to send data in a specific format, you do not need to specify the adapter's envelop and routes, the adapter is generated from the device payload.
      • If the device can not programmed to send data in the format you want, then specify an adapter to translate the incoming payload into the data format you want to work with. Turn on the option to Specify inbound envelope and routes:
        • Upload inbound envelope .json file: Upload a .json file that contains the inbound envelope for this adapter.
        • Paste inbound envelope JSON: Add the inbound envelope JSON to this adapter.
    6. Inbound routes specification: Add a list of route definitions with conditions and optional payload mappings. Routes are evaluated in order.
      • Upload inbound routes .json file: Upload inbound routes in a .json file.
      • Paste inbound routes JSON: Add the inbound routes in JSON format.
    7. Tags: (Optional) Add one or more tags to the digital twin adapter. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
    8. Select Create.

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