ThingsBoard
ThingsBoard
1. Product Overview
1.1 Introduction to ThingsBoard
ThingsBoard is an open-source IoT platform that provides device management, data collection, and visualization to help users rapidly develop, manage, and scale IoT applications. For more information, see the ThingsBoard website.

1.2 Integrating ThingsBoard with the IoTDB Table Model
The iotdb-thingsboard-table extension provided by IoTDB stores ThingsBoard historical telemetry, latest telemetry values, and entity attributes in the IoTDB table model. It also supports reading and displaying this data in ThingsBoard. Users can choose which types of data to store in IoTDB and use ThingsBoard for device data management and visualization.
2. Integration Steps
2.1 Environment Requirements
This guide uses IoTDB 2.0.11, ThingsBoard 4.3.1.2, and iotdb-thingsboard-table 2.0.11 as examples. When using later versions, check extension compatibility in the documentation for those versions and adjust the dependencies, configuration, and startup procedure accordingly.
| Software | Example Version or Configuration | Purpose |
|---|---|---|
| IoTDB | 2.0.11, table model | Stores telemetry and/or attributes |
| ThingsBoard | 4.3.1.2 | Device connectivity and data management |
| JDK | 17 | Runs IoTDB and ThingsBoard |
IoTDB and ThingsBoard can run on different hosts or in separate containers. The ThingsBoard runtime must be able to reach the IoTDB RPC address (default port: 6667). For an initial deployment, use a separate test instance and test devices.
2.2 Install the Base Environment
Install ThingsBoard and IoTDB according to their official installation guides and verify that each can start independently. Complete the ThingsBoard installation and database initialization before connecting it to the IoTDB table model as described below.
- For IoTDB installation and deployment, see Standalone Deployment.
- Download an installation package from the ThingsBoard 4.3.1.2 release page, then follow the official ThingsBoard installation guide to install the software, configure the database, and initialize it.
If IoTDB and ThingsBoard run in separate containers, connect them to the same Docker network and configure IoTDB with a service name that ThingsBoard can reach. For the apache/iotdb:2.0.11-standalone image, assuming the IoTDB service is named iotdb, set the following entries in that service's environment section:
cn_seed_config_node: iotdb:10710
dn_seed_config_node: iotdb:10710
cn_internal_address: iotdb
dn_internal_address: iotdb
dn_rpc_address: iotdb2.3 Obtain and Deploy the Extension
Obtain the extension. Download
iotdb-thingsboard-table-2.0.11.jarfrom the Apache IoTDB Extras 2.0.11 release page.Download the dependencies. The extension JAR does not include the IoTDB client libraries. Download all nine dependency JARs using the Maven Central links below and save them together with the extension JAR in a local
libdirectory.Maven Dependency Version JAR Download org.apache.iotdb:iotdb-session2.0.11iotdb-session-2.0.11.jar org.apache.iotdb:isession2.0.11isession-2.0.11.jar org.apache.iotdb:service-rpc2.0.11service-rpc-2.0.11.jar org.apache.iotdb:iotdb-thrift2.0.11iotdb-thrift-2.0.11.jar org.apache.iotdb:iotdb-thrift-commons2.0.11iotdb-thrift-commons-2.0.11.jar org.apache.thrift:libthrift0.23.0libthrift-0.23.0.jar org.apache.tsfile:tsfile2.4.0tsfile-2.4.0.jar org.apache.tsfile:common2.4.0common-2.4.0.jar org.tukaani:xz1.10xz-1.10.jar Alternatively, run the following Bash commands to download the extension and all dependencies into a
libdirectory under the current directory (for Linux, macOS, or Windows Git Bash):mkdir -p lib R=https://github.com/apache/iotdb-extras/releases/download/v2.0.11 curl -fL -o lib/iotdb-thingsboard-table-2.0.11.jar "$R/iotdb-thingsboard-table-2.0.11.jar" M=https://repo1.maven.org/maven2 for path in \ org/apache/iotdb/iotdb-session/2.0.11/iotdb-session-2.0.11.jar \ org/apache/iotdb/isession/2.0.11/isession-2.0.11.jar \ org/apache/iotdb/service-rpc/2.0.11/service-rpc-2.0.11.jar \ org/apache/iotdb/iotdb-thrift/2.0.11/iotdb-thrift-2.0.11.jar \ org/apache/iotdb/iotdb-thrift-commons/2.0.11/iotdb-thrift-commons-2.0.11.jar \ org/apache/thrift/libthrift/0.23.0/libthrift-0.23.0.jar \ org/apache/tsfile/tsfile/2.4.0/tsfile-2.4.0.jar \ org/apache/tsfile/common/2.4.0/common-2.4.0.jar \ org/tukaani/xz/1.10/xz-1.10.jar; do curl -fL -o "lib/${path##*/}" "$M/$path" doneAfter downloading, the
libdirectory should contain 10 JARs: one extension JAR and nine dependency JARs.ThingsBoard 4.3.1.2 already includes the LZ4, Zstd, Snappy, and ANTLR runtime libraries. Do not place duplicate versions of these libraries in the extension directory.
Deploy the extension. Place the extension JAR and all nine dependency JARs in the ThingsBoard extension directory:
- Linux (
.debpackage):/usr/share/thingsboard/extensionsfor a standard installation using the official ThingsBoard 4.3.1.2.debpackage. Create the directory manually if it does not exist. - Windows:
<ThingsBoard-directory>\extensions. - Docker: Mount the
libdirectory at/usr/share/thingsboard/extensionsinside the container. See Section 2.4.1 for an example.
For a Linux
.debinstallation, run the following commands from the directory containing thelibfolder to create the extension directory and copy all JARs:sudo install -d /usr/share/thingsboard/extensions sudo install -m 0644 lib/*.jar /usr/share/thingsboard/extensions/If you change the installation location or startup configuration, use the actual extension loading path of the ThingsBoard process. Creating a directory and copying JARs into it does not automatically add it to the loading path.
- Linux (
Optional: To verify the source and integrity of the extension package, import the release signing public key from the Apache IoTDB KEYS file and verify the signature using the
.ascfile corresponding to the extension JAR from the same release. The signature file does not need to be deployed to the extension directory.
2.4 Configure the Extension
Pass the configuration through the SPRING_APPLICATION_JSON environment variable of the ThingsBoard process. The following examples apply to a single ThingsBoard node and enable historical telemetry, latest telemetry, and entity attribute storage together.
Adjust the IoTDB host, port, credentials, and database name for your deployment. If SPRING_APPLICATION_JSON is already set, merge these properties into the existing JSON object and retain the other settings. Use hyphens and underscores in property names exactly as shown.
By default, the extension connects to 127.0.0.1:6667 with username/password root/root, database name thingsboard, and session pool size 8. When iotdb.schema.bootstrap=true, the extension automatically creates the database and required tables on first startup. In containers, explicitly specify a reachable IoTDB hostname; the default address does not change automatically for container deployments.
2.4.1 Docker Compose
Merge the following snippet into the ThingsBoard service in your existing Compose file. The example uses thingsboard as the ThingsBoard service name and iotdb as the IoTDB service name. Adjust these names as needed and retain the existing ports, networks, volumes, and other environment variables. The lib directory downloaded in Section 2.3 should be in the same directory as the Compose file.
services:
thingsboard:
image: thingsboard/tb-node:4.3.1.2
volumes:
- ./lib:/usr/share/thingsboard/extensions:ro
environment:
SPRING_APPLICATION_JSON: >-
{
"iotdb.host": "iotdb",
"iotdb.port": "6667",
"iotdb.username": "root",
"iotdb.password": "root",
"iotdb.database": "thingsboard",
"iotdb.session-pool-size": "8",
"iotdb.schema.bootstrap": "true",
"database.ts.type": "iotdb-table",
"iotdb.ts.experimental-raw-only": "true",
"database.ts_latest.type": "iotdb-table",
"iotdb.ts_latest.cluster_mode": "disabled",
"database.attributes.type": "iotdb-table",
"iotdb.attributes.cluster_mode": "disabled"
}This snippet is for an existing ThingsBoard service whose base installation is complete; it is not a complete standalone Compose file. If the extension directory is already mounted, place all 10 JARs in the existing mounted directory and avoid mounting the same container path twice.
2.4.2 Linux (.deb Package)
Add the following configuration to /etc/thingsboard/conf/thingsboard.conf, retaining the existing settings. The ThingsBoard service reads this shell file at startup, so keep export and the single quotes around the JSON. Exporting the variable only in a terminal does not update the system service configuration.
This example assumes IoTDB and ThingsBoard run on the same host. If they use different addresses, change iotdb.host.
export SPRING_APPLICATION_JSON='{
"iotdb.host": "127.0.0.1",
"iotdb.port": "6667",
"iotdb.username": "root",
"iotdb.password": "root",
"iotdb.database": "thingsboard",
"iotdb.session-pool-size": "8",
"iotdb.schema.bootstrap": "true",
"database.ts.type": "iotdb-table",
"iotdb.ts.experimental-raw-only": "true",
"database.ts_latest.type": "iotdb-table",
"iotdb.ts_latest.cluster_mode": "disabled",
"database.attributes.type": "iotdb-table",
"iotdb.attributes.cluster_mode": "disabled"
}'2.4.3 Windows
Set the JSON object from SPRING_APPLICATION_JSON in Section 2.4.2 as a system or service environment variable that the ThingsBoard service process can read. The variable name is SPRING_APPLICATION_JSON. Its value must contain only the JSON from { to }, without the Bash export statement or surrounding single quotes.
Setting $env:SPRING_APPLICATION_JSON only in the current PowerShell window does not change the environment of an installed service. The official Windows installation package configures the extension loading path through install.bat. If you change the installation location or startup method, confirm that the actual loading path includes the extension directory.
2.5 Start and Check ThingsBoard
Start or restart ThingsBoard according to your deployment method:
Docker Compose: Run the command below from the directory containing the Compose file. Replace
thingsboardif your service has a different name.docker compose up -d thingsboardWhen the configuration changes, this command recreates the container. Restarting an existing container alone does not apply changes to environment variables or volume mounts.
Linux (
.debpackage): Restart the system service.sudo systemctl restart thingsboardWindows: Restart the ThingsBoard service through Windows Services.
Confirm that the logs contain the extension's session pool initialization message. If schema initialization is enabled, the schema creation completion message should also appear:
IoTDB Table Mode session pool initialized
IoTDB Table Mode schema bootstrap completeWhen entity attribute storage is enabled, a WARN message indicating that the extension replaces jpaAttributeDao is expected. If NoClassDefFoundError: org/apache/iotdb/isession/pool/ITableSessionPool appears, confirm that the extension directory contains the extension JAR and all nine dependency JARs, and that this directory is included in the ThingsBoard loading path.
Logs for a Linux .deb service are usually located in /var/log/thingsboard/. Log locations for Windows services and containers depend on their installation or runtime configuration. When running in the foreground, logs are usually written to the console or the log directory configured for that process.
2.6 Verify the Data
Create a device in ThingsBoard and obtain its access token. Send data to the device telemetry endpoint:
POST http://<ThingsBoard-address>:8080/api/v1/<device-access-token>/telemetry
Content-Type: application/json
{"temperature":23.75,"status":"ok"}Send data to the client attributes endpoint:
POST http://<ThingsBoard-address>:8080/api/v1/<device-access-token>/attributes
Content-Type: application/json
{"site":"local"}Use any HTTP client to send these requests. In Windows PowerShell, use curl.exe or Invoke-RestMethod; these are simply different ways to issue the requests from the command line.
After writing the data, open the device details to inspect it:
- On the Latest telemetry tab, confirm the telemetry keys and values.

- On the Attributes tab, select Client attributes and confirm the attribute keys and values.

These screenshots are examples. Their keys and values differ from the sample requests in this guide; check against the data you actually sent.
Wait for the telemetry batch write to complete, then query the data through the IoTDB table model CLI or a JDBC client. Replace <device-id> with the device ID from ThingsBoard:
USE thingsboard;
SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v
FROM telemetry
WHERE entity_id = '<device-id>'
ORDER BY time DESC
LIMIT 10;
SELECT time, entity_id, key, bool_v, long_v, double_v, str_v, json_v
FROM telemetry_latest
WHERE entity_id = '<device-id>'
ORDER BY time DESC
LIMIT 10;
SELECT time, entity_id, attribute_scope, key, bool_v, long_v, double_v, str_v, json_v
FROM entity_attributes
WHERE entity_id = '<device-id>'
ORDER BY time DESC
LIMIT 10;Compare the entity IDs, keys, and values. The telemetry sample's ts and value are stored in json_v. The table's time column represents the IoTDB row time, which may differ from the sample timestamp in the request. Check attributes by scope and the corresponding typed column; for example, a string attribute in CLIENT_SCOPE is stored in str_v. The latest telemetry and attributes on the ThingsBoard device page can also be used to verify readback.
3. Storage Configuration
Keep the required storage selectors and parameters in SPRING_APPLICATION_JSON according to your needs:
| Storage Type | Configuration | Description |
|---|---|---|
| Historical telemetry | database.ts.type=iotdb-table, iotdb.ts.experimental-raw-only=true | Supports writes, raw queries, deletion, and time-window aggregation. experimental-raw-only is a compatibility configuration name and must be set together with the historical telemetry selector. |
| Latest telemetry | database.ts_latest.type=iotdb-table, iotdb.ts_latest.cluster_mode | Depends on historical telemetry storage. If this selector is not enabled, the latest telemetry continues to use the original ThingsBoard storage backend. |
| Entity attributes | database.attributes.type=iotdb-table, iotdb.attributes.cluster_mode | Independent of telemetry storage. When enabled, it uses the attribute DAO provided by the extension. |
When enabling latest telemetry or entity attribute storage, set a valid value for the corresponding cluster_mode:
- For a single ThingsBoard node, use
disabled. - For multiple ThingsBoard nodes, use
sticky-routingonly when writes, updates, and deletions of latest telemetry values and attributes for the same device or entity can consistently be routed to the same node. This setting does not automatically configure ThingsBoard traffic routing. - In a multi-node deployment without sticky routing, using
disabledmay result in inconsistent values when different nodes concurrently update the same latest telemetry key or attribute. The extension does not coordinate writes across nodes.
Here, a "node" means a ThingsBoard node, not an IoTDB node. disabled does not disable storage. If the corresponding backend is enabled but cluster_mode is missing, empty, or set to any other value, ThingsBoard fails to start.
4. Data Migration and Limitations
- Existing data: The extension does not migrate data automatically. Backfill and verify existing data before switching an existing instance. After attribute storage is enabled, old attributes that have not been migrated may become inaccessible through ThingsBoard.
- Data retention: IoTDB configures TTL at the table level and does not apply ThingsBoard's per-record TTL. By default,
telemetry_latestdoes not expire automatically and is unaffected by the historical telemetry table's TTL. Plan its retention policy separately. - Data types: Keep the data type consistent for the same entity, key, and timestamp. Changing types across batches may cause that data point to fail on read.
- Version notifications: Latest telemetry and attribute operations return
nullforversion. Notifications that depend on a non-null version number do not take effect. - Reverting the configuration: Restoring the original storage configuration does not automatically migrate data back from IoTDB. To retain data added during the integration period, arrange a separate backfill or synchronization process.
5. References
For the complete configuration parameters, table schemas, and data migration mappings, see the IoTDB ThingsBoard Table extension documentation. In that directory, README.md provides a module overview, while docs/user-guide.md and docs/migration-guide.md provide detailed usage and migration instructions, respectively.