Device Image Topic Cluster

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

Device Image Properties Update

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
  • Device image update supports QoS1. If publish QoS = 1, the platform returns publish ack.
  • If device image update succeeded, the platform sends a success message by system topic: $sys/{pid}/{device-name}/image/update/accepted.
  • If device image update failed, the platform sends an update failure message by system topic: $sys/{pid}/{device-name}/image/update/rejected. Please refer to the table of error codes.
  • After successful device update, if there is a difference between the reported content and the desired content, delta messaging will be triggered, and the device can get the difference message by subscribing to the system topic: $sys/{pid}/{device-name}/image/update/delta.

Difference in Properties Obtained by Device

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
}

Device Image Property Query

The device can query the latest image data by publishing a null message to the system topic: $sys/{pid}/{device-name}/image/get.

  • The device image query supports QoS1. If publish QoS = 1, the platform returns publish ack.
  • If device image query succeeded, the platform issues the latest device image data by system topic: $sys/{pid}/{device-name}/image/get/accepted.
  • If device image update failed, the platform sends an update failure message by the system topic: $sys/{pid}/{device-name}/image/get/rejected. Please refer to the table of error codes.

Error Code

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

More help

Learn about the best practices for device state synchronization using device image

个搜索结果,搜索内容 “

    0 个搜索结果,搜索内容 “