Star

ThingsBoard Documentation

Documentation for using ThingsBoard IoT Platform.

Working with IoT dashboards

Prerequisites

For faster learning and a better understanding of this guide, first, you have to follow the Getting Started guide to get familiar with ThingsBoard devices and dashboards.

Introduction

ThingsBoard provides the ability to create and manage Dashboards.

Each Dashboard may contain plenty of widgets. Dashboards display data from many entities: devices, assets, etc. Dashboards can be assigned to Customers.

This guide covers main concepts and various configuration settings.

Dashboard overview

Before starting working with a dashboard, get familiar with its appearance and understand which features are responsible for what actions.

Title

Editable dashboard title appears in the top-left corner of the dashboard. Dashboard Title displays in the application breadcrumbs to simplify the navigation. You can change and adjust a Title in the settings of the dashboard

Edit mode

Use the “pencil” button in the bottom-right corner of the screen to enter dashboard edit mode. Once you switch to the edit mode, you can add new widgets and access controls in the dashboard toolbar. You can also use button “Apply changes” to save the dashboard or “Decline changes” to rollback all unsaved changes.

Toolbar

Dashboard toolbar allows you to manage states, layouts, settings, aliases, filters, and configure timewindow using the corresponding icons in the toolbar.

Some of these icons (stats, layout, settings) are visible only in the “edit” mode. All other icons are visible in both “view” and “edit” mode. You can hide these icons or configure the toolbar to be minimized by default using settings.

Entity Aliases

Entity Aliases determine which entities (devices, assets, etc) you would like to display on the dashboard. You can treat alias as a reference to one or more devices. These references can be static or dynamic.

An example of the static alias is the “Single Entity” alias. The entity is configured once in the alias definition. All users see the same data if they have permission to access this device.

An example of a dynamic alias is the “Device type” alias, which displays all devices of a certain type (e.g. “Thermometer”). This alias is dynamic because the list of devices depends on the user using the dashboard. If you are logged in as a Tenant administrator, the alias will resolve all “Thermometer” devices. However, if you are logged in as a Customer User, the alias will resolve to “Thermometer” devices that are assigned/belong by that Customer.

Please see the Entity Aliases documentation for more details and examples of other aliases.

Entity Filters

Entity Filters allow you to determine a filter for the list of entities resolved by the entity alias.

Let’s see an example: Suppose you have thousands of “Thermometer” devices, and you would like to display thermometers of a specific model and with certain battery levels. Let’s also assume that thermometer model is stored as an attribute, and the battery level is stored as a time series data. We will define a filter that checks if the model is “DHT22” and the battery level is less than 20 percent.

Please note: while adding the filter, you can configure the ability to edit it for users by moving the slider opposite the Filter name.

Filters are applied only to the “latest” value of the attribute or time series key. Don’t use this feature to “filter out” historical time series values.

You can combine different logical expressions over one key using “complex” filters. For example: “(A > 0 and A < 20) or (A > 50 and A < 100)”. Also, you can combine two expressions for different keys using the “and” relation. For example: “(A > 0 and A < 20) and (B > 50 and B < 100)”. It’s not possible to use “or” relation to combining different keys yet. For example: “(A > 0 and A < 20) or (B > 50 and B < 100)”.

See more examples how to use filters in this video:

Widgets

Widget types

Widgets are the building blocks of your dashboard. There are 5 types of widgets:

More about widget types you can learn here.

Adding widget to the dashboard

To add a widget to the dashboard, you should:

Add widget dialog and settings

Widget consists of the widget type, one or multiple data sources, basic and advanced settings, and the list of actions.
Therefore, the “Add widget” dialog contains four tabs to define a widget. Note that only the datasource configuration is strictly required. You may leave all other configuration tabs with the default values in most of the cases.
We will discuss each of those tabs below.

1. Widget data settings

Widget data settings allow you to add one or multiple data sources. A Data source is a combination of entity alias, optional filter, and list of data keys. Basically, the data source determines which entities widget should use (alias and filter) and what data keys to fetch for those entities.

For example, let’s configure data source to fetch temperature and humidity values for all “Thermometer” devices that have model “DHT22” and battery level is less than 20 percent. We will use “Thermometer” alias and “Low battery DHT22 Thermometers” filter configured in the previous parts of this doc, see alias and filter correspondingly.

The example above assumes that “temperature” and “humidity” are two time series data keys. The list of available data keys for particular data source depends on the widget type:

Let’s assume you don’t have the required time series or attribute key in the database yet. In such case, you can still add a key to the data source, and the widget will start displaying the data once the device will send it to ThingsBoard.

Besides the data keys, time series widget allows you to select the time window. Also, alarm widget allows you to select both time window and alarm filter.

2. Data keys

Data key defines time series, attribute or entity field that you would like to use in the widget. Data key definition consists of type (time series, attribute of entity field) and the actual key.

List of available attribute keys is basically a list of all client, server and shared attributes of your device or other entity.

List of available time series keys depends on what time series data you devices report to ThingsBoard or what time series data you have saved via rule engine or REST API.

List of entity fields depends on the entity type and may extend in the future:

2.1. Basic Data keys settings

Coming soon…

2.2. Advanced Data keys settings

Coming soon…

3. Widget time window

A widget time window defines a time interval and aggregation function that should be used to fetch the time series or alarm data. By default, every widget uses the main time window determined in the dashboard’s toolbar. You can overwrite the default time window using the “Use dashboard timewindow” checkbox. You can also hide the time window selection for a specific widget from the user using the “Display timewindow” checkbox.

Learn more about time window configuration here.

4. Alarm filter

In addition to the time window configuration, alarm widgets allow you to filter alarms based on status, severity, and type. You can choose a combination of alarm statuses and severity. You may also define specific alarm types as well as enable search of propagated alarms.

Basic widget settings

Let’s assume you have added the “Timeseries - Flot” widget to display thermometers using the widget data configuration step only. You should see a similar widget (note that you should send/simulate some data to see the actual lines in the chart):

Let’s use the basic widget settings to customize the widget. We will demonstrate how each setting affects the widget.

1. Widget Title

You can input custom widget title, tooltip and title style. You may also add an icon to the title and control icon color and size. See configuration and the corresponding result below.

Title style from the screen above:

{
  "fontSize": "10px",
  "fontWeight": 600
}

You may also completely hide the title using the “Display title” checkbox. You may also disable the widget shadow using the “Drop shadow” checkbox and disable fullscreen using the “Enable fullscreen” checkbox. All those settings are enabled by default.

2. Widget Style

You can customize personal style for the widget using CSS properties. This style will be applied to the main div element of the widget. You can also change the background color, text color, padding, and margin. See the configuration and the corresponding result below.

Please note that the style and background color are just an example and are definitely not part of our guidelines.

Widget style from the screen above:

{
  "border": "3px solid #2E86C1",
  "cursor": "pointer"
}
3. Legend settings

For chart widgets, the “Display legend” option is enabled by default. The legend is used to display the min/max/average/total values. Other widgets have this option disabled.

While the legend is enabled, you can choose the direction and position of the legend. Also, you can choose which data to include (min, max, average, total) and either to sort the data keys or not.

You may notice that the legend displays the data key label for each configured data key. When you have data from multiple devices in the same widget, it is hard to find which device corresponds to which record in the legend or in the tooltip. In order to make the legend and tooltip clear, you should use “${entityName}” or “${entityLabel}” in the data key configuration.

See configuration and the corresponding result below:

4. Mobile mode settings

Mobile Mode settings consist of two options:

5. Other settings

You can choose which symbol to display next to the value and the number of digits after the floating-point number. These settings are useful if you want to apply the same settings for all axis. For example, if you are showing temperature readings for multiple devices, you can add ‘°C’ or ‘°F’ symbol. However, if you are displaying both temperature and humidity, you have to configure these data keys separately using data key settings.

6. Advanced widget settings

Advanced widget settings are specific to widget implementation. Those settings allow you to fine tune the widget. For example, “Timeseries - Flot” widget allows you to configure line style, width, enable comparison with the previous time interval and use entity attributes in the legend.

Learn more about specific advanced settings in the corresponding widget documentation:

Coming soon…

Widget actions

Each type of widget has its own actions. They are similar and serve the same purpose - to help you quickly switch from the created widget to certain detailed information about its devices.

You can read more about the action widget in the article dedicated to it.

Time window

Dashboard time window defines default time interval and aggregation function that will be used to fetch the time series or alarm data. This time window will be used by all the time series and alarm widgets unless they are explicitly configured to overwrite this behaviour. In case of time series widget, ThingsBoard will obviously fetch telemetry with timestamp that matches the time window. In case of alarm widget, ThingsBoard will fetch alarms with created time that matches the time window.

The data aggregation function is applicable for time series data and is not applicable for alarms. Data aggregation is useful when you don’t want to fetch all time series data to UI, and you would like to pre-aggregate it on the database level. Using the aggregation functions saves network bandwidth and computation power of the client browser. We recommend to use aggregation functions whenever is possible if you have a lot of raw values.

There are 5 aggregation functions available at the moment: Min, Max, Average, Sum and Count. The special function called None is used to disable the aggregation. The default behavior of the dashboard is to show average values for the last minute grouped into 1 second intervals. Most likely, you will need to change this interval to last day or even last 30 days. You may notice that the value of minimum grouping interval is automatically adjusted according to the main time interval. The goal of the adjustment is to keep number of intervals lower than configurable value (700 in our case).

The time window may work in two modes: realtime and history. While in history mode, the widget will receive data only during the initial load and no updates will be issued over websockets.
In the realtime mode, the widgets will constantly receive updates from the server and will automatically show you only the data that matches the time window for a current timestamp.

Settings

Dashboard settings allow adjusting and altering the overall look of the Dashboard. To start customizing the Dashboard for a better user experience, the first thing you need to do is to enter the Edit mode by clicking the “Pencil” icon at the bottom right of the page (Enter edit mode).

When the edit mode is entered, you should click the “Gear” icon at the top of the window, so the Dashboard Settings will be opened.

State controller

The first thing that can be changed is State controller. By default, it’s set to “entity”, so to use all the features and work with the Dashboard as comfortable as possible we need to leave it that way.

Leave toolbar opened

The checkbox Leave toolbar opened is responsible for displaying the toolbar on the Dashboard page. Toolbar allows changing the dashboard you’re currently using, edit timewindow, export dashboard and expand the dashboard to the full screen.

If we remove the checkmark, the toolbar will be closed. Instead of it, on the upper right of the screen you find the three-dots icon. By clicking on it, the hidden toolbar will be opened.

Title of the Dashboard

If you’d like to see the Title of the Dashboard, you need to check the box Display dashboard title. The default text color is black. Color and transparency are easily adjusted using the Title color parameter by clicking the colored circle and choosing the desired color for the title by moving the slider. The changed title appears on the top left of the Dashboard.

Dashboard Toolbar Settings

The checkboxes Display Dashboard selection, Display entities selection, Display filters, Display timewindow, and Display export are responsible for the visibility of the appropriate options on the Dashboard toolbar panel.

Filters option is shown on the toolbar panel only when the one has been created. If the filter was created, but you’d like to limit the customer’s opportunity to modify the device’s indicators, we disable the ability to see filters on the toolbar panel by unchecking the corresponding checkbox.

Color

The line Color indicates the color of the text messages that you may see while editing your Dashboard. The Color adjusts by clicking the colored circle on the left from the line. A small window will open, and by moving the sliders, you can adjust the color and transparency of the text. By default, the color is set to black. For instance, if the widgets haven’t yet been added to the dashboard, and we change the Color, the message “Add new widget” will change.

Capacity

While editing the Dashboard, specifically the size and space of your widgets, you can notice a whitish grid on a grey background. These are columns that determine how many widgets can fit horizontally on a Dashboard. By default, the number of columns is 24. You can increase or decrease their number. The minimum number of columns is 10. The maximum number is 1000 columns.

This margin type determines how much space is between widgets. Be default, the margin is set on 10. You can remove it by placing 0 in the Margin between widgets line, or increase margin, that is, the distance between widgets. The maximum margin is 50.

By default, the Automatic Fill Layout Height checkbox is unchecked so that you can freely adjust the size of the widgets. If you tick this option, all the widgets on the Dashboard will fill in vertically in the space of the screen.

Background

1. Background color

The Background color option allows you to customize the color that you’d like to be on the Dashboard’s background. To alter it, click on the colored circle, and with sliders choose the needed color and wished transparency. Then, press “Save” to apply changes. After saving, you can see the customized background.

2. Background image

This option allows setting the picture as a background. To do this, you should drop an image in the appropriate field, or upload it from a folder on your computer. Once you select it, an image preview will appear on the left of the Settings window. To adjust the position of the image more precisely, click the drop-down menu and choose how exactly the picture will fill the background space. For instance, let’s choose “Cover” and click “Save” to see how the background has changed.

Mobile layout settings

By default, the Automatic Fill Layout Height checkbox is unchecked so that you can freely adjust the size of the widgets on your mobile device. If you tick this option, all the widgets on the Dashboard will fill in vertically in the space of the screen.

Mobile row height determines how tall you’d like your widgets to be on your mobile device. By default, the height is set to 70px, but you can make it smaller or larger. The minimum Mobile row height is 5px, the maximum is 200px.

Layouts

Layouts define how widgets are arranged on a Dashboard. To manage a layout, you should enter the Edit mode by clicking the “Pencil” icon at the lower right corner of the screen. As soon as you appear in the Edit mode, click the small button three-rectangles “Manage layouts” in the upper left corner of the Dashboard window. It opens the small window for layouts’ control.

The Main layout is the one which you’re managing now. Basically, it’s your dashboard. If you click the big blue square button named “Main”, the Layout settings window will open. The layouts’ settings are identical to the Capacity and the Background of the Dashboard settings.

If we tick the “Right” checkbox, we divide the Dashboard into two separate parts. For each part, we are able to configure their own settings and appearance.

Just to see how it can look like, let’s set up both layouts in completely different ways. On the screenshot, you can see how the settings differ from each other (it is just an example and definitely not a recommendation). After adjusting the settings, click the “Save” button in the Layouts window to see the changes.

States

The States feature exists to create a layered hierarchy in your Dashboard. To use States properly you need to assign a specific action to a widget that will help you fast “travel” among the required states. To do this, you should click the upper left button with two-layered squares “Manage dashboard states”. It will open the window with a dashboard state configuration.

Since you haven’t created any states yet, you have only your “Root state”, namely your Dashboard. Root state defines the main state of your hierarchy. After creating additional states. You easily can change a root state by clicking the “Pencil” icon (Edit dashboard state) and ticking the “Root state” checkbox.

To add a new state, you need to click the “+” button in the right upper of the window, it will open a small window for a creating of a new state. Give it a name, a State ID will form automatically according to the name, but you can change it.

Giving a corresponding action to a particular widget allows traveling between states. To add an action, you should click the “pencil” icon (Edit widget) at the upper right corner of the widget to enter the widget configuration field. There you need to navigate to the “Action” cell and click the “+” icon to add a new action. It will open the “Add action” window.

In our case, a Type should be “Navigate to new dashboard state”. After choosing this option, the line “Target dashboard state” will appear, where we have to choose a newly created state. When the configuration for a new state is done, click the “Save” button. The new state appears in the Action list. Click the orange tick mark at the upper right of the window to apply changes.

As we have chosen the “On row click” action, we need to click on the row of our widget to bring the action into effect. After clicking, we immediately transfer to the chosen state.

Export

In ThingsBoard Community Edition, a Dashboard export or an exporting of a specific widget is possible as a configuration file in JSON format. You can use this file to transfer your Dashboard or widget configuration to another instance.

Export dashboard

In the Dashboards section, find the dashboard you want to export from the list. Opposite the name of the dashboard in the list, click on the “Export dashboard” button. The configuration file in JSON format with all settings on the control panel will be saved on your PC.

You can do this directly from the Dashboard. Open the Dashboard and click the “Export dashboard” button in the upper right corner of the screen.

Export widget

To export the widget, you should go to a Dashboard, where the widget is located.
Then go to the “Edit mode” by clicking on the “Pencil” icon in the lower right corner. Now in the upper right corner of the needed widget, click the button “Export widget”. This action saves the configuration file of the JSON format with all the settings of a particular widget to your PC.

ThingsBoard Professional Edition export

In ThingsBoard Professional Edition, dashboard export is possible in several additional formats: PDF, PNG & JPEG. This is useful when you need to send the data displayed in your dashboard by email or print.