Updated on 2022-06-30 GMT+08:00

Device Shadow

Overview

IoTDA supports the creation of device shadows. A device shadow is a JSON file that stores the device status, latest device properties reported, and device configurations to deliver. Each device has only one shadow. A device can retrieve and set its shadow to synchronize properties, either from the shadow to the device or from the device to the shadow.

The device shadow contains two sections: desired and reported.
  • The desired section stores the desired configurations of device properties. You can modify the desired properties in the device shadow when needed. If the device is online, the desired properties are synchronized to the device immediately. If the device is offline, the desired properties are synchronized to the device when the device goes online or reports data.
  • The reported section stores the properties most recently reported by the device. When the device reports data, the platform changes the properties in the reported section to those reported by the device.
    • You can configure the device shadow by calling the platform API or by clicking Configure Property on the Device Shadow tab page of the device details page on the IoTDA console. (The device shadow is mainly used to configure device properties. Its configuration depends on the product model.)
    • The device shadow configuration is an asynchronous command. The platform directly returns a configuration response. Then, the platform determines whether to deliver the configuration immediately or cache the configuration based on the device status.
    • When the device goes online, the device shadow delivers the desired properties to the device. After the device reports its properties, the device shadow checks whether the reported properties match the delivered ones. If they match, the shadow data is configured on the device and the cache is cleared. If they do not match, the shadow data fails to be configured on the device. When the device goes online or reports properties next time, the platform delivers the desired properties to the device again until the configuration delivery is successful.
    • Restriction: Keys in the device shadow JSON file cannot contain periods (.), dollar signs ($), and the null character (hexadecimal ASCII code 00). Otherwise, the device shadow file cannot be refreshed.

Application Scenarios

The device shadow is applicable to devices with limited resources and low power consumption or devices in the dormant state for a long time.

  • Querying the latest data reported by the device and the latest online status of the device:

    • You may be unable to query the console for the mostly recent data because the device is offline or the network is unstable. With the device shadow, the platform can obtain the data from the shadow.

    • There may be too many applications simultaneously querying the device. IoT devices typically have limited processing capabilities, so too many queries can adversely affect their performance. With the device shadow, the device can synchronize its status to the shadow just once. The applications can obtain the device status from the device shadow, without reaching the real device.
  • Modifying device properties: You can modify device properties on the device details page. Because the device may be offline for a long time, the modified device properties cannot be delivered to the device in time. The platform stores these properties in the device shadow. When the device goes online, the platform synchronizes the properties from the shadow to the device.

Service Flow

Modifying a Device Property

After a property in the desired section is modified, it is synchronized to the device immediately if the device is online, or cached and delivered until the device goes online or reports data.

  1. A user modifies a device property on the console or application. Example message:
    PUT https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/shadow
    Content-Type: application/json
    X-Auth-Token: ********
    Instance-Id: ********
    
    {
      "shadow" : [ {
        "desired" : {
          "temperature" : "60"
        },
        "service_id" : "WaterMeter",
        "version" : 1
      } ]
    }
  2. The platform modifies the property in the desired section.
  3. The platform sends a response.
  4. The platform detects that the device goes online or reports data.
  5. The platform synchronizes the property to the device.
  6. The device sends a response.
  7. When the device reports data, the platform changes the properties in the reported section to those reported by the device.

Querying Device Properties

The device shadow saves the most recent device properties. Once the device properties change, the device synchronizes the changes to the device shadow. Using the device shadow, a user can obtain the device status quickly regardless of whether the device is online.

  1. A user queries device properties on the console or application. Example message:
    GET https://{Endpoint}/v5/iot/{project_id}/devices/{device_id}/shadow
    Content-Type: application/json
    X-Auth-Token: ********
    Instance-Id: ********
  2. The platform returns the desired and reported properties. Example message:

    Status Code: 200 OK

    Content-Type: application/json
    
    {
      "device_id" : "40fe3542-f4cc-4b6a-98c3-61a49ba1acd4",
      "shadow" : [ {
        "desired" : {
          "properties" : {
            "temperature" : "60"
          },
          "event_time" : "20151212T121212Z"
        },
        "service_id" : "WaterMeter",
        "reported" : {
          "properties" : {
            "temperature" : "60"
          },
          "event_time" : "20151212T121212Z"
        },
        "version" : 1
      } ]
    }

Querying and Modifying a Device Shadow

Querying a Device Shadow

Method 1: An application calls the API Querying a Device Shadow.

Method 2: Log in to the IoTDA console. In the navigation pane, choose Devices > All Devices. Click View in the role of a device to access its details. On the Device Shadow tab page, you can view the device properties, including reported and desired values.
  • If the reported value is inconsistent with the desired value, the desired value is highlighted. This may occur when the device is offline and the value is still in the device shadow waiting to be synchronized to the device.
  • If the reported value matches the desired value, the desired value is not highlighted. The latest property reported by the device matches the desired property.

Modifying a Device Shadow

Method 1: An application calls the API Configuring Desired Properties in a Device Shadow.

Method 2: Log in to the IoTDA console. In the navigation pane, choose Devices > All Devices. Click View in the role of a device to access its details. On the Device Shadow tab page, click Configure Property and enter the desired values of the service properties.

APIs

Querying a Device Shadow

Configuring Desired Properties in a Device Shadow