IoT Platform provides device shadows to cache device status. Online devices can receive commands from IoT Platform. If devices are offline, you can request commands from IoT Platform after the devices go online.

What is a device shadow?

A device shadow is a JSON file that is used to store the status submitted by a device and the desired device status obtained from applications.

Each device has only one shadow. A device can obtain or set the shadow in IoT Platform over Message Queuing Telemetry Transport (MQTT) to synchronize the status.

Scenarios

  • Applications request the device status.

    Description:

    • 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 at the same time. The device cannot process the concurrent requests and return responses to the applications.

    You can synchronize the status from the device to the shadow in IoT Platform. Applications can obtain the latest status 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.

    Device network instability
  • 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 determine 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.

    Applications send commands

View and update a device shadow

After you develop the device and connected devices, you can view and update the device shadow status in the IoT Platform console.

  1. Log on to the IoT Platform console.
  2. In the left-side navigation pane, choose Devices > Devices.
  3. On the Devices page, find the device that you want to manage and click View in the Actions column. The Device Details page appears.
  4. Click the Device Shadow tab. On this tab, you can view the device shadow submitted by the device.
    Device shadow
  5. 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 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. After the device goes online, the device pulls the latest desired status from IoT Platform.

Related API operations

GetDeviceShadow: queries a device shadow.

UpdateDeviceShadow: updates a device shadow.