thingsboard-gateway: a Python protocol adapter with sixteen connectors

A protocol adapter with one fixed publishing format

The useful way to think about this project is as a translation layer with a narrow output. On the input side it speaks a long list of industrial, networking, energy and building protocols. On the output side it speaks exactly one thing: the ThingsBoard platform, over MQTT or gRPC. The README describes it as an open source, Python-based application that enables integration of legacy and third party devices, serving as a protocol adapter that collects data from external sources and publishes it in a unified format.

That asymmetry is the whole design. The gateway does not try to be a general purpose ingestion broker where you pick a backend later. If your data has to land in ThingsBoard, this solves a real and tedious problem. If you want to land it in InfluxDB, Grafana or a Kafka topic, this is the wrong tool, and the closest you get is writing a custom connector and throwing away the publishing side.

The scale suggests this is a working project rather than an experiment. GitHub reports 2191 stars, 1008 forks and 75 open issues, and the repository is not archived. The last push was on 2026-09-24, with release 3.8.5 published on 2026-09-17, so the default branch named master is receiving changes.

Sixteen connectors across industrial, networking and building systems

The connector inventory is the substance of the project, and the README groups it into four bands. Industrial and SCADA covers Modbus for TCP and RTU devices such as PLCs and energy meters, OPC-UA for industrial automation, S7 for Siemens PLCs, CAN for controller area network devices, and ODBC for reading telemetry out of SQL compliant databases. IoT and networking adds MQTT subscriptions to external brokers, a REST API for pushing data, a Request connector that polls HTTP and HTTPS APIs, FTP and SFTP file reading, a raw TCP and UDP socket connector, SNMP polling against routers and switches, and XMPP.

The remaining two bands are where a general purpose ingestion tool usually stops. Smart energy adds OCPP for EV charging stations, which is a protocol with real message sequencing requirements and its own version negotiation. Smart building adds BACnet for HVAC, lighting and fire systems, KNX for wired building automation, and BLE for beacons and wearables. That is sixteen documented connectors, and the count matters because each one is a separate parsing and mapping problem rather than a configuration flag.

Several of these carry version and reliability work that shows up in the release notes. Version 3.8.5 moved the OCPP library from 1.6 to 2.1 and implemented RPC handling for it, which is the kind of protocol migration that breaks deployed chargers if it lands without review. The same release added an S7 connector with uplink and downlink conversion for 64 bit integers, date and time values and characters, plus a set of S7 RPC methods. Version 3.8.4 added offline docker builds and image exports for air gapped environments, a maxRegistersPerRequest parameter for Modbus batch reading, and fixes for register counts, certificate verification and connection recovery after the platform link is lost.

Converters and custom connectors as the extension path

A connector gets bytes off a wire; a converter decides what those bytes mean in platform terms. The README separates these and treats both as extension points, listing a data mapping engine that transforms raw device input into the platform's unified format through customizable converters, and a custom connectors path for building your own protocol handlers in Python.

This split is what lets the gateway handle messy real deployments. Most industrial protocols are syntactically simple and semantically ambiguous: a Modbus register holding four 16 bit words might be a timestamp, a float, two scaled integers or a packed bitfield, and only the site knows which. Encoding that knowledge as a converter keeps it out of the connector and out of the transport, so the same connector serves every deployment that shares a protocol.

The README characterizes the internal design as a modular architecture resembling microservices, with custom connectors for new devices, custom converters for message transformation, and the gateway encapsulating shared platform work such as device provisioning, local persistence and delivery. Whether or not the service description is literal, the practical consequence is the same and is worth stating plainly: because extensions are Python, they need the gateway process to be able to import them, so extension code has to travel with your deployment rather than being fetched at runtime.

Remote configuration, remote logging and remote shell

The management features are the part of the README that goes beyond protocol conversion, and they deserve a careful read rather than a quick skim. Remote configuration lets you update and manage the gateway configuration from the ThingsBoard web interface instead of editing files on the host. Remote logging streams the gateway's logs back into the platform for troubleshooting, which solves the field problem where the machine producing the errors is behind someone else's firewall.

Then there are two features with security weight. Gateway service RPC methods let the platform initiate commands against the gateway, and remote shell access lets you run shell commands on the gateway host through the platform. That second one is a full remote command channel by design. It is genuinely useful for fleet maintenance and it is also the kind of capability you want to know about before you connect a gateway to a network. The release history shows it being hardened rather than removed: version 3.8.4 fixed server certificate verification and TLS access token authentication, and fixed silent disabling of remote configuration on self provisioning gateways.

Two smaller platform-side behaviours are documented as well. Device rename and removal detection synchronises renames and deletions so the platform device list stays accurate, and the gateway buffers telemetry locally so an outage on the network or the host does not lose data, with automatic reconnection to the cluster afterwards. Buffering plus retry is the difference between a gap in your dashboard and a gap in your record.

Packaging: PyInstaller specs, deb packages and multiarch docker

The repository tree shows that deployment is a first class concern rather than an afterthought. There are two PyInstaller spec files, thingsboard-gateway.spec and thingsboard-gateway-offline.spec, which is what produces the standalone Windows binaries that installations traditionally point at. There is make_packages.sh and generate_deb_package.sh for Linux packaging, a requirements-full.txt alongside the leaner requirements.txt, a MANIFEST.in for the source distribution, and a tests directory.

Docker is handled with equal attention: a docker directory, build_latest_docker.sh and docker_build_multiarch.sh for producing images across CPU architectures, plus a .dockerignore. That multiarch script matters more than it sounds for gateways specifically, because these run on ARM boards next to the equipment, and a single-architecture image turns a five minute install into a build project.

The Python floor is explicit in setup.py, which sets python_requires to 3.10 or later and ships under the Apache License 2.0, matching the license GitHub reports. The dependency list in requirements.txt is short and gives a good picture of the transport layer: grpcio and protobuf for gRPC, orjson for fast serialisation, PyYAML for configuration, tb-paho-mqtt-client and tb-mqtt-client for MQTT, plus psutil, cryptography and PySocks. Worth noticing for fleet deployments is that tb-mqtt-client is pinned to an exact version rather than a floor, so gateway upgrades can pull a client change deliberately rather than incidentally.

Where the repository metadata and the README disagree

Three places where the project's own descriptions do not line up are worth knowing, because each one sends you looking in the wrong direction if you trust the wrong source.

The first is protocol coverage. The repository description on GitHub names eight protocols: Modbus, CAN bus, BACnet, BLE, OPC-UA, MQTT, ODBC and REST. The README documents sixteen connectors, adding S7, SNMP, XMPP, KNX, FTP, Socket, Request and OCPP to that list. The README is the current state and the repository description is simply older and shorter, so trust the connector list and the per protocol documentation pages it links.

The second is the topic tags, which run ahead of the README in the other direction. Among the tags are aws, aws-iot and sigfox, and none of those three appear anywhere in the README connector list. Whether they are planned, experimental or left over, the README does not document them, so treat AWS and Sigfox as unverified and check the documentation site before designing around them.

The third is the MQTT client, which appears twice in different forms. The tree contains a tb_mqtt_client directory alongside a .gitmodules file, meaning it is wired in as a git submodule, while requirements.txt pins tb-mqtt-client to 1.13.14 as an ordinary package. Both facts are recorded and neither cancels the other: the submodule is how the source is developed, the pin is what an install resolves. The practical consequence is for offline and air gapped builds, which the project explicitly supports, since you need the submodule populated to build the client that matches the pin.

Editorial conclusion

ThingsBoard IoT Gateway is a sensible answer when your devices speak industrial or building protocols and your backend is ThingsBoard, and a poor one otherwise, because the output format is fixed to that platform. The connector set is broad enough that a Modbus or OPC-UA rollout will not need custom code, and the converter plus custom connector path covers the proprietary leftovers. Two things deserve a look before you commit: compare the sixteen connectors in the README against the eight named in the repository description, since the topics also advertise AWS and Sigfox support that the README does not document, and check whether the tb_mqtt_client submodule is what you actually want in your dependency chain. Starting point is the Getting Started guide with its demo servers, which runs the pipeline without hardware.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. thingsboard/thingsboard-gateway on GitHub