Skip to content

Introduction

MT2 is an MQTT API. It can be used when connecting gateways to an MQTT broker.

The gateway will publish to the following topics (g is lowercase gateway MAC address):

Publish topic Description
mt/gateway/{g}/device/.. Device reporting
mt/gateway/{g}/response/.. Request responses

The gateway will subscribe to the following topics (g is lowercase gateway MAC address):

Subscribe topic Description
mt/gateway/{g}/request/# Requests
mt/gateways/# Broadcast (typically requests)

Note

In future versions of the protocol, new publish/subscribe topics may be added. Keep this in mind when setting up broker rules.

  • MQTT version: 3.1.1
  • QoS level: 1

Modes

MT2 can be configured to operate in two modes:

  • raw (default)
  • decoded

The mode only determines the format of reporting topics. All request/response topics are available in both modes.

In raw mode (default) the gateway will use raw hex strings for values and identifiers when reporting. No translation is required by the gateway.

In decoded mode the gateway will try to decode identifiers to human-readable identifier names and JSON values when reporting. If it fails to decode, it will fall back to raw. In decoded mode, topics ending with -decoded will be used when reporting.

Note

In versions prior to 2.0.0, the default mode was called legacy and the topics were slightly different.

Configuration

The following configuration parameters are used to configure the MT2 connection for a gateway.

Parameter Type Optional Description
id string "MT2"
host string Hostname of MQTT broker
port number Port number of MQTT broker
useTls boolean Set to true to use TLS
userName string Username. Set to "" when not used.
password string Password. Set to "" when not used.
rootCertificates cert[] Root CA certificates. When not in use, set to []. NOTE: Setting root certificates this way is not recommended. Use 0x8030 - Add Root Certificate instead.
mode string x "decoded" or "raw". When not set, mode is "raw". Added in version 1.1.1.
topicPrefix string x When set, this topic will be added before /mt/.. Added in version 1.2.0.
disableSubscribe boolean x When set to true, gateway will not subscribe to any topics and the gateway will not be able to handle requests. Default: false. Added in version 1.2.0.
keepAlive number x Keep Alive interval in seconds. Default: 15. Added in version 2.3.0.
certificate string x Client certificate in PEM format. When used, set username/password to "". Added in version 2.3.0.
privateKey string x Private key in PEM format. When used, set username/password to "". Added in version 2.3.0.
ignoreRevocationErrors boolean x Ignore certificate revocation errors. Default: true. Added in version 2.3.0.

Root certificates are defined with the cert type:

Parameter Type Optional Description
format string "pem"
data string[] Lines in PEM file without newline ending 
{
  "format": "pem",
  "data": [
      "-----BEGIN CERTIFICATE-----",
      "...",
      "-----END CERTIFICATE-----"
  ]
}

Note

Setting root certificates this way is not recommended. Use 0x8030 - Add Root Certificate instead.

MQTT Client ID

The gateway will connect with a client ID equal to the Bluetooth MAC address, 12 lowercase hex digits. Example: ef6d7dd1d9ed.

Breaking Changes

If there are breaking changes to the API, the mt/ prefix will normally be changed to distinguish between different breaking API versions. Major version is increased when doing breaking changes.

API Version History

2.3.0

  • Added configuration options: keepAlive, certificate, privateKey, ignoreRevocationErrors

2.2.0

  • Added optional accessType, publicKey and key to read and write requests.

2.1.0

  • Added optional extenderId to read and write requests.

2.0.1

  • apiversion fixes
    • Added responseTime, origin and route
    • Fixed response when not addressed to the gateway

2.0.0

  • BREAKING CHANGE:
    • Topics using decoded identifiers are now named ending with -decoded
    • -raw ending has been removed and they are now the default/raw topics
    • Former "legacy" mode is no longer used
  • Added support for identifier value extensions. Optional ext property added to -decoded variants of request/response and reporting payloads
  • Added read/write response metadata:
    • responseTime, origin
    • route, extenderId, extenderRoute (optional)

1.3.0

  • Adding lastCount to device heartbeat payload.

1.2.0

  • Adding configuration options: topicPrefix, disableSubscribe

1.1.1

  • Adding support for mode
    • When migrating from 1.0.0, mode will be "legacy".
    • New implementations should use "raw" or "decoded" mode.
  • New raw-topics for (hex)

1.0.0

Initial release.