IoT Gateway Configuration

• Directory structure
• Environmental variables
• General configuration file
  • Sections in config file
  • Connection to ThingsBoard
    • Subsection “statistics”
    • Subsection “deviceFiltering”
    • Subsection “checkingDeviceActivity”
    • Subsection “security”
    • Subsection “provisioning”
  • Storage configuration
  • Connectors 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

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:

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

Subsection “statistics”

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

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.

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.

Subsection “security”

There are 3 variants of security subsection:

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

1
2
3
4
5
6
7
...
"security": {
  "clientId": "YOUR_CLIENT_ID",
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD"
},
...

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

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

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

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

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

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.

1
2
3
4
5
6
7
...
"storage": {
  "type": "memory",
  "read_records_count": 10,
  "max_records_count": 100
},
...

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
},
...

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:

* – 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: info@thingsboard.io.