Skip to content

MQTT Explorer

This section aims at showing how to use MQTT Explorer to read/write properties to the devices and decode the received values.

Glossary

Tool Description
MQTT Broker (Mosquitto) A server that receives all messages from the clients and then routes the messages to the appropriate destination clients
MQTT Client (MQTT Explorer) Any device that runs an MQTT library and connects to an MQTT broker over a network.
MT2 Meshtech Backend
Identifier A property of a device

To read and write properties to the devices, there is a broker needed. The broker is backend. Aside from the broker, a client needs to be connected as well. It's also recommended to make sure that the GW's backend config contains 'MT2' and port '1883'.

Mosquitto Installation

Download Mosquitto or RabbitMQ. Mosquitto is used in this example.

There has to be server working on to establish connection in MQTT Explorer.

Run mosquitto for Windows users:

net start mosquitto

Run mosquitto for macOS users:

/usr/local/sbin/mosquitto -c /usr/local/etc/mosquitto/mosquitto.conf

A received result in a command line is:

New client connected from 127.0.0.1 as mqtt-explorer-d6be7972 (p2, c1, k60).

Now the broker is up and running.

MQTT Explorer Installation

There is a wide range of the available clients. MQTT Explorer is used in this example. To download and set MQTT Explorer up, please, follow the instructions provided here.

Gateway Configuration

A local GW should be connected to the computer. In order to connect it, use any SSH client to change backend config.

Go to cd /boot/data/mtgw, choose backend.json and change configs. Use the computer's IP address as a host, change port to 1883 if needed. Reboot GW. This can be done via Device Management Portal by generating a backend config file and creating a job to change configs.

Connection Setup

Set a new connection up to work with the local devices:

Open the client and add a new connection. Enter following data:

  • Name: local-host
  • Validate certificate: off
  • Encryption (tls): off
  • Protocol: mqtt://
  • Host: localhost
  • Port: 1883

Open Advanced Settings. There are subscriptions # and $SYS/#. Add a new subscription:

  • MQTT Client ID: mqtt-explorer-d6be7972
  • Subscription: mtble/#

Click Back.

Save a just created connection and click Connect.

Click on 'mt' and see what devices are available. Note that 'mt' takes some time to appear in the list.

read-raw

In this example, a Temperature measurement of MT MultiTracker 111 which is connected to a GW is read.

  • In Publish section of the client, there is Topic. For reading a measurement the following command is used:

mt/gateway/{g}/request/{d}/read-raw/{identifier}
Where {g} is GW's MAC, {d} is MAC of a device to read the properties from - e.g MT MultiTracker in this example, and {identifier} is a property to be read.

Example:

mt/gateway/e4ebc3f77f09/request/da51bdeef18c/read-raw/8800

Where e4ebc3f77f09 is GW's MAC and da51bdeef18c is MultiTracker's MAC.

  • Choose json.
  • Go to MT MultiTracker 11x's Properties list and choose the property to be read. Some properties are read-only and some are write-only. This information is mentioned at the top of each identifier's page. However, some properties can be both readable and writable. For example, 0x8110 - Device Mode. The measurement of temperature 0x8800 - Temperature is read in this example.

  • Enter the following json to a Publish section: 

    {
    "id": "420"
}
    "id" uniquely identifies the request. Properties should not contain dots. Use this format: "8101", "8007", "8801" etc.

  • Click Publish.

In the tree of the devices, two new topics should appear - 'request' and 'reponse'. Expand them.

The topic 'request' contains: 

mt/gateway/e4ebc3f77f09/request/da51bdeef18c/read-raw/8800

{
  "id": "420"
}
The topic 'response' contains:

mt/gateway/e4ebc3f77f09/response/da51bdeef18c/read-raw/8800

{
  "id": "420",
  "time": "2020-12-02T14:37:35.485Z",
  "status": 0,
  "value": "08D8"
}
  • Convert the received data.

Type of the measurement that is being read - 0x8800 - Temperature - is s16 - 2 bytes (signed).

There is status. To decode what a status' value means, go to Status Code. The values can be converted here. On the website, there are three views.

In the first view, choose Text and enter "0".

In the second view, choose Decode. Choose Integer. Format in this view should be Decimal. In Type choose 16-bit signed integer (I16) - since the measurement has a type of s16 (2 bytes signed). Byte order should be Big-endian.

In the third view, choose Bytes. Format should be hexadecimal. Group by Byte. A received result in this view is "00 00".

Receive a result: a decimal 0 is hex 0000. Switch back to Status Codes and find 0000. A received 0000 status code is "OK". It means that an 0x8800 - Temperature measurement was successfully read.

Switch back to the client. A value is 08D8 and it can be converted here.

In the first view, choose Bytes. Format hexadecimal. Group by Byte. Enter "08D8".

In the second view, choose Encode. Choose Integer. Format Decimal. Type 16-bit signed integer (I16). Byte order Big-endian.

In the third view, choose Text. A received result in this view is "2264". Go back to Temperature. In Examples, it's mentioned a value is multiplied by 100. A final received result is: 2264/100 = 22.64 ºC.

read

mt/gateway/{g}/request/{d}/read/{identifier-name}

Example:

mt/gateway/c792f46aea0a/request/c9b6565ad837/read/temperature

{
  "id": "00"
}

Response:

mt/gateway/c792f46aea0a/response/c9b6565ad837/read/temperature

{
  "id": "00",
  "time": "2021-06-52T16:00:52.304Z",
  "status": 0,
  "value": 25.56
}

write-raw

Writing a property is alike to reading a property.

mt/gateway/{g}/request/{d}/write-raw/{identifier}

Let's write a 0x9800 - Alarm State / SOS property to the MT PocketClip 231 to turn off Alarm mode.

  • In Publish section of MQTT Explorer, there is Topic. Write a property with the following command:

mt/gateway/e4ebc3f77f09/request/f3d77bb046f5/write-raw/9800
Where e4ebc3f77f09 is GW's MAC and f3d77bb046f5 is the PockectClip's MAC.

  • Choose json.

  • Go to MT PocketClip 231's Properties list and choose the property. Let's write 0x98.00 - Alarm State / SOS. To turn Alarm mode off, write "00" value.

  • Put the following json to a Publish section: 

    {
    "id": "421",
    "value":"00"
}

  • Click Publish.

The topic 'request' contains: 

mt/gateway/e4ebc3f77f09/request/f3d77bb046f5/write-raw/9800

{
  "id": "421",
  "value": "00"
}
The topic 'response' contains:

mt/gateway/e4ebc3f77f09/response/f3d77bb046f5/write-raw/9800

{
  "id": "421",
  "time": "2020-12-02T14:56:12.187Z",
  "status": 0
}
  • Receive a status: 0 decimal is 0000 in hex. A received 0 status means that property has been written successfully and the PocketClip has Alarm state off.

write

mt/gateway/{g}/request/{d}/write/{identifier-name}

Example:

mt/gateway/c792f46aea0a/request/c9b6565ad837/write/led-0-control

{
    "id": "01",
    "value": "1000"
}

Response:

mt/gateway/c792f46aea0a/response/c9b6565ad837/write/led-0-control

{
  "id": "01",
  "time": "2021-06-52T16:24:51.360Z",
  "status": 0,
}

The red LED light is on for 500 milliseconds.