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.

Digital Twin Instance Options:
  • 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 in the same region and tenancy as any other related IoT resources. For a specific example, see Scenario: Create a Digital Twin Instance that uses a mTLS Certificate. Use the certificate OCID or the vault secret OCID as the value for the --auth-id parameter. If a digital twin instance contains an authentication ID then it does not require a digital twin model. For example, Scenario: Sending Unstructured Data Using HTTPs.
    • 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 to authenticate a device when you send data you must use the base 64 encoded 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.
    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

  • Digital Twin Adapter Options: For more information, see creating a digital twin adapter.
    • 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.

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

    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.