View Documentation Use cases Getting started Live demo

Thingsboard Documentation

Documentation for using Thingsboard IoT Platform.

Working with telemetry data

Thingsboard provides rich set of features related to telemetry data:

This guide provides overview of the features listed above and some useful links to get more details.

image

Device telemetry upload API

Thingsboard provides an API to upload timeseries key-value data. Flexibility and simplicity of key-value format allows easy and seamless integration with almost any IoT device on the market. Telemetry upload API is specific for each supported network protocol. You can review API and examples in corresponding reference page:

Telemetry plugin

Thingsboard consist of core services and plug-able modules called plugins. Telemetry plugin is responsible for persisting timeseries data to internal data storage; provides server-side api to query and subscribe for data updates. Since Telemetry plugin functionality is critical for data visualization purposes in dashboards, it is configured on the system level by system administrator. Advanced users or platform developers can customize telemetry plugin functionality.

Internal data storage

Thingsboard uses Cassandra NoSQL database. This database is optimized for storage of timeseries data. Cassandra takes care of data replication and provides scalable, reliable and fault-tolerant storage.

Device that is sending data to the server will receive confirmation about data delivery as soon as data is stored in cassandra. Modern MQTT clients allow temporary local storage of undelivered data. Thus, even if one of the Thingsboard nodes goes down, device will not lose the data and will be able to push it to other servers.

Data is stored into several column families:

Although you can query database directly, Thingsboard provide set of RESTful and Websocket API that simplify this process and apply certain security policies:

Data Query API

Telemetry plugin provides following API to fetch device data:

Timeseries data keys API

You can fetch list of all data keys for particular device id using GET request to the following URL

http(s)://host:port/api/plugins/telemetry/{deviceId}/keys/timeseries
resources/get-telemetry-keys.sh
 
curl -v -X GET http://localhost:8080/api/plugins/telemetry/ac8e6020-ae99-11e6-b9bd-2b15845ada4e/keys/timeseries \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
Timeseries data values API

You can fetch list of latest values for particular device id using GET request to the following URL

http(s)://host:port/api/plugins/telemetry/{deviceId}/values/timeseries?keys=key1,key2,key3
resources/get-latest-telemetry-values.sh
 
curl -v -X GET http://localhost:8080/api/plugins/telemetry/ac8e6020-ae99-11e6-b9bd-2b15845ada4e/values/timeseries?keys=gas,temperature \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
resources/get-latest-telemetry-values-result.json
 
{
  "gas": [
    {
      "ts": 1479735870786,
      "value": "1"
    }
  ],
  "temperature": [
    {
      "ts": 1479735870786,
      "value": "3"
    }
  ]
}

You can also fetch list of historical values for particular device id using GET request to the following URL

http(s)://host:port/api/plugins/telemetry/{deviceId}/values/timeseries?keys=key1,key2,key3&startTs=1479735870785&endTs=1479735871858&interval=60000&limit=100&agg=AVG

The supported parameters are described below:

Thingsboard will use startTs, endTs and interval to identify aggregation partitions or sub-queries and execute asynchronous queries to Cassandra that levarage built-in aggregation functions.

resources/get-telemetry-values.sh
 
curl -v -X GET "http://localhost:8080/api/plugins/telemetry/ac8e6020-ae99-11e6-b9bd-2b15845ada4e/values/timeseries?keys=gas,temperature&startTs=1479735870785&endTs=1479735871858&interval=60000&limit=100&agg=AVG" \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
resources/get-telemetry-values-result.json
 
{
  "gas": [
    {
      "ts": 1479735870786,
      "value": "1"
    },
    {
      "ts": 1479735871857,
      "value": "2"
    }
  ],
  "temperature": [
    {
      "ts": 1479735870786,
      "value": "3"
    },
    {
      "ts": 1479735871857,
      "value": "4"
    }
  ]
}

Websocket API

Websockets are actively used by Thingsobard Web UI. Websocket API duplicates REST API functionality and provides ability to subscribe to device data changes. You can open a websocket connection to a telemetry plugin using following URL

ws(s)://host:port/api/ws/plugins/telemetry?token=$JWT_TOKEN

Once opened, you can send subscription commands and receive subscription updates:

where

Complete example is coming soon!

Data visualization

Thingsboard provide ability to configure and customize dashboards for data visualization. This topic is covered in separate guide.

Data Visualization guide

Rule engine

Thingsboard provide ability to configure data processing rules. Each rule consists of

Rule Engine guide