Working with IoT device attributes

• Video Tutorial
• Attribute types
• Device specific Attribute types
• Device attributes API
• Telemetry Service
  • Internal data storage
  • Data Query API
    • Attribute keys API
    • Attribute values API
  • Telemetry Rule Node
• Data visualization
• Rule engine

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.

Video Tutorial

Attribute types

Attributes are separated into three main groups:

• server-side - attributes are reported and managed by the server-side application. Not visible to the device application. Some secret data that may be used by thingsboard rules but should not be available to the device. Any ThingsBoard entity supports server-side attributes: Device, Asset, Customer, Tenant, Rules, etc.

  

• client-side - see device specific attributes
• shared - see device specific attributes

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:

• client-side - attributes are reported and managed by the device application. For example current software/firmware version, hardware specification, etc.

  

• shared - attributes are reported and managed by the server-side application. Visible to the device application. For example customer subscription plan, target software/firmware version.

  

Device attributes API

ThingsBoard provides following API to device applications:

• upload client-side attributes to the server
• request client-side and shared attributes from the server.
• subscribe to updates of shared attributes.

Attributes API is specific for each supported network protocol. You can review API and examples in corresponding reference page:

• MQTT API reference
• CoAP API reference
• HTTP API reference

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:

• Tenant Administrator user is able to manage attributes for all entities that belong to the corresponding tenant.
• Customer user is able to manage attributes only for entities that are assigned to the corresponding customer.

Data Query API

Telemetry Service provides following REST API to fetch entity data:

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

• get-attributes-keys.sh
• get-attributes-keys-result.json

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

• get-attributes-values.sh
• get-attributes-values-result.json

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:

• Enrichment Nodes - load latest telemetry for entity
• Save Timeseries
• Save Attributes

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