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
4	Highest
3	High
2	Medium
1	Low
0	Lowest

When no priority level is specified, Medium 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.

JSON Object Payload Parameters (optional)

Property	Type	Description	Version
priority	number	Network level priority. Value range: 0 - 4.
extenderId	string	Hex string ID of extender to use to reach unconnected target device.	2.1.0+

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.

JSON Object Payload Parameters (optional)

Property	Type	Description	Version
priority	number	Network level priority. Value range: 0 - 4.
extenderId	string	Hex string ID of extender to use to reach unconnected target device.	2.1.0+

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

JSON Object Payload Parameters (optional)

Property	Type	Description	Version
value	string	Hex string value to be written to the device property.
priority	number	Network level priority. Value range: 0 - 4.
extenderId	string	Uppercase hex string ID of extender to use to reach unconnected target device.	2.1.0+

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 operation 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.

JSON Object Payload Parameters (optional)

Property	Type	Description	Version
value	JSON	The JSON value to be written to the device property.
ext	object	Value extensions.	2.0.0+
priority	number	Network level priority. Value range: 0 - 4.
extenderId	string	Uppercase hex string ID of extender to use to reach unconnected target device.	2.1.0+

If value is null or not included, a NULL ("no value") is written. This is typically used for pure command-properties that are just triggered by the write operation 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
}