tencent cloud

All product documents
IoT Hub
DocumentationIoT HubDeveloper ManualDevice ShadowDevice Shadow Details
Device Shadow Details
Download PDF
Last updated: 2024-12-27 15:54:13
Device Shadow Details
Last updated: 2024-12-27 15:54:13
Download PDF
A device shadow document is a file of status and configuration data cached by the server for a device, which is stored as JSON text and consists of the following parts:
thing_shadow


state

reported This is the status reported by the device itself. The device can write data to this part of the document to report its new status, and the application can read this part to get the status of the device.
desired This is the desired status of the device. The application writes data to this part of the document through the HTTP RESTful API to update the device status. The device SDK syncs the shadow data to the device by registering relevant attributes and callback through the device shadow service.

metadata

This is the metadata information of the device shadow, including the last updated time of each attribute in the state section.

version

This is the version number of the device shadow document, which is increased each time the document is updated. The version number is maintained by Tencent Cloud on the backend, ensuring that the data of the device is consistent with that of the device shadow.

timestamp

This is the last updated time of the device shadow document. Below is a sample document:
{
 "state": {
  "reported": {
   "attr_name1": "value1"
  },
  "desired": {
   "attr_name2": "value2"
  }
 },
 "metadata": {
  "reported": {
   "attr_name1": {
    "timestamp": 123456789
   }
  },
  "desired": {
   "attr_name2": {
    "timestamp": 123456789
   }
  }
 },
 "version": 1,
 "timestamp": 123456789
}

Blank part

Below is a sample device shadow document that is blank:
{
    "state":{},
    "metadata":{},
    "version":0
}
Only when the device shadow document has the desired status will there be a desired part, and the reported part can be empty; for example:
{
 "state": {
  "desired": {
   "attr_name2": "value2"
  }
 },
 "metadata": {
  "desired": {
   "attr_name2": {
    "timestamp": 123456789
   }
  }
 },
 "version": 1,
 "timestamp": 123456789
}
After the device status is successfully updated, the latest status needs to be reported, and the desired part needs to be removed from the document. To remove this part, you need to set it to null; for example:
{
 "state": {
  "reported": {
   "attr_name1": "new_value1",
   "attr_name2": "new_value2"
  },
  "desired": null
 },
 "version": 1
}

Array

The device shadow document supports arrays. Only an entire array but not an element in the array can be updated, and none of the elements can be null.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Contact Us
Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

Submit a Ticket
7x24 Phone Support
Hong Kong, China
+852 800 906 020 (Toll Free)
United States
+1 844 606 0804 (Toll Free)
United Kingdom
+44 808 196 4551 (Toll Free)
Canada
+1 888 605 7930 (Toll Free)
Australia
+61 1300 986 386 (Toll Free)
EdgeOne hotline
+852 300 80699
More local hotlines coming soon