Oracle Cloud Infrastructure Documentation

Scenario: Upgrade a Digital Twin Instance to a Compatible Digital Twin Model Version

Upgrade a digital twin instance by creating a compatible minor version of the digital twin model, creating a new digital twin adapter for that digital twin model version, and then updating the digital twin instance to use the new digital twin adapter without deleting the digital twin instance.

Use this scenario when a replacement or upgraded device sends an additive payload shape, such as a new telemetry value, and you want to preserve continuity for the existing digital twin instance. The digital twin model remains the contract for normalized data. The digital twin adapter maps the incoming device payload to that contract.

OCI IoT supports updating an active digital twin instance to a different digital twin adapter when the new digital twin adapter references the same digital twin model version or a compatible higher minor version of the same digital twin model. This scenario shows how to build on a base HVAC digital twin model and how to create a new HVAC digital twin model version with an additional sensor while keeping the previous digital twin model intact.

Major digital twin model version changes are incompatible for this upgrade flow. Downgrades are not supported.

HVAC stands for Heating, Ventilation, and Air Conditioning, referring to the different systems used in buildings to regulate indoor temperature, humidity, and overall air quality.

Tasks

  1. Review compatible digital twin model versioning rules.
  2. Create the base HVAC digital twin model.
  3. Create the base HVAC digital twin adapter.
  4. Create the digital twin instance.
  5. Send telemetry to the base digital twin instance.
  6. Create a compatible minor digital twin model version.
  7. Create a digital twin adapter for the new digital twin model version.
  8. Update the digital twin instance to use the new digital twin adapter.
  9. Validate digital twin instance telemetry after the upgrade.
  10. Review FAQs.
  11. Troubleshoot digital twin model upgrade issues.

Best Practices

  • Adding values to an existing digital twin model: Use the steps in this scenario to create a minor DTMI version for additive digital twin model changes, for example change the version number from 1 to 1.1, this keeps the major DTMI version the same when updating an existing digital twin instance to a new digital twin adapter, as supported in the DTDL v3 Specification:

    dtmi:com:oracle:example:hvac;1 to dtmi:com:oracle:example:hvac;1.1

  • Creating new values in your digital twin model, then create a new digital twin instance: Use a new major DTMI version, when you need to create a digital twin model with different values. For this type of update, you need to create a new digital twin instance with a new digital twin model major version change, for example:

    dtmi:com:oracle:example:hvac;1 to dtmi:com:oracle:example:hvac;2

  • Inheritance recommended: For minor updates, adding new values, it's recommended to use inheritance for additive digital twin model changes, such as a digital twin model that extends the previous digital twin model version. Instead of redefining basic attributes such as @id, location, or core status for every new digital twin model version, the new digital twin model inherits the values automatically, reducing errors and saving development time.
  • Keep existing telemetry, properties, commands, relationships, and schemas compatible. Do not rename, remove, narrow, or change existing contract elements during a minor upgrade.
  • Create a new digital twin adapter for the new digital twin model version and keep the previous digital twin adapter available for rollback until the upgraded devices are validated.
  • Test payloads with representative telemetry before a production rollout.

Understanding the Files in this Scenario

  • hvac-model.json: Base DTDL digital twin model for temperature and humidity telemetry.
  • hvac-envelope.json: Base digital twin adapter envelope that extracts timeObserved.
  • hvac-routes.json: Base digital twin adapter route mapping for temperature and humidity.
  • hvac-e-model.json: Compatible minor DTDL digital twin model version that adds energy consumption telemetry.
  • hvac-e-envelope.json: Upgraded digital twin adapter envelope that accepts the extra telemetry field.
  • hvac-e-routes.json: Upgraded digital twin adapter route mapping for temperature, humidity, and energy consumption.

Step 1: Review Compatible Digital Twin Model Versioning Rules

When you create a digital twin model, OCI IoT checks if an active digital twin model already exists for the same major version.

If one exists, a new minor version digital twin model must be a strictly additive with a compatible version number and values. When you update a digital twin instance to use a different digital twin adapter, the adapter must reference the same digital twin model version or a compatible higher minor version.

The following compatibility checks apply between the old digital twin model version and the new digital twin model version:

When you create an upgraded digital twin interface and model version the new minor version must be the exact the previous minor version plus .1 for example:

dtmi:com:oracle:example:hvac;1 to dtmi:com:oracle:example:hvac;1.1

All the interface @id values including the scheme and path must match, the new minor version the only things that can be new are the version number with minor increments and any additional values that are added to the existing model. Upgrades are only compatible when the major version stays constant and is unchanged.

DTDL ElementCompatibility RuleNote
InterfaceExisting extends values must remain the same. Additional extends are allowed. All existing model contents must remain with the same name. New contents is allowed. Schema collections must have same size and same schema ID paths.Adding reusable interface schemas is not supported and rejected.
TelemetryExisting telemetry must keep the same name, DTDL class, semantic or adjunct types, @id path, unit, schema, and validation constraints.comment, displayName, and description are not compared.
PropertyExisting properties must keep the same content rules, writable setting, schema, unit, and validation constraints.Applies to interface properties and relationship properties.
CommandExisting commands must remain. Request and response presence, names, schemas, and validation constraints must match.Adding, removing, or changing a request or response is incompatible.
RelationshipExisting relationships must keep the same writable setting, target, minimum multiplicity, maximum multiplicity, and existing relationship properties.New relationship properties are allowed.
ComponentThe component schema must remain the same.The referenced component interface is not recursively compared in this check.
SchemaThe concrete schema type must remain the same. Existing primitive, geospatial, array, enum, map, object, and field schemas must retain compatible types and validation constraints.Primitive-to-object, enum-to-map, and similar changes are incompatible.
EnumExisting enum values must remain with the same name and literal value.New enum values are allowed.
ObjectExisting fields must remain. Each existing field schema and validation constraint must match.New object fields are allowed.
Interface schemasEach old reusable schema must exist in the new digital twin model by the same DTMI scheme and path and pass its schema-specific comparison.Removing or changing an existing reusable schema is incompatible. New reusable schemas are allowed when supported.

Step 2: Create the Base HVAC Digital Twin Model

Create the base digital twin model with temperature and humidity telemetry.

  • Use the Console to create the base HVAC digital twin model in the IoT domain.

    1. On the IoT domains list page, open the IoT domain you want to work with.
    2. Select the Digital twin models tab, and then select Create.
    3. Upload or paste the DTDL JSON from hvac-model.json.
    4. Select Create.
    hvac-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

  • Use the oci iot digital-twin-model create command to create the base HVAC digital twin model in the IoT domain.

    oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://hvac-model.json
    hvac-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

  • Run the CreateDigitalTwinModel operation to create the base HVAC digital twin model in the IoT domain.

    Use the same DTDL payload shown in hvac-model.json when you call the API.

Step 3: Create the Base HVAC Digital Twin Adapter

Create a digital twin adapter that references the base HVAC digital twin model version and maps the device payload to the digital twin model telemetry fields.

  • Use the Console to create the base HVAC digital twin adapter and upload or paste the inbound envelope and routes JSON.

    1. On the IoT domains list page, open the IoT domain you want to work with.
    2. Select the Digital twin adapters tab, and then select Create.
    3. Enter a name and optional description for the base HVAC digital twin adapter.
    4. Select the base HVAC digital twin model with the DTMI dtmi:com:oracle:example:hvac;1.
    5. Turn on Specify inbound envelope and routes, and then upload or paste hvac-envelope.json and hvac-routes.json.
    6. Select Create.
    hvac-envelope.json
    {
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temp": 0,
      "hum": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}
    hvac-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temp",
      "$.humidity": "$.hum"
    }
  }
]

  • Use the oci iot digital-twin-adapter create command to create the base HVAC digital twin adapter.

    oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1" \
  --inbound-envelope file://hvac-envelope.json \
  --inbound-routes file://hvac-routes.json
    hvac-envelope.json
    {
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temp": 0,
      "hum": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}
    hvac-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temp",
      "$.humidity": "$.hum"
    }
  }
]

  • Run the CreateDigitalTwinAdapter operation to create the base HVAC digital twin adapter in the IoT domain.

    Use the same inbound envelope and inbound routes payloads shown in the downloadable files.

Step 4: Create the Digital Twin Instance

Create a digital twin instance that uses the base HVAC digital twin adapter. The external key is the user name that the device uses when it connects.

  • Use the Console to create the digital twin instance for the HVAC device.

    1. On the IoT domains list page, open the IoT domain you want to work with.
    2. Select the Digital twin instances tab, and then select Create.
    3. Enter LG HVAC 1 as the display name.
    4. Select the base HVAC digital twin adapter created in Step 3.
    5. Select the authentication ID or paste the certificate or secret OCID.
    6. Enter hvac1 as the external key.
    7. Select Create.

  • Use the oci iot digital-twin-instance create command to create the digital twin instance.

    oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --display-name "LG HVAC 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <base-digital-twin-adapter-OCID> \
  --external-key hvac1

  • Run the CreateDigitalTwinInstance operation to create the digital twin instance.

    Use the base HVAC digital twin adapter OCID and the authentication ID for the device credentials.

Step 5: Send Telemetry to the Base Digital Twin Instance

Send a payload that matches the base digital twin adapter mapping, and then get the digital twin instance content to verify the normalized telemetry.

  • Use MQTTX to send telemetry over MQTTS.

    mqttx pub \
  -t "data" \
  -m '{
    "temp": 70,
    "hum": 60
  }' \
  -u hvac1 \
  -P '<secret-contents>'

  • Use curl to send telemetry over HTTPS. This example uses HTTP basic authentication with the digital twin instance external key and the plain-text secret contents.

    curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temp": 70,
    "hum": 60
  }'

Get the digital twin instance content to verify the latest normalized values.

  • On the Digital twin instances tab, open the digital twin instance details page for LG HVAC 1 and review the latest content values.

  • Use the oci iot digital-twin-instance get-content command to get content from the digital twin instance.

    oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>

  • Run the GetDigitalTwinInstanceContent operation to get content from the digital twin instance.

Step 6: Create a Compatible Minor HVAC Digital Twin Model Version

Create a compatible minor digital twin model version that extends the base HVAC digital twin model and adds telemetry for energy consumption. The major version stays 1, and the minor version increases to 1.1.

  • Use the Console to create the compatible minor HVAC digital twin model version in the IoT domain.

    1. On the IoT domains list page, open the IoT domain you want to work with.
    2. Select the Digital twin models tab, and then select Create.
    3. Upload or paste the DTDL JSON from hvac-e-model.json.
    4. Select Create.
    hvac-e-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1.1",
  "@type": "Interface",
  "extends": "dtmi:com:oracle:example:hvac;1",
  "displayName": "HVACe",
  "description": "A digital twin model for HVACe",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "energyConsumption",
      "schema": "integer"
    }
  ]
}

  • Use the oci iot digital-twin-model create command to create the compatible minor HVAC digital twin model version.

    oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://hvac-e-model.json
    hvac-e-model.json
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1.1",
  "@type": "Interface",
  "@extends": "dtmi:com:oracle:example:hvac;1",
  "displayName": "HVACe",
  "description": "A digital twin model for HVACe",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "energyConsumption",
      "schema": "integer"
    }
  ]
}

  • Run the CreateDigitalTwinModel operation to create the compatible minor HVAC digital twin model version in the IoT domain.

    Use the same DTDL payload shown in hvac-e-model.json when you call the API.

Step 7: Create a Digital Twin Adapter for the New Digital Twin Model Version

Create a new digital twin adapter that references the compatible minor HVAC digital twin model version and maps the additional telemetry field.

  • Use the Console to create the upgraded HVAC digital twin adapter and upload or paste the inbound envelope and routes JSON.

    1. On the IoT domains list page, open the IoT domain you want to work with.
    2. Select the Digital twin adapters tab, and then select Create.
    3. Enter a name and optional description for the upgraded HVAC digital twin adapter.
    4. Select the HVAC digital twin model version with the DTMI dtmi:com:oracle:example:hvac;1.1.
    5. Turn on Specify inbound envelope and routes, and then upload or paste hvac-e-envelope.json and hvac-e-routes.json.
    6. Select Create.
    hvac-e-envelope.json
    {
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temp": 0,
      "hum": 0,
      "ec": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}
    hvac-e-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temp",
      "$.humidity": "$.hum",
      "$.energyConsumption": "$.ec"
    }
  }
]

  • Use the oci iot digital-twin-adapter create command to create the upgraded HVAC digital twin adapter.

    oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1.1" \
  --inbound-envelope file://hvac-e-envelope.json \
  --inbound-routes file://hvac-e-routes.json
    hvac-e-envelope.json
    {
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temp": 0,
      "hum": 0,
      "ec": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}
    hvac-e-routes.json
    [
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temp",
      "$.humidity": "$.hum",
      "$.energyConsumption": "$.ec"
    }
  }
]

  • Run the CreateDigitalTwinAdapter operation to create the upgraded HVAC digital twin adapter in the IoT domain.

    Use the same inbound envelope and inbound routes payloads shown in the downloadable files.

Step 8: Update the Digital Twin Instance to Use the New Digital Twin Adapter

Update the existing digital twin instance to reference the digital twin adapter for the compatible minor digital twin model version. The digital twin instance keeps the same identity, external key, and data continuity while it starts accepting payloads for the new digital twin model contract.

Note

Use a new digital twin instance instead of updating the existing digital twin instance when the replacement digital twin model uses a new major version, removes existing elements, renames fields, narrows constraints, or otherwise changes the digital twin model contract in a non-additive way.

  • Use the Console to update the existing digital twin instance to use the upgraded HVAC digital twin adapter.

    1. On the IoT domains list page, open the IoT domain you want to work with.
    2. Select the Digital twin instances tab.
    3. Open the digital twin instance details page for LG HVAC 1.
    4. Select Edit.
    5. Change the digital twin adapter to the upgraded HVAC digital twin adapter created in Step 7.
    6. Save the changes.

  • Use the oci iot digital-twin-instance update command to update the digital twin instance.

    oci iot digital-twin-instance update \
  --digital-twin-instance-id <lg-hvac-1-OCID> \
  --digital-twin-adapter-id <upgraded-digital-twin-adapter-OCID>

  • Run the UpdateDigitalTwinInstance operation to update the digital twin instance.

    Set the digital twin adapter ID to the OCID of the upgraded HVAC digital twin adapter.

Step 9: Validate Digital Twin Instance Telemetry After the Upgrade

Send a payload that includes the new telemetry field and verify that the digital twin instance content includes the values mapped by the upgraded digital twin adapter.

If validation fails, compare the digital twin model DTMI, digital twin adapter --digital-twin-model-spec-uri, envelope mapping, and route payload mapping. The upgraded digital twin adapter must reference the compatible minor digital twin model version and map payload fields to the names defined by that digital twin model.

  • Use MQTTX to send telemetry over MQTTS.

    mqttx pub \
  -t "data" \
  -m '{
    "temp": 70,
    "hum": 60,
    "ec": 38
  }' \
  -u hvac1 \
  -P '<secret-contents>'

  • Use curl to send telemetry over HTTPS. This example uses HTTP basic authentication with the digital twin instance external key and the plain-text secret contents.

    curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temp": 70,
    "hum": 60,
    "ec": 38
  }'

Optional Step: Get Contents

Get the digital twin instance content to verify the latest normalized values.

  • On the Digital twin instances tab, open the digital twin instance details page for LG HVAC 1 and review the latest content values.

  • Use the oci iot digital-twin-instance get-content command to get content from the digital twin instance.

    oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>

  • Run the GetDigitalTwinInstanceContent operation to get content from the digital twin instance.

FAQ

This FAQ describes compatible digital twin model upgrades and additive payload shapes.

What is an additive payload shape?
An additive payload shape keeps the existing payload fields and adds new fields without changing the existing field names, data types, meaning, units, or constraints. In this scenario, the base payload { "temp": 70, "hum": 60 } becomes { "temp": 70, "hum": 60, "ec": 38 }. The payload is additive because temp and hum still mean the same thing and the device only adds ec for energy consumption.
How does an additive payload shape relate to the digital twin model version?
The device payload and the digital twin model must evolve together. The new digital twin model version adds energyConsumption while keeping the existing temperature and humidity telemetry compatible. The upgraded digital twin adapter maps the new payload field ec to the new digital twin model field energyConsumption.
What is not additive?
A change is not additive if it renames an existing field, removes an existing field, changes a schema type, changes units or meaning, narrows validation constraints, changes command request or response contracts, or moves to a different major digital twin model version. For example, changing hum to humidityPct or changing temp from an integer to a string is not additive.
Can old devices keep sending the original payload?
Yes, old devices can keep sending the original fields if the upgraded digital twin adapter mapping still handles them. The new field is only populated when the upgraded device sends it and the digital twin adapter maps it to the new digital twin model field.

Troubleshooting

The digital twin model creation request is rejected

The new minor digital twin model version might have changed an existing contract element instead of only adding new content. Compare the old and new DTDL digital twin models. Existing telemetry, properties, commands, relationships, schemas, and validation constraints must remain compatible.

The digital twin instance update request is rejected

The new digital twin adapter might reference an incompatible digital twin model version, a different major version, or a downgrade. Confirm that the digital twin adapter uses the same digital twin model version or the next compatible higher minor version, such as dtmi:com:oracle:example:hvac;1.1.

The upgrade succeeds, but the new field is not stored

The digital twin instance might still use the old digital twin adapter, or the upgraded route mapping might not map the new payload field. Verify the digital twin instance's digital twin adapter OCID and check that hvac-e-routes.json maps $.energyConsumption to $.ec.

Existing telemetry is missing after the upgrade

The upgraded digital twin adapter mapping might have dropped the existing payload mappings or changed the payload path. Keep the existing mappings for temperature and humidity, and then add the new mapping for energyConsumption.

Old devices fail after the digital twin instance moves to the upgraded digital twin adapter

The upgraded digital twin adapter might require the new field or no longer support the original payload shape. Make the digital twin adapter mapping tolerant of payloads that do not include the new field, or move devices in smaller groups after validating each device payload shape.