Stand with Ukraine flag
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 > Configuration guides > General configuration
Getting Started
Installation
On this page

IoT Gateway Configuration

Directory structure

Please see default directory structure below for daemon installation.

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
/etc/thingsboard-gateway/config                   - Configuration folder.
    tb_gateway.json                               - Main configuration file for Gateway.
    logs.json                                     - Configuration file for logging.
    modbus.json                                   - Modbus connector configuration.
    mqtt.json                                     - MQTT connector configuration.
    ble.json                                      - BLE connector configuration.
    opcua.json                                    - OPC-UA connector configuration.
    request.json                                  - Request connector configuration.
    can.json                                      - CAN connector configuration. 
    ... 

/var/lib/thingsboard_gateway/extensions           - Folder for custom connectors/converters.                      
    modbus                                        - Folder for Modbus custom connectors/converters.
    mqtt                                          - Folder for MQTT custom connectors/converters.
        __init__.py                               - Default Python package file, needed for correct imports.
        custom_uplink_mqtt_converter.py           - Custom MQTT converter example.
    ...
    opcua                                         - Folder for OPC-UA custom connectors/converters.
    ble                                           - Folder for BLE custom connectors/converters.
    request                                       - Folder for Request custom connectors/converters.
    can                                           - Folder for CAN custom connectors/converters.

/var/log/thingsboard-gateway                      - Logs folder.
    connector.log                                 - Connector logs.
    service.log                                   - Main gateway service logs.
    storage.log                                   - Storage logs.
    tb_connection.log                             - Logs for connection to the ThingsBoard instance.

Environmental variables

Doc info icon

Values of environment variables have a higher priority than values of parameters from the configuration file. This means that the gateway will use the values of the environment variables (if they are set) and not the values from the configuration file.

The gateway provides the capability to configure essential connection parameters using environment variables. For example, let’s illustrate how you can configure basic parameters such as the host, port, and access token by using environment variables within a Docker Compose file. Here’s how you can achieve this:

1
2
3
4
5
6
7
8
9
10
11
12
13
version: '3.4'
services:
  # ThingsBoard IoT Gateway Service Configuration
  tb-gateway:
    image: thingsboard/tb-gateway
    container_name: tb-gateway
    ...
    # Environment variables
    environment:
      - TB_GW_HOST=host.docker.internal
      - TB_GW_PORT=1883
      - TB_GW_ACCESS_TOKEN=YOUR_ACCESS_TOKEN
    ...

In the example above, we set the “host.docker.internal” as a host, 1883 as a port and “YOUR_ACCESS_TOKEN” as an access token for the gateway using the “TB_GW_HOST”, “TB_GW_PORT” and “TB_GW_ACCESS_TOKEN” environment variables, respectively.

The following environmental variables can be used to configure the ThingsBoard IoT Gateway:

ENV variable Default value Description
TB_GW_HOST host.docker.internal Hostname or IP address of ThingsBoard server.
TB_GW_PORT 1883 Port of MQTT service on ThingsBoard server.
TB_GW_ACCESS_TOKEN YOUR_ACCESS_TOKEN Access token for the gateway from ThingsBoard server.
TB_GW_CA_CERT   Path to CA certificate file.
TB_GW_PRIVATE_KEY   Path to private key file.
TB_GW_CERT   Path to certificate file.
TB_GW_CLIENT_ID   MQTT client id for the gateway form ThingsBoard server.
TB_GW_USERNAME   MQTT username for the gateway form ThingsBoard server.
TB_GW_PASSWORD   MQTT password for the gateway form ThingsBoard server.
TB_GW_RATE_LIMITS 15:1,300:60, Messages rate limit to ThingsBoard server in MESSSAGE_COUNT:TIME, format.
TB_GW_DP_RATE_LIMITS 15:1,300:60, Data points rate limit to ThingsBoard server in DATA_POINTS_COUNT:TIME, format.
TB_GW_LOGS_PATH /thingsboard_gateway/logs Path to the logs folder.

General configuration file

The main configuration file that is used for connection to ThingsBoard platform instance and enable/disable connectors.

The example configuration file provided below sets a connection to the ThingsBoard instance located at thingsboard.cloud and utilizes memory file storage, which is set up to hold a maximum of 100,000 records. There are 4 different connectors active. If you prefer to use only one, simply remove the others from the configuration.

Example of main configuration file. Press to show.

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
{
  "thingsboard": {
    "host": "thingsboard.cloud",
    "port": 1883,
    "remoteShell": false,
    "remoteConfiguration": true,
    "statistics": {
      "enable": true,
      "statsSendPeriodInSeconds": 60
    },
    "deviceFiltering": {
      "enable": false,
      "filterFile": "list.json"
    },
    "maxPayloadSizeBytes": 1024,
    "minPackSendDelayMS": 60,
    "minPackSizeToSend": 500,
    "checkConnectorsConfigurationInSeconds": 10,
    "handleDeviceRenaming": true,
    "security": {
      "type": "accessToken",
      "accessToken": "YOUR_ACCESS_TOKEN"
    },
    "qos": 1,
    "checkingDeviceActivity": {
      "checkDeviceInactivity": false,
      "inactivityTimeoutSeconds": 200,
      "inactivityCheckPeriodSeconds": 500
    }
  },
  "storage": {
    "type": "memory",
    "read_records_count": 100,
    "max_records_count": 10000
  },
  "grpc": {
    "enabled": false,
    "serverPort": 9595,
    "keepaliveTimeMs": 10000,
    "keepaliveTimeoutMs": 5000,
    "keepalivePermitWithoutCalls": true,
    "maxPingsWithoutData": 0,
    "minTimeBetweenPingsMs": 10000,
    "minPingIntervalWithoutDataMs": 5000,
    "keepAliveTimeMs": 10000,
    "keepAliveTimeoutMs": 5000
  },
  "connectors": [
    {
      "type": "mqtt",
      "name": "MQTT Broker Connector",
      "configuration": "mqtt.json"
    },
    {
      "type": "modbus",
      "name": "Modbus Connector",
      "configuration": "modbus.json"
    },
    {
      "type": "modbus",
      "name": "Modbus Serial Connector",
      "configuration": "modbus_serial.json"
    },
    {
      "type": "opcua",
      "name": "OPC-UA Connector",
      "configuration": "opcua.json"
    }
  ]
}

Sections in config file

  • thingsboard – Configuration for connecting to ThingsBoard platform.
    • security – Configuration for type of encryption and authorization.
  • storage – Configuration for local storage of incoming data from devices.
  • connectors – Array of Connectors and their configuration to use.

Connection to ThingsBoard

Parameter Default value Description
thingsboard   Configuration for connection to server.
host thingsboard.cloud Hostname or IP address of ThingsBoard server.
port 1883 Port of MQTT service on ThingsBoard server.
qos 1 QoS levels 0 (at most once) and 1 (at least once).
minPackSendDelayMS 200 Delay between sending packets (Decreasing this setting results in increased CPU usage).
minPackSizeToSend 500 Minimum size of packs to send.
Subsection “statistics”

This subsection is used to configure collecting statistics data and sending them to ThingsBoard Gateway device attributes.

Parameter Default value Description
statistics   Configuration for enabling statistics collecting.
… enable true A boolean value that is used to on/off collecting statistics.
… statsSendPeriodInSeconds 3600 An integer value is utilized for transmitting data at regular intervals.
… configuration statistics.json Name of a configuration file for additional user statistics data (in seconds).

You can define additional parameter “configuration” and provide your own command for collecting some additional data. This configuration file can look like the example below:

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
[
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "ps -A -o cpu,%mem | awk '{cpu += $1}END{print cpu}'"],
    "attributeOnGateway": "CPU"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "ps -A -o %cpu,%mem | awk '{mem += $2}END{print mem}'"],
    "attributeOnGateway": "Memory"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "ipconfig getifaddr en0"],
    "attributeOnGateway": "IP address"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "sw_vers -productName"],
    "attributeOnGateway": "OS"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "uptime"],
    "attributeOnGateway": "Uptime"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "system_profiler SPUSBDataType"],
    "attributeOnGateway": "USBs"
  }
]

Also, you can find example files for different OS (Linux, macOS, Windows) in /config/statistics/ folder.

Subsection “deviceFiltering”

This subsection is optional and used to filter allowed devices to send data to ThingsBoard.

The Device Filtering feature allows you to define rules for filtering devices based on specific criteria.

Parameter Default value Description
deviceFiltering   Configuration for device filtering
… enable false Boolean value that is used to on/off device filtering
… filterFile list.json Name of a configuration file

Configuration file can look like the example below:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "deny": {
    "MQTT Broker Connector": [
      "Temperature Device",
      "(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$)"
    ],
    "Modbus Connector": [
      "My Modbus Device"
    ]
  },
  "allow": {
    "MQTT Broker Connector": [
      "My Temperature Sensor"
    ]
  }
}

The configuration above consists of two main properties: “deny” and “allow”. Each property contains a set of connector types as keys, with corresponding arrays of device names as their values.

The “deny” property is used to specify devices that should be denied access to certain connector names. The devices listed under each connector name will be blocked from accessing the specified connector.

The structure of the “deny” property is as follows:

1
2
3
4
5
6
7
8
"deny": {
  "<Connector Name>": [
    "<Device Name 1>",
    "<Device Name 2>",
    ...
  ],
  ...
}

Example:

1
2
3
4
5
6
7
8
9
"deny": {
  "MQTT Broker Connector": [
    "Temperature Device",
    "(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$)"
  ],
  "Modbus Connector": [
    "My Modbus Device"
  ]
}

In the above example, the following rules are defined:

  • The device named “Temperature Device” and any device with an email address format are denied access to the “MQTT Broker Connector”.
  • The device named “My Modbus Device” is denied access to the “Modbus Connector”.

The “allow” property is used to specify devices that should be explicitly allowed to access certain connector names. The devices listed under each connector name will have unrestricted access to the specified connector.

The structure of the “allow” property is as follows:

1
2
3
4
5
6
7
8
"allow": {
  "<Connector Name>": [
    "<Device Name 1>",
    "<Device Name 2>",
    ...
  ],
  ...
}

Example:

1
2
3
4
5
"allow": {
  "MQTT Broker Connector": [
    "My Temperature Sensor"
  ]
}

In the above example, the following rule is defined:

  • The device named “My Temperature Sensor” is allowed access to the “MQTT Broker Connector”.

The Device Filtering feature provides a flexible way to define rules for allowing or denying access to connector types based on device names. By using the “deny” and “allow” properties, you can easily control device access within your gateway.

Subsection “checkingDeviceActivity”

This subsection is optional and used to monitor the activity of each connected device.

If you define this section, the Gateway will check the activity of each device every n second that means, if the device is inactive for n seconds, it will disconnect it.

Parameter Default value Description
checkingDeviceActivity   Configuration for checking devices activity
… checkDeviceInactivity false Boolean value that is used to on/off checking device activity
… inactivityTimeoutSeconds 120 Inactivity device time after whose Gateway will disconnect it
… inactivityCheckPeriodSeconds 10 Periodicity of device activity check
Subsection “security”

There are 3 variants of security subsection:

One type of security configuration is accessToken, to get it you should login into your ThingsBoard platform instance, go to DEVICE tab, press the plus icon, fill the values and check the “Is gateway” option, open this device and press the “COPY ACCESS TOKEN” button and replace default with your value

Parameter Default value Description
accessToken PUT_YOUR_GW_ACCESS_TOKEN_HERE Access token for the gateway from ThingsBoard server.

Security subsection in configuration file will look like this:

1
2
3
4
5
...
"security": {
  "accessToken": "YOUR_ACCESS_TOKEN"
},
...

One type of security configuration is using clientId, username, and password, to get them you should login into your ThingsBoard platform instance, go to DEVICE tab, press the plus icon, fill the values and check the “Is gateway” option, press “Next: Credentials”, check “Add credentials”, select credentials type “MQTT Basic” and replace default with your value.

Parameter Default value Description
clientId clientId MQTT client id for the gateway form ThingsBoard server
username admin MQTT username for the gateway form ThingsBoard server
password admin MQTT password for the gateway form ThingsBoard server
1
2
3
4
5
6
7
...
"security": {
  "clientId": "YOUR_CLIENT_ID",
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD"
},
...

In table below described parameters to configure authorization of IoT gateway on ThingsBoard platform.

Parameter Default value Description
accessToken PUT_YOUR_GW_ACCESS_TOKEN_HERE Access token for the gateway from ThingsBoard server.
caCert /etc/thingsboard-gateway/mqttserver.pub.pem Path to CA certificate file.

Security subsection in configuration file will look like this:

1
2
3
4
5
6
...
"security": {
  "accessToken": "PUT_YOUR_GW_ACCESS_TOKEN_HERE",
  "caCert": "/etc/thingsboard-gateway/mqttserver.pub.pem"
},
...

In table below described parameters to configure authorization of IoT gateway on ThingsBoard platform.

Parameter Default value Description
caCert /etc/thingsboard-gateway/ca.pem Path to CA file.
privateKey /etc/thingsboard-gateway/privateKey.pem Path to private key file.
cert /etc/thingsboard-gateway/certificate.pem Path to certificate file.
checkCertPeriod 86400 The period in seconds when the certificate will be checked
certificateDaysLeft 3 Days until the certificate expires, when a new one will be generated

Security subsection in configuration file will look like this:

1
2
3
4
5
6
7
8
9
...
"security": {
  "caCert": "/etc/thingsboard-gateway/ca.pem",
  "privateKey": "/etc/thingsboard-gateway/privateKey.pem",
  "cert": "/etc/thingsboard-gateway/certificate.pem",
  "checkCertPeriod": 86400,
  "certificateDaysLeft": 3
},
...
Subsection “provisioning”

There are 4 options of provisioning configuration (you can read more about provisioning in the official documentation):

Using the following config, you can configure Gateway to use auto-generated Access Token by server provisioning strategy:

Parameter Default value Description
type AUTO Type of provisioning strategy.
provisionDeviceKey DEVICE_KEY Provisioning device key, you should take it from configured device profile.
provisionDeviceSecret DEVICE_SECRET Provisioning device secret, you should take it from configured device profile.

Provisioning subsection in configuration file will look like this:

1
2
3
4
5
6
7
...
"provisioning": {
  "type": "AUTO",
  "provisionDeviceKey": "PUT_YOUR_DEVICE_KEY_HERE",
  "provisionDeviceSecret": "PUT_YOUR_DEVICE_SECRET_HERE"
},
...

Using the following config, you can configure Gateway to use Access Token provisioning strategy:

Parameter Default value Description
type ACCESS_TOKEN Type of provisioning strategy.
provisionDeviceKey DEVICE_KEY Provisioning device key, you should take it from configured device profile.
provisionDeviceSecret DEVICE_SECRET Provisioning device secret, you should take it from configured device profile.

Provisioning subsection in configuration file will look like this:

1
2
3
4
5
6
...
  provisioning:
    type: ACCESS_TOKEN
    provisionDeviceKey: PUT_YOUR_DEVICE_KEY_HERE
    provisionDeviceSecret: PUT_YOUR_DEVICE_SECRET_HERE
...

Using the following config, you can configure Gateway to use MQTT Basic provisioning strategy:

Parameter Default value Description
type MQTT_BASIC Type of provisioning strategy.
provisionDeviceKey DEVICE_KEY Provisioning device key, you should take it from configured device profile.
provisionDeviceSecret DEVICE_SECRET Provisioning device secret, you should take it from configured device profile.

Provisioning subsection in configuration file will look like this:

1
2
3
4
5
6
7
...
"provisioning": {
  "type": "MQTT_BASIC",
  "provisionDeviceKey": "PUT_YOUR_DEVICE_KEY_HERE",
  "provisionDeviceSecret": "PUT_YOUR_DEVICE_SECRET_HERE"
},
...

Using the following config, you can configure Gateway to use X.509 Certificate provisioning strategy:

Parameter Default value Description
type X509_CERTIFICATE Type of provisioning strategy.
provisionDeviceKey DEVICE_KEY Provisioning device key, you should take it from configured device profile.
provisionDeviceSecret DEVICE_SECRET Provisioning device secret, you should take it from configured device profile.
caCert ca-root.pem Public key X509 for device in ThingsBoard.

Provisioning subsection in configuration file will look like this:

1
2
3
4
5
6
7
8
...
"provisioning": {
  "type": "X509_CERTIFICATE",
  "provisionDeviceKey": "PUT_YOUR_DEVICE_KEY_HERE",
  "provisionDeviceSecret": "PUT_YOUR_DEVICE_SECRET_HERE",
  "caCert": "/etc/thingsboard-gateway/ca.pem"
},
...

Storage configuration

Configs in storage subsection provides configuration for saving incoming data before it will be send to ThingsBoard platform.

There are 2 variants for this section: memory or file.

  1. Memory storage - Received data saving to the RAM memory.
  2. File storage - Received data saving to the hard drive.
  3. SQLite storage - Received data saving to the .db file.
Parameter Default value Description
type memory Storage type (Saving data to RAM, no save to hard drive).
read_records_count 10 Count of messages to get from storage and send to ThingsBoard.
max_records_count * 100 Maximum count of data in storage before send to ThingsBoard.

* – If receive data when storage has already counted, described in this parameter, new data will lose.

Storage section of configuration file will look like:

1
2
3
4
5
6
7
...
"storage": {
  "type": "memory",
  "read_records_count": 10,
  "max_records_count": 100
},
...
Parameter Default value Description
type file Storage type (Saving data to hard drive)
data_folder_path ./data/ Path to folder, that will contains data (Relative or Absolute).
max_file_count 5 Maximum count of file that will be saved.
max_read_records_count * 6 Count of messages to get from storage and send to ThingsBoard.
max_records_per_file 14 Maximum count of records that will be stored in one file.

* – If receive data when storage has already counted, described in this parameter, new data will lose.

Storage section of configuration file will look like:

1
2
3
4
5
6
7
8
9
...
"storage": {
  "type": "file",
  "data_folder_path": "./data/",
  "max_file_count": 5,
  "max_read_records_count": 6,
  "max_records_per_file": 14
},
...
Parameter Default value Description
type sqlite Storage type (Saving data to .db file)
data_file_path ./data/data.db Path to folder, that will contains data (Relative or Absolute).
messages_ttl_check_in_hours 1 How often will Gateway check data for obsolescence
messages_ttl_in_days * 7 Maximum days that storage will save data

* – If receive data when storage has already counted, described in this parameter, new data will lose.

Storage section of configuration file will look like:

1
2
3
4
5
6
7
8
...
"storage": {
  "type": "memory",
  "data_file_path": "./data/data.db",
  "messages_ttl_check_in_hours": 1,
  "messages_ttl_in_days": 7
},
...

Connectors configuration

Configs in connectors section configuration for connecting to devices by implemented protocols. Config for every connector in this section must have parameters as in table below:

Parameter Default value Description
useGRPC true OPTIONAL parameter that is used to on/off GRPC transport for default connector realisation
name MQTT Broker Connector Name of connector to broker.
type mqtt Type of connector, must be like a name of folder, contained configuration file.
configuration mqtt.json Name of the file with configuration in config folder.*

* – Folder with this configuration file.

Section connectors in your configuration file may differ from shown below, but they should have structure like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
...
"connectors": [
  {
    "type": "mqtt",
    "name": "MQTT Broker Connector",
    "configuration": "mqtt.json"
  },
  {
    "type": "modbus",
    "name": "Modbus Connector",
    "configuration": "modbus.json"
  },
  {
    "type": "modbus",
    "name": "Modbus Serial Connector",
    "configuration": "modbus_serial.json"
  },
  {
    "type": "opcua",
    "name": "OPC-UA Connector",
    "configuration": "opcua.json"
  }
]
...

Note: You can use several similar connectors at same time, but you should provide different names and configuration files to them.

If you need different type of connector, you can implement it using customization guide or email us: [email protected].