Skip to content

Introduction

MT2 is the default Meshtech MQTT API. It can be used when connecting gateways to generic MQTT brokers like mosquitto or RabbitMQ.

A gateway will publish/subscribe to topics under mt/gateway/{g}, where {g} is the gateway MAC address, for example mt/gateway/ef6d7dd1d9ed.

All gateways will also subscribe to the topics starting with mt/gateways for incoming broadcast requests.

MQTT Version: 3.1.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 Description
id "MT2"
host Hostname of MQTT broker
port Port number of MQTT broker
useTls Set to true to use TLS
userName Username
password Password
rootCertificates Root CA certificates. Typically, not needed.
mode "decoded" or "raw". When not set, mode is "raw". Added in version 1.1.1.
topicPrefix Optional. When set, this topic will be added before /mt/.. Added in version 1.2.0.
disableSubscribe Optional. 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.

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 Versions

1.0.0

Initial release.

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

  • Adding configuration options: topicPrefix, disableSubscribe

1.3.0

  • Adding lastCount to device heartbeat payload.

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)

2.0.1

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

2.1.0

  • Added optional extenderId to read/write request.