.png)
How to Connect IoT Devices to ThingsBoard: A Complete Connectivity Guide
Connecting an IoT device to ThingsBoard is not a single fixed path. A battery-powered NB-IoT sensor, a custom MQTT device, a Modbus energy meter, and a BACnet building controller all need different connection patterns.
The good news is that ThingsBoard supports several connectivity options. The right choice depends on what the device can speak, where it sits on the network, how secure the connection must be, and whether you control the firmware.
This guide from ProSight Software explains the main ways to connect devices to ThingsBoard, when to use each one, and how to choose between IoT Hub, direct protocol connections, and the ThingsBoard IoT Gateway.
Start with the device, not the platform
Before choosing a connection method, look at the device itself. The best setup is usually the one that matches what the device already supports.
Ask four practical questions:
Does the device already have a ready-made ThingsBoard template?
Can the device connect over IP using MQTT, HTTP, CoAP, LwM2M, or SNMP?
Does the device speak an industrial protocol such as Modbus, OPC-UA, BACnet, CAN, or BLE?
Can you change the firmware, or do you need to connect it as-is?
These answers usually point to one of three paths:
Connection option | Best fit | Typical setup |
IoT Hub | Supported hardware with a ready-made template | Select the device template, follow setup steps, connect quickly |
Direct connection | Devices with custom firmware or native IP connectivity | Device connects straight to ThingsBoard using a supported protocol |
IoT Gateway | Industrial, building, or enterprise networks with non-IP or legacy protocols | Local gateway translates field protocols and sends data to ThingsBoard over MQTT |
Each path can work well. The goal is to avoid adding middleware where it is not needed, while still supporting older equipment and industrial networks that were not designed for cloud IoT platforms.
Use IoT Hub when a ready-made template exists
ThingsBoard IoT Hub is the fastest route when your hardware is supported. It offers a growing catalogue of ready-made IoT device templates from trusted contributors, so you do not have to build every integration from scratch.
A template usually gives you the connection settings and device-specific steps needed to get telemetry flowing. That makes IoT Hub useful for teams that want to test hardware quickly, run a proof of concept, or roll out common device types with less custom work.
Use IoT Hub when:
The device model appears in the catalogue
You want to connect hardware in minutes rather than write firmware
You prefer guided setup over low-level protocol configuration
The device behaviour matches the template closely
This is often the best starting point for common sensors, trackers, meters, and other known hardware. If the device is listed, try the template first. If it is not listed, or if you need custom behaviour, move to a direct connection or gateway setup.
Use a direct connection for custom firmware and IP devices
A direct connection means the device talks to ThingsBoard over the network without any middleware. This is the cleanest architecture when the device can run custom firmware and has IP connectivity.
In this model, the device sends telemetry, receives attributes, and can respond to commands using one of the supported protocols. It works well for connected controllers, embedded Linux devices, ESP32-class hardware, cellular devices with IP access, and any product where the firmware team controls the integration.
Direct connection is usually the right choice when:
The device has access to the internet or a private IP route to ThingsBoard
You can add ThingsBoard credentials to the firmware
You need real-time telemetry, attributes, or remote procedure calls
You do not need a local protocol bridge
ThingsBoard supports several direct protocols. Each one has a different role.
Protocol | Credentials | Best for | Reference |
MQTT | Access Token, MQTT Basic, X.509 | Custom firmware, real-time telemetry, RPC commands | MQTT API |
MQTT Sparkplug B | Access Token, MQTT Basic, X.509 | SCADA and IIoT systems with Sparkplug-aware brokers | Sparkplug B API |
HTTP | Access Token, X.509 | Periodic uploads and devices behind strict firewalls | HTTP API |
CoAP | Access Token, X.509 | Constrained devices and UDP networks | CoAP API |
LwM2M | PSK, RPK, X.509, No-Sec | NB-IoT, cellular IoT, and standardised object models | LwM2M API |
SNMP | Community string for v1 or v2c, USM for v3 | Network devices and industrial equipment | SNMP API |
MQTT works well for live telemetry and commands
MQTT is a common choice for IoT because it is lightweight, widely supported, and suited to frequent small messages. It is often the best default for custom firmware when the device needs to publish telemetry and receive commands.
Use MQTT when you need:
Frequent telemetry updates
Device attributes
Server-side commands through RPC
Long-lived connections
Broad library support across embedded platforms
For authentication, ThingsBoard supports access tokens, MQTT Basic credentials, and X.509 certificates. Access tokens are simple for early development. X.509 adds stronger identity controls for production devices.
MQTT Sparkplug B fits SCADA and IIoT systems
MQTT Sparkplug B is useful in industrial settings where systems already follow the Sparkplug specification. It adds a structured payload and topic model for industrial telemetry, birth messages, death messages, and state awareness.
Use Sparkplug B when your environment already includes Sparkplug-aware brokers or SCADA systems. It is less likely to be the first choice for a small custom sensor, but it can be a strong fit for larger industrial architectures.
HTTP is practical for simple periodic uploads
HTTP is easy to understand and often allowed through strict network firewalls. It suits devices that wake up, send a payload, then go back to sleep.
Use HTTP when:
The device sends data at intervals
Real-time commands are not central
Network rules favour standard HTTPS traffic
The firmware stack already supports HTTP well
HTTP can be a good fit for simple metering, environmental monitoring, or devices that only need one-way telemetry most of the time.
CoAP suits constrained devices and UDP networks
CoAP is designed for constrained devices and networks. It runs over UDP and can reduce overhead compared with heavier options.
Use CoAP when device resources are limited or when the network design favours UDP. It is often considered for embedded systems, low-power devices, and specialised IoT networks.
LwM2M is built for managed cellular IoT fleets
LwM2M is more than a transport. It defines a standard object model for device management, telemetry, configuration, and firmware workflows.
Use LwM2M for NB-IoT, cellular IoT, and fleets that need standardised device management. It supports credential options including PSK, RPK, X.509, and No-Sec, although production deployments should use secure credential modes wherever possible.
SNMP connects network and industrial equipment
SNMP is common in network devices, power systems, industrial equipment, and monitoring hardware. If a device already exposes values through SNMP, ThingsBoard can collect and process that data without firmware changes.
SNMP v1 and v2c use community strings. SNMP v3 uses USM, which provides stronger security options. For modern deployments, SNMP v3 is usually preferred where the device supports it.
Use the Check connectivity tool before writing code
ThingsBoard includes a built-in Check connectivity tool on the device details page. It can generate a ready-to-run command for your chosen protocol and operating system.
That is useful before writing firmware because it proves the basics:
The device exists in ThingsBoard
The credentials are valid
The network path works
The protocol endpoint is reachable
The payload format is accepted
For example, you can test an MQTT or HTTP telemetry message from a development machine before embedding the same logic into device code. This cuts down guesswork. If the generated command works but the device does not, the issue is probably in firmware, networking, DNS, certificates, or payload formatting on the device side.
Test the protocol path first, then build it into the device. It is much easier to debug a command-line request than a sealed field device.
Use ThingsBoard IoT Gateway for industrial and building systems
Many industrial and building devices do not connect directly to IoT platforms. They speak field protocols such as Modbus, OPC-UA, BACnet, CAN, or BLE. Some devices sit on local networks with no direct internet access. Others are old, reliable, and not worth replacing.
The ThingsBoard IoT Gateway solves this by running on a local machine near the devices. It connects to local equipment using protocol-specific connectors, then bridges the data to ThingsBoard over MQTT.
This gateway model is common in:
Factories
Utilities
Building management systems
Energy monitoring systems
Water and wastewater sites
Cold-chain and equipment monitoring
Retrofit projects with legacy controllers
A gateway setup is a good choice when devices are local, numerous, or tied to industrial protocols. It also lets you reduce outbound connections, since the gateway can collect local data and send it upstream in a controlled way.
Choose the right gateway connector
ThingsBoard IoT Gateway uses connectors for different protocols and sources. The connector handles the local side of the integration, while the gateway handles the connection to ThingsBoard.
Connector | Protocols or sources | Reference |
MQTT | MQTT brokers and MQTT devices | MQTT Connector |
OPC-UA | OPC-UA servers | OPC-UA Connector |
Modbus | Modbus RTU and Modbus TCP devices | Modbus Connector |
BLE | Bluetooth Low Energy devices | BLE Connector |
CAN | CAN bus devices | CAN Connector |
BACnet | BACnet/IP and BACnet MS/TP | BACnet Connector |
SNMP | SNMP-managed devices | SNMP Connector |
ODBC | Databases via ODBC | ODBC Connector |
Modbus is common for meters and controllers
Modbus remains widely used in energy meters, PLCs, temperature controllers, variable speed drives, and industrial sensors. If devices expose registers over Modbus RTU or Modbus TCP, the gateway can poll those registers and map values into ThingsBoard telemetry.
This works well for retrofit projects because the existing device does not need to know about ThingsBoard.
OPC-UA fits structured industrial data
OPC-UA is common in industrial automation where servers expose structured machine or process data. The gateway can connect to OPC-UA servers and forward selected nodes to ThingsBoard.
OPC-UA often suits plants with SCADA systems, machine controllers, or industrial data servers already in place.
BACnet suits building management
BACnet is widely used in HVAC, lighting, access, and building control systems. The gateway can connect to BACnet/IP or BACnet MS/TP networks and bring equipment data into ThingsBoard.
This is useful for energy dashboards, fault detection, occupancy-related control, and maintenance monitoring.
BLE and CAN cover local device networks
BLE is useful for nearby wireless sensors and beacons. CAN is common in vehicles, machinery, and embedded control systems. In both cases, the gateway acts as the local collector and sends selected data to ThingsBoard.
ODBC connects existing databases
Some systems already store operational data in a database. The ODBC connector can pull data from supported databases through ODBC rather than connecting to each source device directly.
That can be useful when the database is the stable integration point and the underlying devices are managed by another system.
Match the connection method to the real deployment
A good ThingsBoard design usually follows the simplest reliable path.
If the device has a supported IoT Hub template, use that first. It saves time and reduces setup errors.
If the device has custom firmware and IP connectivity, connect it directly. MQTT is often the best starting point for live telemetry and commands. HTTP is useful for simple uploads. CoAP and LwM2M suit constrained and cellular devices. SNMP fits equipment that already exposes management data.
If the device belongs to an industrial or building network, use the IoT Gateway. It lets you keep local protocols in place while sending clean telemetry to ThingsBoard.
Here is a quick decision guide:
If your device or system looks like this | Choose this path |
A supported off-the-shelf device appears in the template catalogue | IoT Hub |
A custom firmware device needs live telemetry and commands | Direct MQTT |
A device sends simple periodic data through a strict firewall | Direct HTTP |
A constrained device uses UDP networks | Direct CoAP |
A cellular IoT device needs standard device management | Direct LwM2M |
A router, switch, UPS, or industrial device exposes SNMP | Direct SNMP or Gateway SNMP |
A factory device uses Modbus, OPC-UA, CAN, or BLE | ThingsBoard IoT Gateway |
A building system uses BACnet | ThingsBoard IoT Gateway |
Operational data already sits in a database | Gateway ODBC connector |
Plan security before rollout
Connectivity is not only about getting the first payload into ThingsBoard. Production deployments need clear credential handling and network rules.
For direct connections, choose credentials that match the risk level and device capability. Access tokens are simple, but certificate-based authentication can provide stronger identity controls. For MQTT and HTTP, use secure transport where supported. For SNMP, prefer v3 when available.
For gateway deployments, protect both sides:
The local connection to field devices
The outbound MQTT connection to ThingsBoard
The gateway host operating system
Configuration files that store credentials
Remote access to the gateway machine
Also plan how credentials will be created, rotated, and removed when devices are replaced. This matters more as fleets grow.
What success looks like
A successful ThingsBoard connection is more than a green status indicator. The setup should be repeatable, secure, and easy to recognise when something goes wrong.
A working deployment should have:
Telemetry arriving under the correct device
Credentials stored safely
Payloads mapped to clear attribute and telemetry names
Commands tested where RPC is required
Gateway connectors documented where gateways are used
A known test method using the Check connectivity tool
Clear ownership of firmware, gateway, and platform configuration
The simplest path is usually the best one. Use IoT Hub when a template exists. Use direct protocols when the device can speak to ThingsBoard itself. Use the IoT Gateway when real-world equipment speaks industrial or building protocols.
That approach gives each device the connection method it needs, without forcing every project into the same architecture.
