Overview of Internet of Things Platform

Use the Oracle Cloud Infrastructure (OCI) Internet of Things Platform to transfer data to and from your devices and sensors to OCI.

The Internet of Things Platform enables devices with almost any data shape and size to communicate with each other and other systems in real time. The data coming to and from a physical device or an external system is saved to the database as normalized telemetry data.

How your Internet of Things Works

Configuration Overview

After an administrator configures policies and authentication, and then follows these steps to set up an Internet of Things.

Create an IoT domain group, which automatically provisions a database.
Create an IoT domain within the domain group, a database schema is automatically provisioned in the database.
Create digital twin resources instances, models, adapters, and relationships in an IoT domain.
Configure IoT devices or third-party cloud devices with a target host, endpoint, and credentials.
Devices or servers in a third-party cloud connect to OCI Internet of Things Platform over MQTTs, HTTPs, or MQTTs over WebSocket. You can configure devices to subscribe and receive commands using the IoT Platform.
Access IoT data from the database by using ORDS, or APEX, or directly in the database by using a TCPS connection string. Or you can create a connection to Oracle Analytics Cloud.

Code Samples for Digital Twin Scenarios

For code samples and scenarios to configure digital twins to collect telemetry data and send bidirectional messages using the command line or programming languages, see GitHub.

Concepts

The following key concepts describe how to work with your Internet of Things (IoT).

IoT domain group

A resource in a compartment that contains a collection of IoT domains. When you create an IoT domain group a database is automatically provisioned that's accessible by its unique data access endpoint. After you create a domain group, you can get the domain group details to view the data host.

data-host:<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com

IoT domain

A resource in a compartment you can use to manage all of your digital twin resources including your digital twin models, adapters, instances, and relationships. An IoT domain receives data on a unique device endpoint that connects to a dedicated database schema that's located in a specific compartment and associated to a domain group. After you create an IoT domain, you can get the IoT domain details to view the device host.

device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com

Overview of how digital twin resources relate to each other.

digital twin model

A digital twin model defines the semantics of a digital twin and is based on the DTDL v3 specifications. A digital twin uses a Digital Twin Model Identifier (DTMI) as a unique identifier.

For example: dtmi:com:yourcompany:iot:example;1

digital twin adapter

A digital twin adapter facilitates data integration by interpreting and converting 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.

digital twin instance

A digital twin instance is a digital representation of a physical entity, that's based on a digital twin model.

digital twin relationship

A digital twin relationship describes a link to another digital twin instance and enables you to create graph of its relationship to other digital twin instances.

raw data

A collection of records containing raw data received from an IoT device. Such data includes an endpoint, a received time, content type, and actual content.

rejected data

A collection of rejected records containing raw data received from an IoT device. Such data includes code and a detailed message containing the rejection reason.

normalized data

A collection of records normalized according to the mapping specified in the digital twin adapter. Each record includes the value of a content path for a digital twin instance and the specific timestamp when it was observed.

historized data

If the digital twin model's content is marked for historized, then the time-series data for the digital twin instances is collected for each IoT domain.

snapshot data

Contains a snapshot of the last known value for a digital twin instance in an IoT domain.

raw command data

Raw data commands are sent to a digital twin instance in an IoT domain along with any response details including a delivery status.

unstructured data

The data is opaque to the IoT Platform and does not go through any normalization process.

structured data

The shape of the data is known to the IoT Platform as a digital twin adapter that translates data to digital twin models for data snapshots and if configured, captures historized data.

Flow of Data

IoT devices and external applications send unstructured raw or structured telemetry data in payloads to a database. The following diagram shows how the bidirectional data flow works between the IoT Platform and IoT devices.

An overview of the data flow:

Data received from IoT devices is enqueued as-is into raw data in queue.
Data from a raw data in queue is dequeued and inserted into the raw data table, and is stored for the configured retention period. The default value is 16 days for raw data, rejected data, and raw command data, the default value for historized data is 30 days. You can update the data retention period to increase the number of days.
Data from the raw data in queue is dequeued and enqueued into the rejected data queue, if it can't be normalized as described in digital twin adapter mapping.
Data from the rejected data queue is dequeued and inserted into the rejected data table and is stored for a configured retention period.
If the data can be normalized as described in the digital twin adapter mapping, then the data from the raw data in queue is dequeued and enqueued into the normalized data queue.
If you create a digital twin model's specifications with content that's specified for historization, the data from the normalized data queue is dequeued and inserted into historized data table.
Data from the normalized data queue is dequeued and corresponds with the last known value that's updated in the snapshot data table.
Commands invoked by the user are inserted into raw command data table.
Command from the raw command data table are enqueued into raw data out queue.
Commands from the raw command data queue are dequeued and sent to the targeted IoT device that's subscribed.
If a command response is received from the IoT device it's enqueued as-is into the raw data in queue.
Command responses from raw data in queue are dequeued and inserted into the raw data table and stored for a configured retention period.
Commands from the raw command data queue are dequeued, correlated with the command record and stored in the raw command data table.
Users can query the raw command data table for the status of a command and retrieve the command response if one exists.
Users can query any data table either directly in the database or by using Oracle REST Data Services (ORDS).
For more information, see the IoT domain database schema.

Setting Up Your Internet of Things

After you create an IoT domain group and an IoT domain, depending on the type data that you want to send and receive, consider the following example scenarios to connect a device and then apply the following concepts to your use case to set up your Internet of Things.

Consume Your Data

The IoT Platform normalizes data received from different devices according to the mapping specified in the digital twin adapter. Use any of the following options to consume your data.

APEX: To build APEX applications with your data configure access to APEX.
ORDS: To make REST API calls to get your data using the IoT Data API or build custom REST APIs with your IoT data configure access to ORDS.
Direct Database Connection: To query the IoT domain schema directly configure a direct database connection.
Analytics Cloud: To connect to Analytics Cloud to create a datasets with your data configure access to Analytics Cloud.

IoT Data in APEX

Building APEX applications with your IoT database requires configuring an IoT domain to connect to APEX,

This diagram explains the data flow for APEX to access to your IoT data.

The diagram above and these steps describe an overview for configuring access to APEX.

Configure data access for an IoT domain by setting an initial password for the APEX workspace.
Go to APEX in a browser by using https://<data-host-from-domain-group>/ords/apex and log in to APEX from your IoT workspace by using <domain-short-id-from-device-host>__WKSP with the same user name.
In APEX, access two IoT database schemas for your IoT domain. Notice two underscores:
- Read-only access to <domain-short-id-from-device-host>__IOT that contains the device data.
- Read and write access to <domain-short-id-from-device-host>__WKSP to work with your data.
```
https://<domain-group-short-id-from-data-host>.data.iot.<region>.oci.oraclecloud.com/ords/apex
```

IoT Data in Oracle REST Data Service (ORDS)

Making API calls to get data from IoT database using the IoT Data API or using ORDS to build custom REST APIs with your IoT data requires configuring your IoT domain to access Oracle REST Data Service (ORDS).

The diagram above and these steps describe an overview to configure access to ORDS.

User creates an integrated confidential application in the Identity domain, with the primary audience set to <domain-group-short-id> and set the scope to iot/<domain-short-id-from-device-host>.
User configures data access to the IoT domain with Identity domain host information, so the data host can validate the access token to provide ORDS access to the IoT Data API.
User obtains the access token with the password that grants client id and the secret of the integrated application and their credentials with scope set to ‘<domain-group-short-id>/iot/<domain-short-id-from-device-host>’
User invokes IoT Data API using ORDS on the data host using the oAuth token from step 3.

https://<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com/ords/20250531/<domain-short-id-from-device-host>

Internet of Things Data API Endpoints

After you authenticate to ORDS, you can use the Internet of Things Data API to get your IoT data from the IoT database schema. All ORDS data endpoints except the snapshot data endpoint, support GET to get all data from a device or specific data with an ID.

https://<iot-domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com/ords/<iot-Domain-short-id>/20250531

IoT Data in a Database

Working with your IoT data directly in the database requires configuring your IoT domain to access the database directly.

Access IoT data in the database.

The diagram above and these steps describe an overview for configuring a direct database connection.

User retrieves the OCID for the virtual cloud network (VCN) to allowlist direct database connectivity to the data host.
User configures data access on the IoT domain group to allowlist the VCN OCID for direct database connectivity to the data host.
User retrieves the groups or dynamic groups needed to allow access to the IoT domain data.
User configures data access on the IoT domain to allow the groups or dynamic groups to access the IoT domain data.
Both the user and the application running on the virtual machines, that are located in the allowlisted VCN, can retrieve the db-token from the Identity and Access Management (IAM) service by using the db-token-scope.
Both the user and the application can establish a connection to the data host by using db-connection-string and the OCI token to query the IoT domain data.
database schema: <domain-short-id-from-device-host>__IOT
Data Endpoint
```
data-host:<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com
```

IoT Data in Analytics Cloud

Use Oracle Cloud Analytics to perform analytics on your IoT data. To do this, you must configure access to view your IoT data in Oracle Analytics Cloud.

Configure Oracle Analytics Cloud Access

Overview of steps to set up access to your IoT data in Analytics Cloud, as depicted in the preceding diagram:

For a complete list of steps to configure a connection to Oracle Analytics Cloud, see Scenario: Connecting your IoT Data to Analytics Cloud

User retrieves the OCID of the VCN to allowlist direct database connectivity to the data host.
User configures data access for the IoT domain group to allowlist the VCN OCID for direct database connectivity to the data host.
User retrieves the groups required to allow access to the IoT domain data.
User configures data access on the IoT domain to allow the group(s) to access the IoT domain data including setting database password for the user logging from Oracle Analytics Cloud.
User creates the Oracle Analytics Cloud instance to analyze data from the IoT data host.
User configures the Oracle Analytics Cloud instance with a Private Access Channel and a DNS zone that points to the public data host name, for example adb.<region>oraclecloud.com in the subnet within the allowlisted VCN.
User creates an Autonomous Transaction Processing (ATP) connection in the Oracle Analytics Cloud instance with a connection string.
User can now Oracle Analytics Cloud to create datasets by using this connection.
Oracle Analytics Cloud queries the data host by using the Private Access Channel through the service gateway.

Ways to Access Oracle Cloud Infrastructure

You can access Oracle Cloud Infrastructure (OCI) by using the Console (a browser-based interface), the REST API, or the OCI CLI. For a list of available SDKs, see Software Development Kits and Command Line Interface.

In this release of OCI IoT Platform, you can use the Console to work with IoT domains and IoT domain groups and use the API and CLI for all resources.

Using the Console

Use a supported browser to go to the Console sign-in page:
```
https://cloud.oracle.com
```
The IoT Platform is available in the following regions:
- eu-frankfurt-1
- uk-london-1
- us-ashburn-1
- us-phoenix-1
Enter your cloud tenant, your user name, and your password.
Open the navigation menu, select Developer Services, and then under Internet of Things, select Domains or Domain groups.

Using the APIs

Use Cloud Shell or another tool to access the Internet of Things REST API by using these endpoints in the following supported regions. For information, see Using REST APIs.

https://iot.eu-frankfurt-1.oci.oraclecloud.com
https://iot.uk-london-1.oci.oraclecloud.com
https://iot.us-ashburn-1.oci.oraclecloud.com
https://iot.us-phoenix-1.oci.oraclecloud.com

Using the CLI

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

Device Endpoints

The device endpoint is the URL where a device sends and receives data. Each endpoint is linked to a specific region and requires authentication using API keys, vault secrets, or certificates specific to the region. For security, all IoT resources must be in the same region.

After you create an IoT domain, you can get the IoT domain details to view the device host.

Receive messages: IoT devices generate events. An event could be a normal part of operations such as a heartbeat or an event could report an error.
Send messages: Send commands to the device endpoint.

device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com

The following diagram and steps show how IoT device access and bidirectional flows work.

Overview of steps in the preceding diagram:

Device 1 publishes telemetry to the IoT Platform using MQTTs and basic authentication.
Devices or sensors in a third-party cloud can post telemetry using HTTPs to the IoT Platform using basic authentication.
Device 2 which is on-premises, behind a firewall with a proxy, publishes telemetry to the IoT Platform using MQTTs over WebSocket with a client certificate that's based on mTLS authentication.
Device 3 subscribes to a topic to receive commands from the IoT Platform.
The user sends a command to the IoT Platform with the details about which device and where to send the request, and if configured, when and where to receive the reply from the device.
IoT Platform publishes the request to Device 3 on the topic it's subscribed to.
Device 3 optionally, if configured publishes a response to the IoT Platform.

Prerequisites

An administrator in your organization must set up groups, compartments, and policies that control which users can access which tasks, resources, and the type of access they have.

For administrators:

Policies control who can create new IoT domains, and domain groups, and who can create and manage digital twin resources. For information about IoT policies, see Policy Details for the Internet of Things (IoT) Platform. For more information, see Managing Identity Domains.
For example, this policy lets your user group manage any IoT resource in a specific compartment:
```
Allow group <group-name> to manage iot-family in compartment <your-compartment-name>
```
When you create a digital twin instance to collect device data, it requires either a certificate or a secret to authenticate. Create a secret or a create a certificate in the same region as your IoT domain and the associated digital twin resources for your devices.
Add the following policies to your tenancy to allow the IoT Platform to access your vault secrets and certificates to authenticate your IoT devices. Replace the <vault-OCID> with the vault OCID for your digital twin instance secrets. Replace <compartment-name> value with the compartment name where your secrets or certificates reside.
```
Allow any-user to {SECRET_BUNDLE_READ, SECRET_READ} where ALL {request.principal.type = 'iotdomain' and target.resource.id = '<vault-OCID>'}
Allow any-user to {CERTIFICATE_BUNDLE_READ, CERTIFICATE_READ} in compartment <compartment-name> where request.principal.type = 'iotdomain'
Allow any-user to {CERTIFICATE_AUTHORITY_BUNDLE_READ, CERTIFICATE_AUTHORITY_READ} in compartment <compartment-name> where request.principal.type = 'iotdomain'
Allow any-user to {CABUNDLE_READ} in compartment <compartment-name> where request.principal.type = 'iotdomain'
```

For users: If you're a user other than an administrator who needs to use the OCI resources, contact your administrator to set up a user ID for you. The administrator can confirm which compartment or compartments you can use. After an administrator configures policies, you can access and work with IoT resources according to your permissions.

Authentication

You need to set up authentication for your user to connect to the Oracle Cloud Console, to use the SDKs or CLI, or to use the REST API:

To use the REST APIs and signing requests, set up an API signing key to authenticate.
Developers use the Internet of Things Platform APIs and SDKs to interact with and manage OCI services and resources. To use the SDKs, configure an instance SSH key to access a compute instance.
To use the CLI commands, see Command Line Reference for Internet of Things.

Resource Identifiers

Most types of Oracle Cloud Infrastructure resources have a unique, Oracle-assigned identifier called an Oracle Cloud ID (OCID). For information about the OCID format and other ways to identify your resources, see Resource Identifiers and Locating Oracle Cloud Infrastructure IDs.

Limits on IoT Resources

The following IoT resource limits are regional.

Note

Oracle restricts creating up to 2 IoT domains in each IoT domain group. The maximum number of IoT domain groups is 5 and maximum number IoT domains is 10 per region in your tenancy.


Resource	Limit Name	Oracle Universal Credits	Pay As You Go
Maximum number of IoT domain groups.	iot-domain-group-count	5	5 Contact us to request an exception to increase the paid IoT domain group limit.
Maximum number of IoT domains.	iot-domain-count	10	10 Contact us to request an exception to increase the paid IoT domain limit.

For a list of applicable limits and instructions for requesting a limit increase, see Service Limits.

API Resource Limits

The following API resource limits are regional.


Resource	Limit Name	Oracle Universal Credits
IoT Domain Group	Maximum number of allowlisted VCNs.	5
IoT Domain	Maximum number of allowlisted identity domain group names.	5
IoT Domain	Minimum retention period (in days) for raw, rejected, normalized, and command data.	16
Digital Twin Adapter	Maximum number of inbound routes.	128

Securing your Internet of Things

In general, Oracle provides security of cloud infrastructure and operations, such as cloud operator access controls and infrastructure security patching. You are responsible for securely configuring your cloud resources. Security in the cloud is a shared responsibility between you and Oracle.

Oracle is responsible for the following security requirements:

Physical Security: Oracle is responsible for protecting the global infrastructure that runs all services offered in Oracle Cloud Infrastructure. This infrastructure consists of the hardware, software, networking, and facilities that run Oracle Cloud Infrastructure services.

Your security responsibilities described on this page include the following areas:

Access Control: Limit privileges as much as possible. Users should be given only the access necessary to perform their work.
Physical Security: Limit access to on-premises Internet of Things devices.

Oracle Cloud Infrastructure Documentation