IoT FAQ

How do I manage an IoT domain group?

See IoT Domain Groups for the available Console, CLI, and API operations for creating, listing, updating, moving, configuring, and deleting domain groups.

How do I manage an IoT domain?

See IoT Domains for the available Console, CLI, and API operations for creating, listing, updating, moving, configuring data access and retention, and deleting domains.

Is there an example of using an IoT domain group?

Yes. Working with an IoT Domain Group shows how to create a domain group, associate a domain, and configure database access. For more examples, see Scenarios.

Is there an example of using an IoT domain?

Yes. Working with an IoT Domain shows how to create a domain and configure database access. For more examples, see Scenarios.

How does timeObserved affect data retention?

Retention for historized data is calculated from when a sample is inserted into the database, not from its timeObserved value. Buffered or delayed telemetry can therefore remain longer than its observation timestamp alone suggests. A record becomes eligible for removal when the elapsed time since insertion exceeds the configured retention period. See Managing Data Retention.

How do I view work requests?

See Work Requests to list work requests, review their lifecycle states, and retrieve associated errors and logs by using the Console, CLI, or API.

How do I work with digital twin instances?

See Digital Twin Instances to create, list, get, update, and delete instances, retrieve their content, configure connectivity, and invoke commands.

How do I configure authentication for a digital twin instance?

Configure basic authentication with an OCI Vault secret or configure production authentication with an mTLS certificate. See Digital Twin Instances for related instance operations.

How do I work with digital twin models?

A digital twin model defines the semantics of a digital twin and uses a Digital Twin Model Identifier (DTMI). See DTDL v3 for the supported Digital Twins Definition Language requirements and Creating a Digital Twin Model.

How do I work with digital twin adapters?

A digital twin adapter defines the data mappings and reference payload associated with a digital twin. See Digital Twin Adapters for the available operations and examples.

How do I work with digital twin relationships?

A digital twin relationship describes a link to another digital twin instance. See Digital Twin Relationships for the available operations.

When do I use a plain-text secret value or base64 secret contents?

Use the decoded plain-text secret value as the device password when authenticating with HTTPS or MQTTS. HTTP and MQTT clients perform the required protocol encoding, so don't supply an already base64-encoded password. Encode secret contents as required when creating or uploading an OCI Vault secret. When you obtain an OAuth access token for ORDS, follow that procedure's requirements for the secret value.

What timestamp formats are accepted for timeObserved?

Direct JSONPath mapping accepts a JSON number containing a Unix epoch value in seconds, milliseconds, or microseconds, or a UTC string in exactly the form yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z', such as 2025-08-20T16:07:09.888841Z. See Mapping timeObserved.

Is direct JSONPath assignment, such as timeObserved: $.timestamp, supported?

Yes. Use "timeObserved": "$.timestamp" when the selected value is already in an accepted form. JSONPath selects the value without converting it. See Mapping timeObserved.

What happens when the mapped timestamp field is missing or null?

A missing direct-mapped field causes the platform to use the message receive time. An explicit JSON null selected by direct JSONPath isn't a supported timestamp. If the field can be missing or null, use the guarded expression in Handle a missing or null timestamp.

When are timestamp conversion functions required in the adapter?

Use the OCI IoT JQ extension fromdateformat when the payload timestamp uses another format, such as a custom-formatted string. It parses the value with the specified pattern and returns epoch microseconds. See Mapping timeObserved.

Where should timestamp parsing errors appear in adapter diagnostics or logs?

Static JSON, JQ syntax, or configuration errors are reported by Console or API validation when the adapter is created or updated. An HTTP 202 Accepted response to a device request only confirms acceptance for asynchronous processing. For runtime timestamp conversion or validation failures, check the domain database REJECTED_DATA table and its REASON_CODE and REASON_MESSAGE columns. An adapter-specific OCI Logging location for these failures is not documented. See Troubleshooting timeObserved mappings.

Are there reference examples showing how to map a device payload timestamp into digital twin observation time?

Yes. Mapping timeObserved includes direct JSONPath and fromdateformat examples and links to the public OCI IoT sample.

Are there examples of connecting devices?

Yes. Connecting a Device includes HTTPS and MQTTS examples for sending structured and unstructured telemetry and receiving commands.

Are there examples of accessing data in the IoT Platform?

Yes. Connecting to IoT Data covers APEX, ORDS, direct database connections, Oracle Analytics Cloud, and other supported data-access patterns.

What can I ask Select AI about IoT data?

You can ask about device readings, telemetry trends, missing data, abnormal events, and recent device activity when the Select AI profile has access to the relevant IoT tables, views, or schemas. See Querying IoT Data with Select AI in APEX.

Does Select AI replace SQL review?

No. Select AI can generate and run SQL from a natural-language prompt, but review generated SQL before using the results for operational decisions, automation, or incident response.

How does Select AI know which IoT tables to use?

Select AI uses the database objects and metadata from the IoT database schema.

Can Select AI query IoT data that isn't stored locally in Autonomous AI Database?

Yes, when the data is exposed through supported database objects such as views over database links, cloud links, external tables, or federated tables. See Use an AI Data Gateway for Select AI NL2SQL.

Do I have to set up Select AI?

Yes. Configure the database connection for the IoT domain, and then follow the Select AI scenario to create a profile and query the IoT data.

For an end-to-end gateway workflow, see Create Digital Twins for Indirectly Connected Devices Using a Gateway. For advanced route-level targeting and nested payload examples, see Route Indirect Device Data Using target and contentRoot.

Can I configure a digital twin instance to be indirectly connected so that another device sends data on its behalf?

Yes. Create the instance with the INDIRECT connectivity type and associate it with one or more gateway digital twin instances instead of giving the device its own authentication ID. See Working with Indirectly Connected Devices and Gateways.

Can I change the connectivity type of an existing digital twin instance?

Yes. You can change an existing instance between DIRECT, INDIRECT, and GATEWAY. Include the complete model, adapter, authentication ID, and gateway configuration required by the destination type. See Change a Digital Twin Instance Connectivity Type for the end-to-end scenario and Updating a Digital Twin Instance for the authoritative operation requirements.

Can I change an existing digital twin instance to Not connected or NONE?

No. Not connected is the Console label for the CLI and API value NONE, but it isn't a supported update destination. Create a new digital twin instance with that connectivity type instead.

Can I select a different model while changing connectivity?

Only when the model is compatible. It must have the same DTMI path and major version as the current model, and the same or a higher minor version. You can't switch to an unrelated model in the same update.

Why can't I change a gateway to another connectivity type?

Active indirectly connected instances still depend on it. Reassign those downstream instances to another gateway or change them to a supported connectivity type, and then retry the gateway update.

How can I tell which devices are connected through a specific gateway and understand the impact of losing that gateway?

Use the gateway details page to review the associated device count and dependent digital twin instances before maintenance, migration, or delete operations. Find the Gateway details on the IoT domain page, by selecting the Gateway tab to view the gateway list, select a gateway to go to the Gateway details page. See Listing IoT Domains.

How do I know which digital twin instances are directly connected, indirectly connected, or gateways?

Review the connectivity type for each digital twin instance and use the digital twin instance or gateway list pages to identify gateway associations and understand the domain topology.

How can I configure a gateway adapter so incoming telemetry is routed to the correct target device?

Resolve target in the inbound envelope when forwarded messages use one consistent device identification and payload convention. Resolve it in the inbound routes when device families require different target expressions, content roots, endpoint conditions, or payload mappings. See Create Digital Twin Adapters and Route Indirect Device Data Using target and contentRoot.

When should I use envelope-level targeting instead of route-level targeting?

Use envelope-level targeting when forwarded device messages follow one consistent device identification and payload convention. Use route-level targeting when device families require different target expressions, content roots, endpoint conditions, or payload mappings. See Choose a Gateway Adapter Pattern.

When are the gateway's inbound routes evaluated?

The service evaluates the inbound routes only when the gateway envelope's target expression is absent or resolves to null. If an envelope-level target resolves to a non-null value, the message is delegated immediately and the inbound routes are not evaluated.

What does a route-level target identify?

It is a JQ expression that must resolve to the external key of a digital twin instance associated with the gateway. In the content root scenario, ${endpoint(2)} resolves to hvac1 or compressor1.

Does target change the incoming endpoint?

No. The target expression resolves the indirectly connected digital twin and its adapter, but it does not rewrite the endpoint. The target adapter receives the original endpoint and then evaluates its own inbound routes.

Can the target adapter have multiple inbound routes?

Yes. The target adapter can use condition-based routes, including a wildcard route. Because the original endpoint is preserved, design the route conditions carefully when an adapter is shared by directly and indirectly connected devices.

When is a route-level contentRoot used?

It is used only when that route's target resolves to a non-null value. The service delegates the selected object to the target device's adapter. See Route by target and contentRoot.

What happens when a route's target resolves to null?

The route's contentRoot is ignored. If the route also contains payloadMapping, the mapping is applied to the current digital twin instance.

How can the gateway process its own telemetry?

Define a gateway route whose target is absent or resolves to null, and use payloadMapping to map the data to the gateway digital twin. Gateway telemetry and indirectly connected device telemetry can use separate endpoints so that each route has a clear condition.

Can the target external key come from the message instead of the endpoint?

Yes. The target expression can resolve an external key from a shared envelope field, such as a device key at the top level of the incoming JSON message. This can be useful when clients use a stable topic instead of placing each device key in the endpoint.

Can one digital twin model have multiple adapters?

Yes. You can create multiple adapters for the same model when devices use different data structures. Each digital twin instance is associated with the adapter that matches its incoming data.

Can directly and indirectly connected devices share an adapter?

Yes, when their payload structures and endpoint-routing requirements are compatible. Adapters typically represent the structure of incoming data rather than the connectivity topology.

How many envelope mapping sections can an adapter define?

An adapter has one envelopeMapping section. Use route-level target and contentRoot values when the adapter must route multiple indirectly connected device types or payload structures.

How is timeObserved handled after delegation?

The target adapter inherits the non-null timeObserved value resolved by the gateway envelope. If the target adapter resolves its own non-null value, that value overrides the inherited timestamp.

Why are the wrong-content-root test messages rejected?

The HVAC route delegates $.data, so a payload that contains only $.telemetry does not provide the expected HVAC data. The compressor route delegates $.telemetry, so a payload that contains only $.data does not provide the expected compressor data. See Send Telemetry Data.

Can I reuse one gateway across directly and indirectly connected devices without duplicating definitions?

Yes. Treat the gateway as a reusable asset, create the matching adapters once, and associate the gateway with each indirectly connected device that uses the adapter route condition.

Can I send unstructured telemetry from indirectly connected devices?

Yes. If you don't need structured payload mapping for the target device, send the raw payload through the gateway and omit the device-specific adapter.

Can I invoke unstructured commands on indirectly connected devices and on the gateway itself?

Yes. Use raw command endpoints for both patterns. Add a response endpoint when the gateway must publish an application-level acknowledgment for the target device. See Invoke Unstructured Commands.

For example, use boilers/boiler1/actions/reset as the request endpoint and boilers/boiler1/actions/response as the response endpoint.

Can I associate a device with multiple gateways so that it can roam?

Yes. An indirectly connected device can be associated with one or more gateways so it retains the same digital twin identity while moving between available gateways.

Use the --gateways option with an array of gateway digital twin instance OCIDs:

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "Roaming Wireless Device 1" \
  --gateways '["<gateway-instance-1-OCID>","<gateway-instance-2-OCID>"]' \
  --external-key roaming-device1

Before using multi-gateway roaming in production, validate the gateway handoff behavior in a test environment.