Skip to content
 
Try for free

ThingsBoard Cloud

Choose your data region

Your data stays in the region you choose, for residency and compliance. No credit card required.

North America Data stored in North America Europe Data stored in the European Union

Rather run it yourself? Install on your own servers

General Configuration

The gateway is configured through tb_gateway.json and per-connector JSON files located in the config directory. Connection parameters can also be overridden with environment variables.

Directory Structure

Section titled “Directory Structure”

Default layout for a daemon installation:

/etc/thingsboard-gateway/config/
  tb_gateway.json                           Main gateway configuration file
  logs.json                                 Logging configuration
  mqtt.json                                 MQTT connector configuration
  modbus.json                               Modbus connector configuration
  opcua.json                                OPC-UA connector configuration
  request.json                              Request connector configuration
  ble.json                                  BLE connector configuration
  can.json                                  CAN connector configuration
  ...


/var/lib/thingsboard_gateway/extensions/    Folder for 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
  modbus/                                   Folder for Modbus custom connectors/converters
  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/
  service.log                               Main gateway service logs
  connector.log                             Connector logs
  storage.log                               Storage logs
  tb_connection.log                         ThingsBoard connection logs

Environment Variables

Section titled “Environment Variables”

Environment variables are useful for Docker deployments — set them in docker-compose.yml to avoid hard-coding credentials in the config file:

services:
  tb-gateway:
    image: thingsboard/tb-gateway
    container_name: tb-gateway
    environment:
      - TB_GW_HOST=host.docker.internal
      - TB_GW_PORT=1883
      - TB_GW_ACCESS_TOKEN=YOUR_ACCESS_TOKEN

Full list of supported variables:

Variable Default Description
TB_GW_HOST host.docker.internal Hostname or IP address of ThingsBoard server
TB_GW_PORT 1883 MQTT service port on ThingsBoard server
TB_GW_SECURITY_TYPE accessToken Security type: accessToken, usernamePassword, tlsAccessToken
TB_GW_ACCESS_TOKEN — Access token for the gateway
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
TB_GW_USERNAME — MQTT username
TB_GW_PASSWORD — MQTT password
TB_GW_RATE_LIMITS 15:1,300:60, Message rate limit in COUNT:SECONDS, format
TB_GW_DP_RATE_LIMITS 15:1,300:60, Data point rate limit in COUNT:SECONDS, format
TB_GW_LOGS_PATH /thingsboard_gateway/logs Path to the logs folder

General Configuration File

Section titled “General Configuration File”

The main tb_gateway.json file controls the platform connection, security, storage backend, and the list of active connectors. Below is a full example connecting to thingsboard.cloud with memory storage and four connectors:

{
  "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
    }
  },

The file has three top-level sections:

Section Description
thingsboard Platform connection, security, and gateway behaviour
storage Local buffer for incoming data before sending to the platform
connectors Array of active connectors and their config files

Connection Parameters

Section titled “Connection Parameters”

Parameters inside the thingsboard object:

Parameter Default Description
host thingsboard.cloud Hostname or IP address of the ThingsBoard server
port 1883 MQTT service port
qos 1 MQTT QoS: 0 (at most once) or 1 (at least once)
minPackSendDelayMS 200 Delay between outgoing packets (lower value → higher CPU usage)
minPackSizeToSend 500 Minimum packet size before sending
maxPayloadSizeBytes 1024 Maximum message payload size in bytes
checkConnectorsConfigurationInSeconds 10 How often connector configs are checked for changes
handleDeviceRenaming true Enable device rename/delete notifications from the platform

statistics

Section titled “statistics”

Configures collection and reporting of gateway statistics as device attributes.

Parameter Default Description
enable true Enable statistics collection
statsSendPeriodInSeconds 3600 How often statistics are sent to ThingsBoard
configuration statistics.json Optional: path to a custom statistics commands file

The optional statistics.json file lets you collect arbitrary system metrics via shell commands:

[
  {
    "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"
  }
]

Example files for Linux, macOS, and Windows are included in the config/statistics/ folder.

deviceFiltering

Section titled “deviceFiltering”

Optional. Restricts which devices are allowed to send data to ThingsBoard based on connector and device name rules.

Parameter Default Description
enable false Enable device filtering
filterFile list.json Name of the filter rules file in the config folder

The filter file supports deny and allow rules per connector. Device names may be exact strings or regular expressions:

{
  "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"
    ]
  }
}
  • deny — devices matching these names (or patterns) are blocked from reporting through the specified connector.
  • allow — devices explicitly permitted regardless of deny rules.

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 device named “My Temperature Sensor” is allowed access to the “MQTT Broker Connector”.

checkingDeviceActivity

Section titled “checkingDeviceActivity”

Optional. Disconnects devices that have been inactive for longer than the configured timeout.

Parameter Default Description
checkDeviceInactivity false Enable inactivity monitoring
inactivityTimeoutSeconds 120 Seconds of inactivity before the device is disconnected
inactivityCheckPeriodSeconds 10 How often device activity is checked

security

Section titled “security”

Choose one of four security modes:

Simple token-based authentication. Create a gateway device in ThingsBoard and copy its access token.

Parameter Description
accessToken Access token from the ThingsBoard device credentials 
"security": {
  "type": "accessToken",
  "accessToken": "YOUR_ACCESS_TOKEN"
}

provisioning

Section titled “provisioning”

Optional. When set, the gateway auto-registers on the platform using the specified strategy instead of using pre-configured credentials. See Device Provisioning for the full workflow.

The platform generates and assigns an access token automatically.

Parameter Description
type AUTO
provisionDeviceKey Provisioning key from the device profile
provisionDeviceSecret Provisioning secret from the device profile 
"provisioning": {
  "type": "AUTO",
  "provisionDeviceKey": "YOUR_PROVISION_KEY",
  "provisionDeviceSecret": "YOUR_PROVISION_SECRET"
}

Storage Configuration

Section titled “Storage Configuration”

The storage section configures how the gateway buffers incoming device data before forwarding it to ThingsBoard. Choose one of three backends:

Persists data to .db files on disk. Recommended for most production setups.

Parameter Default Description
type sqlite Storage type
data_file_path ./data/ Directory for database files (trailing separator required)
max_read_records_count 1000 Max messages read from storage per batch and sent to ThingsBoard
size_limit 1024 Max size (MB) of each SQLite file before rotation to a new file
max_db_amount 10 Max number of rotated DB files to keep; writes are dropped when exceeded
oversize_check_period 1 Frequency (minutes) to check whether the current DB exceeds size_limit
writing_batch_size 1000 Max messages batched before a single write to the DB
messages_ttl_check_in_hours 1 How often to check for expired messages
messages_ttl_in_days 7 Days to retain messages before automatic deletion 
"storage": {
  "type": "sqlite",
  "data_file_path": "./data/",
  "max_read_records_count": 1000,
  "size_limit": 1024,
  "max_db_amount": 10,
  "oversize_check_period": 1,
  "writing_batch_size": 1000,
  "messages_ttl_check_in_hours": 1,
  "messages_ttl_in_days": 7
}

Connectors Configuration

Section titled “Connectors Configuration”

The connectors array lists all active connectors. Each entry requires:

Parameter Example Description
type mqtt Connector type — must match the folder name containing the connector implementation
name MQTT Broker Connector Display name for the connector
configuration mqtt.json Filename of the connector config file in the config directory
useGRPC true Optional. Enable/disable gRPC transport for the connector 
"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"
  }
]

Multiple connectors of the same type are supported — give each a unique name and configuration file. For custom connector types, see the Customization guide.

© 2026 The ThingsBoard Authors