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)

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

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.

Example

mt/gateway/e4ebc3f77f09/request/e4ebc3f77f09/apiversion

{
  "id": "42"
}

mt/gateway/e4ebc3f77f09/response/e4ebc3f77f09/apiversion

{
  "id": "42",
  "time": "2025-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.

identifier is encoded as lowercase hex string.

JSON Object Payload Parameters (optional)

Example

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

{
    "id": "420"
}

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

{
  "id": "420",
  "time": "2025-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)

Example

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

{
    "id": "420"
}

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

{
  "id": "420",
  "time": "2025-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": "2025-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)

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": "2025-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)

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": "2025-10-09T12:14:41.830Z",
  "status": 0
}

ack¶

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

ACK received timestamped measurement/event sample.

Payload

Example

mt/gateway/ef6d7dd1d9ed/request/cd10a7eff81f/ack/8800

{
  "time": "2025-11-04T10:09:42.467Z",
  "type": 1
}

ack-decoded¶

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

ACK received timestamped-decoded measurement/event sample.

Payload

Example

mt/gateway/ef6d7dd1d9ed/request/cd10a7eff81f/ack-decoded/temperature

{
  "time": "2025-11-04T10:09:42.467Z",
  "type": 1
}

multicast-write¶

mt/gateway/{g}/request/{g}/multicast-write/{identifier}

Write a device property on multiple devices using multicast. The individual write operations will not have any responses. This request must be addressed to the gateway.

Payload

If value is null, an empty string or not included, a NULL value is written. The hex string can be uppercase or lowercase.

Example (pin all extenders)

mt/gateway/d7e94d98b48d/request/d7e94d98b48d/multicast-write/9007

{
  "id": "22",
  "value": null,
  "ex": true
}

mt/gateway/d7e94d98b48d/response/d7e94d98b48d/multicast-write/9007

{
  "id": "22",
  "time": "2026-09-01T08:04:25.647Z",
  "status": 0,
  "responseTime": 1,
  "origin": 0,
  "route": "FFFFFFFFFFF0"
}

multicast-write-decoded¶

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

Write a device property on multiple devices using multicast. The individual write operations will not have any responses. This request must be addressed to the gateway.

Payload

If value is null or not included, a NULL value is written. If the identifier supports extensions, the extension can be included in ext.

Example (unpin all extenders)

mt/gateway/d7e94d98b48d/request/d7e94d98b48d/multicast-write-decoded/unpin-from-parent

{
  "id": "21",
  "value": null,
  "ex": true
}

mt/gateway/d7e94d98b48d/response/d7e94d98b48d/multicast-write-decoded/unpin-from-parent

{
  "id": "21",
  "time": "2026-09-01T08:30:24.593Z",
  "status": 0,
  "responseTime": 3,
  "origin": 0,
  "route": "FFFFFFFFFFF0"
}