Stop the war

Stand with Ukraine flag

Support Ukraine

Try it now Pricing
IoT Gateway
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
Documentation Installation
On this page

Getting started with ThingsBoard IoT Gateway

The ThingsBoard IoT Gateway is an open-source solution, designed to serve as a bridge between IoT devices connected to legacy and third-party systems with ThingsBoard.

This guide covers initial IoT Gateway installation and configuration, we will do the following things:

  • Create a new gateway device using ThingsBoard IoT Gateways dashboard;
  • Launch the gateway using Docker command;
  • Configure different connector types (MQTT, OPC-UA, Modbus) in order to connect to a local demo servers and read data from them;
  • Check received device data on ThingsBoard.

Prerequisites

  • Before initiating the Gateway setup, ensure that the ThingsBoard server is up and running. The simplest approach is to utilize the Live Demo or ThingsBoard Cloud. Alternatively, you can install ThingsBoard manually by following the steps outlined in the Installation Guide.
  • Before moving forward, ensure Docker is installed and properly configured on your machine. If you haven’t installed Docker yet, you can download it from the official Docker website and follow their installation guide for your specific operating system.
  • If you don’t have a dashboard installed, you can download Gateway widget bundle JSON file here and ThingsBoard IoT Gateways dashboard JSON file here. You can do this using the section below:

(Optional) Import gateway widgets bundle and dashboard

First, we have to import gateway widgets bundle, for this purpose, use the following steps:

  • Go to the “Widgets Library” page, and click the “+” button in the upper right corner of the “Widgets Bundles” page. Select “Import widgets bundle” from the drop-down menu.

  • In the popup, you will be prompted to upload the downloaded gateway widgets bundle JSON file. Drag and drop a file from your computer, then click “Import” to add a widget bundle to the library.

  • The widgets bundle is imported.

To import ThingsBoard IoT Gateways dashboard, follow these steps:

  • Go to the “Dashboards” page and click on the “+” button in the upper right corner of the page and select “Import dashboard” from the drop-down menu;

  • In the import dashboard window, upload downloaded the gateway dashboard JSON file and click “Import”.

  • Dashboard imported. Click on the row with the name of the dashboard to open it.

Step 1. Create new gateway device on ThingsBoard

First, we have to add a gateway device to your ThingsBoard instance. You can do this using following steps:

  • Go to “Dashboards” tab and open “ThingsBoard IoT Gateways” dashboard.

  • Click the “+” button, enter the gateway device name (e.g., “My New Gateway”), and select the device profile.

Doc info icon

If you've previously configured the gateway, create a backup, as the new remote configuration will overwrite existing settings files.
For those who used a gateway version earlier than 3.4, the gateway will automatically generate a new configuration file in JSON format.

To launch the gateway, use the following steps:

  • On the gateway dashboard, click on “Launch command” button in the top right corner.

  • Copy auto-generated command and execute it in your terminal.

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

Step 2. Enable remote logging

To view gateway and connector logs on the dashboard, you need to enable remote logging. For this purpose, use the following steps:

  • On the gateway dashboard, click on “General configuration” button on the right panel.

  • Navigate to the “Logs” tab. Enable the “Remote logs” toggle. Select “DEBUG” in the “Log level” row.

Step 3. Add new connector

By choosing the type of connector, you determine the specific method of connection you will use to ensure the interaction of your gateway with other systems or devices.

To see how the connector works, you can choose one of the following connectors:

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 commands:

1
docker ps

Find your gateway container name as you can see on the following image and copy it:

Create an environment variable using the following command, replace YOUR_TB_GATEWAY_CONTAINER_NAME with the copied gateway container name. Copy and run the provided command in your terminal:

1
export TB_GATEWAY_CONTAINER_NAME=YOUR_TB_GATEWAY_CONTAINER_NAME

Copy and execute the following command in your terminal:

1
docker run -it --net=container:$(docker inspect -f '{{.Id}}' ${TB_GATEWAY_CONTAINER_NAME}) 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": "localhost",
    "port": 1884,
    "clientId": "ThingsBoard_gateway",
    "version": 5,
    "maxMessageNumberPerWorker": 10,
    "maxNumberOfWorkers": 100,
    "sendDataOnlyOnChange": false,
    "security": {
      "type": "anonymous"
    }
  },
  "mapping": [
    {
      "topicFilter": "data/",
      "converter": {
        "type": "json",
        "deviceNameJsonExpression": "Device Demo",
        "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": []
}

To create a connector, use the following 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 connector works, for this purpose, use the following 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 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 commands:

1
docker ps

Find your gateway container name as you can see on the following image and copy it:

Create an environment variable using the following command, replace YOUR_TB_GATEWAY_CONTAINER_NAME with the copied gateway container name. Copy and run the provided command in your terminal:

1
export TB_GATEWAY_CONTAINER_NAME=YOUR_TB_GATEWAY_CONTAINER_NAME

Copy and execute the following command in your terminal:

1
docker run -it --net=container:$(docker inspect -f '{{.Id}}' ${TB_GATEWAY_CONTAINER_NAME}) 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": "localhost",
        "port": 5021,
        "type": "tcp",
        "method": "socket",
        "timeout": 35,
        "byteOrder": "LITTLE",
        "wordOrder": "LITTLE",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 5000,
        "unitId": 1,
        "deviceName": "Device Demo",
        "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": []
      }
    ]
  }
}

To create a connector, use the following 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 connector works, for this purpose, use the following 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 commands:

1
docker ps

Find your gateway container name as you can see on the following image and copy it:

Create an environment variable using the following command, replace YOUR_TB_GATEWAY_CONTAINER_NAME with the copied gateway container name. Copy and run the provided command in your terminal:

1
export TB_GATEWAY_CONTAINER_NAME=YOUR_TB_GATEWAY_CONTAINER_NAME

Copy and execute the following command in your terminal:

1
docker run -it --net=container:$(docker inspect -f '{{.Id}}' ${TB_GATEWAY_CONTAINER_NAME}) 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://localhost:4840/freeopcua/server/",
    "timeoutInMillis": 5000,
    "scanPeriodInMillis": 5000,
    "disableSubscriptions": false,
    "subCheckPeriodInMillis": 100,
    "showMap": true,
    "security": "Basic128Rsa15",
    "identity": {
      "type": "anonymous"
    },
    "mapping": [
      {
        "deviceNodePattern": "Root\\.Objects\\.MyObject",
        "deviceNamePattern": "Device Demo",
        "deviceTypePattern": "default",
        "attributes": [
          {
            "key": "frequency",
            "path": "${Frequency}"
          },
          {
            "key": "power",
            "path": "${Power}"
          }
        ],
        "timeseries": [
          {
            "key": "temperature",
            "path": "${Temperature}"
          },
          {
            "key": "humidity",
            "path": "${Humidity}"
          }
        ],
        "rpc_methods": [],
        "attributes_updates": []
      }
    ]
  }
}

To create a connector, use the following 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 connector works, for this purpose, use the following 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.

Step 4. Check device data

To review the data uploaded from your gateway, use the following steps:

  • Navigate to the Devices page and click on the created device. This will open the device details page. From there, switch to the “Attributes” tab to view the attributes that were configured in the connector.

  • To view real-time telemetry data from the device, navigate to the “Latest Telemetry” tab. Here, you will find the telemetry data being sent by the device, including metrics like “humidity” and “temperature”. This tab provides real-time device telemetry updates.

Configure other connectors

After the successful installation and configuration of your first connector, you can configure other connectors to connect to different devices. You can find more information about connectors in the following articles:

More about ThingsBoard IoT Gateways Dashboard, you can read here.

Next steps

Explore guides related to main ThingsBoard features: