Stop the war

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
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.yaml                               - Main configuration file for Gateway.
    logs.conf                                     - 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.

General configuration file

The main configuration file that is used for connection to ThingsBoard platform instance and enable/disable connectors. This configuration points to ThingsBoard instance thingsboard.cloud and uses memory file storage configured to store maximum of 100,000 records. There are 4 different connectors active. If you like to use only one of them - just remove all other connectors.


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
thingsboard:
  host: thingsboard.cloud
  port: 1883
  remoteShell: false
  remoteConfiguration: false
  statistics:
    enable: true
    statsSendPeriodInSeconds: 3600
  minPackSendDelayMS: 0
  checkConnectorsConfigurationInSeconds: 60
  handleDeviceRenaming: true
  checkingDeviceActivity:
    checkDeviceInactivity: false
    inactivityTimeoutSeconds: 120
    inactivityCheckPeriodSeconds: 10
  security:
    accessToken: PUT_YOUR_ACCESS_TOKEN_HERE
  qos: 1
storage:
  type: memory
  read_records_count: 100
  max_records_count: 100000
grpc:
  enabled: false
  serverPort: 9595
  keepaliveTimeMs: 10000
  keepaliveTimeoutMs: 5000
  keepalivePermitWithoutCalls: true
  maxPingsWithoutData: 0
  minTimeBetweenPingsMs: 10000
  minPingIntervalWithoutDataMs: 5000
connectors:
  -
    name: MQTT Broker Connector
    type: mqtt
    configuration: mqtt.json

  -
    name: Modbus Connector
    type: modbus
    configuration: modbus.json

  -
    name: Modbus Connector
    type: modbus
    configuration: modbus_serial.json

  -
    name: OPC-UA Connector
    type: opcua
    configuration: opcua.json

  -
    name: BLE Connector
    type: ble
    configuration: ble.json

  -
    name: CAN Connector
    type: can
    configuration: can.json

  -
    name: Custom Serial Connector
    type: serial
    configuration: custom_serial.json
    class: CustomSerialConnector
Spaces identity are important.

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.
Subsection “statistics”

This subsection uses 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 that is used to send data some every period
… configuration statistics.json Name of a configuration file for additional user statistics data

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"
  }
]
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
...
  security:
    accessToken: PUT_YOUR_GW_ACCESS_TOKEN_HERE
...

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
  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
  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
  security:
    privateKey: /etc/thingsboard-gateway/privateKey.pem
    caCert: /etc/thingsboard-gateway/ca.pem
    cert: /etc/thingsboard-gateway/certificate.pem
    checkCertPeriod: 86400
    certificateDaysLeft: 3

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
storage:
  type: memory
  read_records_count: 10
  max_records_count: 1000
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
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
storage
  type: sqlite
  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
25
26
27
28
29
30
31
32
33
34
35
36
37
connectors:

  -
    name: MQTT Broker Connector
    type: mqtt
    configuration: mqtt.json

  -
    name: Modbus Connector
    type: modbus
    configuration: modbus.json

  -
    name: Modbus Connector
    type: modbus
    configuration: modbus_serial.json

  -
    name: OPC-UA Connector
    type: opcua
    configuration: opcua.json

  -
    name: BLE Connector
    type: ble
    configuration: ble.json

  -
    name: CAN Connector
    type: can
    configuration: can.json

  -
    name: Custom Serial Connector
    type: serial
    configuration: custom_serial.json
    class: CustomSerialConnector

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].