Skip to content

Getting Started

This tutorial shows all the steps needed to configure a gateway and exploring data from nearby Meshtech devices. It will briefly introduce the concepts performed in each step.

In this tutorial we will use these devices:

Device Role
MT MeshConnect 2011 gateway
Minew MBM01 0043 extender
Raytac MDBT50Q-RX 0040 extender
MT MultiTracker 11x sensor
Minew B10 0011-03 wristband

If you have different devices than listed, the procedure should be quite similar, but some details might differ slightly. Visit the documentation for your particular device if needed.

Device Management Portal

Initial configuration is most easily done by logging in to the Meshtech Management Portal.

A link with invitation and instructions should be received by e-mail for new customers. Existing customers can ask their admin user to create a user for them.

Claim your Gateway

After logging in to the portal, you will see a list of all gateways associated with your user/customer. If you do not see the gateway you are trying to control/configure, you need to claim it. To add a gateway you own, use the Claim button and type in the gateway ID. ID's are lowercase and should be entered in this format bmac-{macaddress}, for example bmac-abcdef012345. The BLE MAC address can be found printed on a sticker on the gateway. Connect BLE antenna, ethernet plug and power for the gateway. If gateway is successfully powered on, with an internet connection it should have a green symbol in the connectivity column. This means it is accessible to interact with from the portal and we can move to the next step. If the connectivity status is not green, you can try to click the Sync at the bottom of the Information tab.

Configure Backend Connection

MT2 is the recommended backend type for new customers. In MT2 the gateway connect to an MQTT broker where it will publish data from all devices on different topics as described in MT2 API. The gateway is configured via a backend.json configuration file where credentials and endpoint of MQTT broker is specified. In this getting started guide we will use mqtt.meshtech.no as an example for demo purpose, but you are advised to host your own MQTT broker where you control who can access the data and interact with your devices once you move into development and production. Alternatively, you can use the Clarify frontend if you do not wish to develop your own system for consuming data and interacting with devices.

  • For demo purpose, use this config file. Save it somewhere on your computer where you can find it in the next step.
  • Edit the backend.json template file you downloaded and add userName and password fields with values as provided by Meshtech. Save the file.
  • To send backend configuration to your gateway, select checkbox next to gateway ID you wish to configure, and click New Job button. In the Configurations section, click Choose File next to Backend. Select appropriate backend.json file and click Submit.

Enabling Devices

We have now configured the gateway, and we can start enabling our BLE devices through this gateway. By default all Meshtech devices are delivered in Storage mode.

To enable a device you must:

  1. Wake up the device (so that it starts advertising)
  2. Write the property 0x8110 - Device Mode to "connected" or "unconnected".

The first step is required for most devices and is typically done by holding down a button for at least 1 second. See the documentation for the particular device for details on this. Writing of the property is done through the gateway (directly or via an network of extenders).

Discovery and enabling of devices can be automated through the backend connection, but in this Getting Started guide we will use the Management Portal.

  1. Start by clicking the gateway ID of your gateway.
  2. Select Devices tab, and click Request button to fetch a list of devices the gateway has observed. This will likely be a very short list at this point, unless you have several enabled devices nearby already.
  3. Start by enabling extenders, Minew MBM01 in this case.
  4. To wake up the device, press and hold the button for more than 1s until LED light up.
  5. Click Request button again, this device should now be found in the list, in storage mode.
  6. Click Storage in the DEVICE MODE column in the row of the device, click Switch to and select Connected. This will write the 0x8110 - Device Mode property to "connected". You also do this by clicking the device ID link and use the Read/Write tab of the Interact dialog.
  7. The device will now switch mode to connected and attempt to join a network. After 20s has passed, it is expected to have joined the network and connected to the gateway if it is in range. Verify this by going to Network tab, and click Request button.
  8. Repeat steps 4-7 for all the devices you wish to enable, keeping in mind that some devices (wristbands/trackers) typically operate in unconnected mode, so select Unconnected for those in step 6 instead of Connected.

Interacting with Backend (MQTT)

We will now capture and explore the data being sent from the devices we enabled, using MQTT Explorer client.

Connection Setup

First we need to configure our MQTT Explorer client to connect to the same MQTT broker that we pointed our gateway to earlier: mqtt.meshtech.no.

Open the client and add a new connection by clicking the + next to Connections. Enter the following:

  • Name: meshtech-demo
  • Validate certificate: on
  • Encryption (tls): on
  • Protocol: mqtt://
  • Host: mqtt.meshtech.no
  • Port: 8883
  • Username and password as provided by Meshtech

Click Save then Connect.

Exploring Incoming Data

By default MQTT Explorer subscribe to all topics (wildcard character #), and thus all traffic going through mqtt.meshtech.no will appear.

Only messages published after we subscribed (Connected) our MQTT Explorer client will appear. If you do not see your gateway/device immediately, it could be that it has not published anything since you connected. Wait a moment, or force an update, for example by clicking the button on the MT MultiTracker 11x. This should appear quickly in topic /mt/gateway/{gwmac}/device/{devicemac}/event-decoded/button-0. To navigate and explore topics, click the name to expand. In this example click 'mt', 'gateway', '{gwmac}', 'device', '{devicemac}', 'event-decoded' then 'button-0'.

Interacting with Devices

Sending requests to devices is done by publishing to topics.

For example, to read the latest temperature sample (as a property), publish according to the following example-topic:

Topic: mt/gateway/c792f46aea0a/request/c9b6565ad837/read-decoded/temperature

Message Payload: 

{
  "id": "my_request_1"
}

The gateway will then respond by publishing a response like this:

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

Message Payload:

{
  "id": "my_request_1",
  "time": "2024-02-02T11:09:28.478Z",
  "status": 0,
  "value": 22.12,
  "responseTime": 1873,
  "origin": 0, 
  "route": "0FFFFFFFFFF0"
}

Note

  • value type will depend on which property you read. In this case it is a number, 22.12 degrees C.
  • status = 0 means that the request succeded.
  • responseTime is the number of milliseconds it took from the gateway sent the request into the network to the response was received.
  • origin = 0 means that the device itself responded.
  • route = "0FFFFFFFFFF0" means that origin (device) is in the network at route 0FFFFFFFFFF0.

Writing a property is alike to reading a property.

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

For example, to turn the red LED on for 2 seconds (2000 milliseconds), publish like this:

Topic: mt/gateway/c792f46aea0a/request/c9b6565ad837/write-decoded/led-0-control

Message Payload: 

{
  "id": "my_request_2", 
  "value": 2000
}

The gateway will respond like this:

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

Message Payload: 

{
  "id": "my_request_2",
  "time": "2024-02-02T12:01:24.419Z",
  "status": 0,
  "responseTime": 1298,
  "origin": 0,
  "route": "0FFFFFFFFFF0"
}