IoT Platform provides the device shadow feature to cache the status data that is submitted by each device and the commands that are sent by applications. Online devices can receive commands from IoT Platform. If the devices are offline, you can request commands from IoT Platform after the devices go online. This topic describes the scenarios of the device shadow feature and how to use this feature.
Device shadows
A device shadow is a JSON file that is used to store the status data that is submitted by a device and the device status data that is desired by applications. For more information about JSON data, see JSON format of device shadows.
Each device has only one shadow. A device can obtain or configure the shadow in IoT Platform over Message Queuing Telemetry Transport (MQTT) to synchronize the status.
Differences between device shadows and desired property values
Desired property values and device shadows are desired data that is stored in IoT Platform. After devices go online, the devices obtain desired data to implement the corresponding business logic. The following table describes the differences between desired property values and device shadows based on the application scope.
| Item | Description |
| Desired property values | The application scope is narrow. You can specify values only for the Thing Specification Language (TSL) properties of a device. Before you use the feature, you must define a TSL model for a device. If you want to specify desired values for the TSL properties of a device, you can use the feature. For more examples, see Specify a desired property value to control the status of a bulb. |
| Device shadows | The application scope is broad. The feature is independent of TSL properties. You can use the feature to specify data for devices, such as device status. The following section describes specific scenarios. For more information about how to configure device shadows, see JSON format of device shadows. |
Scenarios
In the following scenarios, you can use the device shadow feature to obtain the status data that is submitted by devices and the device status data that is desired by applications.
- Applications request the device status.
Scenarios:
- A device frequently goes online and offline due to network instability. In this case, the device cannot process the requests from applications.
- Multiple applications may request the device status data at the same time. The device cannot process the concurrent requests or return responses to the applications.
You can synchronize the status from the device to the shadow in IoT Platform. Applications can obtain the most recent status data from the shadow. This way, the applications are decoupled from the device.
The following figure shows the process. For more information, see The device submits the status.
- Applications send commands to change the device status.
Description: A device is offline, or the device frequently goes online and offline due to network instability. In this case, the commands from applications may fail to be sent to the device.
You can store the commands with timestamps in the shadow. After the device goes online, the device obtains the commands from the shadow and determines whether to process the commands based on timestamps.
The following figure shows the process. For more information, see Applications change the device status, The device requests the shadow, and The device deletes shadow properties.
View and update a device shadow
You must configure the device shadow feature for the device. For more information, see Device shadow.
After you configure the device and connect the device to IoT Platform, you can view and update the device shadow status in the IoT Platform console.
- Log on to the IoT Platform console.
- On the Overview page, select an environment, find the instance that you want to manage, and click the instance ID or instance name. Important This step is required only if Enterprise Edition instances are available. If the Enterprise Edition instances are unavailable in the region that you selected, skip this step. For information about supported regions and instances, see Overview.
- In the left-side navigation pane, choose .
- On the Devices page, find the device that you want to manage and click View in the Actions column. The Device Details page appears.
- Click the Device Shadow tab. On this tab, you can view the device shadow that is submitted by the device.
- Click Update Shadow. Enter the desired status information in the
"desired"section.For information about the format of device shadows, see JSON format of device shadows.
The device obtains the desired status data by subscribing to a specific topic. If the device is online, IoT Platform pushes the desired status to the device in real time.
If the device is offline, the shadow caches the desired status data. After the device goes online, the device pulls the latest desired status data from IoT Platform.
Related API operations
GetDeviceShadow: queries a device shadow.
UpdateDeviceShadow: updates a device shadow.