← Back to Architecture Transport · Azure IoT Hub · Cloud

Device Twin
State · OTA Config

The digital twin of each IoT Pod in Azure IoT Hub. A bidirectional JSON document that keeps the on-board device's actual state and the desired configuration from the cloud in sync, including OTA firmware updates.

What it is

The Device Twin is a JSON document stored in Azure IoT Hub that acts as a persistent representation of each IoT device in the system. It is not a message stream but a state: it exists even when the device is disconnected, and it synchronises automatically the moment the CM4 regains connectivity.

Each IN-SIGHT IoT Pod has its own Device Twin with three independent sections: tags (fleet metadata), desired properties (configuration sent by the cloud) and reported properties (state reported by the device). The divergence between desired and reported indicates exactly which changes are pending application on the device.

Design principle: The Device Twin decouples the configuration channel from the telemetry channel. The EKF parameters, alert thresholds and firmware version do not travel in the data stream: they are managed independently, with explicit application confirmation from the device.

Device Twin structure in IN-SIGHT

Each IoT Pod has a structured twin with the following sections:

{
  "tags": {
    "vehicleId": "TMB-5000-04",
    "subsystem": "bogie-delantero",
    "installDate": "2025-11-12",
    "firmwareGroup": "stable"
  },
  "properties": {
    "desired": {
      "ekf": {
        "processNoise": 0.001,
        "measurementNoise": 0.05,
        "alertThresholdSigma": 3.5
      },
      "sampling": {
        "rateHz": 6667,
        "batchSeconds": 30
      },
      "firmware": {
        "version": "2.4.1",
        "url": "https://ota.in3-insight.cloud/fw/2.4.1.bin",
        "sha256": "e3b0c44298fc..."
      },
      "$version": 47
    },
    "reported": {
      "firmware": { "version": "2.4.0" },
      "sensors": {
        "imu": "ok",
        "temperature": "ok",
        "lastCalibration": "2025-12-01T08:30:00Z"
      },
      "connectivity": {
        "rssi": -67,
        "lastSeen": "2026-06-19T14:22:10Z"
      },
      "$version": 46
    }
  }
}

The difference in $version between desired (47) and reported (46) indicates a firmware change pending confirmation. Portal IN-SIGHT shows this state as "update in progress".

OTA flow — Firmware update

Firmware updates are coordinated entirely through the Device Twin, with no additional channel:

  1. Publishing: Portal IN-SIGHT writes the new version, URL and SHA-256 hash to desired.firmware.
  2. Notification: IoT Hub notifies the CM4 of the change in desired properties via MQTT in real time.
  3. Download and verification: The CM4 downloads the binary from the signed URL, verifies the SHA-256 hash and stores it in an alternate partition.
  4. Application: At the next scheduled maintenance cycle (or immediately if the version is critical), the CM4 swaps the partition and reboots.
  5. Confirmation: After the reboot, the CM4 updates reported.firmware.version. The Portal detects the convergence and marks the update as completed.
Automatic rollback: If the CM4 does not confirm the new version within the configured window (30 minutes by default), the system automatically restores the previous partition and logs the event as an OTA failure in the vehicle's history.