Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Platforms and Applications

Device Twins, Shadows and Digital Twins

Understand device shadows and twins: desired and reported state, deltas and versions, how offline devices catch up, and how digital twins model real systems.

Devices are often offline: asleep to save battery, out of coverage, rebooting. Yet an app wants to say "set the thermostat to 22 degrees" and see the current value at any moment. The trick that platforms use is a device shadow (AWS term) or device twin (Azure term): a JSON document stored in the cloud that represents the device. Apps talk to the shadow; the device synchronizes with it whenever it is connected.

This builds on the cloud platform concepts and on MQTT's retained messages, which solve a similar problem in a simpler way.

Desired, reported and delta

A shadow document has two key sections:

JSON
{
  "state": {
    "desired":  { "targetTemp": 22, "mode": "heat" },
    "reported": { "targetTemp": 20, "mode": "heat", "currentTemp": 19.4 }
  },
  "version": 12
}
  • desired is what apps and users want. Anyone with permission writes it.
  • reported is what the device says is true. Only the device writes it.
  • delta is the difference: the desired values that the device has not yet reported. Here, targetTemp: 22.
  • version increases on every change, to detect outdated writes.
sequenceDiagram
  participant A as App
  participant S as Shadow (cloud)
  participant D as Device
  A->>S: update desired {targetTemp: 22}
  S-->>D: delta {targetTemp: 22} (when online)
  D->>D: apply setting
  D->>S: update reported {targetTemp: 22}
  S-->>A: state now in sync

The app never talks to the device directly, so it works even while the device sleeps.

Building a shadow

The simulation below keeps desired and reported state, computes the delta and lets an offline device catch up after reconnecting. It also uses the version number so that an outdated update is rejected (optimistic concurrency).

Node.js A device shadow with delta and versions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

While the device was offline, two desired changes piled up in the shadow. When it woke up it received one delta containing both and applied them. The app that tried to write based on version 2 was rejected because the shadow had moved on, protecting against two apps overwriting each other.

Shadows versus retained MQTT messages

Need Retained messages Shadow
Last known value for new subscribers Yes Yes
Separate "wanted" and "actual" Manual (two topics) Built in
Compute delta Manual Built in
Versioning No Yes
Cost and complexity Minimal Platform feature

For a handful of devices on your own broker, the pair of retained topics .../set and .../state is enough. At fleet scale, the shadow adds structure.

Caveats: commands such as "unlock the door now" do not fit a shadow well, because they are events, not state. Platforms offer direct methods / commands / jobs for those, with an immediate response or error (for example Azure's direct methods).

Digital twins

A digital twin goes beyond state mirroring: it is a model of a real asset (a pump, a building, a wind turbine) that you can query, simulate and use for prediction. Shadows record what is; a digital twin can answer "what would happen if". Platforms such as Azure Digital Twins add relationships (a room contains devices, a floor contains rooms) in a graph.

A small example: a thermal model of a room predicts how fast it cools, so the system can decide when to start heating before people arrive.

Node.js A simple thermal digital twin

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The model's parameter k is calibrated with real sensor data from the actual room. When reality drifts from the model (a window was left open), the gap itself is a useful signal.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. In a device shadow, who normally writes the reported section?

    The device reports what is true; apps write desired state.
  2. 2. What is the delta?

    Delta = desired minus reported; it is what the device still has to apply.
  3. 3. Why does the shadow store a version number?

    Optimistic concurrency prevents two writers from silently overwriting each other.
  4. 4. Which fits poorly in a shadow?

    A command is an event, not state; use direct methods or jobs that report success or failure.

Summary

  • A shadow/twin is a cloud JSON document with desired and reported state, a delta and a version.
  • Apps write desired; devices report; offline devices catch up with one delta on reconnect.
  • Versions give safe concurrent updates.
  • Use shadows for state and commands/jobs for events; simpler setups can use retained set/state topics.
  • Digital twins model assets for simulation and prediction, calibrated with sensor data.

Next: IoT Applications: Home, Industry, City, Agriculture and Health