Data in device shadows is forwarded by using topics. This article describes how device shadow data is forwarded in the following scenarios: A device reports its status to the device shadow. An application changes the status of the device. After the device goes offline and then comes online again, it actively obtains the status information from the device shadow. The device makes a request to clear property information in the device shadow.

Topics related to device shadows

For each device, IoT Platform predefines two topics for data forwarding. You can use them directly.

  • /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 information in the device shadow is synchronized to this topic. Each device can subscribe to this topic to obtain the latest status information.

Example

The following sections describe how the device shadow data of a light bulb is forwarded to illustrate the communication among a device, the device shadow, and an application.

In this example, the key of the product is a1PbRCF**** and the name of the device is lightbulb. The device uses Quality of Service 1 (QoS 1) to publish messages and subscribes to the two topics that are related to the device shadow.

This example describes how device shadow data is forwarded in the following scenarios: The device actively reports its status. An application changes the status of the device. The device actively obtains information from the device shadow. The device actively clears property information in the device shadow.

1. The device actively reports its status

When the device is online, it actively reports the device status to its shadow. Applications actively obtain the status information from the device shadow.

The following figure shows the process of data forwarding.

  1. When the light bulb is online, it reports its latest status to the device shadow by sending a JSON message to the /shadow/update/a1PbRCF****/lightbulb topic.
    The JSON message has the following format:
    {
      "method": "update", 
      "state": {
        "reported": {
          "color": "red"
        }
      }, 
      "version": 1
    }
    Table 1. JSON 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 that will be checked by the device shadow.

    The device shadow accepts the request and is updated to the specified version only when the new version 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 accepts the request from the device and updates its version to 0.

  2. After the device shadow receives the status that is reported by the light bulb, the device shadow updates the JSON file.
    {
      "state": {
        "reported": {
          "color": "red"
        }
      }, 
      "metadata": {
        "reported": {
          "color": {
            "timestamp": 1469564492
          }
        }
      }, 
      "timestamp": 1469564492, 
      "version": 1
    }
  3. After the JSON file is updated, the device shadow returns the result to the device, which is the light bulb in this example. Specifically, the device shadow sends a message to the /shadow/get/a1PbRCF****/lightbulb topic that the device is subscribed to.
    • 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
      errorCode errorMessage
      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.

2. An application changes the status of the device

An application sends its desired status to the device shadow by calling the UpdateDeviceShadow operation. Then, the device shadow updates the device on the JSON file. The device updates its status based on the status information that is sent by the device shadow. Then, the device reports its latest status to the device shadow.

The following figure shows the process of data forwarding.

  1. The application calls the UpdateDeviceShadow operation to send a request to change the status of the light bulb, for example, 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
    }
  2. The device shadow receives the update request and updates the JSON file, as shown in the following code:
    {
      "state": {
        "reported": {
          "color": "red"
        }, 
        "desired": {
          "color": "green"
        }
      }, 
      "metadata": {
        "reported": {
          "color": {
            "timestamp": 1469564492
          }
        }, 
        "desired": {
          "color": {
            "timestamp": 1469564576
          }
        }
      }, 
      "timestamp": 1469564576, 
      "version": 2
    }
  3. After the device shadow completes the update, it returns the result to the /shadow/get/a1PbRCF****/lightbulb topic. The information in the return result 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
    }
  4. If the light bulb is online and has subscribed to the /shadow/get/a1PbRCF****/lightbulb topic, the light bulb immediately receives the 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 reports its 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.
  5. After the latest status is reported 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 body of the message:
      {
        "method": "update", 
        "state": {
          "desired": "null"
        }, 
        "version": 4
      }
    • The device shadow updates the JSON file. The following code shows the content of the JSON file after the update:
      {
        "state": {
          "reported": {
            "color": "green"
          }
        }, 
        "metadata": {
          "reported": {
            "color": {
              "timestamp": 1469564577
            }
          }, 
          "desired": {
            "timestamp": 1469564576
          }
        }, 
        "version": 4
      }

3. The device actively obtains information from the device shadow

Assume that when the application sends the command, the device is offline. After the device comes online again, it actively obtains information from the device shadow.

The following figure shows the process of data forwarding.

  1. The light bulb actively sends the following message to the /shadow/update/a1PbRCF****/lightbulb topic to request the latest status information that is stored in the device shadow:
    {
    "method": "get"
    }
  2. After the device shadow receives the message, the device shadow sends the latest status information to the /shadow/get/a1PbRCF****/lightbulb topic. The light bulb obtains the latest status information 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
    }

4. The device actively clears property information in the device shadow

If the device is in the latest state, the device can send a command to clear specific property information in the device shadow.

The following figure shows the process of data forwarding.

The device sends the following content 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.

  • Clear the information of a property in the device shadow.
    {
      "method": "delete", 
      "state": {
        "reported": {
          "color": "null", 
          "temperature": "null"
        }
      }, 
      "version": 1
    }
  • Clear the information of all properties in the device shadow.
    {
      "method": "delete", 
      "state": {
        "reported": "null"
      }, 
      "version": 1
    }