Forwarding of device shadow data - IoT Platform - Alibaba Cloud Documentation Center

Device shadow-specific topics

IoT Platform predefines two topics to forward shadow data.

/shadow/update/${YourProductKey}/${YourDeviceName}
Each device and each application publish messages to this topic. After a message is sent to the topic, IoT Platform synchronizes the status in the message to the device shadow.
/shadow/get/${YourProductKey}/${YourDeviceName}
The updated status in the device shadow is sent to this topic. Each device can subscribe to this topic to obtain the latest status.

Examples

This article describes how a device submits the status to the shadow, applications change the device status, the device requests the shadow, and the device deletes shadow properties. In this example, a light bulb device is used.

The ProductKey is a1PbRCF**** and the DeviceName is lightbulb. The device subscribes to the two device shadow-specific topics and publishes QoS 1 messages.

The device submits the status

If the device is online, the device can submit the status to its shadow. Applications obtain the status from the shadow.

The following figure shows the process of data forwarding.

When the light bulb device is online, the device submit its latest status to the shadow by using the /shadow/update/a1PbRCF****/lightbulb topic.

JSON-formatted message:

{
  "method": "update", 
  "state": {
    "reported": {
      "color": "red"
    }
  }, 
  "version": 1
}

Table 1. Parameters
Parameter	Description
method	The type of the operation in the request that the device or application sends to the device shadow. For an update operation, the method parameter is required and must be set to update.
state	The status information that the device sends to the device shadow. The reported parameter is required. The status information is synchronized to the reported parameter of the device shadow.
version	The version information in the request. This parameter is checked by the device shadow. The device shadow updates the version only when the new version specified in the request is later than the current version. If the version parameter is set to `-1`, all data of the device shadow is cleared. The device shadow updates its version to `0`.

After the device shadow receives the status that is submitted by the light bulb, the device shadow updates the JSON file.

{
  "state": {
    "reported": {
      "color": "red"
    }
  }, 
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564492
      }
    }
  }, 
  "timestamp": 1469564492, 
  "version": 1
}

After the JSON file is updated, the device shadow returns a response to the light bulb by using the /shadow/get/a1PbRCF****/lightbulb topic.

If the update succeeds, the device shadow sends the following message:

{
  "method": "reply", 
  "payload": {
    "status": "success", 
    "version": 1
  }, 
  "timestamp": 1469564576
}

If the update fails, the device shadow sends the following message:

{
  "method": "reply", 
  "payload": {
    "status": "error", 
    "content": {
      "errorcode": "${errorcode}", 
      "errormessage": "${errormessage}"
    }
  }, 
  "timestamp": 1469564576
}

Table 2. Error codes
Error code	Error message
400	The JSON format is invalid.
401	The method parameter is not specified.
402	The state parameter is not specified.
403	The value of the version parameter is not a number.
404	The reported parameter is not specified.
405	The reported parameter is empty.
406	The value of the method parameter is invalid.
407	The device shadow is empty.
408	The reported parameter contains more than 128 properties.
409	A version conflict has occurred.
500	A server exception has occurred.

Applications change the device status

An application sends the desired status to the device shadow by calling the UpdateDeviceShadow operation. Then, IoT Platform sends the shadow file to the device. The device updates its status based on the shadow file and then submits the latest status to the device shadow.

The following figure shows the process of data forwarding.

The application calls the UpdateDeviceShadow operation to change the status of the light bulb. In this example, the operation is called to change the value of the color property to green.
The following code shows the ShadowMessage parameter in the API request:
```
{
  "method": "update", 
  "state": {
    "desired": {
      "color": "green"
    }
  }, 
  "version": 2
}
```

The device shadow receives the update request and updates the JSON file.

{
  "state": {
    "reported": {
      "color": "red"
    }, 
    "desired": {
      "color": "green"
    }
  }, 
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564492
      }
    }, 
    "desired": {
      "color": {
        "timestamp": 1469564576
      }
    }
  }, 
  "timestamp": 1469564576, 
  "version": 2
}

After the device shadow completes the update, it returns a response to the /shadow/get/a1PbRCF****/lightbulb topic. The returned information is determined by the device shadow.

{
  "method": "control", 
  "payload": {
    "state": {
      "reported": {
        "color": "red"
      }, 
      "desired": {
        "color": "green"
      }
    }, 
    "metadata": {
      "reported": {
        "color": {
          "timestamp": 1469564492
        }
      }, 
      "desired": {
        "color": {
          "timestamp": 1469564576
        }
      }
    }
  }, 
  "version": 2, 
  "timestamp": 1469564576
}

If the light bulb is online and has subscribed to the /shadow/get/a1PbRCF****/lightbulb topic, the light bulb can receive a message.
After the light bulb receives the message, it changes its color to green based on the value of the desired parameter in the message.

After the light bulb updates its status, it submits the latest status to IoT Platform.
```
{
  "method": "update", 
  "state": {
    "reported": {
      "color": "green"
    }
  }, 
  "version": 3
}
```
Note If the light bulb determines that the command has expired based on the timestamp, it does not perform an update.
After the latest status is submitted to IoT Platform, the device and the device shadow perform the following operations:
- The device sends a message to the /shadow/update/a1PbRCF****/lightbulb topic to clear the desired property. The following code shows the message:
```
{
  "method": "update", 
  "state": {
    "desired": "null"
  }, 
  "version": 4
}
```
- The device shadow updates the JSON file. The following code shows the JSON file after the update:
```
{
  "state": {
    "reported": {
      "color": "green"
    }
  }, 
  "metadata": {
    "reported": {
      "color": {
        "timestamp": 1469564577
      }
    }, 
    "desired": {
      "timestamp": 1469564576
    }
  }, 
  "version": 4
}
```

The device requests the shadow

When an application sends a command, the device may be offline. After the device goes online, the device can request the shadow.

The following figure shows the process of data forwarding.

The light bulb sends the following message to the /shadow/update/a1PbRCF****/lightbulb topic to request the latest status that is stored in the device shadow:
```
{
"method": "get"
}
```

After the device shadow receives the message, the device shadow sends the latest status to the /shadow/get/a1PbRCF****/lightbulb topic. The light bulb obtains the latest status by subscribing to the topic. The following code shows the message that the device shadow sends to the device:

{
  "method": "reply", 
  "payload": {
    "status": "success", 
    "state": {
      "reported": {
        "color": "red"
      }, 
      "desired": {
        "color": "green"
      }
    }, 
    "metadata": {
      "reported": {
        "color": {
          "timestamp": 1469564492
        }
      }, 
      "desired": {
        "color": {
          "timestamp": 1469564492
        }
      }
    }
  }, 
  "version": 2, 
  "timestamp": 1469564576
}

The device deletes shadow properties

If the device is in the latest status, the device can send a command to delete properties in the device shadow.

The following figure shows the process of data forwarding.

The device sends the following message to the /shadow/update/a1PbRCF****/lightbulb topic.

In the following code, the value of the method parameter is delete. The values of the properties are null.

Deletes a property in the shadow.

{
  "method": "delete", 
  "state": {
    "reported": {
      "color": "null", 
      "temperature": "null"
    }
  }, 
  "version": 1
}

Delete all properties in the shadow.

{
  "method": "delete", 
  "state": {
    "reported": "null"
  }, 
  "version": 1
}