Help Center/ IoT Device Access/ API Reference/ MQTT or MQTTS API Reference on the Device Side/ Device Commands/ Platform Delivering a Command
Updated on 2024-12-02 GMT+08:00
View PDF
Share

Platform Delivering a Command

Function

This API is used by the platform to deliver a command to a device. After the platform delivers a command, the device needs to return the command execution result to the platform in a timely manner. Otherwise, the platform considers that the command execution has timed out. For differences between command delivery and message delivery, see Message Communications.

It is not suitable to report data in JSON format for devices with low configuration and limited resources or with limits on bandwidth usage. In this case, devices can transparently transmit the original binary data to the platform, but a codec is required to convert binary data to JSON format. For details about how to develop codecs, see Developing a Codec.

Topic

Downstream: $oc/devices/{device_id}/sys/commands/request_id={request_id}

Upstream: $oc/devices/{device_id}/sys/commands/response/request_id={request_id}

  • {request_id} is used to uniquely identify a request. If a device receives a downstream request with a topic carrying a request ID, the request ID must be included in the topic of the upstream response returned by the device.
  • When an application delivers a device command through the platform, the platform generates a unique ID (command_id) to identify the command and returns the ID to the application. In addition, the ID is sent to the device through requst_id in the downstream topic of the device command.
  • The device cannot detect the request_id in advance. When a device subscribes to a topic that ends with request_id={request_id}, the number sign (#) can be used to replaced request_id={request_id}, for example, $oc/devices/{device_id}/sys/commands/#.

Downstream Request Parameters

Parameter

Mandatory/Optional

Type

Description

object_device_id

Optional

String

Explanation:

  • For directly connected device: This parameter is not carried.
  • For gateway child device: The value is the child device ID in the topic.

service_id

Optional

String

Explanation:

Device service ID, which is defined in the product model associated with the device.

command_name

Optional

String

Explanation:

Device command name, which is defined in the product model associated with the device.

paras

Mandatory

Object

Explanation:

Command execution parameters, which are defined in the product model associated with the device.

Upstream Response Parameters

Responses are in JSON format.

Parameter

Mandatory/Optional

Type

Description

result_code

Optional

Integer

Explanation:

Command execution result. 0 indicates a successful execution, whereas other values indicate an execution failure. If this parameter is not specified, the default value 0 is used.

response_name

Optional

String

Explanation:

Response name of the command.

paras

Optional

Object

Explanation:

Indicates the response parameters, which are defined in the product model associated with the device.

Example Downstream Request

Topic: $oc/devices/{device_id}/sys/commands/request_id={request_id} 
Data format:
{
  "object_device_id": "{object_device_id}",
  "command_name": "ON_OFF",
  "service_id": "WaterMeter",
  "paras": {
    "value": "1"
  }
}

Example Upstream Response

Topic: $oc/devices/{device_id}/sys/commands/response/request_id={request_id}
Data format:
{
    "result_code": 0,
    "response_name": "COMMAND_RESPONSE",
    "paras": {
        "result": "success"
    }
}
Parent topic: Device Commands