Skip to content

docs: add the ThingsBoard table-model integration page - #1199

Open
PDGGK wants to merge 5 commits into
apache:mainfrom
PDGGK:docs-thingsboard-table-model
Open

PDGGK wants to merge 5 commits into
apache:mainfrom
PDGGK:docs-thingsboard-table-model

Conversation

@PDGGK

@PDGGK PDGGK commented Aug 20, 2026 •

Copy link
Copy Markdown

What

Adds a user-guide page for the iotdb-thingsboard-table module in apache/iotdb-extras, which lets a stock ThingsBoard instance store telemetry and attributes in IoTDB 2.x table model by putting the module and its runtime dependencies on its classpath and setting a few properties. (The page lists the exact jar set; it is not a single jar.)

The page is modelled on the existing Spark-IoTDB page — overview first, then requirements and deployment — and adds Configuration and Known Limitations sections that this integration needs.

Why a second ThingsBoard page

The site already has a ThingsBoard page under the tree model, but it documents a different deployment — an IoTDB-adapted ThingsBoard package writing to root.thingsboard. This one is stock ThingsBoard plus the module and its runtime dependencies, against table model.

Rather than replace or merge them, the new page opens with a paragraph distinguishing the two and links across to the tree-model page, so a reader who has landed on the wrong one can get to the right one.

That link is currently one-directional — the tree-model page does not point back here. Making it symmetric is a follow-up I have deliberately left out of this PR; see the last note below.

Files (10)

new Thingsboard.md in latest-Table and Master/Table, EN + ZH
modified en-Table.ts / zh-Table.ts sidebars — new "IoT Platform" / "物联网对接" group
modified Ecosystem-Overview_apache.md index row in all four trees

Notes for reviewers

  • No screenshots. In this directory the screenshot-heavy pages are the GUI clients — DBeaver has 11, DataGrip 13. The code-integration pages carry few or none: SeaTunnel, Mybatis-Generator and Spring-Boot-Starter have zero, MyBatisPlus-Generator has one, Spark-IoTDB two. This page is a code integration, so I left them out rather than manufacture images. I have since run the deployment end to end (ThingsBoard 4.3.1.2 against IoTDB 2.0.8), so real screenshots are now possible — say the word and I will add them.
  • Cross-tree links differ by tree because the layout requires it: from latest-Table the tree-model page is at ../../latest/, from Master/Table it is at ../../Tree/. There is no Master/latest and no top-level Tree, so exactly one of these resolves per copy.
  • The back-link is not in this PR. The tree-model ThingsBoard page exists in four version trees (V1.3.x, dev-1.3, latest, Master/Tree) in both languages, so a blanket back-link is 8 files. I would suggest scoping it to latest and Master/Tree (4 files) rather than all eight: V1.3.x and dev-1.3 document IoTDB versions that have no table model, so pointing them at a table-model integration would advertise something those versions cannot run. Happy to do that as a follow-up, or fold it in here if you would rather it land together.

The module is the deliverable of GSoC 2026 project GSOC-304, mentored by @CritasWang, who asked for this page.

@PDGGK
PDGGK force-pushed the docs-thingsboard-table-model branch 2 times, most recently from 56a80ea to e44cfd4 Compare August 21, 2026 09:37
@PDGGK PDGGK changed the title docs: add ThingsBoard table-model integration page docs: add the ThingsBoard table-model integration page Aug 21, 2026
@CritasWang

Copy link
Copy Markdown
Contributor

@PDGGK add some's screenshots

Adds a user-guide page for the iotdb-thingsboard-table module in
apache/iotdb-extras: stock ThingsBoard storing telemetry and attributes in
IoTDB 2.x table model, by placing the module and its runtime dependencies on
ThingsBoard's classpath and setting a few properties. The page lists the exact
jar set, including the ones that must NOT be copied because ThingsBoard bundles
newer copies of them.

Four new pages -- Thingsboard.md in latest-Table and Master/Table, English and
Chinese -- plus the two sidebar groups and the four Ecosystem-Overview index
rows. Structure follows the existing Spark-IoTDB page.

The attributes selector is documented as not yet usable on a stock ThingsBoard:
ThingsBoard registers its JPA attributes bean unconditionally and exposes no
switch for it, so setting the selector currently fails startup. The fix is
apache/iotdb-extras#125; the page says so and will be updated when a build
containing it is released.
@PDGGK
PDGGK force-pushed the docs-thingsboard-table-model branch from 9d334cc to 3bac99e Compare September 23, 2026 07:51
The module is now released in Apache IoTDB Extras 2.0.11, with its jar
attached to the GitHub release. Download it and its nine IoTDB client
dependencies instead of building from a commit, and update the tested
IoTDB version to 2.0.11.

The jar list changes for the 2.0.11 client: pipe-api is no longer needed,
libthrift is 0.23.0 and tsfile/common are 2.4.0. All ten jars are required
even with no selector set, because ThingsBoard does not start with the
module jar alone.

Signed-off-by: Zihan Dai <1436286758@qq.com>
@PDGGK

PDGGK commented Oct 23, 2026

Copy link
Copy Markdown
Author

@CritasWang The screenshots you asked for are in section 4 (the device's latest telemetry and client attributes pages), added in 3bac99e. I have also updated the page for the 2.0.11 release: it now downloads iotdb-thingsboard-table-2.0.11.jar from the release and the nine IoTDB client jars from Maven Central, instead of building from a commit. I followed the updated steps on ThingsBoard 4.3.1.2 with IoTDB 2.0.11: the commands give the ten jars with a good signature, ThingsBoard starts, and telemetry and a client attribute sent through ThingsBoard read back from IoTDB with the same timestamps.

PDGGK added 2 commits October 23, 2026 16:52
- Say where the settings go: a Docker Compose snippet and the Linux
  package's /etc/thingsboard/conf/thingsboard.conf, both passing them as
  SPRING_APPLICATION_JSON, and note that the .deb does not create
  /usr/share/thingsboard/extensions.
- Explain each setting for operators: what iotdb.ts.experimental-raw-only
  actually switches on, how the three kinds of data depend on each other,
  and what cluster_mode requires with one or several ThingsBoard nodes.
- List the jars once, keep other extension jars, and drop design terms
  the reader does not need.
- Compare IoTDB rows against the device's own ID, keys and times.
- Rewrite the Chinese page in plain Chinese rather than as a translation.

Signed-off-by: Zihan Dai <1436286758@qq.com>
Give the configuration section one subsection each for Docker, the Linux
package, choosing what IoTDB stores, and one or several ThingsBoard
nodes, so the JSON appears only where it is used. Clarify that a node
here is a ThingsBoard node, that sticky-routing does not set up routing
and that disabled does not turn storage off, and that an existing
SPRING_APPLICATION_JSON or extensions mount should be merged rather than
duplicated. Install the jars on the .deb with install -m 0644.

Signed-off-by: Zihan Dai <1436286758@qq.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants