IoT Platform provides device shadows to cache device status. An online device can directly receive commands from IoT Platform. An offline device can actively request cached commands from IoT Platform after the device comes online again.

Scenarios

A device shadow is a JSON file that is used to store the status that a device reports and the device status that applications desire.

Each device has only one shadow. A device can obtain and set the shadow by using Message Queuing Telemetry Transport (MQTT) for status synchronization. The synchronization is bi-directional, either from the shadow to the device or from the device to the shadow.

Device shadows can be used in the following scenarios:

  • Scenario 1: On an unstable network, a device frequently disconnects from and reconnects to IoT Platform.

    A device frequently disconnects from and reconnects to IoT Platform due to network instability. When an application requests the status of the device, the device goes offline, which leads to a request failure. When the device is reconnected, the application fails to initiate another status request.

    Based on the device shadow feature, the latest status of the device is updated and stored in the device shadow. When an application requests the status of the device, the application can obtain the status information from the device shadow regardless of whether the device is online.

  • Scenario 2: Multiple applications simultaneously request the status information about a device.

    On a stable network, multiple applications simultaneously request the status information about a device. The device must respond to each status request even though the responses are the same. The device may be overloaded with the requests.

    Based on the device shadow feature, the device only needs to synchronize status information to its shadow. Applications can obtain the latest status information from the device shadow instead of the device. This way, the applications are decoupled from the device.

  • Scenario 3: A device goes offline.
    • On an unstable network, a device frequently disconnects from and reconnects to IoT Platform. When an application sends a control command to the device, the device goes offline. The command fails to be dispatched to the device.
      • Quality of Service 1 or 2 (QoS 1 or 2) may resolve this issue. However, we recommend that you do not use this method. This method increases the workload of the server.
      • Based on the device shadow feature, the control command that the application sends to the device is stored in the device shadow with the timestamp when the command is received. After the device is reconnected, the device obtains the command and checks the timestamp to determine whether to run the command.
    • A device goes offline and fails to receive a command from an application. When the device is reconnected, the device obtains the command and timestamp and determines whether to run the command. If the command has expired, the device does not run the command.

View and update a device shadow

You can view and update a device shadow in the IoT Platform console.

Procedure:

  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. The device shadow stores the status that is reported 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 information by subscribing to a specific topic. When the device is online, IoT Platform pushes the desired status information to the device in real time.

    When the device is offline, the shadow of the device caches the desired status information. After the device comes online again, it actively pulls the latest desired status information from IoT Platform.

Related API operations

GetDeviceShadow: queries a device shadow.

UpdateDeviceShadow: updates a device shadow.