Stand with Ukraine flag
Try it now Pricing
Cloud
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application MQTT Broker
North America
North America N. Virginia Europe Frankfurt
Documentation > Dashboards > Widgets > Overview
Getting Started
Devices Library Guides API FAQ
On this page

Working with widgets

Prerequisites

Before proceeding with this guide, it’s recommended that you follow Getting Started guide to become familiar with ThingsBoard dashboards and widgets. This will enhance your learning experience and understanding of the concepts presented here.

Introduction

All IoT dashboards are constructed using ThingsBoard widgets.

A widget is an element that displays a specific type of information or functionality on a dashboard. Widgets are used to display data and visualize information obtained from devices connected to the ThingsBoard platform, remote device control, alarms management, and display static custom HTML content.

Widget types

There are five types of widgets:

  • Timeseries widgets display data for a specific time window. It can be either Realtime - the dynamically changed time frame for a certain latest interval, or History - a fixed historical time frame.
    Examples of timeseries widgets are chart widgets. Obviously, timeseries widgets are designed to display time series and not attributes;
  • Latest values widgets display the latest values of particular attribute or time series keys. For example, device model or latest temperature reading;
  • Control widgets allow you to send RPC commands to your devices. For example, control desired temperature on the thermostat device;
  • Alarm widgets allow you to display alarms;
  • Static widgets are designed to display static data. For example, floor plan or static company information.

More about widget types you can learn here.

Each widget typically has specific settings and parameters that allow users to customize its behavior and appearance according to their needs.

This guide covers main concepts and various widget settings.

Adding a widget to the dashboard

To add a new widget to a dashboard, you should:

  • Open your dashboard and enter edit mode;
  • Click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the Select widgets bundle dialog window;
  • Select a widget bundle, such as "Charts". To quickly find your desired widget, use the search bar by clicking the magnifying glass icon and entering the widget's name;
  • Choose a widget, for instance, "Time series Line Chart" and click on it to open the "Add Widget" dialog window;
  • Specify the data source, add the data key, and click the "Add" button. Finally, apply your changes;
  • Your first widget has been created.
Open your dashboard and enter edit mode;
Open your dashboard and enter edit mode;
Click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the Select widgets bundle dialog window;
Click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the Select widgets bundle dialog window;
Select a widget bundle, such as "Charts". To quickly find your desired widget, use the search bar by clicking the magnifying glass icon and entering the widget's name;
Select a widget bundle, such as "Charts". To quickly find your desired widget, use the search bar by clicking the magnifying glass icon and entering the widget's name;
Choose a widget, for instance, "Time series Line Chart" and click on it to open the "Add Widget" dialog window;
Choose a widget, for instance, "Time series Line Chart" and click on it to open the "Add Widget" dialog window;
Specify the data source, add the data key, and click the "Add" button. Finally, apply your changes;
Specify the data source, add the data key, and click the "Add" button. Finally, apply your changes;
Your first widget has been created.
Your first widget has been created.

Widget settings

Widget settings consist of one or multiple data sources, appearance settings, widget card settings, actions, and mobile appearance that you can customize and perform on the widget’s content.

Doc info icon

Please note
that only the data source configuration is strictly required. You can leave all other configuration tabs with the default values in most of the cases.

During widget creation, you can choose between basic and advanced functionality. Switching between modes is done in the top right corner of the widget creation window.

Basic functionality

Basic functionality is suitable for a quick start when you are using a single data source type without additional conditions or filters. It includes settings for the timewindow, datasource selection (entity alias or device), and a basic set of settings for the appearance of widgets, which depends on the widget’s purpose.

If you are using basic features to create a widget, you need to select the datasource type (device or entity alias) and add the series key. Then click "Add".
If you are using basic features to create a widget, you need to select the datasource type (device or entity alias) and add the series key. Then click "Add".

Advanced functionality

In the advanced functionality, you can use multiple datasources (if supported by the widget), and apply filters, and it includes five tabs for more detailed widget configuration: Data, Appearance, Widget card, Actions, and Mobile.

Additionally, in the advanced functionality, there are additional datasource types available: Function, Entities count and Alarms count (these data types are not supported by all widgets).

Using advanced functionality to create a widget, you need to select multiple datasources (if supported by the widget) and apply filters. Then click "Add".
Using advanced functionality to create a widget, you need to select multiple datasources (if supported by the widget) and apply filters. Then click "Add".

Data settings

Widget time window

A widget timewindow 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 timewindow determined in the dashboard’s toolbar. You can overwrite the default timewindow by toggling the option to “Use widget timewindow” parameter. You can also hide the timewindow selection for a specific widget from the user using the “Display timewindow” checkbox.

By default, every widget uses the main timewindow determined in the dashboard's toolbar.
By default, every widget uses the main timewindow determined in the dashboard's toolbar.
Toggle the "Use widget timewindow" checkbox to overwrite the default timewindow.
Toggle the "Use widget timewindow" checkbox to overwrite the default timewindow.

Learn more about time window configuration here.

Data source types

Widget data settings are for adding one or multiple data sources. A data source is a combination of a data source type, an entity alias, an optional filter, and list of data keys (entity time series). Basically, the data source determines which entities (alias and filter) widget should use and what data keys to fetch for those entities.

There are three main types of data sources: Device, Entity, and Function.

Additionally, for some widgets (such as the Value card), there are additional data source types, such as Entities count and Alarms count.

Below, we will discuss each of these types.


Device as the datasource

Specifying a device as the data source retrieves data from the specified device.

Let’s assume you have a device that publishes indoor temperature values, and you want to display these data on a widget. Let’s visualize this data using the Thermometer scale widget.

  • Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
  • Select "Analogue gauge" widget bundle;
  • Then select a "Thermometer scale" widget;
  • The "Add Widget" dialog window will open. Select data source type - "Device" and select your device. Then add data key - "temperature". Click "Add" and save all changes;
  • Thermometer scale widget is created.
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Select "Analogue gauge" widget bundle;
Select "Analogue gauge" widget bundle;
Then select a "Thermometer scale" widget;
Then select a "Thermometer scale" widget;
The "Add Widget" dialog window will open. Select data source type - "Device" and select your device. Then add data key - "temperature". Click "Add" and save all changes;
The "Add Widget" dialog window will open. Select data source type - "Device" and select your device. Then add data key - "temperature". Click "Add" and save all changes;
Thermometer scale widget is created.
Thermometer scale widget is created.
Doc info icon

Please note
that in this case, the data source can only be a single device.

Entity as the datasource

Specifying an entity as a data source fetches data from specified entity alias.

Let’s get familiar with this feature using a basic example, displaying all existing devices on the widget.

  • Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
  • Select "Tables" widget bundle;
  • Then select an "Entities table" widget;
  • The "Add Widget" dialog window will open. Select data source type - "Entity". Now, we need to create a new entity alias. Click "Create new" button in the entity alias row;
  • In the opened Add alias dialog, enter an alias name, select filter type - "Entity type", and choose an entity type - "Device". Click "Add";
  • Add data keys. Then click "Add" and save all changes;
  • A widget has been added that displays all devices using an entity alias as the datasource.
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Select "Tables" widget bundle;
Select "Tables" widget bundle;
Then select an "Entities table" widget;
Then select an "Entities table" widget;
The "Add Widget" dialog window will open. Select data source type - "Entity". Now, we need to create a new entity alias. Click "Create new" button in the entity alias row;
The "Add Widget" dialog window will open. Select data source type - "Entity". Now, we need to create a new entity alias. Click "Create new" button in the entity alias row;
In the opened Add alias dialog, enter an alias name, select filter type - "Entity type", and choose an entity type - "Device". Click "Add";
In the opened Add alias dialog, enter an alias name, select filter type - "Entity type", and choose an entity type - "Device". Click "Add";
Add data keys. Then click "Add" and save all changes;
Add data keys. Then click "Add" and save all changes;
A widget has been added that displays all devices using an entity alias as the datasource.
A widget has been added that displays all devices using an entity alias as the datasource.


Function as the datasource

Function as a data source is used when you do not have any data, but you’d like to test a widget visualization. Let’s say you haven’t added alias and haven’t received any telemetry, but you want to see how a widget displays data.

  • Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
  • Select a "Cards" widget bundle;
  • Then select a "Value card" widget;
  • The "Add Widget" dialog window will open. Navigate to the advanced functionality and select data source type - "Random". Then add a function - "Random" and click the "pencil" icon of the "Random" key to open data key configuration window;
  • Change the label name to "temperature" and specify units. Click "Save";
  • Click "Add" and save all changes;
  • Created the value card widget which displays random value.
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Select a "Cards" widget bundle;
Select a "Cards" widget bundle;
Then select a "Value card" widget;
Then select a "Value card" widget;
The "Add Widget" dialog window will open. Navigate to the advanced functionality and select data source type - "Random". Then add a function - "Random" and click the "pencil" icon of the "Random" key to open data key configuration window;
The "Add Widget" dialog window will open. Navigate to the advanced functionality and select data source type - "Random". Then add a function - "Random" and click the "pencil" icon of the "Random" key to open data key configuration window;
Change the label name to "temperature" and specify units. Click "Save";
Change the label name to "temperature" and specify units. Click "Save";
Click "Add" and save all changes;
Click "Add" and save all changes;
Created the value card widget which displays random value.
Created the value card widget which displays random value.


Entities сount

The Entities сount allows you to see the number of entities by displaying them on a widget and thus determine the number of devices, assets, etc.

Let’s get familiar with this feature using a basic example, displaying the total number of existing devices on the widget.

  • Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
  • Select a "Cards" widget bundle;
  • Then select a "Value card" widget;
  • The "Add Widget" dialog window will open. Go to the advanced functionality and select data source type - "Entities count". Now, we need create new entity alias. Click "Create new" button in the entity alias row;
  • In the opened Add alias dialog, enter an alias name, select filter type - "Entity type", and choose an entity type - "Device". Click "Add";
  • In the Data key row click the "pencil" icon of the "count" key to open data key configuration window;
  • Change label name to "Devices count" and specify units. Click "Save";
  • Finally, click "Add" and save all changes;
  • Now we have a widget that displays the number of existing devices.
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Select a "Cards" widget bundle;
Select a "Cards" widget bundle;
Then select a "Value card" widget;
Then select a "Value card" widget;
The "Add Widget" dialog window will open. Go to the advanced functionality and select data source type - "Entities count". Now, we need create new entity alias. Click "Create new" button in the entity alias row;
The "Add Widget" dialog window will open. Go to the advanced functionality and select data source type - "Entities count". Now, we need create new entity alias. Click "Create new" button in the entity alias row;
In the opened Add alias dialog, enter an alias name, select filter type - "Entity type", and choose an entity type - "Device". Click "Add";
In the opened Add alias dialog, enter an alias name, select filter type - "Entity type", and choose an entity type - "Device". Click "Add";
In the Data key row click the "pencil" icon of the "count" key to open data key configuration window;
In the Data key row click the "pencil" icon of the "count" key to open data key configuration window;
Change label name to "Devices count" and specify units. Click "Save";
Change label name to "Devices count" and specify units. Click "Save";
Finally, click "Add" and save all changes;
Finally, click "Add" and save all changes;
Now we have a widget that displays the number of existing devices.
Now we have a widget that displays the number of existing devices.


Alarms count

The Alarms count allows you to display the total number of alarms from all your devices and devices of your customers on a widget.

Let’s get familiar with this feature using a basic example, displaying the total number of existing alarms on the widget.

  • Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
  • Select "Cards" widget bundle;
  • Then select a "Value card" widget;
  • The "Add Widget" dialog window will open. Go to the advanced functionality, select data source type - "Alarms count" and specify filters. In the Data key row click the "pencil" icon of the "count" key to open data key configuration window;
  • Change label name to "Alarms count" and specify units. Click "Save";
  • Finally, click "Add" and apply changes;
  • Now we have a widget that displays all alarms of existing devices.
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the "Widgets bundle” dialog window;
Select "Cards" widget bundle;
Select "Cards" widget bundle;
Then select a "Value card" widget;
Then select a "Value card" widget;
The "Add Widget" dialog window will open. Go to the advanced functionality, select data source type - "Alarms count" and specify filters. In the Data key row click the "pencil" icon of the "count" key to open data key configuration window;
The "Add Widget" dialog window will open. Go to the advanced functionality, select data source type - "Alarms count" and specify filters. In the Data key row click the "pencil" icon of the "count" key to open data key configuration window;
Change label name to "Alarms count" and specify units. Click "Save";
Change label name to "Alarms count" and specify units. Click "Save";
Finally, click "Add" and apply changes;
Finally, click "Add" and apply changes;
Now we have a widget that displays all alarms of existing devices.
Now we have a widget that displays all alarms of existing devices.

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.

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

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

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

  • Devices, assets and entity views have the following fields: create time, entity type, name, type, label, additional info.
  • User has the following fields: created time, first name, last name, email and additional info.
  • Customer has the following fields: create time, entity type, email, title, country, state, city, address, zip code, phone, additional info.

The data keys list for data source depends on the widget type:

  • Timeseries widgets allow choosing time series data keys. Additionally, you can configure timewindow;
  • Latest values widgets allow choosing time series, attributes and entity fields;
  • Static and Control widgets do not require a data key;
  • Alarm widgets allow choosing all data keys: time series, attributes, entity and alarm fields. Additionally, you can configure timewindow and alarm filter.

To add a time series or attribute key to the data source, click on the data keys row and select the desired key from the dropdown menu.

To add a key to the data source, click on the data keys row and select the desired key from the dropdown menu.
To add a key to the data source, click on the data keys row and select the desired key from the dropdown menu.

Let’s assume you don’t have the required time series or attribute key in the database yet. In such a case, you can still add a key to the data source, and the widget will start displaying the data as soon as the device will send it to ThingsBoard. To do this, click on the data key row, then enter the name and select the type of the future key: Attributes, Entity field, or Timeseries.

Within the Advanced widget settings, the data key can be configured in two distinct modes: General and Advanced. Both modes offer unique configuration options.

General data key configuration

The data key configuration varies based on the widget type and its accepted data type. In general settings, some widgets allow you to modify the key’s name and color, adjust the label name, add a specific character next to the value (exclusive to the Timeseries key), define decimal precision, and toggle the “Use post-processing function” on or off.

If you use the basic functionality for adding a new widget, these settings are available right in the widget creation window.

If you use the advanced functionality for adding a new widget, click the “pencil” icon of a key in the data keys row to open the full data key settings.

Basic data key configuration

Let’s look at the basic data key settings an example of the “Entities table” widget from the “Tables” bundle:

  • Key. You can change the name of the key. In this case, will be displayed data of the key, which key name you specify in the “Key” line. Change the name of the key and click “Save”.
Doc info icon

Please note:
There are four types of keys: Attributes, Time Series, Entity Field and Alarm Field (only for Alarm widget). To correctly display data, change the key name to the existing key name of the same type. If you don’t have the required time series or attribute key in the database yet, you can still add a key to the data source. The widget will start displaying the data as soon as the device will send it to ThingsBoard.

  • Label. In your widget, the name of the data column is the label name. Change the label name as desired and click “Save” in the lower right corner of the dialog window.
  • Units. You can indicate a special symbol that will be displayed next to the value. Enter the desired character in the units field and click “Save”.
  • Decimals. Specify the desired number of digits to be displayed after floating-point number and click “Save”.
  • Color. Each key is assigned a different color. In some widgets (for example, Chart), the color of the graph line displayed in the widget is the color of the key. You can change color of the key. Click on the colored circle, select the desired label color and press “Select”.
Click on the colored icon of the data key;
Click on the colored icon of the data key;
Select the desired label color and press "Select";
Select the desired label color and press "Select";
The label color is changed. Save all changes;
The label color is changed. Save all changes;
The graph line color is changed;
The graph line color is changed;

Aggregation of key

By default, the Latest values widgets do not have the time window. If you enable aggregation for any data key in the ‘Latest values’ widgets, the time window control will appear. You can set up aggregation for each telemetry key individually, which you want to display and at the same time do not need to store it in the database. The time window configuration is limited to the real-time intervals (Current Hour/Day/Month) and ‘History’ time intervals. The real-time intervals like ‘last 30 minutes’ or ‘last 24 hours’ are not supported for performance reasons. If you need to store the aggregation as telemetry, follow for more details at the link.

Aggregation options:

  • Min or Max:
    Selects the minimum or maximum value from the given interval. Using to detect peak negative or positive values. For example, power surges in the power cable, air pollution, equipment workload, etc.
  • Average:
    Calculates the average from the selected interval (Summarizes, then divides by the count of telemetry from the selected interval). For example, you can use average aggregation for weekly fuel consumption, acoustical noise in dB, rotation fan speed, signal quality, etc.
  • Sum:
    Summarizes all telemetry for the specified period. Aggregation, for example, uses for different types of telemetry, mileage (km), water consumption, idle time, etc.
  • Count:
    Calculates the total number of transmitted messages for the selected period. It can be useful in setting up and optimizing devices running on battery power or when evaluating sensor activation sensitivity, etc.

Delta function:

Allows you to calculate the delta between aggregated values for current and relative time window intervals.

Comparison period - is a parameter that takes the history interval as a basis and converts it according to the selected option. List of options below.

  • Previous interval (default) - set as a default option, when calculating, not only time is taken into account, but also the type of interval (Current day or Current day so far, etc.)
    Example: History - Current month so far option, suppose is interval 1.09.22 to 25.09.22 then previous interval will be 1.08.22 to 25.08.22
  • Day ago - from the start and end of the history interval, takes away 24 hours.
    For example, with the amount of water spent Current day and Delta - Day ago:
  • Week ago - takes interval one week earlier from history interval (168 hours).
    Example with average, history interval - Current day, and Week ago delta:
  • Month ago - The same interval (in days) as the history interval and subtracts from the current history interval. Example, if the current month is February (28 days) then Month ago would be the previous 28 days, not the entire previous month.
    Example, with sum water, history - Current day and Delta - Month ago:
  • Year ago - Interval that was 365 days ago from the current history interval.
    If it is necessary to compare, suppose the aggregation for the previous month and the month of the past year.
  • Custom interval - This option is for setting individual intervals. The maximum allowed value is limited to the int type. Example: 43200000 = 12 hours.

Delta calculation result:

This option allows you to specify how the result should be displayed:

  • Previous Value - Displays aggregation value of compare interval (not current history interval).

  • Delta (absolute) - Displays the difference between compared intervals, this option is set by default.

  • Delta (percent) - Displays the result as a percentage relative to the previous interval
    formula: (IntervalValue - prevIntervalValue)/prevIntervalValue*100

Use data post-processing function. The data post-processing function allows changing the output data depending on your wishes. To use data post-processing function, you must check the “Use data post-processing function” checkbox and enter the function in the field below. Then click the “Save” button in the lower-right corner.

Advanced data key settings

Advanced data keys configuration is responsible for the visibility, style, and appearance of a specific data key column on the widget. Entity table widget, alarms table widget, and entity admin widget bundles have the same advanced data key configuration. Charts widget bundle has its own unique advanced data key configuration. All other widget bundles have only basic data key configuration.

Learn more about advanced data key settings here.

Alarm filter

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.

Filter alarms by status, severity and type.
Filter alarms by status, severity and type.

Appearance

Let’s assume you have added the “Timeseries Line Chart” 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):

image

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

Data 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 axes. 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.

You can also specify an alternative message that will be displayed if widget doesn’t have incoming data. When data arrives, the message will disappear and the incoming data will be displayed.

You can find these settings in the “Advanced” functionality, “Appearance” tab of the widgets settings.

You can choose which symbol to display next to the value and the number of digits after the floating-point number;
You can choose which symbol to display next to the value and the number of digits after the floating-point number;

Common settings

Stacking mode

This option is relevant to the “Timeseries Bar Chart” widget. The Stacking mode function displays the summed entity values to prevent overlap, with each value distinguished by a unique color. This function can be used only if the data aggregation function is not set to None. Without activating the “Enable stacking mode”, the bars will be split according to the values of the entities used. To view the values of all entities, you need to hover your mouse over the bar.

In the upper right corner of the screen, click on the Time window configuration and choose any preferred Data aggregation function other than None. Click "Update" to apply changes;
In the upper right corner of the screen, click on the Time window configuration and choose any preferred Data aggregation function other than None. Click "Update" to apply changes;
In the widget settings, on the "Appearance" tab, toggle "Enable stacking mode" checkbox and apply changes;
In the widget settings, on the "Appearance" tab, toggle "Enable stacking mode" checkbox and apply changes;
To view the values of all entities, you need to hover your mouse over the bar.
To view the values of all entities, you need to hover your mouse over the bar.

If you need to exclude a specific key from stacking, go to the advanced data key configuration, and check the “Exclude from stacking” checkbox.

If you need to exclude a specific key from stacking, go to the advanced configuration of that data key;
If you need to exclude a specific key from stacking, go to the advanced configuration of that data key;
Check the "Exclude from stacking" checkbox. Apply changes.
Check the "Exclude from stacking" checkbox. Apply changes.
Hover the mouse over a bar to see values of all entities.
Hover the mouse over a bar to see values of all entities.

Legend settings

By default, the “Display legend” option is enabled for chart widgets. This legend displays statistical values, including min, max, average, and total. In contrast, other widgets do not have this option enabled.

While the legend is enabled, you have the flexibility to:

  • Choose the legend’s direction and position;
  • Select which data values to include (min, max, average, total);
  • Select to sort the data keys or keep them unsorted.
The legend is used to display the min/max/average/total/latest values;
The legend is used to display the min/max/average/total/latest values;

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.

Use "${entity Name}" to take the entity name from the device.
Use "${entity Name}" to take the entity name from the device.

Axis settings

Configure the preferred axis parameters.

Specify the titles of the vertical and horizontal axes, and set the minimum and maximum scale values.

You can also set the ticks color, the number of decimal places, and step size between ticks.

Vertical axis settings:

Set the minimum and maximum scale values. Also, you can specify the vertical axis title, set the ticks color, decimals and step size between ticks of the vertical axis.
Set the minimum and maximum scale values. Also, you can specify the vertical axis title, set the ticks color, decimals and step size between ticks of the vertical axis.

Horizontal axis settings:

You can specify the title of the horizontal axis and set the ticks color.
You can specify the title of the horizontal axis and set the ticks color.

Ticks formatter function, f(value)

Let’s say we have telemetry which takes values of very large numbers, especially when there is a special symbol near values. However, we need to build a small graph (since we don’t have a lot of free space on the dashboard). Therefore, using the ticks-formatter function, we can convert the ticks values to a more compact form.

1

return value.toExponential(1) + " C";
In the "Appearance" tab, in the Ticks formatter function field, enter the custom function and apply changes.
In the "Appearance" tab, in the Ticks formatter function field, enter the custom function and apply changes.
The function has been applied and values became more compact. By hovering the mouse over a widget you can see the tooltip with not reduced values.
The function has been applied and values became more compact. By hovering the mouse over a widget you can see the tooltip with not reduced values.

Chart background settings

You can change the appearance of the chart grid: customize the color of the background, the grid frame and its ticks, and turn off lines visibility.

Configure preferred grid settings and apply changes;
Configure preferred grid settings and apply changes;

Tooltip settings

  • Hover individual points. When the box “Hover individual points” is checked, you won’t see value points on the lines.

  • Show cumulative values in stacking mode. While stacking mode is on, you can check the box “Cumulative values” to enable your chart to display sum of all entity values.

Tooltip value format function, f(value, latestData) is used when you want to manually customize the tooltip.

You can customize the values that will be displayed in the tooltip via tooltip settings or Advanced Data key configuration. Tooltip configuration via Settings is basic and applied to all entities at the same time. When configured in the Advanced Data key configuration, it is applied only to the specific time series data, and the basic tooltip function will be overwritten by this configuration.

In State Chart, you can configure entity states to be shown on a tooltip depending on entity values.

Let’s use the function to convert values from Celsius to Fahrenheit and display these values side by side:

1
2
3

let celsiusValue = parseFloat(value).toFixed(2);
let farenheitValue = parseFloat(celsiusValue*1.8 + 32).toFixed(2);
return celsiusValue + ' °C (' + farenheitValue + ' °F)';
  • In the Tooltip value format function field, enter your tooltip function, then apply changes;
  • Hover with your mouse over the widget to see tooltip with applied value format function.
In the Tooltip value format function field, enter your tooltip function, then apply changes;
In the Tooltip value format function field, enter your tooltip function, then apply changes;
Hover with your mouse over the widget to see tooltip with applied value format function.
Hover with your mouse over the widget to see tooltip with applied value format function.

Comparison settings

You can show historical data with which to compare.

  • In the "Appearance" tab, toggle the "Enable comparison" checkbox and from the drop-down menu select time to show historical data with which to compare. In the "Comparison X axis settings" section, select axis position, where the compared axis will be located on the widget. Also, you can enter the axis title and show axis tick labels;
  • Navigate to the "Data" tab and click the “pencil” icon of a key in the data keys row;
  • In the data key configuration window, navigate to the "Advanced" tab and choose the comparison line color. When you are done with Comparison Settings configuration, then apply changes;
  • Since comparison settings work only in history time window mode, click "Edit time window" icon in the dashboard toolbar, go to the "History" tab, and select the time interval with which you want to compare the current data. Then click "Update" to apply;
  • Now you can compare the value for the current minute and the five minutes ago.
In the "Appearance" tab, toggle the "Enable comparison" checkbox and from the drop-down menu select time to show historical data with which to compare. In the "Comparison X axis settings" section, select axis position, where the compared axis will be located on the widget. Also, you can enter the axis title and show axis tick labels;
In the "Appearance" tab, toggle the "Enable comparison" checkbox and from the drop-down menu select time to show historical data with which to compare. In the "Comparison X axis settings" section, select axis position, where the compared axis will be located on the widget. Also, you can enter the axis title and show axis tick labels;
Navigate to the "Data" tab and click the “pencil” icon of a key in the data keys row;
Navigate to the "Data" tab and click the “pencil” icon of a key in the data keys row;
In the data key configuration window, navigate to the "Advanced" tab and choose the comparison line color. When you are done with Comparison Settings configuration, then apply changes;
In the data key configuration window, navigate to the "Advanced" tab and choose the comparison line color. When you are done with Comparison Settings configuration, then apply changes;
Since comparison settings work only in history time window mode, click "Edit time window" icon in the dashboard toolbar, go to the "History" tab, and select the time interval with which you want to compare the current data. Then click "Update" to apply;
Since comparison settings work only in history time window mode, click "Edit time window" icon in the dashboard toolbar, go to the "History" tab, and select the time interval with which you want to compare the current data. Then click "Update" to apply;
Now you can compare the value for the current minute and the five minutes ago.
Now you can compare the value for the current minute and the five minutes ago.

Custom legend settings

Use Custom Legend Settings when you need to showcase data that isn’t suitable for chart representation, such as specific attributes, or when you want to display only certain time series in the Chart legend. For instance, consider active/inactive attributes that can be displayed in a Table widget but not on a Chart.

  • Navigate to the "Appearance" tab. Activate the "Enable custom legend" option to use attribute or time series values as key labels. Click on "+ Add new key". In the drop-down menu that appears, input the key name and choose the key type;
  • Proceed to the "Data" tab. Click the pencil icon next to a data key to access the Data key configuration window;
  • In the label line, input the pattern ${} and place the data key name within the brackets. Click "Save" to set the new label name and apply all changes;
  • Now, when you view the widget, you'll see that the custom legend settings have been applied.
Navigate to the "Appearance" tab. Activate the "Enable custom legend" option to use attribute or time series values as key labels. Click on "+ Add new key". In the drop-down menu that appears, input the key name and choose the key type;
Navigate to the "Appearance" tab. Activate the "Enable custom legend" option to use attribute or time series values as key labels. Click on "+ Add new key". In the drop-down menu that appears, input the key name and choose the key type;
Proceed to the "Data" tab. Click the pencil icon next to a data key to access the Data key configuration window;
Proceed to the "Data" tab. Click the pencil icon next to a data key to access the Data key configuration window;
In the label line, input the pattern ${} and place the data key name within the brackets. Click "Save" to set the new label name and apply all changes;
In the label line, input the pattern ${} and place the data key name within the brackets. Click "Save" to set the new label name and apply all changes;
Now, when you view the widget, you'll see that the custom legend settings have been applied.
Now, when you view the widget, you'll see that the custom legend settings have been applied.

Widget card

Widget title settings

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.

Edit widget title settings and apply changes;
Edit widget title settings and apply changes;
The title style have been changed.
The title style have been changed.

Title style from the screen above:

1
2
3
4

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

Widget style settings

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 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.

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.

Customize the widget style and apply changes;
Customize the widget style and apply changes;
The widget style has been changed.
The widget style has been changed.

Widget style from the screen above:

1
2
3
4

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

Widget buttons settings

Enable data export

The “Enable data export” button is responsible for enabling/disabling the ability to export data that is displayed in the widget. By default, data export is enabled. To download data, click on the “Export widget data” icon at the top right of the widget. You can export the data in csv, xls or xlsx format.

By default, data export is enabled.
By default, data export is enabled.
To download widget data, click on the “Export widget data” icon at the top right of the widget. You can export the data in csv, xls or xlsx format.
To download widget data, click on the “Export widget data” icon at the top right of the widget. You can export the data in csv, xls or xlsx format.
You can disable the ability to export data.
You can disable the ability to export data.

Enable fullscreen

You may disable fullscreen using the “Enable fullscreen” checkbox. This setting is enabled by default.

All those settings are enabled by default.

By default, fullscreen is enabled.
By default, fullscreen is enabled.
To expand widget to fullscreen, click on the “Expand to fullscreen” icon at the top right of the widget.
To expand widget to fullscreen, click on the “Expand to fullscreen” icon at the top right of the widget.
You can disable the ability to expand widget to fullscreen.
You can disable the ability to expand widget to fullscreen.

Widget actions

Actions allow quickly and easily configuring the transition to the created state, transferring to other dashboards, or even updating the dashboard you are in. Depending on the widget, the action sources differ. However, the type of action you are able to choose will be the same for all widgets. Actions are adjusted in the Edit mode of the needed widget. To fully understand how to use Actions, you have to add a State to your widget.

Read more about widget actions in the documentation dedicated to it.

Mobile mode settings

With mobile mode settings, you can optimize the widget for easy viewing on mobile devices.

Additionally, you can hide/show the widget in mobile mode or desktop mode.

Mobile Mode settings consist of two options:

  • Order - set to an integer, specifies the priority of the order of displaying widgets in mobile mode (note that in mobile mode all widgets are displayed in one vertical column). If you need to arrange widgets in this column in a custom order, you can configure different order values for each widget.
  • Height - takes an integer value from 1 to 10. It sets the height of the widget in Mobile Mode in the range from 70px (1) to 700px (10), ignoring its original height. For example, with a value of 5, the widget height will be 350px. (70 * 5) If no value is specified, its original height will be used.

Import and Export widget

Import widget

You can import a widget from a JSON file.

To import a widget, you should:

  • Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the Select widgets bundle dialog window;
  • Click the "Import widget" button in the upper right corner of the screen;
  • In the widget import window, upload the JSON file and click "Import";
  • The widget has been imported. However, the widget does not yet display data because the data source is not specified. Enter Edit widget mode to specify the data source;
  • Specify data source, add the data key(s), and apply changes;
  • You should now see the data in the widget. In our case, this is a temperature graph. After all the settings, save the dashboard.
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the Select widgets bundle dialog window;
Open your dashboard and enter edit mode. Then click the "+ Add widget" icon at the top of the screen, or (if this is your first widget on this dashboard) click a large "Add new widget" sign in the middle of the screen to open the Select widgets bundle dialog window;
Click the "Import widget" button in the upper right corner of the screen;
Click the "Import widget" button in the upper right corner of the screen;
In the widget import window, upload the JSON file and click "Import";
In the widget import window, upload the JSON file and click "Import";
The widget has been imported. However, the widget does not yet display data because the data source is not specified. Enter Edit widget mode to specify the data source;
The widget has been imported. However, the widget does not yet display data because the data source is not specified. Enter Edit widget mode to specify the data source;
Specify data source, add the data key(s), and apply changes;
Specify data source, add the data key(s), and apply changes;
You should now see the data in the widget. In our case, this is a temperature graph. After all the settings, save the dashboard.
You should now see the data in the widget. In our case, this is a temperature graph. After all the settings, save the dashboard.

Export widget

To export a widget, you should go to a dashboard, where a widget is located.
Then go to the “Edit mode”. 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.

To export a widget, enter “Edit mode”. 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.
To export a widget, enter “Edit mode”. 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.

Next steps