Device shadow overview
IoT Platform provides a device shadow feature. A device shadow caches status data from a device and instructions from an application. An online device can retrieve instructions directly from IoT Platform. An offline device can pull instructions from IoT Platform when it comes back online. This topic describes the common scenarios and usage of device shadows.
What is a device shadow
A device shadow is a JSON document that stores reported device status data and desired application state information. For more information about the JSON data format, see Device shadow JSON reference.
Each device has only one device shadow. A device can use MQTT to retrieve and set the device shadow to sync its state. The synchronization can occur from the shadow to the device, or from the device to the shadow.
Differences from setting desired property values
Both the device shadow and the set desired property value features store desired data in the IoT Platform cloud. When a device comes online, it retrieves the corresponding desired data to control its business logic. The two features have different application scopes, as described in the following table.
| Feature | Difference |
| Set desired property values | This feature has a specific scope. It only sets the property values of a device's Thing Specification Language (TSL) model. Before you use this feature, you must define TSL model properties for the device. Use this feature to set the desired values of a device's TSL model properties. For a usage example, see Control a light bulb by setting desired property values. |
| Device shadow | This feature has a wider application scope and does not depend on TSL model property definitions. You can use it to set data such as device status. For specific scenarios, see the description below. For information about how to set a device shadow, see Device shadow JSON reference. |
Scenarios
You can use the device shadow feature in the following scenarios to retrieve reported device data and desired application data.
- An application requests the device status.
Scenario description:
- The device has an unstable network connection and frequently goes online and offline. It cannot respond to application requests normally.
- The device has a stable network connection but must respond to multiple application requests at the same time. Even if the responses are the same, the device's limited processing power cannot handle the load of multiple requests.
With the device shadow feature, when a device's status changes, it only needs to sync its status to the device shadow once. When an application requests the device status, it can retrieve the current status from the device shadow. This works regardless of the number of application requests or whether the device is online. This achieves decoupling between the application and the device.
The following flowchart shows how an application retrieves the device status from the device shadow. For more information about the data forwarding process, see Device reports its status.
- An application sends instructions to a device to change its status.
Scenario description: The device is offline or has an unstable network connection and frequently goes online and offline. If an application sends a control instruction to the device while it is offline, the instruction is not delivered.
With the device shadow feature, instructions sent from an application can be stored in the device shadow with a timestamp. When the device comes online again, it retrieves the instructions from the device shadow and decides whether to execute them based on the timestamp.
The following flowchart shows how an application updates the device status. For more information about the data forwarding process, see Application changes the device status, Device retrieves the shadow content, and Device deletes shadow properties.
View and update a device shadow
You must first implement the device shadow feature on the device. For more information, see Device shadow.
After the device is developed and connected to IoT Platform, you can view the device shadow information and update the device shadow status in the IoT Platform console.
- Log on to the IoT Platform console.
On the Overview page, find the instance that you want to manage and click the instance ID or instance name.
- In the navigation pane on the left, choose .
- Click View for the target device to go to the Device Details page.
- Click the Device Shadow tab. The page displays the shadow status reported by the device.
- Click Update Shadow. In the
"desired"section, enter the desired device state.For more information about the device shadow document format, see Device shadow JSON reference.
If the device is online, the device shadow saves the desired state, and the device retrieves the desired state directly by subscribing to a topic.
If the device is offline, the device shadow caches the desired state. When the device comes online, it actively pulls the latest desired state from IoT Platform.
Related API operations
GetDeviceShadow: Retrieves a device shadow.
UpdateDeviceShadow: Updates a device shadow.