Getting started with ThingsBoard IoT Gateway

Let’s add an MQTT connector, which will subscribe to some data topics using the demo broker with a built-in data generator and send data to the gateway.

Setup demo MQTT broker

As a demo MQTT broker, we will use docker image, that can be installed and run using the following command:

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

After running docker image, you can see the following logs in your terminal:

Setup connector

Copy the following connector configuration (we will use it later):

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
{
  "broker": {
    "name": "Demo Broker",
    "host": "host.docker.internal",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "sendDataOnlyOnChange": false,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "data/",
      "converter": {
        "type": "json",
        "deviceNameJsonExpression": "Demo Device",
        "deviceTypeJsonExpression": "default",
        "sendDataOnlyOnChange": false,
        "timeout": 60000,
        "attributes": [
          {
            "type": "integer",
            "key": "frequency",
            "value": "${frequency}"
          },
          {
            "type": "integer",
            "key": "power",
            "value": "${power}"
          }
        ],
        "timeseries": [
          {
            "type": "integer",
            "key": "temperature",
            "value": "${temperature}"
          },
          {
            "type": "integer",
            "key": "humidity",
            "value": "${humidity}"
          }
        ]
      }
    }
  ],
  "connectRequests": [
    {
      "topicFilter": "sensor/connect",
      "deviceNameJsonExpression": "${SerialNumber}"
    },
    {
      "topicFilter": "sensor/+/connect",
      "deviceNameTopicExpression": "(?<=sensor\/)(.*?)(?=\/connect)"
    }
  ],
  "disconnectRequests": [
    {
      "topicFilter": "sensor/disconnect",
      "deviceNameJsonExpression": "${SerialNumber}"
    },
    {
      "topicFilter": "sensor/+/disconnect",
      "deviceNameTopicExpression": "(?<=sensor\/)(.*?)(?=\/disconnect)"
    }
  ],
  "attributeRequests": [],
  "attributeUpdates": [],
  "serverSideRpc": []
}

This MQTT connector configuration establishes a connection to a broker named “Demo Broker” at “host.docker.internal” on port 1884, using an anonymous security type. It includes a mapping for the “data/” topic, specifying a JSON converter and defining attribute and timeseries mappings for device data. Additionally, it handles connect and disconnect requests for sensors with expressions to extract device names from topic filters.

To create a connector, follow these steps:

• Click “Connectors configuration” button on the right panel.

• Click the “+” button, fill in “Name”, “Type” and “Logging level” fields, paste your connector configuration into Configuration field and click on Save button.

• Connector has been successfully added.

• Toggle the switch to enable the connector.

Following the steps outlined, your gateway will receive and apply the new configuration. It will then synchronize its state with the remote server. You can view the synchronization status of the connector configuration in the “Configuration” column, which will indicate whether the gateway is successfully aligned with the remote settings.

Also, you can see the connector logs to make sure that the connector works, for this purpose, follow these steps:

• Click on logs icon to open connector logs page.

• You can see the “Logs” table that consists of “Created time”, “Status” and “Message” columns.

For now, the gateway is ready to process data through the newly created and configured MQTT connector.

Let’s publish data to the MQTT Broker defined in the configuration above, you can follow these steps using a tool like mosquitto_pub or an MQTT client library in your preferred programming language. In this example, we’ll use the mosquitto_pub command-line tool.

1.Ensure that the Mosquitto MQTT clients are installed on your system. Typically, you can install them using the package manager of your operating system:

• For Ubuntu:

  1
  sudo apt-get install mosquitto-clients
  

• For Windows:

  Download the Mosquitto client tools from the official website.

  Install the tools, ensuring that the installation directory is added to the system’s PATH.

• For MacOS:

  1
  brew install mosquitto
  

2.Use the mosquitto_pub command to publish data to a specific MQTT topic. In this case, we’ll use the “data/” topic as defined in the configuration:

1
mosquitto_pub -h localhost -p 1884 -t data/ -m '{"frequency": 50, "power": 100, "temperature": 25, "humidity": 60}'

Where:

• -h - specifies the MQTT broker’s host address;
• -p - specifies the MQTT broker’s port;
• -t - specifies the MQTT topic to publish to (“data/” in our case);
• -m - specifies the payload or message to publish. It should be in JSON format, following the structure defined in the mapping section of your configuration.

Adjust the payload values as needed.

Let’s add a Modbus connector, which will read some data from the demo slave to the created gateway.

Setup demo server

As a demo simulation slave, we will use docker image, that can be installed and run using the following command:

1
docker run -it -p 5021:5021 thingsboard/tb-gw-modbus-server:latest

After running docker image, you can see the following logs in your terminal:

Setup connector

Copy the following connector configuration (we will use it later):

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
  "master": {
    "slaves": [
      {
        "host": "host.docker.internal",
        "port": 5021,
        "type": "tcp",
        "method": "socket",
        "timeout": 35,
        "byteOrder": "LITTLE",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 5000,
        "unitId": 1,
        "deviceName": "Demo Device",
        "deviceType": "default",
        "sendDataOnlyOnChange": false,
        "connectAttemptTimeMs": 5000,
        "connectAttemptCount": 5,
        "waitAfterFailedAttemptsMs": 300000,
        "attributes": [
          {
            "tag": "frequency",
            "type": "8int",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 4
          },
          {
            "tag": "power",
            "type": "16float",
            "functionCode": 4,
            "objectsCount": 2,
            "address": 8
          }
        ],
        "timeseries": [
          {
            "tag": "humidity",
            "type": "8uint",
            "functionCode": 4,
            "objectsCount": 1,
            "address": 4
          },
          {
            "tag": "temperature",
            "type": "16uint",
            "functionCode": 4,
            "objectsCount": 2,
            "address": 4
          }
        ],
        "attributeUpdates": [],
        "rpc": []
      }
    ]
  }
}

This Modbus connector configuration sets up a master to communicate with a slave device located at “host.docker.internal” on port 5021 using TCP. The configuration includes specifications for data retrieval such as byte and word order, timeout, and polling period. The slave device, named “Demo Device” is configured to handle Modbus function code 4 requests. Attribute and timeseries mappings are defined for parameters like frequency, power, humidity, and temperature. Additionally, settings for connection attempts, retries, and wait times after failed attempts are provided.

To create a connector, follow these steps:

• Click “Connectors configuration” button on the right panel.

• Click the “+” button, fill in “Name”, “Type” and “Logging level” fields, paste your connector configuration into Configuration field and click on Save button.

• Connector has been successfully added.

• Toggle the switch to enable the connector.

Following the steps outlined, your gateway will receive and apply the new configuration. It will then synchronize its state with the remote server. You can view the synchronization status of the connector configuration in the “Configuration” column, which will indicate whether the gateway is successfully aligned with the remote settings.

Also, you can see the connector logs to make sure that the connector works, for this purpose, follow these steps:

• Click on logs icon to open connector logs page.

• You can see the “Logs” table that consists of “Created time”, “Status” and “Message” columns.

For now, the gateway is ready to process data through the newly created and configured Modbus connector.

Let’s add an OPC-UA connector, which will read some data from the demo server to the created gateway.

Setup demo server

As a demo simulation server, we will use docker image, that can be installed and run using the following command:

1
docker run -it -p 4840:4840 thingsboard/tb-gw-opcua-server:latest

After running docker image, you can see the following logs in your terminal:

Setup connector

Copy the following connector configuration (we will use it later):

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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
{
  "server": {
    "name": "OPC-UA Demo Server",
    "url": "opc.tcp://host.docker.internal:4840/freeopcua/server/",
    "timeoutInMillis": 5000,
    "scanPeriodInMillis": 5000,
    "disableSubscriptions": false,
    "subCheckPeriodInMillis": 100,
    "showMap": true,
    "security": "Basic128Rsa15",
    "identity": {
      "type": "anonymous"
    },
    "mapping": [
      {
        "deviceNodePattern": "Root\\.Objects\\.MyObject",
        "deviceNamePattern": "Demo Device",
        "deviceTypePattern": "default",
        "attributes": [
          {
            "key": "frequency",
            "path": "${Frequency}"
          },
          {
            "key": "power",
            "path": "${Power}"
          }
        ],
        "timeseries": [
          {
            "key": "temperature",
            "path": "${Temperature}"
          },
          {
            "key": "humidity",
            "path": "${Humidity}"
          }
        ],
        "rpc_methods": [],
        "attributes_updates": []
      }
    ]
  }
}

This OPC-UA connector configuration establishes a connection to a server named “OPC-UA Demo Server” at “opc.tcp://host.docker.internal:4840/freeopcua/server/”. The configuration specifies various settings, including timeouts, scan periods, and security mechanisms such as “Basic128Rsa15” with anonymous identity.

The mapping section defines how OPC-UA nodes are mapped to devices and their attributes and timeseries. In this case, a device with the name “Demo Device” and type “default” is mapped to nodes under “Root.Objects.MyObject”. Attributes such as frequency and power, as well as timeseries like temperature and humidity, are mapped to specific paths in the OPC-UA server. Additionally, the configuration supports RPC methods and attribute updates.

To create a connector, follow these steps:

• Click “Connectors configuration” button on the right panel.

• Click the “+” button, fill in “Name”, “Type” and “Logging level” fields, paste your connector configuration into Configuration field and click on Save button.

• Connector has been successfully added.

• Toggle the switch to enable the connector.

Following the steps outlined, your gateway will receive and apply the new configuration. It will then synchronize its state with the remote server. You can view the synchronization status of the connector configuration in the “Configuration” column, which will indicate whether the gateway is successfully aligned with the remote settings.

Also, you can see the connector logs to make sure that the connector works, for this purpose, follow these steps:

• Click on logs icon to open connector logs page.

• You can see the “Logs” table that consists of “Created time”, “Status” and “Message” columns.

For now, the gateway is ready to process data through the newly created and configured OPC-UA connector.