Scenario: Change a Digital Twin Instance Connectivity Type

Change digital twin instances between directly connected, indirectly connected, and gateway configurations while keeping the model, adapter, authentication, and gateway settings valid.

Use this scenario to change a directly connected digital twin instance to a gateway, associate an indirectly connected device with that gateway, reassign the device to direct connectivity, and then change the gateway to direct connectivity. Each update must provide a valid destination configuration as a whole.

If you update the model during a connectivity change, the destination model 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.

Destination Connectivity Requirements
Destination type	Required	Not allowed or restricted
All supported destination types	The selected model, adapter, authentication, and gateway settings must form one valid destination configuration. Keep the current model, or use a compatible model with the same DTMI path and major version and the same or a higher minor version.	A model with a different DTMI path or major version, or a lower minor version, isn't allowed.
`DIRECT`	An authentication ID and an adapter without gateway target mapping. In the API, specify `authId`; in the CLI, use `--auth-id`.	Gateway associations and adapters with gateway target mapping aren't allowed. Omit `gateways` from the API request and `--gateways` from the CLI command.
`INDIRECT`	A nonempty `gateways` list containing one or more active gateway instance OCIDs and an adapter without gateway target mapping.	The destination configuration can't retain an authentication ID or use an adapter with gateway target mapping. Don't include duplicate or inactive gateways, and don't exceed a gateway's device capacity.
`GATEWAY`	An authentication ID and an adapter with gateway target mapping. In the API, specify `authId`; in the CLI, use `--auth-id`.	Gateway associations and adapters without gateway target mapping aren't allowed. Omit `gateways` from the API request and `--gateways` from the CLI command. To change an existing gateway to another connectivity type, first reassign all active indirectly connected devices that use it.

Note

In the Console when you create or edit a digital twin instance, Not connected corresponds to the CLI and API value NONE. Updating an existing digital twin instance to NONE isn't supported. If you need an unconnected resource, create a new digital twin instance and select Not connected or specify NONE.

Step 1: Prepare the IoT Resources

Before you begin, create or find the resources you want to work with in one IoT domain:

An active directly connected digital twin instance that uses an authentication ID.
An adapter with gateway target mapping for the gateway configuration.
An adapter without gateway target mapping for directly and indirectly connected device configurations.
An authentication ID for every instance that will use DIRECT or GATEWAY.
A digital twin model that remains unchanged, or a compatible replacement model with the same DTMI path and major version and the same or a higher minor version.

Record the instance, adapter, model, and authentication OCIDs that you want to use. For a scenario that shows how to create these resources, see Create Digital Twins for Indirectly Connected Devices Using a Gateway.

Step 2: Change the Connectivity Types

Complete the sequence by using one of the following interfaces. Changing an instance to its current connectivity type is idempotent when the complete configuration remains valid.

1. On the IoT domain details page, select Digital twin instances, and then open the directly connected instance.
2. Select Edit, change the connectivity type to Gateway, select the adapter with gateway target mapping, and confirm that an authentication ID is selected. Select Update, and then select Confirm change connectivity type.
3. Create an indirectly connected digital twin instance. Select the adapter without gateway target mapping, associate the gateway that you updated, and don't specify an authentication ID.
4. Open the indirectly connected instance and select Edit. Change the connectivity type to Directly connected, select the adapter without gateway target mapping, and select an authentication ID. Select Update, and then confirm the change.
5. After the former gateway has no indirectly connected devices, open it and select Edit. Change the connectivity type to Directly connected, select the adapter without gateway target mapping, keep or select its authentication ID, and then update and confirm the change.

Change the directly connected instance to a gateway:

oci iot digital-twin-instance update \
  --digital-twin-instance-id <direct-instance-OCID> \
  --connectivity-type GATEWAY \
  --auth-id <authentication-OCID> \
  --digital-twin-adapter-id <gateway-adapter-OCID> \
  --force

Create an indirectly connected instance associated with the gateway:

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --display-name <indirect-device-name> \
  --external-key <indirect-device-external-key> \
  --connectivity-type INDIRECT \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <direct-adapter-OCID>

Reassign the indirectly connected instance to direct connectivity:

oci iot digital-twin-instance update \
  --digital-twin-instance-id <indirect-device-instance-OCID> \
  --connectivity-type DIRECT \
  --auth-id <device-authentication-OCID> \
  --digital-twin-adapter-id <direct-adapter-OCID> \
  --force

After all downstream devices are reassigned, change the gateway to direct connectivity:

oci iot digital-twin-instance update \
  --digital-twin-instance-id <gateway-instance-OCID> \
  --connectivity-type DIRECT \
  --auth-id <authentication-OCID> \
  --digital-twin-adapter-id <direct-adapter-OCID> \
  --force

Run the UpdateDigitalTwinInstance operation to change the directly connected instance to a gateway:

{
  "connectivityType": "GATEWAY",
  "authId": "<authentication-OCID>",
  "digitalTwinAdapterId": "<gateway-adapter-OCID>"
}

Run the CreateDigitalTwinInstance operation to create an indirectly connected instance:

{
  "displayName": "<indirect-device-name>",
  "externalKey": "<indirect-device-external-key>",
  "connectivityType": "INDIRECT",
  "digitalTwinAdapterId": "<direct-adapter-OCID>",
  "gateways": [
    "<gateway-instance-OCID>"
  ]
}

Update the indirectly connected instance to direct connectivity by supplying an authentication ID and an adapter without gateway target mapping:

{
  "connectivityType": "DIRECT",
  "authId": "<device-authentication-OCID>",
  "digitalTwinAdapterId": "<direct-adapter-OCID>"
}

After no indirectly connected devices depend on the gateway, update it to direct connectivity:

{
  "connectivityType": "DIRECT",
  "authId": "<authentication-OCID>",
  "digitalTwinAdapterId": "<direct-adapter-OCID>"
}

Step 3: Verify the Destination Configurations

Get each updated digital twin instance and confirm its lifecycle state is ACTIVE.
Confirm each instance uses the expected connectivity type, model, and adapter.
Confirm directly connected instances have authentication IDs and no gateway associations.
If you retain an indirectly connected instance, confirm that it has no authentication ID and has at least one active gateway association.
If you retain a gateway instance, confirm that it has an authentication ID, an adapter with gateway target mapping, and the intended downstream associations.

Troubleshooting

The destination configuration is rejected

An HTTP 400 response means that the connectivity type and companion settings aren't valid together. Check the model compatibility, authentication ID, adapter target mapping, and gateway associations, and then resubmit the complete destination configuration.

The gateway update returns HTTP 409

One or more active indirectly connected digital twin instances still use the gateway. Reassign those instances to another gateway or change them to a supported connectivity type, and then retry the gateway update.

An indirect configuration retains an authentication ID

An indirectly connected instance can't have an authentication ID. Don't pass --auth-id null because the CLI treats null as text. When you must explicitly clear the value, use the API with "authId": null.

The adapter doesn't match the destination type

For GATEWAY, select an adapter with gateway target mapping. For DIRECT or INDIRECT, select an adapter without gateway target mapping.

You need a Not connected instance

Don't try to change the existing instance to NONE. Create a new digital twin instance and select Not connected in the Console or specify NONE in the CLI or API.

FAQs

Are Not connected and NONE the same connectivity type?: Yes. Not connected is the Console label, and NONE is the corresponding CLI and API value.
Can I change an existing digital twin instance to Not connected?: No. Create a new Not connected instance instead.
Can I change the model during the connectivity update?: Only to a compatible model with the same DTMI path and major version and the same or a higher minor version. You can't select an unrelated model.
Why must I reassign indirectly connected devices first?: Those devices depend on the gateway configuration. The gateway can't change to another connectivity type while active downstream instances still use it.
Can I submit the current connectivity type again?: Yes. A same-type update is idempotent when the complete configuration remains valid.

For more questions, see Indirectly Connected Devices and Gateways FAQs.

Next Steps

For more information about creating new resources or getting details for existing resources, see:

Oracle Cloud Infrastructure Documentation