MT MQTT Setup Guide
Overview
While MT sensors provide a rich user experience on the Dashboard, we’re introducing a new paradigm for consuming the MT sensor data using an MQTT Telemetry stream. This guide is intended to help users set up and enable MQTT brokers on the Dashboard for MT sensors and consume the telemetry data from the broker.
How does MQTT work for MT?
MQTT uses a server/client, publish/subscribe architecture where a client can publish a specifically formatted data to a defined topic path in the server. Another client can then consume this data by subscribing to the said topic.
Roles for each device are as below:
-
MT sensors - collects telemetry data and sends it to a gateway (MV/MR). Sensors do not directly communicate with the broker.
-
Gateway (MV/MR) - Acts as a publisher client. All MVs and MRs in the network will publish the telemetry data it collected to the broker
-
Broker - On site/Cloud based broker on the user’s environment that ingests the data and stores it in the database.
-
Subscriber - Another 3rd party device that reads the data from the broker database
Requirements
Since MT data is sent via the gateway, both MV and MR needs to be running the required firmware with MQTT support for MT telemetry.
Minimum firmware requirement:
-
MR - 28.6+
-
MV - 4.16+
For users who have MT sensors in a combined network with MV and MR, it is critical that both the Cameras and APs be upgraded to the firmware listed above.
This is because the gateways do not have a control over where the sensors are connecting and in any case an MT connects to a gateway that does not support MQTT, the telemetry data will not be published, resulting in a gap of data in the broker database. Note that this does not affect Dashboard data in any scenario and is strictly exclusive to MQTT telemetry stream.
Caveats
Keeping the roles in mind, there are some caveats. MT sensors still follow the same wake up mechanism to collect and report the data
-
MT10/MT11 samples temp/humidity every 2 mins and reports it to the gateway every 20 minutes.
-
This means that the gateway will publish 10+10 messages for temperature and humidity every 20 minutes. The payload will consist of a timestamp (ISO 8601) of when the sample was taken.
-
Apart from an alert where the sensor will interrupt its cycle and immediately report the data.
-
-
MT12/MT20 samples the current state constantly but only reports every 20 minutes or there is a state change
-
This means the gateway will publish the current state every 20 minutes
-
Or when the state changes like door open/close or water detected.
-
Getting Started
Configuring the Dashboard
The MQTT broker for MT sensors can be configured under Environmental>Overview>MQTT Brokers
MQTT Brokers tab is only visible if the Minimum Firmware Requirements are met.
Add the broker by selecting Edit MQTT Brokers and then selecting New MQTT broker
-
Broker Name: An identifier for the user. It can be any word.
-
Host: IP of the broker you are going to configure.
-
Port: Port used by MQTT server, by default servers use TCP port 1883.
-
Username: Optional depending on the configuration of the server.
-
Password: Optional depending on the configuration of the server.
-
Security: Can be None or TLS security. If TLS security is selected, a new option will show for you to upload the certificate to be used.
Once all the fields are configured, click Save and make sure to Select the broker that was just configured.
As soon as the configuration is saved and pushed to the gateways, they will connect to the broker and start publishing the telemetry data.
MT MQTT Telemetry Data structure
Topic and Data Format
To create a consistent experience, we are going to be using the topic format as below.
meraki/v1/mt/{locale_id}/ble/{sensor_mac}/{metric}
Example:
meraki/v1/mt/L_643451796760561416/ble/54:6C:0E:8A:9E:81/temperature
The topic structure is defined based on a specific sensor perspective and its metric.
Regarding the actual data payload returned, our goal is to have a readable format that we can export to other platforms. This is the v1 format
Sensor Metrics
Sensor telemetry data for different metrics
|
Topic |
Payload |
Notes |
|
temperature |
{ "ts":"2021-08-12T17:44:46Z", "fahrenheit":72.6, "celsius":22.6 } |
Includes timestamp(of reading) and temperature readings in °C and °F. Data reported every 20 mins(unless threshold set in dashboard is violated). Temperature data is collected every 2 minutes but reported in 20 min intervals, so expect up to 10 messages per connection.
|
|
humidity |
{ "ts":"2021-08-12T17:44:46Z", "humidity":62 } |
Ts(of reading) and Humidity in %RH. Data reported every 20 mins(unless threshold set in dashboard is violated). Humidity data is collected every 2 minutes but reported in 20 min intervals, so expect up to 10 messages per connection. |
|
waterDetection |
{ "ts":"2021-08-12T17:59:38Z", "wet":false } |
Ts(of reading) and wet status as a true/false boolean. Current state reported every 20 mins or if there is a change in state |
|
door |
{ "ts":"2021-08-12T18:00:54Z", "open":false } |
Ts(of reading) and door open status as a true/false boolean. Current state reported every 20 mins or if there is a change in state |
Sensor Health
These are the Device level metrics that provide status information about the device
|
Topic |
Payload |
Notes |
|
batteryPercentage |
{ "ts":"2021-08-12T21:30:48Z", "battery percentage":100 } |
Includes timestamp(of reading) and battery level in %. Data reported every 20 mins(unless threshold set in dashboard is violated)
|
|
usbPowered |
{ "ts":"2021-08-12T21:35:49Z", "usb powered":false } |
Ts(of reading) and USB connection status as a true/false boolean. Data reported every 20 mins(unless threshold set in dashboard is violated). Only applies to devices with external power supply |
|
buttonPressed |
{ "ts":"2021-08-12T21:46:55Z", "button pressed":true } |
Ts(of reading) and General Purpose button press as a true/false boolean. Only reported when physically pressed |
|
cableConnected |
{ "ts":"2021-08-12T18:00:54Z", "cable connected":false } |
Ts(of reading) and water leak cable connection status as a true/false boolean. Current state reported every 20 mins or if there is a change in state. Only applies to MT12 Water Leak Sensor |
|
probeType |
{ "ts":"2021-10-14T18:41:41Z", "probe type":"Bare Metal Temperature Probe" } { "ts":"2021-08-12T21:48:27Z", "cable type":"Glycol Temperature Probe" } |
Ts(of reading) and probe cable type. Current state reported every 20 mins or if there is a change in state. Only applies to MT11 Probe Sensor |
Exceptions
Since the topic structure is designed by keeping the sensor metrics in mind, the above format does not accommodate RSSI values as those values are recorded from the perspective of a gateway.
To accurately organize the topics, the RSSI values can be retrieved by a slightly different topic structure:
|
meraki/v1/mt/{locale_id}/ble/{sensor_mac}/gateway/{gateway_mac}/rssi
|
||
|
meraki/v1/mt/L_647955396388043043/ble/2C:3F:0B:FF:F7:18/gateway/34:56:FE:A2:D4:FA/rssi
|
{ "ts":"2021-08-12T21:55:38Z", "rssi":-69, "units":"dBm" } |
Ts(of reading) and rssi value in dBm. |
As noted in the example topic above, the RSSI value for Sensor(2C:3F:0B:FF:F7:18) from the perspective of a specific Gateway(34:56:FE:A2:D4:FA) is reported.
Note that the RSSI value of a single sensor can be reported by multiple gateways if they are in the immediate vicinity of the sensor but can only connect to 1 at a time. All subsequent telemetry data is reported from the connected gateway.
General MQTT features
Retained Message
The current MQTT implementation for MT data also includes Retained Messages.
Since the MT sensors only report data every 20 minutes, the last data retrieved by a gateway is buffered and published when a broker subscribes to a specific topic so that the user does not have to wait for the next time the MT sensor connects to the gateway.
Wildcards
Using wildcards is also allowed in the current implementation. While it is always recommended to use specific individual topics to get more accuracy and optimize database entries, users may also want to use regex wildcards to consume multiple data points using a single topic.
Single Level: +
As the name suggests, a single-level wildcard replaces one topic level. The plus symbol represents a single-level wildcard in a topic.
Example: meraki/v1/mt/{network_id}/ble/+/temperature
In the example above, the plus symbol will act as a wildcard and match all sensors that provide temperature metrics.
Multi-Level: #
The multi-level wildcard covers many topic levels. The hash symbol represents the multi-level wild card in the topic. For the broker to determine which topics match, the multi-level wildcard must be placed as the last character in the topic and preceded by a forward slash.
Example: meraki/v1/mt/{network_id}/ble/#
In the example above, when a client subscribes to a topic with a multi-level wildcard, it receives all messages of a topic that begins with the pattern before the wildcard character, no matter how long or deep the topic is. If you specify only the multi-level wildcard as a topic (#), you receive all messages that are sent to the MQTT broker. Note that the higher the wildcard is on the topic the higher the throughput of messages as the volume will significantly increase.
QoS
No QoS is enabled (i.e., we are using level 0 implicitly). This means there is no guarantee of data delivery to the broker. At the moment, this cannot be modified.