Star

Guides

How to get started, and accomplish tasks, using Thingsboard.

Working with device attributes

Thingsboard provides ability to assign custom attributes to your devices and manage them. Attributes are treated key-value pairs. Flexibility and simplicity of key-value format allows easy and seamless integration with almost any IoT device on the market.

All attributes may be used in Rule Engine components: filters, processors and actions. This guide provides overview of the features listed above and some useful links to get more details.

Attribute types

Attributes are separated into three main groups:

Device attributes API

Thingsboard provides following API to device applications:

Attributes 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 attributes data to internal data storage; provides server-side api to query and subscribe for attribute 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.

Attributes are stored in attributes_kv_cf column family.

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 attributes:

Attribute keys API

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

http(s)://host:port/api/plugins/telemetry/{deviceId}/keys/attributes
resources/get-attributes-keys.sh
curl -v -X GET http://localhost:8080/api/plugins/telemetry/ac8e6020-ae99-11e6-b9bd-2b15845ada4e/keys/attributes \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
resources/get-attributes-keys-result.json
["model","softwareVersion"]

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/attributes?keys=key1,key2,key3
resources/get-attributes-values.sh
curl -v -X GET http://localhost:8080/api/plugins/telemetry/ac8e6020-ae99-11e6-b9bd-2b15845ada4e/values/attributes?keys=model,softwareVersion \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
resources/get-attributes-values-result.json
[
  {
    "lastUpdateTs": 1479735871836,
    "key": "model",
    "value": "Model 42"
  },
  {
    "lastUpdateTs": 1479735871836,
    "key": "softwareVersion",
    "value": "1.0.0"
  }
]

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. Device attributes can be used inside rule filters. This allows to apply rules based on certain device properties. You can find more details in a separate guide.

Rule Engine guide