Skip to content

Requests

Requests are used to trigger operations on a device/gateway. A request may or may not return data.

Request topic: c/{d}/q/...

Response topic: c/{d}/s/...

In the following {d} is the device MAC address. MAC addresses are lowercase hex, 12 characters.

All requests require an UTF-8 encoded JSON object in the MQTT message payload. This object contains required and optional parameters for the request.

All request objects can specify an optional id component of a request command. This id component is used to uniquely identify the request. If id is included in the request, the id is returned in the response payload. This can be used to correlate request and response. It is the responsibility of the client(s) to ensure the uniqueness of this string.

Some properties are always present in the response message object:

  • type - Type of the command Request id. This is included when id was included in the request.
  • id - A requested property id/name.
  • time - Time the response was generated in ISO-8601 format

Optional response properties:

  • errorMessage - When a request fails, this string-property can be included in the response payload to help troubleshoot the failure. Applications should not rely on the exact content of this string. The string might be changed in the future and may differ between invocations.

read

c//{d}/q/{id}/read

Where {id} is a unique identifier of the request.

Read the value of device property.

Example

c//f8889b14e968/q/02/read

{
  "id": "8110"
}

Response:

c//f8889b14e968/s/02/200

{
  "type": "read",
  "id": "8110",
  "time": "2021-06-22T14:32:04.126Z",
  "value": "04"
}

read-decoded

c//{d}/q/{id}/read-decoded

Where {id} is a unique identifier of the request.

Read the value of device property.

Example

c//f8889b14e968/q/01/read-decoded

{
  "id": "device-mode"
}

Response:

c//f8889b14e968/s/01/200

{
  "type": "read-decoded",
  "id": "device-mode",
  "time": "2021-06-24T09:05:12.952Z",
  "value": "unconnected"
}

write

c//{d}/q/{id}/write

Where {id} is a unique identifier of the request.

Write the value of device property to the device.

Example

c//f8889b14e968/q/04/write

{
  "id": "838000",
  "value": "1000"
}

Response:

c//f8889b14e968/s/04/200

{
  "type": "write",
  "id": "838000",
  "time":"2021-06-29T10:29:36.661Z"
}

write-decoded

c//{d}/q/{id}/write-decoded

Where {id} is a unique identifier of the request.

Write the value of device property to the device.

Example

c//f8889b14e968/q/03/write-decoded

{
  "id": "alarm",
  "value": 00
}

Response:

c//f8889b14e968/s/03/200

{
  "type": "write-decoded",
  "id": "alarm",
  "time": "2021-06-29T10:22:08.364Z"
}

Note

write also supports ext for value extensions.