Help Center> IoT Device Management> Developer Guide> Product Development> Developing a Codec> Reference> Description of encode API
Updated on 2022-02-24 GMT+08:00
View PDF

Description of encode API

Input parameters of the encode API are commands or responses in JSON format delivered by the IoT platform.

Downstream packets of the IoT platform are classified into commands sent by the IoT platform and responses sent by the IoT platform for data reported by devices (corresponding to messages 2 and 3 in the following figure). The encoding output fields vary depending on the downstream packet.

Figure 1 Downstream packet
Table 1 Definition of input parameters of the encode API over which the IoT platform delivers commands

Field

Type

Description

Mandatory or Optional

identifier

String

Identifier of the device in the application protocol. The IoT platform obtains the parameter over the decode API, encodes the parameter over the encode API, and places the parameter in a stream.

Optional

msgType

String

This field has a fixed value of cloudReq, which indicates that the IoT platform delivers a request.

Mandatory

serviceId

String

Identifier of a service.

Mandatory

cmd

String

Name of a service command. For details about the service command definition, see the profile file.

Mandatory

paras

ObjectNode

Command parameters. Detailed fields are defined in the profile file.

Mandatory

hasMore

Int

Whether the IoT platform has subsequent commands to deliver.

  • 0: The IoT platform does not have subsequent commands to deliver.
  • 1: The IoT platform has subsequent commands to deliver.

Subsequent commands indicate that the IoT platform still needs to deliver commands, and the hasMore field is used to tell the device not to sleep. The hasMore field is valid only in PSM mode with the downstream message indication function enabled.

Mandatory

mid

Int

A 2-byte unsigned command ID that is allocated by the IoT platform. (The value ranges from 1 to 65535.)

When the IoT platform delivers a command over the encode API, the IoT platform places the MID allocated by the IoT platform into a stream and delivers the stream to the device together with the command. When the device reports the command execution result (deviceRsp), the device returns the MID to the IoT platform. In this way, the IoT platform associates the delivered command with the command execution result (deviceRsp) and updates the command delivery status accordingly.

Mandatory

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
 
{
    "identifier": "123",
    "msgType": "cloudReq",
    "serviceId": "NBWaterMeterCommon",
    "mid": 2016,
    "cmd": "SET_TEMPERATURE_READ_PERIOD",
    "paras": {
        "value": 4
    },
    "hasMore": 0}
}

Table 2 Definition of input parameters of the encode API over which the IoT platform responds to data reported by a device

Field

Type

Description

Mandatory or Optional

identifier

String

Identifier of the device in the application protocol. The IoT platform obtains the parameter over the decode API, encodes the parameter over the encode API, and places the parameter in a stream.

Optional

msgType

String

This field has a fixed value of cloudRsp, which indicates that the IoT platform sends a response for data reported by a device.

Mandatory

request

byte[]

Data reported by the device.

Mandatory

errcode

int

Request processing result code. The IoT platform determines the command delivery status based on this field.

  • 0: success
  • 1: failure

Mandatory

hasMore

int

Whether the IoT platform has subsequent messages to deliver.

  • 0: The IoT platform does not have subsequent messages to deliver.
  • 1: The IoT platform has subsequent messages to deliver.

Subsequent messages indicate that the IoT platform still needs to deliver commands, and the hasMore field is used to tell the device not to sleep. The hasMore field is valid only in PSM mode with the downstream message indication function enabled.

Mandatory
NOTE:

If msgType is set to cloudRsp and null is returned by the codec detection tool, the codec does not define the response to the reported data and the IoT platform does not need to respond.

Example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 
{
    "identifier": "123",
    "msgType": "cloudRsp",
    "request": [
        1,
        2
    ],
    "errcode": 0,
    "hasMore": 0
}
Parent topic: Reference