ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.

What is ThingsBoard IoT Gateway?

The Thingsboard IoT Gateway is an open-source solution that allows you to integrate devices connected to legacy and third-party systems with Thingsboard.

Thingsboard is an open-source IoT platform for data collection, processing, visualization, and device management. See What is Thingsboard? if you are new platform user.

Gateway features

ThingsBoard IoT Gateway provides following features:


The IoT Gateway is a software component that is designed to run on a Linux based microcomputers that support Python 3.5+. Main components of ThingsBoard IoT Gateway are listed below.


The purpose of this component is to connect to external system (e.g. MQTT broker or OPC-UA server) or directly to devices (e.g. Modbus, BLE or CAN). Once connected, connector is either poll data from those systems or subscribe to updates. Poll vs subscribe depends on the protocol capabilities. For example, we use subscription model for MQTT connectors and polling for Modbus and CAN. Connector is also able to push updates to devices either directly or via external systems.

It is possible to define your own connector using the customization guide.


Converters are responsible for converting data from protocol specific format to/from ThingsBoard format. Converters are invoked by Connectors. Converters are often specific to protocol supported by Connector. There are uplink and downlink converters. Uplink converter is used to convert data from specific protocol to ThingsBoard format. Downlink converter is used to convert messages from ThingsBoard to specific protocol format.

It is possible to define your own converter using the customization guide.

Event Storage

Event Storage is used to temporary store the telemetry and other events produced by Connectors until they are delivered to ThingsBoard. Event Storage support two implementations: in-memory queue and persistent file storage. Both implementations make sure that your device data is eventually delivered in case of network outages. In-memory queue minimizes the IO operations but may lose message in case of gateway process restart.
Persistent file storage survives the restart of the process but executes IO operations to the file system.

ThingsBoard Client

The Gateway communicates to ThingsBoard via MQTT protocol and uses API described here. ThingsBoard Client is a separate thread that polls Event Storage and delivers messages once connection to ThingsBoard is active.
ThingsBoard Client supports monitoring of the connectivity, batching the events for performance improvement and many other features.

Gateway Service

The Gateway Service is responsible for bootstrap of the Connectors, Event Storage and ThingsBoard Client. This Service collects and periodically reports statistics to ThingsBoard about incoming messages and connected devices. Gateway Service persists list of connected devices to be able to re-subscribe to device configuration updates in case of the restart of the gateway.

Project Roadmap

Gateway Roadmap

Next Steps

Getting Started Guide