Skip to content

Requests

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

Request topic: mt/gateway/{g}/request/{d}/...

Response topic: mt/gateway/{g}/response/{d}/...

In the following {g} is the gateway MAC address and {d} is the device MAC address. MAC addresses are lowercase hex, 12 characters. To send a request to the gateway (root node) itself, use d = g.

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 string property. This id property 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:

  • time - Time the response was generated in ISO-8601 format
  • status - Status code for the response. See Status Codes.
  • responseTime - Response time in milliseconds (added in version 2.0.0)
  • origin - Origin of response (added in version 2.0.0)
    • 0 - Connected Device
    • 1 - Unconnected Device via Extender
    • 16 - Extender responds instead of unconnected target device
    • 32 - Gateway responds instead of target device

Optional response properties:

  • id - Request id. This is included when id was included in the request.
  • 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.
  • route - Route of connected target device (when connected device itself responds) (added in version 2.0.0)
  • extenderId - Id of extender used to reach unconnected target device (added in version 2.0.0)
  • extenderRoute - Route of extender used to reach unconnected target device (added in version 2.0.0)

Note

extenderId/extenderRoute can also be the gateway itself.

It is possible to set the network level priority to use when routing a request and it's response. The following priority levels are supported:

Priority value Priority
0 Lowest
1 Low
2 Intermediate
3 Medium
4 High

When no priority level is specified, Intermediate priority level is used.

Priority is specified while reading or writing a property. 

{
    "id": "420",
    "priority": 3
}

apiversion

mt/gateway/{g}/request/{d}/apiversion

Get API version.

Note

This request will fail if not addressed to the gateway device (root node).

Note

responseTime, origin and route was added in version 2.0.1.

Example

mt/gateway/e4ebc3f77f09/request/e4ebc3f77f09/apiversion 

{
  "id": "42"
}

mt/gateway/e4ebc3f77f09/response/e4ebc3f77f09/apiversion 

{
  "id": "42",
  "time": "2020-10-19T13:16:53.169Z",
  "status": 0,
  "responseTime": 0,
  "origin": 0,
  "route": "FFFFFFFFFFF0",
  "version": "2.1.0"
}

read

mt/gateway/{g}/request/{d}/read/{identifier}

Read the value of device property.

identifer is encoded as lowercase hex string.

Parameters

  • priority: Network level priority (optional)

Example

mt/gateway/e4ebc3f77f09/request/da51bdeef18c/read/8000 

{
    "id": "420"
}

mt/gateway/e4ebc3f77f09/response/da51bdeef18c/read/8000 

{
  "id": "420",
  "time": "2020-10-19T13:22:41.758Z",
  "status": 0,
  "value": "0005"
}

read-decoded

mt/gateway/{g}/request/{d}/read-decoded/{identifier-name}

Read the value of device property.

Parameters

  • priority: Network level priority (optional)

Example

mt/gateway/e4ebc3f77f09/request/da51bdeef18c/read-decoded/model-number 

{
    "id": "420"
}

mt/gateway/e4ebc3f77f09/response/da51bdeef18c/read-decoded/model-number 

{
  "id": "420",
  "time": "2020-10-19T13:22:41.758Z",
  "status": 0,
  "value": 5
}

If the property value is extended, the extensions will be included in the response payload as ext, like this:

{
  "id": "420",
  "time": "2020-10-19T13:22:41.758Z",
  "status": 0,
  "value": 5,
  "ext": {
    "a": 123,
    "b": 456,
  }
}

write

mt/gateway/{g}/request/{d}/write/{identifier}

Write a value to a device property.

Parameters

  • value: The new value to be written to a device (hex string) (optional)
  • priority: Network level priority (optional)

If value is null, an empty string or not included, a NULL ("no value") is written. This is typically used for pure command-properties that are just triggered by the write itself. Hex string can be uppercase or lowercase.

Example

mt/gateway/e4ebc3f77f09/request/da51bdeef18c/write/9000 

{
  "id": "420",
  "value": "32"
}

mt/gateway/e4ebc3f77f09/response/da51bdeef18c/write/9000 

{
  "id": "420",
  "time": "2020-10-09T12:14:41.830Z",
  "status": 0
}

write-decoded

mt/gateway/{g}/request/{d}/write-decoded/{identifier-name}

Write a value to a device property.

Parameters

  • value: The new value to be written to a device (JSON) (optional)
  • ext: value extensions (JSON object, optional)
  • priority: Network level priority (optional)

If value is null or not included, a NULL ("no value") is written. This is used for pure command-properties that are just triggered by the write itself.

If the identifier supports extensions, the extension can be included in ext.

mt/gateway/e4ebc3f77f09/request/da51bdeef18c/write-decoded/scan-window 

{
  "id": "420",
  "value": 50
}

mt/gateway/e4ebc3f77f09/response/da51bdeef18c/write-decoded/scan-window 

{
  "id": "420",
  "time": "2020-10-09T12:14:41.830Z",
  "status": 0
}