Scenario: Setting Up Resources for IoT Flow Runtime Scenarios

1. Create Digital Twin Models
2. Create Digital Twin Adapters
3. Create Digital Twin Instances

Each scenario uses the following network setup.

The flow runtime scenarios use the following names. If you use different names, update every corresponding topic, external key, and flow value.

You need access to the Node-RED editor for the Flow Runtime, and an MQTT client such as MQTTX.

Create an MQTTX connection with these settings:

Description of the placeholder values in this example.

Create digital twin models for gateway health telemetry, HVAC telemetry, and Boiler temperature and pressure telemetry. Save the following specifications as gateway-model.json, hvac-model.json, and boiler-model.json.

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1"
  ],
  "@id": "dtmi:com:oracle:iot:flowruntime:GatewayGuide;1",
  "@type": "Interface",
  "displayName": "Flow Runtime Gateway Guide Model",
  "contents": [
    {"@type": ["Telemetry", "Historized"], "name": "cpuUtilization", "schema": "integer"},
    {"@type": ["Telemetry", "Historized"], "name": "memoryUtilization", "schema": "integer"},
    {"@type": ["Telemetry", "Historized"], "name": "storageUtilization", "schema": "integer"},
    {"@type": ["Telemetry", "Historized"], "name": "firmwareVersion", "schema": "string"}
  ]
}

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1"
  ],
  "@id": "dtmi:com:oracle:iot:flowruntime:HVACGuide;1",
  "@type": "Interface",
  "displayName": "Flow Runtime HVAC Guide Model",
  "contents": [
    {"@type": ["Telemetry", "Historized"], "name": "temperature", "schema": "double"},
    {"@type": ["Telemetry", "Historized"], "name": "humidity", "schema": "double"},
    {"@type": ["Telemetry", "Historized"], "name": "pressure", "schema": "double"},
    {"@type": ["Telemetry", "Historized"], "name": "mode", "schema": "string"}
  ]
}

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:boiler;1",
  "@type": "Interface",
  "displayName": "Boiler",
  "description": "A digital twin model for Boiler",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "pressure",
      "schema": "integer"
    }
  ]
}

Each gateway and HVAC message produces four normalized rows. Each Boiler message produces two normalized rows, one each for temperature and pressure.

Create a digital twin adapter for each model. Save the following definitions as gateway-envelope.json, gateway-routes.json, hvac-envelope.json, hvac-routes.json, boiler-envelope.json, and boiler-routes.json.

{
  "referenceEndpoint": "/data",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "cpuUtil": 30,
      "memUtil": 25,
      "diskUtil": 20,
      "firmware": "Oracle Linux 9.1"
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time",
    "target": "${if ([\"boilers\", \"hvacs\"] | contains([endpoint(1)])) then endpoint(2) else null end}",
    "contentRoot": "$"
  }
}

[
  {
    "condition": "${endpoint(1) == \"data\"}",
    "referencePayload": {
      "dataFormat": "JSON",
      "data": {
        "time": 1773768299143534,
        "cpuUtil": 30,
        "memUtil": 25,
        "diskUtil": 20,
        "firmware": "Oracle Linux 9.1"
      }
    },
    "payloadMapping": {
      "$.cpuUtilization": "$.cpuUtil",
      "$.memoryUtilization": "$.memUtil",
      "$.storageUtilization": "$.diskUtil",
      "$.firmwareVersion": "$.firmware"
    }
  }
]

{
  "referenceEndpoint": "/data",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temperature": 72,
      "humidity": 45,
      "pressure": 101.2,
      "mode": "cool"
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

[
  {
    "condition": "*",
    "referencePayload": {
      "dataFormat": "JSON",
      "data": {
        "time": 1773768299143534,
        "temperature": 72,
        "humidity": 45,
        "pressure": 101.2,
        "mode": "cool"
      }
    },
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.humidity": "$.humidity",
      "$.pressure": "$.pressure",
      "$.mode": "$.mode"
    }
  }
]

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "timestamp": 1773768299143534,
      "temperature": 0,
      "pressure": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.timestamp"
  }
}

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.pressure": "$.pressure"
    }
  }
]

The gateway target mapping delegates messages published to hvacs/<external-key> or boilers/<external-key> to the matching indirectly connected digital twin instance.

Create the directly connected gateway digital twin instance first, and then create two indirectly connected HVAC and two indirectly connected Boiler digital twin instances. The example flows authenticate to the device host as fr-guide-gw-01.

External publishers use source/<device-type>/<external-key>. The Function node converts that topic to the device-host topic required by the adapters.

For one Flow Runtime, subscribe to source/+/+. To distribute messages between two Flow Runtimes, subscribe both runtimes to $share/fr-guide/source/+/+, use MQTT 5.0, and give each runtime a different client ID, such as fr-guide-fr1 and fr-guide-fr2. Publishers continue to publish to the ordinary source/... topics.

After publishing a message, use the message timestamp to verify the target digital twin instance in the OCI Console.

• Confirm that the gateway, HVAC, and Boiler digital twin instances are active.
• Confirm that the raw or ingested data view contains the new gateway or indirectly connected device message.
• Confirm that the gateway snapshot includes cpuUtilization, memoryUtilization, storageUtilization, and firmwareVersion.
• Confirm that each HVAC snapshot includes temperature, humidity, pressure, and mode.
• Confirm that each Boiler snapshot includes temperature and pressure.
• Confirm that four normalized and historical values are created for each gateway and HVAC example message, and two normalized values are created for each Boiler example message.

• If an instance creation request is rejected, confirm that the gateway uses an authentication ID and the adapter with gateway target mapping. Confirm that each indirectly connected HVAC or Boiler instance has no authentication ID, uses its device-specific adapter without gateway target mapping, and lists the active gateway.
• If an HVAC or Boiler message is assigned to the wrong instance, confirm that the topic external key exactly matches an active instance of that device type associated with the gateway.
• If no normalized values appear, confirm that the model content paths match the adapter payload mappings and that the incoming timestamp and numeric values match the sample format.
• If a Flow Runtime can't reach an external broker or the IoT device host, confirm the subnet route, NAT gateway or approved egress path, NSG rules, TLS, and outbound TCP port 8883.
• If an OCI node reports an authorization error in a later scenario, confirm that the Flow Runtime matches the dynamic group and that the resource principal policy grants access to the exact Object Storage bucket, Notifications topic, or digital twin command operation.

For general recovery steps, see Troubleshooting IoT Flow Runtimes.

Why do I create the gateway before the HVAC and Boiler instances?

An indirectly connected digital twin instance must reference at least one active gateway when it is created.

Why does the gateway use a different adapter?

The gateway adapter contains target mapping that delegates forwarded messages to the matching HVAC or Boiler instance. The HVAC and Boiler adapters map the delegated device payloads and don't contain gateway target mapping.

Do I repeat this setup for every Flow Runtime scenario?

No. Create the shared models, adapters, gateway, HVAC instances, and Boiler instances once, and reuse them in the live data ingestion, batch data ingestion, and monitoring scenarios.

Can I use my own resource names and external keys?

Yes. Replace every matching topic, external key, flow value, and OCID consistently across the setup and the individual scenario.

Use the IoT resources created in this scenario to complete any of these scenarios.

• Scenario: Ingesting Live Data from an External Broker
• Scenario: Ingesting Batch Data from Object Storage
• Scenario: Monitoring Normalized IoT Data and Sending Email Alerts