ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform. Open documentation for releases before 2.0
ThingsBoard Professional Edition with White-labeling and Platform Integrations Learn More

Working with IoT device attributes

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

Attribute types

Attributes are separated into three main groups:

Device specific Attribute types

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

Device specific attributes are separated into two 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 Service

Telemetry Service is responsible for persisting attributes data to internal data storage; provides server-side API to query and subscribe for attribute updates.

Internal data storage

ThingsBoard uses either Cassandra NoSQL database or SQL database to store all data.

Although you can query the database directly, ThingsBoard provides a set of RESTful and Websocket API that simplify this process and apply certain security policies:

Data Query API

Telemetry Service provides following REST API to fetch entity data:

image

NOTE: The API listed above is available via Swagger UI, please review general REST API documentation for more details. The API is backward compatible with TB v1.0+ and this is the main reason why API call URLs contain “plugin”.

Attribute keys API

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

http(s)://host:port/api/plugins/telemetry/{entityType}/{entityId}/keys/attributes
resources/get-attributes-keys.sh
curl -v -X GET http://localhost:8080/api/plugins/telemetry/DEVICE/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"]

Supported entity types are: TENANT, CUSTOMER, USER, RULE, DASHBOARD, ASSET, DEVICE, ALARM

Attribute values API

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

http(s)://host:port/api/plugins/telemetry/{entityType}/{entityId}/values/attributes?keys=key1,key2,key3
resources/get-attributes-values.sh
curl -v -X GET http://localhost:8080/api/plugins/telemetry/DEVICE/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"
  }
]

Supported entity types are: TENANT, CUSTOMER, USER, RULE, DASHBOARD, ASSET, DEVICE, ALARM

Telemetry Rule Node

There are Rule Nodes in the Rule Engine that allows to work with Telemetry Service. Please find more details in node description:

Data visualization

ThingsBoard provides the ability to configure and customize dashboards for data visualization. This topic is covered in a separate guide.

Data Visualization guide

Rule engine

ThingsBoard provides the ability to configure data processing rules. Device attributes can be used inside rule filters. This allows applying rules based on certain device properties. You can find more details in a separate guide.

Rule Engine guide