Oracle Cloud Infrastructure Documentation

Creating a Digital Twin Instance

Create a digital twin instance for a device or simulate a device connection that's a digital representation of a physical entity.

For administrators, see Prerequisites for information about policies for IoT resources, certificates, and secrets. For specific examples to set up digital twin instances, see Scenarios.

Consider the following options when you create a digital twin instance:
  • For structured data, create a digital twin instance with an adapter and model : If you are receiving structured data from a device, then you must create and associate a digital twin model and a digital twin adapter to the digital twin instance.
  • For unstructured data, create digital twin instance without an adapter or model: If you are receiving unstructured data from a device, then your digital twin instance does not require a digital twin adapter or model.
  • Authentication: (Optional)
    • With authentication: If the digital twin instance is set up to receive device data or is associated with a digital twin adapter, then you must use the authentication ID parameter with a vault secret or certificate OCID, so the digital twin can authenticate. To do that create a secret or create a certificate.
    • Without authentication: If you want to create a digital twin instance without ingestible data from a device, then you can create a digital twin instance without a digital twin adapter and without the authentication ID parameter, --auth-id. The associated digital twin model is required and must not contain telemetry or properties. After, you create a digital twin instance, you can create a digital twin relationship to simulate your IoT environment for testing without the complexity of data or authentication.
  • External Key: (Optional)
    • Using an external key with a mTLS certificate authentication ID: When you create a digital twin instance the --external-key parameter is optional. If you include an external key and the authentication ID is specified as a mTLS certificate OCID, then you must use the certificate’s common name as the external key value.
    • Using a vault secret authentication ID: When you create a digital twin instance if you use the --auth-id parameter with a vault secret to authenticate a device when you send data, then you must use the plain text secret value as the device password when you send data.
    • Using a device ID as the external key: The external key can be a name for a device, or you can use a specific device ID, for example a MAC address, or a serial number.
    • Without an external key: If you do not include an --external-key when you create a digital twin instance the external key is automatically generated. After, the digital twin instance is created, use the update digital twin instance command to change the external key.
    1. On the IoT domains list page, select the IoT domain you want to work with. If you need help find the IoT domains list page, see Listing IoT Domains.
    2. Select the Digital twin instances tab, and then select Create.
    3. Enter a Name and optionally a Description. Avoid entering any confidential information.
    4. Optional. Enter an External key that's a unique identifier. If you do not specify an external key, it's generated when you save this digital twin instance. Use the external key as the device user name when you connect to or send data to the device.
    5. Select the type:
      • Directly connected: Connect a device or entity directly to the IoT domain. If the device or entity sends structured data, then select an adapter. Selecting an adapter associates this digital twin instance with a transformation layer that converts inbound device payloads into the associated digital twin model's DTDL structure that's expected by the instance.
      • Not connected: Use this option for digital twin instances that are not backed by an IoT device. As a result, these instances cannot receive telemetry and cannot send or receive commands. Digital twin models associated with these instances can define digital twin relationships, but cannot include telemetry or properties. You can use this option to simulate your IoT environment without the complexity of data or device authentication.
      • Authentication ID: If the device or entity sends or receives data then you must specify an authentication ID. For testing create a vault secret authentication ID and for production create a mTLS certificate for the digital twin instance's authentication ID.
        • Select authentication ID: Select the secret or certificate option. For a secret, select the vault compartment, the vault, and the secret. For a certificate, select the certificate compartment and then select the certificate.
        • Paste authentication OCID: Paste the certificate's or secret's OCID.
      • 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.
    6. Select Create.

  • For unstructured data:

    Use the oci iot digital-twin-instance create command and the required parameters to create a digital twin instance for an associated IoT domain.

    Replace the <iot-domain-OCID> with the IoT domain's OCID you want to associate to this digital twin instance and replace <certificate-or-secret-OCID> with your certificate or secret:

    oci iot digital-twin-instance create --auth-id <certificate-or-secret-OCID> --iot-domain-id <iot-domain-OCID>

    For structured data:

    Use the oci iot digital-twin-instance create command and the required parameters. Structured data requires creating a digital twin instance with an authentication id and a digital twin adapter.

    Replace the <iot-domain-OCID> with the IoT domain's OCID you want to associate to this digital twin instance and replace <certificate-or-secret-OCID> with your certificate or secret.

    Replace the <digital-twin-adapter-OCID> with the related digital twin adapter OCID: 
    oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <certificate-or-secret-OCID> --digital-twin-adapter-id <digital-twin-adapter-OCID>
    For more information, see Creating a Digital Twin Adapter.
    Note

    Do not use quotes with an external key value. Some applications or code editors may add unwanted quotes to your values, this can cause an error. When working with external keys, it's a best practice to remove quotes. This also applies to external keys in curl commands. This CLI command shows the --external-key parameter and the corresponding value that does not contain quotes:

    --external-key 01-23-45-67-89-ab

    Without an Authentication ID, a digital twin model, or digital twin adapter:

    This example command shows how to create a digital twin instance without a digital twin adapter, a digital twin model, or an authentication ID and includes the optional external key parameter.

    Replace the external key with an external key for the device. The external key should be unique and can be a descriptive text value or you can use the device's MAC address or serial number.

    In this example, the --external-key value does not contain quotes: 01-23-45-67-89-ab
    oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --external-key 01-23-45-67-89-ab

    For a complete list of parameters and values for CLI commands, see CLI Command Reference.

  • Run the CreateDigitalTwinInstance operation to create a digital twin instance.