Definition
Device Shadow is the virtual representation of a device in the cloud, storing Desired State and Reported State. When the device is offline, the platform can write downlink commands into the shadow, which the device will pull and execute once it goes online, ensuring that the configuration is not lost.
Core Features
- Offline Cache: Configuration distribution can be written into the shadow, which the device automatically pulls after going online
- State Synchronization: Compare desired state and reported state, supporting eventual consistency in configuration
- Remote Control: Works with Remote Control to implement offline command caching
Workflow
The application or platform writes the Desired state to the shadow; after the device comes online, it subscribes to the shadow Topic, pulls the Delta (the difference between Desired and Reported), executes configuration updates, and then reports the Reported state; the platform merges Reported and Desired to achieve final consistency. During the device offline period, Downstream Command downstream instructions can be written to the shadow, and the device will automatically synchronize after coming online, without the need for polling.
Relationship with the Thing Model
The content stored in the shadow follows the attribute structure defined by the Thing Model. It supports partial updates (updating only specified attributes) and version numbers (to prevent concurrent conflicts). It is applicable to scenarios such as configuration deployment, remote switch control, and batch parameter updates, and is one of the core mechanisms of Remote Control.
When desired and reported values count as aligned
A device shadow means the cloud keeping, for each device, two copies of state organized by the thing model: the desired value it should become, and the actual value it reports itself. The difference between them is what still has to be carried out. When the device is online, the platform can push the difference down. When the device is offline, the difference stays in the shadow and is taken when the session returns. Aligned does not mean the cloud wrote once. It means the reported value has covered the corresponding desired value, or the device has explicitly refused and given a reason. Before a report, the desired value is only an intention. A version number is used to reject a stale write. An old request that arrives later must not cover a newer request that arrived first.
What belongs in the shadow is idempotent desired configuration, such as a target switch or a target threshold. What does not belong is a momentary action that must be carried out in order every time and cannot be merged, such as a single jog. Using the shadow assumes the property has a clear type in the thing model, and that the device knows how to read the difference and report after it finishes. A partial update may change only the named properties. Properties that do not appear should stay as they were. This request must not clear other desired values just because it did not include them. Used with connection status, desired values may accumulate while offline, but the screen must say these values have not yet been confirmed by the device. A retired device should not keep accepting new desired writes.
Which offline command overrides which after they pile up
A common mistake is to queue every change to the same property and, when the device comes online, execute them one by one from old to new. The usual meaning of a shadow is that the same property keeps only the latest desired value. The values in between have no meaning on their own. If the business really must execute in order, a shadow overwrite is not enough. Another mistake is the device reporting the actual value while the cloud does not clear the difference already completed, so every reconnect writes the old desired value again, and the site sees the parameter repeatedly changed back. If the version number is not checked, two operators changing at the same time let the slower one win. A parameter changed locally, if the report overwrites the desired value, also knocks away the target the cloud has just delivered. The two sides cover each other.
If the desired structure and the reported structure disagree, for example the cloud has a field the device firmware does not yet recognize, the whole difference is rejected by the device, including the fields it does recognize. The device should be allowed to carry out the fields it knows and to report what it does not recognize. If timestamps use the device’s local clock and that clock is wrong, version comparison is scrambled. A successful write to the shadow is also not a successful execution. Device monitoring must be able to see the stretch that is desired and not yet reported, rather than the device staying offline and then coming online with no trace. Cleaning a shadow must not delete desired values that are not yet confirmed, unless someone explicitly gives up those settings.
One property keeps only the latest desired value
For the same property in the shadow, the usual meaning is to keep only the latest desired value, not to queue every change as something that must be executed one by one. If a threshold is changed three times while the device is offline, the device should see the last change when it comes online. The middle two have no execution of their own. If the business really requires a jog in order, that action should not be recorded only by an overwrite shadow. After the device reports the actual value, the difference already completed has to be cleared. Otherwise every reconnect writes the old desired value again, and the site sees the parameter jump back repeatedly. When two operators change at the same time, the request with the older version must be rejected. It must not cover the newer target just because it arrived later. If a value changed locally covers the cloud desired value unconditionally, the two sides rewrite each other and neither settles.
A new field the device does not yet recognize should not cause the whole difference to be rejected. The device should carry out the part it recognizes and say which fields were skipped. A successful write to the shadow only means the cloud has recorded an intention. Until the device reports, the screen must show not yet confirmed. It must not show already in effect. When a record is cleaned or the shadow is reset, desired values not yet confirmed have to be given up explicitly. They must not be deleted with nobody knowing, and they must not be kept and then executed if a retired device happens to come online. Properties not mentioned by a partial update should stay as they were. A request that only changes a switch must not clear other thresholds to empty.