ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.
Open documentation for releases before 1.3

Entities and relations

Entities Overview

ThingsBoard provides the user interface and REST APIs to provision and manage multiple entity types and their relations in your IoT application. Supported entities are:

Each entity supports:

Additionally, devices and assets also have a type. This allows distinguising them and process data from them in a different way.

This guide provides the overview of the features listed above, some useful links to get more details and real-life examples of their usage.

Real-life application

The easiest way to understand the concepts of ThingsBoard is to implement your first ThingsBoard application. Let’s assume we want to build an application that collects data from soil moisture and temperature sensors, visualize this data on the dashboard, detect issues, raise alarms and control the irrigation.

Let’s also assume we want to support multiple fields with hundreds of sensors. Fields may be also grouped to the Geo regions.

We believe there should be following logical steps to build such an application:

Step 1: Provision entities and relations

We are going to setup following hierarchy of assets and devices:

image

Please review the following screen cast to learn how to provision region and fields assets and their relations using ThingsBoard Web UI

Please review the following screen cast to learn how to provision devices and their relations with assets using ThingsBoard Web UI

You can automate this actions using ThingsBoard REST API. You can provision new asset using POST request to the following URL

http(s)://host:port/api/asset

For example:

resources/create-asset.sh
curl -v -X POST -d @create-asset.json http://localhost:8080/api/asset \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
resources/create-asset.json
{"name":"Field C","type":"field"}

Note: in order to execute this request, you will need to substitute $JWT_TOKEN with a valid JWT token. This token should belong to a user with TENANT_ADMIN role. You can use following guide to get the token.

Also, you can provision new relation using POST request to the following URL

http(s)://host:port/api/relation

For example

resources/create-relation.sh
curl -v -X POST -d @create-asset.json http://localhost:8080/api/relation \
--header "Content-Type:application/json" \
--header "X-Authorization: $JWT_TOKEN"
resources/create-relation.json
{"from":{"id":"$FROM_ASSET_ID","entityType":"ASSET"},"type":"Contains","to":{"entityType":"ASSET","id":"$TO_ASSET_ID"}}

Note: Don’t forget to replace $FROM_ASSET_ID and $TO_ASSET_ID with valid asset ids. Note: One can relate any entities. For example, assets to devices or assets to users. You can receive them as a result of previous REST API call or use Web UI.

Step 2: Assign attributes to the assets

ThingsBoard provides the ability to assign attributes to entities and manage them. This topic is covered in separate guide.

Working with device attributes

Step 3: Upload telemetry data from devices

ThingsBoard provides the ability to work with telemetry data for devices and other entities. This topic is covered in separate guide.

Working with telemetry data

Step 4: Creating Rules for Alarms

ThingsBoard provides the ability to raise alarms using rule engine for devices and other entities. This topic is covered in the separate guide.

Working with alarms

Step 5: Design your dashboard

Please import the following dashboard that demonstrates Map, Alarm, Entity Table and Charts widgets.