This guide will help you to get familiar with MQTT Connector configuration for ThingsBoard IoT Gateway. Use general configuration to enable this Connector. The purpose of this Connector is to connect to an external MQTT broker and subscribe to data feed from devices. The connector is also able to push data to MQTT brokers based on the updates/commands from ThingsBoard.
This connector is useful when you have local MQTT broker in your facility or corporate network and you would like to push data from this broker to ThingsBoard.
We will describe connector configuration file below.
Connector configuration: mqtt.json
Connector configuration is a JSON file that contains information about how to connect to external MQTT broker, what topics to use when subscribing to data feed and how to process the data. Let’s review the format of the configuration file using the example below.
Example of MQTT Connector config file.
The example listed below will connect to MQTT broker in a local network deployed on server with IP 192.168.1.100. Connector will use basic MQTT auth using username and password. Then, connector will subscribe to a list of topics using topic filters from the mapping section. See more info in the description below.
Section “broker”
Parameter | Default value | Description |
---|---|---|
name | Default Local Broker | Broker name for logs and saving to persistent devices. |
host | localhost | Mqtt broker hostname or ip address. |
port | 1883 | Mqtt port on the broker. |
clientId | ThingsBoard_gateway | This is the client ID. It must be unique for each session. |
version | 5 | MQTT protocol version. |
sendDataOnlyOnChange | false | Sending only if data changed from last check, if not – data will be sent after every check. |
Subsection “security”
Subsection “security” provides configuration for client authorization at Mqtt Broker.
One type of security configuration is basic. For authorization, a combination of username and password provided in this section, in config will be used.
Security subsection in configuration file will look like this:
|
Anonymous auth is the most simple option. It is useful for testing on public MQTT brokers, like test.mosquitto.org.
Security subsection in configuration file will look like this:
|
The table below describes the parameters required to configure authorization on MQTT broker.
Security subsection in configuration file will look like this:
|
Section “mapping”
This configuration section contains an array of topics that the gateway will subscribe to after connecting to the broker, along with settings about processing incoming messages (converter)..
Parameter | Default value | Description |
---|---|---|
topicFilter | sensor/data | Topic address for subscribing. |
The topicFilter supports special symbols: ‘#’ and ‘+’, allowing to subscribe to multiple topics.
Also, MQTT connector supports shared subscriptions. To create shared subscription you need to add “$share/” as a prefix for topic filter and shared subscription group name. For example to subscribe to the my-shared-topic in group my-group-name you can set the topic filter to “$share/my-group-name/my-shared-topic”.
Let’s assume we would like to subscribe and process the following data from Thermometer devices:
Example Name | Topic | Topic Filter | Payload | Comments |
Example 1 | sensor/data | sensor/data | {"serialNumber": "SN-001", "sensorType": "Thermometer", "sensorModel": "T1000", "temp": 42, "hum": 58} | Device Name is part of the payload |
Example 2 | sensor/SN-001/data | sensor/+/data | {"sensorType": "Thermometer", "sensorModel": "T1000", "temp": 42, "hum": 58} | Device Name is part of the topic |
In this case the following messages are valid:
Example 1:
1
mosquitto_pub -h YOUR_MQTT_BROKER_HOST -p YOUR_MQTT_BROKER_PORT -t "sensor/data" -m '{"serialNumber": "SN-001", "sensorType": "Thermometer", "sensorModel": "T1000", "temp": 42, "hum": 58}'
Example 2:
1
mosquitto_pub -h YOUR_MQTT_BROKER_HOST -p YOUR_MQTT_BROKER_PORT -t "sensor/SN-001/data" -m '{"sensorType": "Thermometer", "sensorModel": "T1000", "temp": 42, "hum": 58}'
Now let’s review how we can configure JSON converter to parse this data
Subsection “converter”
This subsection contains configurations for processing incoming messages.
The types of MQTT converters are as follows:
- json – Default converter
- raw – Raw default converter
- custom – Custom converter (You can write it yourself, and it will be used to convert incoming data from the broker.)
Json converter is the default converter, it looks for ‘deviceName’, ‘deviceType’, attributes and telemetry in the incoming message from the broker, following the rules described in this subsection:
Note: The device profile is set when the device is created. Changing the device profile using a Gateway is not supported. Mapping subsection for Example 1 will look like:
Mapping for Example 2 will look like:
|
Bytes converter is the default converter, it looks for ‘deviceName’, ‘deviceType’, attributes and telemetry in the incoming message from the broker, following the rules described in this subsection:
Note: The device profile is set when the device is created. Changing the device profile using a Gateway is not supported. Mapping subsection will look like:
|
A custom converter is converter written for some device:
Converter subsection in the configuration will look like:
|
Note: You can specify multiple mapping objects inside the array.
Also, you can combine values from MQTT message in attributes, telemetry and serverSideRpc section, for example:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
{
"topicFilter": "sensor/data",
"converter": {
"type": "json",
"deviceNameJsonExpression": "${serialNumber}",
"deviceTypeJsonExpression": "${sensorType}",
"timeout": 60000,
"attributes": [],
"timeseries": [
{
"type": "integer",
"key": "temperature",
"value": "${temp}"
},
{
"type": "integer",
"key": "humidity",
"value": "${hum}"
},
{
"type": "string",
"key": "combine",
"value": "${hum}:${temp}"
}
]
}
}
}
Mapping process subscribes to the MQTT topics using topicFilter parameter of the mapping object. Each message that is published to this topic by other devices or applications is analyzed to extract device name, type and data (attributes and/or timeseries values). By default, gateway uses Json converter, but it is possible to provide custom converter. See examples in the source code.
Now let’s review an example of sending data from “SN-001” thermometer device.
Let’s assume MQTT broker is installed locally on your server.
Use terminal to simulate sending message from the device to the MQTT broker:
1
mosquitto_pub -h 127.0.0.1 -p 1883 -t "sensor/data" -m '{"serialNumber": "SN-001", "sensorType": "Thermometer", "sensorModel": "T1000", "temp": 42, "hum": 58}'
The device will be created and displayed in ThingsBoard based on the passed parameters.
Section “connectRequests”
ThingsBoard allows sending RPC commands and notifications about device attribute updates to the device. But in order to send them, the platform needs to know if the target device is connected and what gateway or session is used to connect the device at the moment. If your device is constantly sending telemetry data - ThingsBoard already knows how to push notifications. If your device just connects to MQTT broker and waits for commands/updates, you need to send a message to the Gateway and inform that device is connected to the broker.
1. Name in a message from broker:
Parameter | Default value | Description |
---|---|---|
topicFilter | sensor/connect | Topic address on the broker, where the broker sends information about new connected devices. |
deviceNameJsonExpression | ${serialNumber} | JSON-path expression, for looking the new device name. |
2. Name in topic address:
Parameter | Default value | Description |
---|---|---|
topicFilter | sensor/+/connect | Topic address on the broker, where the broker sends information about new connected devices. |
deviceNameTopicExpression | (?<=sensor\/)(.*?)(?=\/connect) | Regular expression for looking the device name in topic path. |
This section in configuration looks like:
1
2
3
4
5
6
7
8
9
10
"connectRequests": [
{
"topicFilter": "sensor/connect",
"deviceNameJsonExpression": "${serialNumber}"
},
{
"topicFilter": "sensor/+/connect",
"deviceNameTopicExpression": "(?<=sensor\/)(.*?)(?=\/connect)"
}
]
In this case the following messages are valid:
1
mosquitto_pub -h YOUR_MQTT_BROKER_HOST -p YOUR_MQTT_BROKER_PORT -t "sensor/connect" -m '{"serialNumber":"SN-001"}'
1
mosquitto_pub -h YOUR_MQTT_BROKER_HOST -p YOUR_MQTT_BROKER_PORT -t "sensor/SN-001/connect" -m ''
Now let’s review an example.
Use a terminal to simulate sending a message from the device to the MQTT broker:
1
mosquitto_pub -h 127.0.0.1 -p 1883 -t "sensor/connect" -m '{"serialNumber": "SN-001"}'
Your ThingsBoard instance will get information from the broker about last connecting time of the device. You can see this information under the “Server attributes” scope in the “Attributes” tab.
Section “disconnectRequest”
This configuration section is optional.
Configuration, provided in this section will be used to get information from the broker about disconnecting device.
If your device just disconnects from MQTT broker and waits for commands/updates, you need to send a message to the Gateway and inform it that device is disconnected from the broker.
1. Name in a message from broker:
Parameter | Default value | Description |
---|---|---|
topicFilter | sensor/disconnect | Topic address on the broker, where the broker sends information about disconnected devices. |
deviceNameJsonExpression | ${serialNumber} | JSON-path expression, for looking the new device name. |
2. Name in topic address:
Parameter | Default value | Description |
---|---|---|
topicFilter | sensor/+/disconnect | Topic address on the broker, where the broker sends information about disconnected devices. |
deviceNameTopicExpression | (?<=sensor\/)(.*?)(?=\/connect) | Regular expression for looking the device name in topic path. |
This section in configuration file looks like:
1
2
3
4
5
6
7
8
9
10
"disconnectRequests": [
{
"topicFilter": "sensor/disconnect",
"deviceNameJsonExpression": "${serialNumber}"
},
{
"topicFilter": "sensor/+/disconnect",
"deviceNameTopicExpression": "(?<=sensor\/)(.*?)(?=\/disconnect)"
}
]
In this case the following messages are valid:
1
mosquitto_pub -h YOUR_MQTT_BROKER_HOST -p YOUR_MQTT_BROKER_PORT -t "sensor/disconnect" -m '{"serialNumber":"SN-001"}'
1
mosquitto_pub -h YOUR_MQTT_BROKER_HOST -p YOUR_MQTT_BROKER_PORT -t "sensor/SN-001/disconnect" -m ''
Now let’s review an example.
Use a terminal to simulate sending a message from the device to MQTT broker:
1
mosquitto_pub -h 127.0.0.1 -p 1883 -t "sensor/disconnect" -m '{"serialNumber": "SN-001"}'
Your ThingsBoard instance will get information from the broker about last disconnecting time of the device. You can see this information under the “Server attributes” scope in the “Attributes” tab.
Section “attributeRequests”
This configuration section is optional.
In order to request client-side or shared device attributes to ThingsBoard server node, Gateway allows sending attribute requests.
Parameter | Default value | Description |
---|---|---|
retain | false | If set to true, the message will be set as the “last known good”/retained message for the topic. |
topicFilter | v1/devices/me/attributes/request | Topic for attribute request |
deviceNameJsonExpression | ${serialNumber} | JSON-path expression, for looking the device name in topicFilter message |
attributeNameJsonExpression | ${versionAttribute} | JSON-path expression, for looking the attribute name in topicFilter message |
topicExpression | devices/${deviceName}/attrs | JSON-path expression, for formatting reply topic |
valueExpression | ${attributeKey}: ${attributeValue} | Message that will be sent to topic from topicExpression |
This section in configuration file looks like:
1
2
3
4
5
6
7
8
9
10
"attributeRequests": [
{
"retain": false,
"topicFilter": "v1/devices/me/attributes/request",
"deviceNameJsonExpression": "${serialNumber}",
"attributeNameJsonExpression": "${versionAttribute}",
"topicExpression": "devices/${deviceName}/attrs",
"valueExpression": "${attributeKey}: ${attributeValue}"
}
]
Also, you can request multiple attributes at once. Simply add one more JSON-path to attributeNameExpression parameter. For example, we want to request two shared attributes in one request, our config will look like:
1
2
3
4
5
6
7
8
9
10
"attributeRequests": [
{
"retain": false,
"topicFilter": "v1/devices/me/attributes/request",
"deviceNameJsonExpression": "${serialNumber}",
"attributeNameJsonExpression": "${versionAttribute}, ${pduAttribute}",
"topicExpression": "devices/${deviceName}/attrs",
"valueExpression": "${attributeKey}: ${attributeValue}"
}
]
Section “attributeUpdates”
This configuration section is optional.
ThingsBoard allows to provision device attributes and fetch some of them from the device application.
You can treat this as a remote configuration for devices. Your devices are able to request shared attributes from ThingsBoard.
See user guide for more details.
The “attributeRequests” configuration allows configuring the format of the corresponding attribute request and response messages.
Parameter | Default value | Description |
---|---|---|
retain | false | If set to true, the message will be set as the “last known good”/retained message for the topic. |
deviceNameFilter | .* | Regular expression device name filter, used to determine, which function to execute. |
attributeFilter | uploadFrequency | Regular expression attribute name filter, used to determine, which function to execute. |
topicExpression | sensor/${deviceName}/${attributeKey} | JSON-path expression used for creating topic address to send a message. |
valueExpression | {\”${attributeKey}\”:\”${attributeValue}\”} | JSON-path expression used for creating the message data that will send to topic. |
This section in configuration file looks like:
1
2
3
4
5
6
7
8
9
"attributeUpdates": [
{
"retain": false,
"deviceNameFilter": ".*",
"attributeFilter": "uploadFrequency",
"topicExpression": "sensor/${deviceName}/${attributeKey}",
"valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
}
]
Let’s look at an example.
Run the command below to start the mosquitto_sub client, subscribing to the topic “sensor/SN-001/firmwareVersion” of the local broker. Start waiting for new messages from ThingsBoard server to broker.
1
mosquitto_sub -t sensor/SN-001/firmwareVersion
Update device attribute value on the ThingsBoard server following these steps:
- Open the “Devices” page;
- Click on your device and navigate to the “Attributes” tab;
- Choose “Shared attributes” scope and click on the “pencil” icon next to “firmwareVersion” attribute.
- Change firmware version value from “1.1” to “1.2”. Then click “Update” button.
The firmware version has been updated to “1.2”.
Broker received new message from the ThingsBoard server about updating attribute “FirmwareVersion” to “1.2”.
Server side RPC commands
ThingsBoard allows sending RPC commands to the device that is connected to ThingsBoard directly or via Gateway.
Configuration, provided in this section is used for sending RPC requests from ThingsBoard to device.
Parameter | Default value | Description |
---|---|---|
deviceNameFilter | .* | Regular expression device name filter, is used to determine, which function to execute. |
methodFilter | echo | Regular expression method name filter, is used to determine, which function to execute. |
requestTopicExpression | sensor/${deviceName}/request/${methodName}/${requestId} | JSON-path expression, is used for creating topic address to send RPC request. |
responseTopicExpression | sensor/${deviceName}/response/${methodName}/${requestId} | JSON-path expression, is used for creating topic address to subscribe for response message. |
responseTimeout | 10000 | Value in milliseconds. If there is no response within this period after sending the request, gateway will unsubscribe from the response topic. |
valueExpression | ${params} | JSON-path expression, is used for creating data for sending to broker. |
This section in configuration file looks like:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
"serverSideRpc": [
{
"deviceNameFilter": ".*",
"methodFilter": "echo",
"requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
"responseTopicExpression": "sensor/${deviceName}/response/${methodName}/${requestId}",
"responseTimeout": 10000,
"valueExpression": "${params}"
},
{
"deviceNameFilter": ".*",
"methodFilter": "no-reply",
"requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
"valueExpression": "${params.hum}::${params.temp}"
}
]
You can use deviceNameFilter and methodFilter to apply different mapping rules for various devices/methods. Once Gateway receives RPC request from the server to the device, it will publish the corresponding message based on requestTopicExpression and valueExpression. In case you expect a reply to the request from the device, you should also specify responseTopicExpression and responseTimeout. The Gateway will subscribe to the “response” topic and wait for a device reply until “responseTimeout” is reached (in milliseconds).
Here is an example of an RPC request (rpc-request.json) that needs to be sent from the server:
1
2
3
4
5
6
{
"method": "echo",
"params": {
"message": "Hello!"
}
}
Also, every telemetry and attribute parameter has built-in GET and SET RPC methods out of the box, so you don’t need to configure it manually. To use them, make sure you set all the required parameters (in the case of MQTT Connector, these are the following: requestTopicExpression, responseTopicExpression, responseTimeout, valueExpression). See the guide.
Next steps
Explore guides related to main ThingsBoard features:
- Data Visualization - how to visualize collected data.
- Device attributes - how to use device attributes.
- Telemetry data collection - how to collect telemetry data.
- Using RPC capabilities - how to send commands to/from devices.
- Rule Engine - how to use rule engine to analyze data from devices.