Device Command Topic Cluster

MQTT IoT Suite supports the application to send a unicast command directly to a device via API, and the device can get and respond to the message using a device command topic cluster.

The interaction through commands is shown as follows:

Topics in a device command topic cluster are listed as follows:

• When the application calls a device create command using the command API, the device must be online.
• The device has to subscribe to the system topic in advance to get the command message.
• The device can respond to the command result by publishing a message to the system topic.
• After the device responds to the command, the platform sends a command response result notification, and the device should subscribe to the system topic in advance to get the message.
• An API return is synchronous, that is, after the device responds to the command or after response timeout, the system returns the API request result. Please refer to the command API details.

Send Device Commands

The application can create Send Command via API, and the platform will publish the command message to a system topic: $sys/{pid}/{device-name}/cmd/request/{cmdid}，If the device subscribed to the topic, it can get the command message, and the user can customize the message content.

Description：

• cmdid is a unique identifier automatically created by the platform for this command.
• The content of the command message is determined by negotiation between the application and the device, and the platform stores the message in publish payload for data passthrough.
• It is recommended that the device subscribe to the command request message in wildcard mode, e.g. $sys/{pid}/{device-name}/cmd/request/+

Command Reply

After receiving the command, the device can respond to the command result by publishing a message to topic: $sys/{pid}/{device-name}/cmd/response/{cmdid}, and the user can customize the response data content.

Description：

• cmdid is a unique identifier with which the platform sends a command. When the device responds to a specific command, cmdid should be placed in the topic path.
• The content of the command response is determined by negotiation between the application and the device, and the device should store the message in publish payload for reporting.
• In a response message, payload size must be less than 1k.

QoS1 is supported when responding to a command. If publish QoS = 1, the platform returns publish ack.

Command Reply Result Notification

Upon receipt of the response, the platform will store the response data via cmdid and notify the processing result by system topic.

• In the event of successful command response, the system publishes a null message by topic $sys/{pid}/{device-name}/cmd/response/{cmdid}/accepted.
• It is not allowed to respond to a command repeatedly, and any resulting messages will be rejected. Information is returned by system topic
• It is recommended that the device subscribe to the command response result message in wildcard mode, e.g.:$sys/{pid}/{device-name}/cmd/response/+/+

Response Error Code

When an error occurred in command response, the platform will publish an error message by topic $sys/{pid}/{device-name}/cmd/response/{cmdid}/rejected.

The error codes therein are listed as follows:

Below is an error message example:

{
    "err_code": 99,
    "err_msg":"maximum payload size exceeded"
}

More help

Learn about the best practices for device synchronization commands