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.

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 not be able 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. Example message:

   Topic: $oc/devices/{device_id}/sys/properties/set/request_id={request_id} 
   Data format:
   {
       "object_device_id": "{object_device_id} ",
       "services": [
           {
               "service_id": "Temperature",
               "properties": {
                   "value": 57,
                   "value2": 60
               }
           },
           {
               "service_id": "Battery",
               "properties": {
                   "level": 80,
                   "level2": 90
               }
           }
       ]
   }

6. The device sends a response. When desired properties are delivered to a device, the device needs to return a response to indicate that the request has been received. Example message:

   Topic: $oc/devices/{device_id}/sys/properties/set/response/request_id={request_id}
   Data format:
   {
       "result_code": 0,
       "result_desc": "success"
   }

7. When a device reports properties, the platform stores the latest property values reported by the device.

• When the device reports properties, the platform changes the properties in the reported section to those reported by the device. Example message:

Topic: $oc/devices/{device_id}/sys/properties/report   
Data format:
{
    "services": [
        {
            "service_id": "Temperature",
            "properties": {
                "value": 57,
                "value2": 60
            },
            "event_time": "20151212T121212Z"
        },
        {
            "service_id": "Battery",
            "properties": {
                "level": 80,
                "level2": 90
            },
            "event_time": "20151212T121212Z"
        }
    ]
}

• The device proactively deletes the reported section of the device shadow.
  • The device proactively deletes a single property from services in the reported section.
    When a device reports a null property, the platform deletes the property from the reported section of the device shadow. An example message is as follows:

    Topic: $oc/devices/{device_id}/sys/properties/report  
    {
        "services": [
            {
                "service_id": "Temperature",
                "properties": {
                    "value": null,
                    "value2": 60
                },
                "event_time": "20151212T121212Z"
            }
        ]
    }

  • The device proactively deletes all properties from services in the reported section.
    When a device reports properties that are set to {}, the platform deletes all property from services in reported section of the device shadow. An example message is as follows:

    Topic: $oc/devices/{device_id}/sys/properties/report 
    {
        "services": [
            {
                "service_id": "Temperature",
                "properties": {},
                "event_time": "20151212T121212Z"
            }
        ]
    }

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" : "********",
     "shadow" : [ {
       "desired" : {
         "properties" : {
           "temperature" : "60"
         },
         "event_time" : "20151212T121212Z"
       },
       "service_id" : "WaterMeter",
       "reported" : {
         "properties" : {
           "temperature" : "60"
         },
         "event_time" : "20151212T121212Z"
       },
       "version" : 1
     } ]
   }

Query, Modification, and Deletion

Querying a device shadow

Method 1: Use an application to call the API for querying a device shadow.

Modifying a device shadow

Method 1: Use an application to call the API for configuring desired properties in a device shadow.

Method 2: Log in to the console and click the target instance card. In the navigation pane, choose Devices > All Devices. On the displayed page, locate the target device, and click View in the Operation column to access its details page. Click the Device Shadow tab, and click Configure Property. In the displayed dialog box, enter the desired value and click OK.

Figure 2 Device shadow - Configuring property

Deleting a device shadow

After a device shadow is deleted, the platform clears all data (including the reported and desired values) in the device shadow.

Figure 3 Deleting a device shadow

APIs

Querying a Device Shadow

Configuring Desired Properties in a Device Shadow