Quick Start: Create a Digital Twin and Send Data

This scenario shows how to create a digital twin instance and how to test your configuration by sending sample data using basic authentication.

Prerequisites

An administrator must create policies for your user to access the OCI resources you want to work with. The following policies are required to set up this scenario. For more information about additional policies related to other IoT scenarios, see Prerequisites.

IoT policies

Use this IoT family policy to let the specified user group manage any IoT resource in a specific compartment or your administrator can use IoT policies to set up specific policies for specific IoT resources:

Allow group <group-name> to manage iot-family in compartment <your-compartment-name>

Vault secret policies

When you use the command for Step 3: Create a digital twin instance if you use the basic authentication, then you will need to create a secret, to do that you need the following policy.

Let any IoT user read secrets in a specific compartment and vault for an IoT domain:

Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} in compartment <compartment-name> where ALL {request.principal.type = 'iotdomain', target.vault.id = '<vault-OCID>'}

Step 1: Create an IoT Domain Group

If you have an existing IoT domain group or IoT domain you want to work with, skip this step and use those OCIDs to create the associated digital twin instance. Or complete these steps to create an IoT domain group and IoT domain. For a complete list of options, see Creating an IoT Domain Group.

1. On the IoT Domain groups list page, select Create domain group. If you need help finding the list page, see Listing IoT Domain Groups.
2. On the Create domain group page, enter a user-friendly name for the new domain group, and an optional description. Avoid entering confidential information.
3. Select a compartment where you want to store the new domain group. Your IoT domain group and IoT domain can be in different compartments. All IoT resources must be in the same region.
4. Select a domain group type. Developer is the default type, you cannot change the domain group type instead create a new domain group.
  
  Developer: Use for development and testing, reduces cost and uses fewer resources.
  
  Standard: For production domain groups, turn off the developer option to scale resources and enable high availability with automatic failover.
  
  Note
  
  You cannot change the domain group type, instead create a new domain group.
5. Select Create.
Use the oci iot domain-group create command and the required --compartment-id parameter to create an IoT domain group in a specific compartment. Replace the <compartment-OCID> value with your compartment OCID:
oci iot domain-group create --compartment-id <compartment-OCID>
Type option:
If you do not specify a --type the default domain group type is lightweight, for development and testing a lightweight domain group that costs less and uses fewer resources. When you want to create a production domain group, then use the standard option.
For a production domain group, use the --type parameter with the standard value to create a standard domain group that scales with high availability and automatic failover.
For a complete list of parameters and values for CLI commands, see CLI Command Reference.
Run the CreateIotDomainGroup operation to create an IoT domain group in a compartment.

Step 2: Create an IoT Domain

1. On the IoT Domain list page, select a compartment where you want to store your IoT domains. Your IoT domain group and IoT domain can be in different compartments. Your IoT digital twin resources can be in different compartments, and must be in the same region. If you need help finding the IoT domains list page, see Listing IoT Domains.
2. Select Create domain.
3. Enter a user-friendly name for the IoT domain. Avoid entering confidential information.
4. (Optional) Enter a description.
5. Select the associated domain group compartment, and select the domain group you want to associate to this domain.
6. Select Create.
7. View and copy Endpoints for the device host of the IoT domain, the device host displays the domain short id. Select Copy to copy this endpoint to use in the next step.
  device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com
  
  For a complete list of options, see Creating an IoT Domain.
1. Use the oci iot domain create command and required parameters to create an IoT domain.
2. Replace the <iot-domain-group-OCID> with the IoT domain group you want to associate to the IoT domain. Replace the <compartment-OCID> with the compartment OCID for the IoT domain:
  oci iot domain create --compartment-id <compartment-OCID> --iot-domain-group-id <iot-domain-group-OCID>
  
  For a complete list of parameters and values for CLI commands, see CLI Command Reference.
Run CreateIotDomain operation to create an IoT domain.

Step 3: Create a Digital Twin Instance

In this example, the digital twin instance is not associated to a digital twin model or to a digital twin adapter. You can use this method if you are just testing your digital twin setup or if you are setting up a digital twin instance to connect to a device that sends unstructured data. For a complete list of options, see Creating a Digital Twin Instance.

External Key Options: The external key is the device user name when you connect to a device to send data in step 5. If you do not include an --external-key parameter, the external key is generated in the response. If you specify the external key, it's recommended not to use quotes with the external key value.
Authentication Options: When you create a digital twin instance, authentication is optional and only required if you send data to or from a device. Add authentication to the digital twin instance using the --auth-id parameter.

The following example uses a secret to authenticate. You can use a secret for a testing environment. For a secure production environment, the digital twin instance should use a mTLS certificate for authentication.

1. Use the oci iot digital-twin-instance create command and these parameters to create a digital twin instance.
2. Replace the <iot-domain-OCID> with the IoT domain you want to associate to this IoT digital twin instance. Replace the <secret-or-certificate-OCID> with the vault secret OCID:
  oci iot digital-twin-instance create --auth-id <secret-OCID> --iot-domain-id <iot-domain-OCID>
For a complete list of parameters and values see IoT CLI command Reference, and CLI Command Reference.
Run the CreateDigitalTwinInstance operation to create a digital twin instance.

Step 4: Get the IoT Domain Details

If you have the device host endpoint for the IoT domain you want to use, skip this step.

The IoT domain details contains the device host, including the domain short id, for more Getting an IoT Domain's Details,

1. On the IoT Domains list page, select the domain that you want to work with. If you need help finding the IoT domains list page or IoT domains, see Listing IoT Domains.
2. Details: View or edit the name of the domain and the description, copy the OCID, the device host endpoint, view the compartment and the timestamp of domain creation.
  device-host: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com
3. Access the various resources and tasks associated with the domain by selecting the links or tabs. For descriptions of the domain settings, see Creating an IoT Domain
Use the oci iot domain get command and the required parameter to get an IoT domain's details, including the device host with the domain short id:
oci iot domain get --iot-domain-id <iot-domain-OCID>
For a complete list of parameters and values for CLI commands, see CLI Command Reference.
Run the GetIotDomain operation to get a domain's details.

Step 5: Send Data

Send sample data to the digital twin instance created in the previous Step 3: Create a Digital Twin Instance.

Device user name: Use the external key from the digital twin instance as the device user name.
Device password: Is associated to the authentication ID for the digital twin instance. If the digital twin instance uses a vault secret OCID for authentication, then use the plain text secret contents as the device password, see Creating a Secret and Getting a Secret's Contents. Using a vault secret as a device password is recommended only for testing, not for production.

The following example uses a secret to authenticate. Alternatively, for production the digital twin instance should use a mTLS certificate for authentication.

Using Curl
POSIX-style shells: Use this curl command when using bash, zsh, macOS Terminal, Linux, or Git Bash on Windows.
curl -u '<digital-twin-instance-external-key>:<device-password>' \ -H 'Content-Type: text/plain' \ -d 'sample data 1' \ 'https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic'
Windows Powershell: Use this curl command in this example use -G to make a GET request and append any data supplied with --data-urlencode to the URL as query parameters. Or you can use the environmental variables.
```
curl.exe -u "<digital-twin-instance-external-key>:<device-password>" `
  -H "Content-Type: text/plain" `
  -d "sample data 1" `
  "https://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic"
```
When you complete Step 3: Create a Digital Twin Instance, if you defined the external key parameter value with quotes, you must include the quotes when you send data: "external-key". For quoting best practices, see Troubleshooting.
Use any MQTT client, this example uses MQTTX with the following settings.
1. Download and set up MQTTX follow these instructions, see Getting Started with MQTTX. Open MQTTX.
2. Select + New Connection, to create a new connection.
3. Enter the external key <unique-id> value as the Username. You can find the external key in the oci iot digital-twin-instance create response, from the previous Step 3: Create a Digital Twin Instance:
  "external-key": "<unique-id>"
4. Enter the device password. If you testing use vault secret, this must be the plain text secret contents. Or for a secure production environment, use a mTLS certificate.
5. Enter the Host. Select the mqtts:// protocol from the host drop-down list and enter the device host: <domain-short-id>.device.iot.<region>.oci.oraclecloud.com from the IoT domain.
6. Enter the port, for example: 8883
  Note
  
  Currently, MQTT Secure (MQTTS) is only supported using port 8883.
7. Turn on the toggle SSL/TLS.
8. Turn on the toggle SSL Secure.
9. For the Certificate, select the CA signed server certificate option.
10. When you configure the MQTTX connection make sure to connect using a clean session and set the Last-Will-Retain option to false to allow client subscriptions to be retained if the device briefly disconnects.
11. Set the Last Will QoS to 1.
12. Select Connect.
After you finish these steps, you have a digital twin instance in the IoT platform that can receive data from a device.

What to do Next

Review the IoT sample files to set up test and production environments.
Configure APEX to view you IoT domain data in APEX, and then install a sample APEX IoT Explorer application to visually monitor your IoT devices and messages.
If you don't plan to keep the resources, delete the IoT domains associated to the IoT domain group, and delete the IoT domain group.

Oracle Cloud Infrastructure Documentation