ThingsBoard IoT Gateway for Building Automation

What Is ThingsBoard IoT Gateway

ThingsBoard IoT Gateway is a modular, Python-based application that sits between field devices and the ThingsBoard IoT platform. Its purpose is straightforward: collect data from devices that speak legacy or industrial protocols and push that data upstream to ThingsBoard over MQTT. From the platform side, every device behind the gateway appears as a standard ThingsBoard device entity with telemetry, attributes, and RPC capabilities.

The gateway ships with built-in connectors for Modbus (TCP, UDP, and serial RTU/ASCII), BACnet/IP, OPC-UA, MQTT, BLE, CAN bus, ODBC, and REST. For building automation integrators, the BACnet, Modbus, and OPC-UA connectors are the most relevant. Each connector runs as an independent module within the gateway process, and you can enable multiple connectors simultaneously—for example, reading BACnet/IP from your HVAC controllers while polling Modbus RTU from your power meters on the same edge device.

Key architectural features that matter for BAS deployments include local data persistence (telemetry is buffered to SQLite when the upstream MQTT connection drops, preventing data loss during network outages), automatic reconnection to the ThingsBoard cluster, remote configuration (update connector settings from the ThingsBoard web UI without SSH access to the gateway), and remote logging (stream gateway logs to the platform for troubleshooting). The gateway also supports custom connectors and custom data converters, so you can extend it for proprietary protocols that your specific building uses.

Installation options include pip (pip3 install thingsboard-gateway), Docker Compose, Debian/Ubuntu packages, and installation from source. The minimum requirement is Python 3.7 or higher running on a Linux-based system. Most BAS deployments run the gateway on a Raspberry Pi, an industrial edge PC, or a small Linux VM co-located with the building's automation network.

BACnet Connector Setup

The BACnet connector enables the gateway to discover and poll BACnet/IP devices on the local network segment. It supports two configuration modes: Basic (a simplified UI-driven setup for quick deployment) and Advanced (full JSON-based configuration for granular control). For building automation work, you will almost always use Advanced mode because it gives you explicit control over which BACnet objects map to which ThingsBoard telemetry keys.

Connector Configuration Structure

The BACnet connector configuration defines three key sections: the gateway's own BACnet identity, a list of target devices, and the object-to-telemetry mapping for each device. Here is a representative configuration snippet:

{
  "general": {
    "objectName": "TB_Gateway",
    "objectIdentifier": 599,
    "address": "192.168.1.50",
    "port": 47808,
    "interface": "eth0"
  },
  "devices": [
    {
      "deviceName": "AHU-1",
      "deviceProfileName": "BACnet AHU",
      "address": "192.168.1.100",
      "pollPeriod": 5000,
      "timeseries": [
        {
          "key": "discharge_air_temp",
          "objectId": "analogInput:1",
          "propertyId": "presentValue"
        },
        {
          "key": "supply_fan_status",
          "objectId": "binaryInput:3",
          "propertyId": "presentValue"
        }
      ],
      "attributes": [
        {
          "key": "device_description",
          "objectId": "device:100",
          "propertyId": "description"
        }
      ]
    }
  ]
}

The general section identifies the gateway itself on the BACnet network. Assign it a unique object identifier that does not conflict with any existing BACnet device on the segment. The devices array lists every BACnet device the gateway should poll. For each device, you define timeseries entries (values that change over time, like temperatures and statuses) and attributes (static or slow-changing metadata like device descriptions and firmware versions).

Object ID Filtering

The connector supports flexible object ID filters. You can target a single object ("objectId": 1234), all objects ("objectId": "*"), a range ("objectId": "0-10"), or multiple ranges ("objectId": ["0-10", "12-15"]). You can also filter by object type: "objectType": "analogValue" for a single type or "objectType": ["analogValue", "binaryInput"] for multiple types. These filters are useful when a controller exposes hundreds of objects but you only need a subset for your dashboard.

EDE File Import

For large BACnet installations, manually mapping every object is impractical. The BACnet connector supports EDE (Engineering Data Exchange) file parsing in Advanced mode. An EDE file describes the complete object structure of a BACnet device—you can export one from YABE or from most BAS engineering tools. Point the connector at the EDE file, and it automatically creates the device in ThingsBoard with all attributes and time series mapped from the file contents. This significantly accelerates commissioning on sites with dozens of controllers.

RPC Commands

The BACnet connector supports bidirectional communication. From the ThingsBoard dashboard, you can send RPC commands that write values to BACnet objects—for example, adjusting a zone temperature setpoint by writing to an Analog Value's Present_Value. This turns the gateway into a control pathway, not just a monitoring tool.

Modbus Connector Setup

The Modbus connector handles communication with Modbus TCP, Modbus UDP, and Modbus RTU/ASCII (serial) devices. In building automation, Modbus is the dominant protocol for power meters, variable frequency drives (VFDs), and standalone IO modules that are not on the BACnet network.

Master Configuration

The gateway runs as a Modbus master (client), polling one or more Modbus slaves (servers). The configuration defines a list of slaves, each with a connection type, address, and register map. Here is a representative configuration for a Modbus TCP power meter:

{
  "master": {
    "slaves": [
      {
        "host": "192.168.1.200",
        "port": 502,
        "type": "tcp",
        "method": "socket",
        "timeout": 3000,
        "byteOrder": "BIG",
        "wordOrder": "BIG",
        "retries": true,
        "retryOnEmpty": true,
        "retryOnInvalid": true,
        "pollPeriod": 5000,
        "unitId": 1,
        "deviceName": "Power Meter - Main Switchgear",
        "deviceType": "Modbus Energy Meter",
        "timeseries": [
          {
            "tag": "voltage_L1",
            "type": "32float",
            "functionCode": 3,
            "objectsCount": 2,
            "address": 0
          },
          {
            "tag": "current_L1",
            "type": "32float",
            "functionCode": 3,
            "objectsCount": 2,
            "address": 2
          },
          {
            "tag": "total_kWh",
            "type": "32float",
            "functionCode": 3,
            "objectsCount": 2,
            "address": 100
          }
        ]
      }
    ]
  }
}

For Modbus RTU over serial, change the type to "serial" and specify port (e.g., /dev/ttyUSB0), baudrate, stopbits, bytesize, and parity instead of a host and TCP port. This is how you connect RS-485 power meters and VFDs that use Modbus RTU.

Register Mapping

Each timeseries or attribute entry maps a Modbus register to a ThingsBoard telemetry key. You specify the function code (1 for coils, 2 for discrete inputs, 3 for holding registers, 4 for input registers), the starting address, the data type (16int, 32float, 64float, string, etc.), and the objects count (number of registers to read). Getting the byte order and word order correct is critical—consult the device's Modbus register map document, as different manufacturers use different endianness conventions.

The connector also supports writing to Modbus registers via RPC from the ThingsBoard UI. This enables control actions like resetting energy counters or adjusting VFD speed setpoints from a centralized dashboard.

OPC-UA Connector

OPC-UA (Open Platform Communications Unified Architecture) is a platform-independent, secure communication protocol widely adopted in industrial and building automation. The ThingsBoard gateway's OPC-UA connector allows you to subscribe to data nodes on an OPC-UA server and map them to ThingsBoard device telemetry.

In BAS environments, OPC-UA is commonly encountered with newer generation controllers, building management systems that expose an OPC-UA server interface, and chiller plants or central utility plants where industrial-grade PLCs with OPC-UA servers manage the equipment. The connector supports both subscription mode (the OPC-UA server pushes updates when values change) and polling mode (the gateway periodically reads node values).

Connection and Security

The OPC-UA connector configuration defines the server URL (e.g., opc.tcp://192.168.1.50:4840), authentication mode (anonymous, username/password, or certificate-based), and security policy (None, Basic128Rsa15, Basic256, Basic256Sha256). For production deployments in building automation, use at minimum Basic256Sha256 with certificate-based authentication. The connector also supports automatic server discovery and scan intervals for detecting new nodes.

Node Mapping

Device identification uses OPC-UA node paths with regular expression matching. For example, a building automation OPC-UA server might organize air handling units under Objects.BuildingAutomation.AirConditioner_1 through AirConditioner_N. You can match all of them with a single regex pattern like Objects\.BuildingAutomation\.AirConditioner_\d+$. Individual data nodes within each device map to ThingsBoard telemetry keys, following the same timeseries/attributes pattern used by the BACnet and Modbus connectors.

RPC commands from ThingsBoard can invoke OPC-UA method calls on the server, enabling write-back and control operations through the gateway.

Data Visualization

Once the gateway pushes telemetry to ThingsBoard, the platform's dashboard system handles visualization. ThingsBoard provides over 600 customizable widgets organized into bundles: Charts (time series line charts, bar charts, state charts for historical and real-time data), Cards (single-value displays, attribute tables, entity tables), Control widgets (buttons, sliders, and switches that send RPC commands to devices through the gateway), and SCADA symbols (graphical representations of equipment like AHUs, chillers, and VAV boxes).

A typical BAS monitoring dashboard built on ThingsBoard includes a building floor plan with overlaid temperature readings from BACnet sensors, time series charts showing discharge air temperature and valve position trends from the past 24 hours, a real-time energy consumption panel fed by Modbus power meter data, and alarm widgets that trigger when values exceed configured thresholds via ThingsBoard rule chains.

Rule Chains for BAS Logic

ThingsBoard rule chains process incoming telemetry and trigger actions. For building automation, common rule chain configurations include threshold-based alarms (alert when zone temperature exceeds setpoint by more than 3 degrees), data aggregation (calculate hourly or daily kWh totals from raw power readings), and downstream RPC commands (if outdoor air temperature drops below a threshold, send an RPC through the gateway to adjust a BACnet setpoint). Rule chains turn the platform from a passive data viewer into an active supervisory layer.

Multi-Tenant Dashboards

ThingsBoard supports multi-tenant architecture, which is valuable for BAS integrators who manage multiple buildings. Each building or customer gets an isolated tenant with its own devices, dashboards, and users. The gateway at each site reports to the correct tenant, and you manage all of them from a single ThingsBoard instance.

Common Mistakes

1. Running the BACnet connector inside Docker without host networking. The BACnet connector needs to send and receive UDP broadcasts on port 47808 to discover and communicate with BACnet/IP devices. Docker's default bridge network isolates the container from the host's broadcast domain. If you run the gateway in Docker, use network_mode: host in your Docker Compose file. Without host networking, the BACnet connector starts without errors but silently fails to reach any device on the local BACnet segment.
2. Incorrect byte order and word order in Modbus register mapping. Different Modbus device manufacturers use different endianness for multi-register values. A 32-bit float occupies two consecutive 16-bit registers, and the byte order (BIG or LITTLE) and word order (BIG or LITTLE) determine how those registers combine into the final value. If you read a temperature register and get 1.23e+18 instead of 72.5, your byte order or word order is wrong. Always consult the device's Modbus register map documentation and test with a known value before mapping dozens of points.
3. Assigning a duplicate BACnet device object identifier to the gateway. The objectIdentifier in the BACnet connector's general section must be unique on the BACnet network segment. If you assign an identifier already used by an existing controller, both devices will respond to WHO-IS requests with the same instance number, causing discovery conflicts across the entire BACnet network. Check the site's BACnet device schedule and pick an identifier well outside the range used by existing controllers—599 or higher is typically safe on sites that use standard low-range numbering.
4. Polling too aggressively and overwhelming field controllers. Setting a 500-millisecond poll period on a BACnet connector talking to an MS/TP controller behind a router, or on a Modbus RTU device sharing a serial bus with 20 other devices, will cause timeouts and data loss. BACnet MS/TP trunks and Modbus RTU buses have limited bandwidth. Start with poll periods of 5,000 to 10,000 milliseconds for serial-based protocols and reduce only after confirming stable communication. For BACnet/IP on a dedicated Ethernet segment, 2,000 to 5,000 milliseconds is a reasonable starting point.
5. Ignoring the gateway's local data persistence configuration. The gateway buffers telemetry locally in SQLite when the upstream MQTT connection to ThingsBoard drops. If you leave the buffer at default settings on a gateway that polls hundreds of points every few seconds, the SQLite database can grow to fill the disk on a resource-constrained edge device during an extended network outage. Configure the maximum buffer size and the data eviction policy to match your edge device's storage capacity.

Platform Compatibility

ThingsBoard IoT Gateway is designed for Linux-based systems with Python 3.7 or higher. It can also run on Windows and macOS for development and testing, though production BAS deployments almost always use Linux.

The upstream ThingsBoard platform (Community Edition or Professional Edition) runs separately as a Java application on its own server or as a cloud-hosted instance. The gateway connects to it over MQTT. For BAS projects, the typical topology is: ThingsBoard platform in the cloud or on an on-premises server, and one ThingsBoard IoT Gateway per building or per automation network segment, installed on an edge device physically connected to the BACnet/IP and Modbus networks.

Hardware requirements for the gateway: The gateway itself is lightweight. A Raspberry Pi 4 with 2 GB RAM can comfortably run multiple connectors polling several hundred points. For larger sites with thousands of points or heavy OPC-UA subscription loads, use an industrial edge PC with 4 GB RAM or more. The main bottleneck is typically network bandwidth on serial buses, not gateway CPU or memory.

Source Attribution

This guide draws from the following publicly available sources:

• ThingsBoard IoT Gateway GitHub Repository — source code, release notes, and issue tracker for the open-source gateway project (1,700+ stars).
• ThingsBoard Documentation: What Is IoT Gateway — official architecture overview, feature list, and supported protocol summary.
• ThingsBoard Documentation: BACnet Connector Configuration — official BACnet connector setup guide with JSON configuration examples and EDE file support.
• ThingsBoard Documentation: Modbus Connector Configuration — official Modbus connector guide covering TCP, UDP, and serial RTU/ASCII modes.
• ThingsBoard Documentation: OPC-UA Connector Configuration — official OPC-UA connector guide with security, authentication, and node mapping details.
• ThingsBoard Documentation: Pip Installation Guide — installation instructions for pip-based deployment on Linux.
• ThingsBoard Documentation: Docker Installation Guide — Docker Compose deployment instructions and container configuration.