MQTT

Anonymous is the simplest option: no credentials are required to publish/subscribe on the MQTT broker. It can be useful for testing
(e.g., public test brokers), but not recommended for production because it allows unattended access..

Basic authentication option uses a username and password configured on the MQTT broker. It’s a good default for most setups - just use strong, unique credentials. For stronger identity and mutual verification, consider certificate-based authentication.

Certificate-based authentication uses TLS so the gateway and broker verify each other. Set the Path to CA certificate file to your CA certificate (to trust the broker), Path to client certificate file to the gateway’s client certificate, and Path to private key file to its private key (so the broker can authenticate the gateway). Use the broker’s TLS port (typically 8883) for encrypted, production-grade security.

The device name and profile can be extracted from the incoming message. In this example, we will use json path to specify the device name and profile.

As an example, we will use ThingsBoard MQTT Demo Broker, which can be run using Docker and the following command:

docker run -it -p 1884:1884 thingsboard/tb-gw-mqtt-broker:latest

The broker available at 0.0.0.0:1884 and publishes data to the topic sensor/data with the following JSON payload:

{
    "serialNumber": "SN-001",
    "sensorType": "Thermometer",
    "sensorModel": "T-100",
    "temp": 22.82,
    "hum": 59.3
}

We also want to extract the device name from the serialNumber field and the device profile from the sensorType field. Let’s configure the device name and profile in the MQTT connector. For this purpose, follow these steps:

1. Go to “Entities” → “Gateways” on the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the created MQTT connector, select “Basic” click on the “Data mapping” Click on the ”+ Add mapping” button.

   

4. In the opened window, fill in “Topic filter” field with sensor/data, also fill “QoS” with one of these values(0,1,2) and for “Payload type” select JSON.

   

5. Then under “Device” subsection choose “Message” for the “Name” field, enter ${serialNumber}, this is the json path to the field that contains the device name.

   

6. Then under “Profile name” subsection choose “Message” for the “Name” field, enter ${sensorType}, this is the json path to the field that contains the device name.

   

7. Also, we need to add at least one attribute/time series because the connector will not add a device without any data to read. Click on the “pencil” icon next to the “Time series” section.

   

8. In the opened window, click on the “Add time series” button and fill the fields as on the corresponding image. Do not forget to save changes.

   

Now we can check if the device name and profile are set correctly. Go to “Entities” > “Devices” and as you can see, the device name is set to SN-001 and the profile is set to Thermometer.

If you are using advanced configuration mode and want to set the device name and profile using topic and json path, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensor/data",
      "subscriptionQos": 1,
      "converter": {
        "type": "json",
        "deviceInfo": {
          "deviceNameExpression": "${serialNumber}",
          "deviceNameExpressionSource": "message",
          "deviceProfileExpressionSource": "message",
          "deviceProfileExpression": "${sensorType}"
        },
        "attributes": [
          {
            "key": "model",
            "type": "string",
            "value": "${sensorModel}"
          }
        ],
        "timeseries": [
          {
            "key": "temperature",
            "type": "double",
            "value": "${temp}"
          }
        ]
      }
    }
  ],
  "requestsMapping": {}
}

The device name and profile can be extracted from the topic. In this example, we will use regex to specify the device name and constant for profile.

As an example, we will use ThingsBoard MQTT Demo Broker, which can be run using Docker and the following command:

docker run -it -p 1884:1884 thingsboard/tb-gw-mqtt-broker:latest

The broker available at 0.0.0.0:1884 and publishes data to the topic sensor/Thermo-A/data where Thermo-A is the device name: with the following JSON payload:

{
    "sensorModel": "T-100",
    "temp": 23.82,
    "hum": 60.3
}

To match this topic, either enter sensor/Thermo-A/data in Topic filter field or use wildcards to subscribe to both sensor/Thermo-A/data and let’s say sensor/Thermo-B/data.

Let’s configure the MQTT connector to take the device name from the topic and use a constant for the device profile (e.g., Thermometer). Follow these steps:

1. Go to “Entities” → “Gateways” on the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the created MQTT connector, select “Basic” click on the “Data mapping” Click on the ”+ Add mapping” button.

   

4. In the opened window, fill in “Topic filter” field with sensor/+/data, also fill “QoS” with one of these values(0,1,2) and for “Payload type” select JSON.

   

5. Then under “Device” subsection choose “Topic” for the “Name” field, enter (?<=sensor/)(.*?)(?=/data), this is the regex used to extract device name.

   

6. Then under “Profile name” subsection choose “Constant” for the “Name” field, enter Thermometer, this is Constant value that will be used to form device profile name.

   

7. Also, we need to add at least one attribute/time series because the connector will not add a device without any data to read. Click on the “pencil” icon next to the “Time series” section.

   

8. In the opened window, click on the “Add time series” button and fill the fields as on the corresponding image. Do not forget to save changes.

   

Now we can check if the device name and profile are set correctly. Go to “Entities” > “Devices” and as you can see, the device name is set to Thermo-A and the profile is set to Thermometer.

If you are using advanced configuration mode and want to set the device name and profile using topic and json path, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensor/+/data",
      "subscriptionQos": 1,
      "converter": {
        "type": "json",
        "deviceInfo": {
          "deviceNameExpression": "(?<=sensor/)(.*?)(?=/data)",
          "deviceNameExpressionSource": "topic",
          "deviceProfileExpressionSource": "constant",
          "deviceProfileExpression": "Thermometer"
        },
        "attributes": [],
        "timeseries": [
          {
            "key": "temperature",
            "type": "double",
            "value": "${temp}"
          }
        ]
      }
    }
  ],
  "requestsMapping": {}
}

The device name and profile can be extracted from the message source and bytes payload. In this example, we will use slices to specify the device name and constant for profile.

As an example, we will use ThingsBoard MQTT Demo Broker, which can be run using Docker and the following command:

docker run -it -p 1884:1884 thingsboard/tb-gw-mqtt-broker:latest

The broker available at 0.0.0.0:1884 and publishes data to the topic sensor/raw_data with the following BYTES payload:

b"AM-120" — Python bytes literal (ASCII)

Suppose we want to create a device from this payload. The first four bytes represent the device name, and the remaining bytes represent the temperature value.

Configure the MQTT connector to extract the device name from the raw bytes and use a constant value for the device profile (for example, default).

Follow these steps:

1. Go to “Entities” → “Gateways” on the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the created MQTT connector, select “Basic” click on the “Data mapping” Click on the ”+ Add mapping” button.

   

4. In the opened window, fill in “Topic filter” field with sensor/raw_data, also fill “QoS” with one of these values(0,1,2) and for “Payload type” select Bytes.

   

5. Then under “Device” subsection choose “Message” for the “Name” field, enter [0:4], those are the slices used to extract device name.

   

6. Then under “Profile name” subsection choose “Constant” for the “Name” field, enter default, this is Constant value that will be used to form device profile name.

   

7. Also, we need to add at least one attribute/time series because the connector will not add a device without any data to read as we remember. The first four bytes represent the device name, and the remaining bytes represent the temperature value. Click on the “pencil” icon next to the “Time series” section.

   

8. In the opened window, click on the “Add time series” button and fill the fields as on the corresponding image. Do not forget to save changes.

   

Now we can check if the device name and profile are set correctly. Go to “Entities” > “Devices” and as you can see, the device name is set to AM-1 and the profile is set to default.

If you are using advanced configuration mode and want to set the device name and profile using topic and json path, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensor/raw_data",
      "subscriptionQos": 1,
      "converter": {
        "type": "bytes",
        "deviceInfo": {
          "deviceNameExpression": "[0:4]",
          "deviceNameExpressionSource": "message",
          "deviceProfileExpressionSource": "constant",
          "deviceProfileExpression": "default"
        },
        "attributes": [],
        "timeseries": [
          {
            "key": "temp",
            "type": "raw",
            "value": "[4:]"
          }
        ]
      }
    }
  ],
  "requestsMapping": {}
}

Attributes and time series data can be retrieved using json-path in the MQTT Connector. This allows to extract the required field(s) from the JSON payload received on the subscribed topic(s).”.

As an example, we will use ThingsBoard MQTT Demo Broker, which can be run using Docker and the following command:

docker run -it -p 1884:1884 thingsboard/tb-gw-mqtt-broker:latest

The broker available at 0.0.0.0:1884 and publishes data to the topic sensor/data with the following JSON payload:

{
    "serialNumber": "SN-001",
    "sensorType": "Thermometer",
    "sensorModel": "T-100",
    "temp": 22.82,
    "hum": 59.3
}

We’ll map sensorModel → model and temp → timeseries temperature. Next, configure the device name and profile in the MQTT connector. Follow these steps:

1. Go to “Entities” → “Gateways” on the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the MQTT connector, click on the “Data mapping” tab. Select data mapping with device to which you want to add time series data (if you do not know how to add a new device, see the Getting Started guide or Data mapping section of this guide with respective examples).

   

4. In the opened data mapping windows, click on the “pencil” icon next to the “Attributes” section.

   

5. Click on the “Add attribute” button. Fill in the “Key” field with model, also select String in “Type” field, and fill in the “Value” field with ${sensorModel}. This is a json-path.

   

6. Remember to save your changes by clicking the designated button.

   

7. In the opened data mapping windows, click on the “pencil” icon next to the “Time series” section.

   

8. Click on the “Add time series” button. Fill in the “Key” field with temperature, also select Double in “Type” field, and fill in the “Value” field with json-path - ${temp}. This is a json-path.

   

9. Remember to save your changes by clicking the designated button.

   

Now we can check if the attribute data is set correctly. Go to “Entities” > “Devices”, select a created device and as you can see, the humidity data is available in the “Attributes” section:

Now we can check if the temperature data is sending correctly. Go to “Entities” > “Devices”, select a created device and as you can see, the humidity data is available in the “Latest telemetry” section:

If you are using advanced configuration mode and want to set the temperature and model data using json-path, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensor/data",
      "subscriptionQos": 1,
      "converter": {
        "type": "json",
        "deviceInfo": {
          "deviceNameExpression": "${serialNumber}",
          "deviceNameExpressionSource": "message",
          "deviceProfileExpressionSource": "message",
          "deviceProfileExpression": "${sensorType}"
        },
        "attributes": [
          {
            "key": "model",
            "type": "string",
            "value": "${sensorModel}"
          }
        ],
        "timeseries": [
          {
            "key": "temperature",
            "type": "double",
            "value": "${temp}"
          }
        ]
      }
    }
  ],
  "requestsMapping": {}
}

Attributes and time series data can be retrieved using slices in the MQTT Connector. This allows to extract the required field(s) from the BYTES payload received on the subscribed topic(s).

As an example, we will use ThingsBoard MQTT Demo Broker, which can be run using Docker and the following command:

docker run -it -p 1884:1884 thingsboard/tb-gw-mqtt-broker:latest

The broker available at 0.0.0.0:1884 and publishes data to the topic sensor/raw_data with the following BYTES payload:

b"AM-120" — Python bytes literal (ASCII)

The first four bytes represent the device name, and the remaining bytes represent the temperature value. Configure the MQTT connector to store the entire raw payload in the rawData attribute, and to parse bytes 5–6 as the temperature and publish it as the temp timeseries. Then configure the device name and profile in the MQTT connector.

Follow these steps:

1. Go to “Entities” → “Gateways” on the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the MQTT connector, click on the “Data mapping” tab. Select data mapping with device to which you want to add time series data (if you do not know how to add a new device, see the Getting Started guide or Data mapping section of this guide with respective examples).

   

4. In the opened data mapping windows, click on the “pencil” icon next to the “Attributes” section.

   

5. Click on the “Add attribute” button. Fill in the “Key” field with rawData, also select Raw in “Type” field, and fill in the “Value” field with [:]. Those are slices.

   

6. Remember to save your changes by clicking the designated button on the screenshot.

   

7. In the opened data mapping windows, click on the “pencil” icon next to the “Time series” section.

   

8. Click on the “Add time series” button. Fill in the “Key” field with temp, also select Raw in “Type” field, and fill in the “Value” field with [4:]. Those are slices.

   

9. Remember to save your changes by clicking the designated button on the screenshot.

   

Now we can check if the attribute data is set correctly. Go to “Entities” > “Devices”, select a created device and as you can see, the humidity data is available in the “Attributes” section:

Now we can check if the temperature data is sending correctly. Go to “Entities” > “Devices”, select a created device and as you can see, the humidity data is available in the “Latest telemetry” section:

If you are using advanced configuration mode and want to set the temperature and model data using json-path, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensor/raw_data",
      "subscriptionQos": 1,
      "converter": {
        "type": "bytes",
        "deviceInfo": {
          "deviceNameExpression": "[0:4]",
          "deviceNameExpressionSource": "message",
          "deviceProfileExpressionSource": "constant",
          "deviceProfileExpression": "default"
        },
        "attributes": [
           {
            "key": "rawData",
            "type": "raw",
            "value": "[:]"
          }
        ],
        "timeseries": [
          {
            "key": "temp",
            "type": "raw",
            "value": "[4:]"
          }
        ]
      }
    }
  ],
  "requestsMapping": {}
}

There are scenarios where the key names for time-series data and attributes need to be extracted directly from the MQTT topic structure. This can be particularly useful when dealing with dynamic topics or when the topic structure conveys important metadata. In this example, we will demonstrate how to configure the MQTT connector to extract key names for both time-series data directly from the topic using regular expression.

As an example, we will use ThingsBoard MQTT Demo Broker, which can be run using Docker and the following command:

docker run -it -p 1884:1884 thingsboard/tb-gw-mqtt-broker:latest

The broker available at 0.0.0.0:1884 and publishes data to the topic sensors/demo-device/{sensor-name}/value. The {sensor-name} part of the topic is dynamic and represents different sensors, such as temperature or humidity.

So the topics will look like this:

• sensors/demo-device/temperature/value with payload {"value": 25.5}
• sensors/demo-device/humidity/value with payload {"value": 60.2}

We’ll map the {sensor-name} part of the topic to time-series data.

Copy and paste the following configuration into the MQTT connector advanced configuration mode:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensors/demo-device/+/value",
      "subscriptionQos": 0,
      "converter": {
        "type": "json",
        "deviceInfo": {
          "deviceNameExpressionSource": "constant",
          "deviceNameExpression": "Demo Device",
          "deviceProfileExpressionSource": "constant",
          "deviceProfileExpression": "default"
        },
        "timeout": 60000,
        "attributes": [],
        "timeseries": [
          {
            "type": "double",
            "keySource": "topic",
            "key": "(?<=sensors/demo-device/)(.*?)(?=/value)",
            "value": "${value}"
          }
        ]
      }
    }
  ],
  "requestsMapping": {}
}

Let’s review the key parts of this configuration:

• The topicFilter is set to sensors/demo-device/+/value, where the + wildcard captures the dynamic sensor name.
• In the timeseries section, we use a regular expression in the key field to extract the sensor name from the topic. The regex (?<=sensors/demo-device/)(.*?)(?=/value) captures the part of the topic between sensors/demo-device/ and /value.
• The keySource is set to topic, indicating that the key name should be extracted from the topic.
• The value field uses ${value} to extract the actual sensor value from the JSON payload.

After applying this configuration, the MQTT connector will extract the sensor name from the topic and use it as the key name for both time-series data. So you will see that the corresponding time series are being updated correctly:

For a Connect request, the gateway must know which device name to target. You can extract it either from the Message payload using json-path or from the topic using a regex. Choose json-path when the device name is inside the JSON message; choose regex when it’s encoded in the topic.

Device SN-001 hasn’t sent telemetry for 10 minutes and is marked inactive, but you still need to send an RPC (and you’re not planning to resume telemetry). Let’s configure a Connect request in the MQTT connector to (re)announce the device so RPC can be delivered. We’ll demonstrate two ways to extract the device name:

• From message (JSON payload).
• From topic (e.g., sensor/SN-001/connect).

Follow these steps:

1. Go to “Entities” - “Gateways” on the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the MQTT connector, click on the “Basic”. Click the “Add mapping” under “Requests mapping” section to add new connect request mapping.

   

4. Select Connect request in the Request type field then fill the “Topic filter” with sensor/connect.

   

5. Select Name - source Message and Profile name - source Constant. In Value, enter ${serialNumber} for the device name and Thermometer for the device profile.

   

6. Remember to save your changes by clicking the designated button.

   

7. Select Connect request in the Request type field then fill the “Topic filter” with sensor/+/connect.

   

8. Select Name - source Topic and Profile name - source Constant. In Value, enter (?<=sensor/)(.*?)(?=/connect) for the device name and Thermometer for the device profile.

   

9. Remember to save your changes by clicking the designated button.

   

After 10 minutes without sending telemetry, device SN-001 is marked as inactive in ThingsBoard, as shown below:

To reactivate the device so it can receive RPC commands, we need to send a Connect request. Let’s demonstrate this with two examples:

Use a terminal to simulate sending a message from the device to the MQTT broker with the device name in the JSON payload:

mosquitto_pub -h 127.0.0.1 -p 1884 -t "sensor/connect" -m '{"serialNumber": "SN-001"}'

After sending this message, ThingsBoard updates both the lastActivityTime and lastConnectTime of the SN-001 device, and its status changes to Active:

The same reactivation can be achieved using the second mapping configuration, where the device name is extracted from the topic instead of the message payload:

mosquitto_pub -h 127.0.0.1 -p 1884 -t "sensor/SN-001/connect" -m ''

If you are using advanced configuration mode, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [],
  "requestsMapping": {
    "connectRequests": [
      {
        "topicFilter": "sensor/connect",
        "deviceInfo": {
          "deviceNameExpression": "${serialNumber}",
          "deviceNameExpressionSource": "message",
          "deviceProfileExpressionSource": "constant",
          "deviceProfileExpression": "Thermometer"
        }
      },
      {
        "topicFilter": "sensor/+/connect",
        "deviceInfo": {
          "deviceNameExpression": "(?<=sensor/)(.*?)(?=/connect)",
          "deviceNameExpressionSource": "topic",
          "deviceProfileExpressionSource": "constant",
          "deviceProfileExpression": "Thermometer"
        }
      }
    ]
  }
}

For a Disconnect request, the gateway must know which device name to target. You can extract it either from the Message payload using json-path or from the topic using a regex. Choose json-path when the device name is inside the JSON message; choose regex when it’s encoded in the topic.

Suppose you want to disconnect device SN-001 from the platform immediately, without waiting for the 10-minute inactivity timeout-useful for dashboards, alarms, and rule chains that react to status changes.

Let’s configure a Disconnect request in the MQTT connector to notify the platform when a device disconnects. We’ll demonstrate two ways to extract the device name:

• From message (JSON payload).
• From topic (e.g., sensor/SN-001/disconnect).

Follow these steps:

1. Go to “Entities” - “Gateways” on the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the MQTT connector, click on the “Basic”. Click the “Add mapping” under “Requests mapping” section to add new disconnect request mapping.

   

4. Select “Disconnect request” in the Request type field, enter the “Topic filter” as sensor/disconnect.

   

5. Select source type for Name field as Message. In Value, enter ${serialNumber} for the device name.

   

6. Remember to save your changes by clicking the designated button.

   

7. Select “Disconnect request” in the Request type field then fill the “Topic filter” with sensor/+/disconnect.

   

8. Select source type for Name field as Topic. In Value, enter (?<=sensor/)(.*?)(?=/disconnect) for the device name.

   

9. Remember to save your changes by clicking the designated button.

   

Let’s demonstrate how to use these disconnect request configurations with two examples:

When the device name is included in the message payload, you can send a disconnect request as follows:

mosquitto_pub -h 127.0.0.1 -p 1884 -t "sensor/disconnect" -m '{"serialNumber": "SN-001"}'

This message contains the device name in the JSON payload, which is extracted using the ${serialNumber} JSON path. After processing this message, ThingsBoard will mark the device SN-001 as disconnected.

When the device name is encoded in the topic path, you can send a disconnect request as follows:

mosquitto_pub -h 127.0.0.1 -p 1884 -t "sensor/SN-001/disconnect" -m ''

In this case, the device name is extracted from the topic using the regular expression (?<=sensor/)(.*?)(?=/disconnect). After processing this message, ThingsBoard will mark the device SN-001 as disconnected.

If you are using advanced configuration mode, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [],
  "requestsMapping": {
    "disconnectRequests": [
      {
        "topicFilter": "sensor/disconnect",
        "deviceInfo": {
          "deviceNameExpression": "${serialNumber}",
          "deviceNameExpressionSource": "message"
        }
      },
      {
        "topicFilter": "sensor/+/disconnect",
        "deviceInfo": {
          "deviceNameExpression": "(?<=sensor/)(.*?)(?=/disconnect)",
          "deviceNameExpressionSource": "topic"
        }
      }
    ]
  }
}

For an Attribute request, the gateway must know which device name to target and which attribute to request. You can extract the device name either from the Message payload using json-path or from the topic using a regex. Choose json-path when the device name is inside the JSON message; choose regex when it’s encoded in the topic.

Suppose you want to retrieve the current firmware version for device SN-001 from ThingsBoard to make decisions based on the firmware version.

Let’s configure an Attribute request in the MQTT connector to allow devices to request attribute values from ThingsBoard. We’ll demonstrate two ways to extract the device name:

• From message (JSON payload).
• From topic (e.g., sensor/SN-001/attributes/request).

Follow these steps:

1. Go to “Entities” - “Gateways” on the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the MQTT connector, click on the “Basic”. Click the “Add mapping” under “Requests mapping” section to add new attribute request mapping.

   

4. Select “Attribute request” in the Request type field, enter the “Topic filter” as v1/devices/me/attributes/request.

   

5. Configure the device name and attribute settings. For device name expression, select source type as Message and enter ${serialNumber} as the value. For attribute name expression, select source type as Message and enter ${versionAttribute}, ${pduAttribute} as the value.

   

6. Configure the response topic as devices/${deviceName}/attrs and the response value expression as ${attributeKey}: ${attributeValue}.

   

7. Remember to save your changes by clicking the designated button.

   

Let’s demonstrate how to use these attribute request configurations with two examples:

Suppose we have a device with an attribute firmwareVersion stored as a shared attribute in ThingsBoard and suppose we want to request this attribute for some purposes.

Let’s add this attribute to the device SN-001 in ThingsBoard first:

1. Go to “Devices” → select device SN-001 - “Attributes” tab - select “Shared attributes”.

2. Then click on the ”+” icon and add firmwareVersion attribute with type “String” and set it to 1.2.3 click the “Add” button.

This message contains the device name in the JSON payload, which is extracted using the ${serialNumber} JSON path, and the attribute name using the ${attributeNames} JSON path. After processing this message, ThingsBoard will retrieve the “firmwareVersion” attribute for device “SN-001” and publish it to the response topic.

The response will be published to the topic devices/SN-001/attrs with a payload like: Let’s subscribe to the response topic to see the result: Open terminal and type the following command and press Enter:

mosquitto_sub -h 127.0.0.1 -p 1884 -t devices/SN-001/attrs

Open another terminal to simulate sending a message from the device to the MQTT broker with the device name and attribute name in the JSON payload:

mosquitto_pub -h 127.0.0.1 -p 1884 -t v1/devices/me/attributes/request -m '{"serialNumber": "SN-001", "versionAttribute": "firmwareVersion"}'

This message contains the device name in the JSON payload, which is extracted using the ${serialNumber} JSON path, and the attribute name using the ${attributeNames} JSON path. After processing this message, ThingsBoard will retrieve the firmwareVersion attribute for device SN-001 and publish it to the response topic.)

firmwareVersion: "1.2.3"

If you are using advanced configuration mode, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensor/data",
      "subscriptionQos": 1,
      "converter": {
        "type": "json",
        "deviceInfo": {
          "deviceNameExpressionSource": "message",
          "deviceNameExpression": "${serialNumber}",
          "deviceProfileExpressionSource": "message",
          "deviceProfileExpression": "${sensorType}"
        },
        "timeout": 60000,
        "attributes": [],
        "timeseries": [
          {
            "type": "string",
            "key": "temperature",
            "value": "${temp}"
          }
        ]
      }
    }
  ],
  "requestsMapping": {
    "attributeRequests": [
      {
        "retain": false,
        "topicFilter": "v1/devices/me/attributes/request",
        "deviceInfo": {
          "deviceNameExpressionSource": "message",
          "deviceNameExpression": "${serialNumber}"
        },
        "attributeNameExpressionSource": "message",
        "attributeNameExpression": "${attributeNames}",
        "topicExpression": "v1/devices/${deviceName}/attributes/response",
        "valueExpression": "{\"${attributeKey}\": \"${attributeValue}\"}"
      }
    ]
  }
}

For Attribute updates, the gateway needs to know which devices should receive updates for which attributes. You configure this using regular expressions for both device names and attribute names. When an attribute is updated in ThingsBoard, the gateway publishes the new value to a configured MQTT topic.

Suppose you want ThingsBoard to automatically push firmware version updates to your devices. When you update the firmwareVersion shared attribute in ThingsBoard, the gateway should publish this update to a topic that your devices are subscribed to.

Let’s configure Attribute updates in the MQTT connector to allow ThingsBoard to push attribute changes to devices.

Follow these steps:

1. Go to “Entities” - “Gateways” in the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the MQTT connector, click on the “Basic”. Click the “Add mapping” under “Requests mapping” section to add new attribute update mapping.

   

4. Select “Attribute update” in the Request type field, enter the “Device name filter” as .* to match all devices, or use a specific pattern to match only certain devices).

   

5. Configure the Attribute filter as firmwareVersion to only update this specific attribute. Set the Response topic expression to sensor/${deviceName}/${attributeKey} and the Response value expression to {"${attributeKey}":"${attributeValue}"}. You can also set the Retain option to determine whether the attribute update message should be retained by the MQTT broker.

   

6. Remember to save your changes by clicking the designated button.

   

7. Go to “Devices” - select device SN-001 - “Attributes” tab - select “Shared attributes”

   

8. Add the firmwareVersion attribute with type “String” and set its value to “1.2.3”.

   

9. Find the firmwareVersion attribute and click the pencil icon to edit it.

   

Let’s demonstrate how to use this attribute update configuration:

1. First, let’s subscribe to the topic where attribute updates will be published:

mosquitto_sub -h 127.0.0.1 -p 1884 -t sensor/SN-001/firmwareVersion

2. After updating the attribute in ThingsBoard, the gateway will detect the change and publish a message to the configured topic:

{"firmwareVersion":"1.2.4"}

This message will be received by any device subscribed to the topic sensor/SN-001/firmwareVersion.

If you are using advanced configuration mode, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensor/data",
      "subscriptionQos": 1,
      "converter": {
        "type": "json",
        "deviceInfo": {
          "deviceNameExpressionSource": "message",
          "deviceNameExpression": "${serialNumber}",
          "deviceProfileExpressionSource": "message",
          "deviceProfileExpression": "${sensorType}"
        },
        "timeout": 60000,
        "attributes": [],
        "timeseries": [
          {
            "type": "string",
            "key": "temperature",
            "value": "${temp}"
          }
        ]
      }
    }
  ],
  "requestsMapping": {
    "attributeUpdates": [
      {
        "retain": true,
        "deviceNameFilter": ".*",
        "attributeFilter": "firmwareVersion",
        "topicExpression": "sensor/${deviceName}/${attributeKey}",
        "valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
      }
    ]
  }
}

GET and SET RPC methods are out of the box, so you don’t need to configure them manually.

Suppose we have a device SN-001 that tracks the light level of the room and is connected to ThingsBoard via an MQTT Gateway. We want to send an RPC command to know the current state of the light level with two options: in the first case we want to get a response back, and in the second case we don’t need a response. Additionally, we will update the room light level by sending a command without expecting a response.

As an example, we will use ThingsBoard MQTT Demo Broker, which can be run using Docker and the following command:

docker run -it -p 1884:1884 thingsboard/tb-gw-mqtt-broker:latest

The broker available at 0.0.0.0:1884 and simulates a device that listens to the topic data/get_light_level for getting the current light level and responds on the topic data/response. It also listens to the topic data/set_light_level to update the light level value.

In the RPC Debug Terminal widget, run the following command to send a two-way RPC request:

get requestTopicExpression=data/get_light_level;responseTopicExpression=data/response;value=${params};

The gateway will:

1. Receive this RPC request
2. Process the built-in “get” method
3. Send a message to the topic data/get_light_level with the specified parameters
4. Subscribe to the topic data/response to wait for a response
5. Return the response to ThingsBoard when received

In the RPC Debug Terminal widget, run the following command to send a one-way RPC request:

get requestTopicExpression=data/get_light_level;value=${params};

The gateway will:

1. Receive this RPC request
2. Process the built-in “get” method
3. Send a message to the topic data/get_light_level with the specified parameters
4. Not wait for any response since no response topic was specified

In the RPC Debug Terminal widget, run the following command to set a new light level value:

set requestTopicExpression=data/set_light_level;value=90;

The gateway will:

1. Receive this RPC request
2. Process the built-in “set” method
3. Send a message to the topic data/set_light_level with the value “90”
4. Not wait for any response since no response topic was specified

After setting the new light level, you can verify the updated value by running:

get requestTopicExpression=data/get_light_level;responseTopicExpression=data/response;value=${params};

The gateway will process this request as in Example 1, and you should see the updated light level value in the response.

If you are using advanced configuration mode, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensor/data",
      "subscriptionQos": 1,
      "converter": {
        "type": "json",
        "deviceInfo": {
          "deviceNameExpressionSource": "message",
          "deviceNameExpression": "${serialNumber}",
          "deviceProfileExpressionSource": "message",
          "deviceProfileExpression": "${sensorType}"
        },
        "timeout": 60000,
        "attributes": [],
        "timeseries": [
          {
            "type": "string",
            "key": "temperature",
            "value": "${temp}"
          }
        ]
      }
    }
  ],
  "requestsMapping": {
    "serverSideRpc": []
  }
}

RPC to Device allows sending RPC commands to the device that is connected to ThingsBoard directly or via Gateway.

Suppose we have a device SN-001 that tracks the light level of the room and is connected to ThingsBoard via an MQTT Gateway. We want to send an RPC command to know the current state of the light level with two options: in the first case we want to get a response back, and in the second case we don’t need a response.

As an example, we will use ThingsBoard MQTT Demo Broker, which can be run using Docker and the following command:

docker run -it -p 1884:1884 thingsboard/tb-gw-mqtt-broker:latest

The demo broker runs at 0.0.0.0:1884 and simulates a device for our RPC examples. For configurable RPC, the device listens on topic sensor/${deviceName}/request/${methodName}/${requestId} for incoming commands and responds on topic sensor/${deviceName}/response/${methodName}/${requestId} when a response is expected.

Let’s configure RPC commands in the MQTT connector to allow ThingsBoard to send commands to devices.

Follow these steps:

1. Go to “Entities” - “Gateways” on the left sidebar and select your gateway.

   

2. Click on the “Connectors configuration” button on the right side menu.

   

3. Select the MQTT connector, click on the “Basic”. Click the “Add mapping” under “Requests mapping” section to add new RPC mapping.

   

4. Select “RPC command” in the Request type field. For two-way RPC (with response).

   

5. Configure the Device name filter as .* to apply to all devices, set the Method filter to echo, the Request topic expression to sensor/${deviceName}/request/${methodName}/${requestId}, the Value expression to ${params}, the Response topic expression to sensor/${deviceName}/response/${methodName}/${requestId}, and set an appropriate Response timeout (e.g., 10000 ms).

   

6. Remember to save your changes by clicking the designated button.

   

7. For one-way RPC (without response), click on the Without response tab. Configure the Device name filter as .* to apply to all devices, set the Method filter to no-reply, the Request topic expression to sensor/${deviceName}/request/${methodName}/${requestId}, and the Value expression to ${params}.

   

8. Remember to save your changes by clicking the designated button.

   

Let’s demonstrate how to use this RPC configuration:

In the RPC Debug Terminal widget, run the following command to send a two-way RPC request:

echo {"deviceName":"SN-001", "methodName":"echo"}

The gateway will:

1. Receive this RPC request
2. Match it to the “echo” method configuration
3. Send a message to the topic sensor/SN-001/request/echo/12345 (where 12345 is a unique request ID)
4. Subscribe to the topic sensor/SN-001/response/echo/12345 to wait for a response
5. Return the response to ThingsBoard when received

In the RPC Debug Terminal widget, run the following command to send a one-way RPC request:

no-reply {"deviceName":"SN-001", "methodName":"no-reply"}

The gateway will:

1. Receive this RPC request
2. Match it to the “no-reply” method configuration
3. Send a message to the topic sensor/SN-001/request/no-reply/12345 (where 12345 is a unique request ID)
4. Not wait for any response

If you are using advanced configuration mode, you can use the following configuration:

{
  "broker": {
    "host": "127.0.0.1",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "keepAlive": 60,
    "cleanSession": true,
    "cleanStart": true,
    "sessionExpiryInterval": 0,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "sensor/data",
      "subscriptionQos": 1,
      "converter": {
        "type": "json",
        "deviceInfo": {
          "deviceNameExpressionSource": "message",
          "deviceNameExpression": "${serialNumber}",
          "deviceProfileExpressionSource": "message",
          "deviceProfileExpression": "${sensorType}"
        },
        "timeout": 60000,
        "attributes": [],
        "timeseries": [
          {
            "type": "string",
            "key": "temperature",
            "value": "${temp}"
          }
        ]
      }
    }
  ],
  "requestsMapping": {
    "serverSideRpc": [
      {
        "type": "twoWay",
        "deviceNameFilter": ".*",
        "methodFilter": "echo",
        "requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
        "responseTopicExpression": "sensor/${deviceName}/response/${methodName}/${requestId}",
        "responseTopicQoS": 1,
        "responseTimeout": 10000,
        "valueExpression": "${params}"
      },
      {
        "type": "oneWay",
        "deviceNameFilter": ".*",
        "methodFilter": "no-reply",
        "requestTopicExpression": "sensor/${deviceName}/request/${methodName}/${requestId}",
        "valueExpression": "${params}"
      }
    ]
  }
}