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:

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:

• 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

More help

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