Professional Edition
ThingsBoard Documentation
Cloud Professional Edition Community Edition IoT Gateway License Server Trendz Analytics
Try it now Pricing
Documentation > Key concepts > Entities and Relations
Getting Started
Guides Installation Architecture API FAQ

On this page

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:

  • Tenants - you can treat the tenant as a separate business-entity: it’s an individual or an organization who owns or produce devices and assets; Tenant may have multiple tenant administrator users and millions of customers, devices and assets;
  • Customers - the customer is also a separate business-entity: individual or organization who purchase or uses tenant devices and/or assets; Customer may have multiple users and millions of devices and/or assets;
  • Users - users are able to browse dashboards and manage entities;
  • Devices - basic IoT entities that may produce telemetry data and handle RPC commands. For example, sensors, actuators, switches;
  • Assets - abstract IoT entities that may be related to other devices and assets. For example factory, field, vehicle;
  • Entity Views - useful if you like to share only part of device or asset data to the customers;
  • Alarms - events that identify issues with your assets, devices, or other entities;
  • Dashboards - visualization of your IoT data and ability to control particular devices through the user interface;
  • Rule Node - processing units for incoming messages, entity lifecycle events, etc;
  • Rule Chain - defines the flow of the processing in the Rule Engine. May contain many rule nodes and links to other rule chains;

Each entity supports:

  • Attributes - static and semi-static key-value pairs associated with entities. For example serial number, model, firmware version;
  • Time-series data - time-series data points available for storage, querying and visualization. For example temperature, humidity, battery level;
  • Relations - directed connections to other entities. For example contains, manages, owns, produces.

Some entities support profiles:

  • Tenant Profiles - contains common settings for multiple tenants: entity, API and rate limits, etc. Each Tenant has the one and only profile at a single point in time.
  • Device Profiles - contains common settings for multiple devices: processing and transport configuration, etc. Each Device has the one and only profile at a single point in time.

Entity Groups:

ThingsBoard Professional Edition allows you to configure Entity Groups for Customers, Users, Devices, Assets, Entity Views and Dashboards. Each entity may belong to multiple groups simultaneously. Entity Group always have an owner - particular Tenant or Customer. All entities in the group must have the same entity type (i.e. You can’t put device and asset into one group). Entity Groups are useful for dashboards and data processing, but the primary reason of their existence is to support advanced Role-Based Access Control (RBAC) for IoT.

Integrations and Data Converters:

ThingsBoard Platform integrations feature was designed for two primary use cases / deployment options:

  • Connect existing NB IoT, LoRaWAN, SigFox and other devices with specific payload formats directly to ThingsBoard platform.
  • Stream data from devices connected to existing IoT Platforms to enable real-time interactive dashboards and efficient data processing.

Data Converters is a part of the Platform Integrations feature. Their purpose is to transform raw payload from device to the format that ThingsBoard uses and vise-versa.

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

Relations

Entity relation defines connection between two ThingsBoard entities that belong to the same Tenant. The relation has an arbitrary type: Contains, Manages, Supports, etc. The relation is also directional. You may treat ThingsBoard relations as a Has-a relationship from object-oriented programming.

Relations help to model physical world objects in ThingsBoard. The easiest way to understand them is using the example. 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 into the Geo regions.

The following diagram explains how those entities are configured and stored in ThingsBoard:

image

See “add and delete assets” and “manage asset relations” to learn how to configure this entities via Administration UI. You may also use REST API to create entities and relations programmatically.

Next steps

Assign attributes to the assets and devices

ThingsBoard provides the ability to assign attributes to entities and manage them. You are welcome to learn how to do it here:

Working with device attributes

Upload telemetry data from devices

ThingsBoard provides the ability to work with telemetry data for devices and other entities. You are welcome to learn how to do it here:

Working with telemetry data

Creating Rules for Alarms

ThingsBoard provides the ability to raise alarms using rule engine for devices and other entities. You are welcome to learn how to do it here:

Working with alarms

Design your dashboard

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