MQTT IoT Suite supports users to synchronize device state and configuration information by device image, as shown below. Please see the Device Image for details.
Topics in a device image topic cluster are listed as follows:
System topic | Purpose | QoS | Subscribe | Publish |
---|---|---|---|---|
$sys/{pid}/{device- name}/image/update | Update device image properties | 0/1 | √ | |
$sys/{pid}/{device- name}/image/update/accepted | The system informs that "Device Image Update Succeeded" | 0 | √ | |
$sys/{pid}/{device- name}/image/update/rejected | The system informs that "Device Image Update Failed" | 0 | √ | |
$sys/{pid}/{device- name}/image/update/delta | The system informs that "There is a difference between the reported property and the desired property" | 0 | √ | |
$sys/{pid}/{device- name}/image/get | Device image information query | 0/1 | √ | |
$sys/{pid}/{device- name}/image/get/accepted | The system informs that that "Device Image Query Succeeded" | 0 | √ | |
$sys/{pid}/{device- name}/image/get/rejected | The system informs that "Device Image Query Failed" | 0 | √ |
Devices can be updated by publishing messages to the system topic: $sys/{pid}/{device-name}/image/update. An example of payload is given as follows:
{
"state": {
"desired": {
"color": "green"
},
"reported": {
"color": "red"
}
}
}
The parameters therein are described as follows:
Parameter | Type | Required? | Description |
---|---|---|---|
state | object | Yes | - |
desired | object | - | Used to update desired device state/configuration information, with at least one reported item |
reported | object | - | Used to update current device state/configuration information, with at least one desired item |
When the application/device updates the reported or desired property, the platform will calculate the difference delta. If delta exists, the platform will send the difference message to the system topic: $sys/{pid}/{device-name}/image/update/delta, and the device can get the difference message by subscribing to this topic. Below is an example of the message:
{
"state": {
"color": "green"
},
"metadata": {
"color": {
"timestamp": 1469574492
}
},
"version":2,
"timestamp":1469574492
}
The device can query the latest image data by publishing a null message to the system topic: $sys/{pid}/{device-name}/image/get.
Error Code err_code | Error Message err_msg | Description |
---|---|---|
128 | unspecified error | Unspecified error |
160 | illegal json | Invalid json |
161 | json out of bound | json data length is out of bound |
162 | json depth out of bound | The depth of json nesting levels is out of bound |
163 | state key not found | state field is not found |
164 | desired or reported key not found | "desired" and "reported" fields are excluded |
165 | invalid parameters | There are invalid parameters |
166 | device image existed | Device image existed |
167 | device image not exists | Device image does not exist |
Learn about the best practices for device state synchronization using device image