Stop the war

Support Ukraine
Try it now Pricing
Cloud
Community Edition Professional Edition Cloud Edge PE Edge IoT Gateway License Server Trendz Analytics Mobile Application PE Mobile Application
Documentation > Dashboards > Widgets > Widgets Library
Getting Started
Devices Library Guides API FAQ

On this page

Widgets Library

Introduction

All IoT Dashboards are constructed using ThingsBoard widgets defined in the Widget Library. Each widget provides end-user functionality such as data visualization, remote device control, alarm management and display of static custom HTML content.

Widget Types

According to the provided features, each widget definition represents a specific type of widget. There are five widget types:

image
.
image
.
image
.

Each widget type has its own specific data source configuration and the corresponding API widget. Each widget requires data sources to visualize data. Types of available data source depend on widget type of the widget:

  • Target device - this data source type is used in RPC. Basically, you need to specify the target device for the RPC widget;
  • Alarm source - this data source type is used in Alarm widgets. This data source requires the source entity to display related alarms and corresponding alarm fields;
  • Entity - this datasource type is used in both time-series and latest values widgets. Basically, you need to specify the target entity, and the time series key, or the attribute name;
  • Entities count - this data source type is used in latest values widgets. Basically, you need to specify the target entity.
  • Function - this data source type is used in both time series and latest values widgets for debugging. Basically, you can specify a javascript function that will simulate data from a device in order to set up visualization;

Latest values

Latest values widget type displays the latest values of a specific entity attribute or time series data point (for example, any Gauge Widget or Entities Table widget). This type of widgets uses values of entity attribute(s) or time series as a data source. Digital Gauge in example is displaying current temperature value.

image
This widget type uses values of entity time series as a data source.
image
Digital Gauge displaying current power value.

Time series

Time series widget type displays historical values for the selected period of time, or the latest values in the certain time window (for example, “Timeseries Line Chart” or “Timeseries Bar Chart”). This widget types uses only the values of entity time series as a data source. In order to specify the time frame of displayed values, Timewindow settings are used. The time window can be specified on the dashboard page or in the widget details. It can be either realtime - dynamically changed time frame for a certain latest interval, or history - fixed historical time frame. All these settings are part of Time series widget configuration. In the example, the “Timeseries Line Chart” displays speed value of device in real-time.

image
This widget type uses only the values of entity time series as a data source.
image
An example of time series widget is the "Timeseries Line Chart". It displays amperage values of devices in real-time.

RPC (Control widget)

Control widget allows sending RPC commands to devices, it handles and visualize reply from the device (for example, “Raspberry Pi GPIO Control”). RPC widgets are configured by specifying the target device as the target endpoint for RPC commands. In the example, the “Basic GPIO Control” widget sends GPIO switch commands and detects current GPIOs switch status.

image
RPC widgets are configured by specifying target device as target endpoint for RPC commands.
image
An example of RPC widget is “Basic GPIO Control”. It sends GPIO switch commands and detects current GPIOs switch status.

Alarm Widget

Alarm Widget type displays alarms related to the specified entity in the certain time window (for example, “Alarms table”). Alarm widget is configured by specifying an entity as the alarm source, and the corresponding alarm fields. As the Time series widgets, Alarm widgets have the timewindow configuration to specify the time frame of the displayed alarms.
In addition, the configuration contains “Alarm status”, “Alarms severity” and “Alarm type” parameters. “Alarm status” parameter specifies the status of alarms being fetched. “Alarms severity” controls alarms fetching frequency in seconds. “Alarm type” helps to identify the root cause of the alarm. For example, “HighTemperature” and “LowHumidity” are two different alarms. In the example, the “Alarms table” widget displays the latest alarm for the device in real-time.

image
Alarm widget is configured by specifying an entity as the alarm source, and the corresponding alarm fields.
image
An example of Alarm widget is the “Alarms table” widget that displays the latest alarm for the device in real-time.

Static

Static widget type displays static customizable HTML content (for example, “HTML card”). Static widgets don’t use any data sources and usually configured by specifying static HTML content and optionally CSS styles. An example of a Static widget is the “HTML card” that displays the specified HTML content.

image
Static widget type is configured by specifying static HTML content and optionally CSS styles.
image
An example of a Static widget is the “HTML card” that displays the specified HTML content.
An example of a CSS style function to adjust an HTML card style. 
1
2
3
4
5
6
7
8
9
10

.card {
font-weight: bold;
font-size: 32px;
color: #999;
width: 100%;
height: 100%;
display: flex;
align-items: center;
justify-content: center;
}
An example of an HTML code for specifying card content. 
1
2

<h1>Static widget title</h1>
<div class='card'>Your text here</div>

Widgets Library (Bundles)

Widgets are grouped into widget bundles according to their purposes. There are System-level and Tenant-level Widgets bundles. Initial ThingsBoard installation comes with a basic set of system-level Widgets bundles.
System level bundles can be managed by a System administrator and are available for use by any tenant in the system. Tenant level bundles can be managed by a Tenant administrator and are available for use only by this tenant and his customers. You can always implement and add your widgets by following this guide.

Alarm widgets

Alarm widgets bundle is useful for visualization alarms for specific entities, both in real-time and history modes.

image
For visualization of alarms for specific entities both in real-time and history mode.

Analog Gauges

Analog Gauges bundle is useful for visualization temperature, humidity, speed, and other integer or float values.

image
For visualization of temperature, humidity, speed and other integer or float values.

Cards

Cards bundle is useful for visualization time series data or attributes in table or card widgets.

image
For visualization of time series data or attributes in a table or card widgets.

Charts

Charts bundle is useful for visualization historical or real-time data with a time window.

image
For visualization of historical or real-time data with a time window.

Control widgets

Control widgets bundle is useful for visualization the current state and sending RPC commands to target devices.

image
For visualization of current state and sending RPC commands to target devices.

Date widgets

Date widgets bundle is useful for changing the data range for other widgets on the dashboard.

image
For changing the data range for other widgets on the dashboard.

Digital Gauges

Digital Gauges bundle is useful for visualization temperature, humidity, speed and other integer or float values.

image
For visualization of temperature, humidity, speed and other integer or float values.

Entity admin widgets

Entity admin widgets are templates of complex widgets that allow listing and creating/updating/deleting devices and assets.

image
For listing and creating/updating/deleting devices and assets.

Gateway widgets

Gateway widgets bundle is useful for managing extensions.

image
For managing extensions.

GPIO widgets

GPIO widgets bundle is useful for visualization and controlling GPIO state for target devices.

image
For visualization and control of GPIO state for target devices.

Input widgets

Input widgets bundle is useful for modifying the attributes of an entity.

image
For changing entity attributes.

Maps widgets

Map widgets bundle is useful for visualizing the geographic location of devices and tracking device routes in both real-time and history modes.

image
For visualization of devices geo locations and tracking devices routes both in real-time and history mode.

Navigation widgets bundle is useful to define home dashboard of the user.

image
For defining home dashboard of the user.

Scheduling widgets

Scheduling widgets bundle is useful for scheduling various types of events with flexible schedule configuration.
Available only in PE and PaaS.

image
For scheduling various types of events with flexible schedule configuration.

Adding widgets bundle

If the system administrator adds a new widgets bundle, it automatically becomes a system one. It means that only he can delete, edit and add widget types into the bundle. Tenant administrators can create widgets bundles as well. In this case, they have permissions to modify created bundles. You can always implement and add your widgets by following this guide.

To add a new widgets bundle, you should:

  • Navigate to the widgets bundle page via the main menu on the left. Click the "+" icon in the upper right of the screen, and select the "Create new widgets bundle" option from the drop-down menu.
  • In the opened dialog window, enter the name for the new bundle. Adding an image and a description is optional. Click "Add" to save applied changes.
  • Since widgets bundles are in alphabetical order, the newly created one may be on the second page.
  • After adding the widgets bundle, you can add widget types in there.
image
Navigate to the widgets bundle page via the main menu on the left. Click the "+" icon in the upper right of the screen, and select the "Create new widgets bundle" option from the drop-down menu.
image
In the opened dialog window, enter the name for the new bundle. Adding an image and a description is optional. Click "Add" to save applied changes.
image
Since widgets bundles are in alphabetical order, the newly created one may be on the second page.
image
After adding the widgets bundle, you can add widget types in there.

Widgets Bundles export/import

Widgets Bundle export

You can export a widgets bundle in JSON format, and import it in the same or different ThingsBoard instance.

In order to export widgets bundle, you should:

  • Go to the Widgets Library page and click the export button on the specific widgets bundle row.
image
Go to the Widgets Library page and click the export button on the specific widgets bundle row.

Widgets Bundle import

Importing a widgets bundle is very similar to exporting it. To import the widgets bundle, you should:

  • Go to the Widgets Library page, click the "+" button in the upper right corner of the "Widgets Bundles" page. Select "Import widgets bundle" from the drop-down menu.
  • The widgets bundle import window should a popup, and you will be prompted to upload the JSON file. Drag and drop a file from your computer, and click "Import" to add a widget bundle to the library.
image
Go to the Widgets Library page, click the "+" button in the upper right corner of the "Widgets Bundles" page. Select "Import widgets bundle" from the drop-down menu.
image
The widgets bundle import window should a popup, and you will be prompted to upload the JSON file. Drag and drop a file from your computer, and click "Import" to add a widget bundle to the library.

Widget Types export/import

You can export a specific type of widget from a widget bundle in JSON format, and import it in the same or different ThingsBoard instance.

Widget Type export

In order to export a widget type, you should:

  • Go to the Widgets Library page, then open the desired widgets bundle and click the export button on the particular widget type card.
image
Go to the Widgets Library page, then open the desired widgets bundle and click the export button on the particular widget type card.

Widget Type import

Please note that only system administrators can modify system (default) widget bundles. This means that only they can delete the system widget bundle, edit and delete widgets inside the bundle, add or import new widgets into the bundle. By creating a new widget bundle at the system administrator level, it will be displayed in the accounts of his tenants as a system one, and they will not be able to modify it.
Nevertheless, tenants can add their own widgets bundles. In this case, they have full rights to manage created widget types inside the bundle.

To import a widget type, you should:

  • Go to the Widgets Library page, open the widgets bundle and click the "+" button in the lower right corner of the screen.
  • Click the import button.
  • A popup will appear in the import widget type window, and you will be prompted to load the JSON file. Drag and drop a file from your computer and click "Import" to add a widget type to the bundle.
image
Go to the Widgets Library page, open the widgets bundle and click the "+" button in the lower right corner of the screen.
image
Click the import button.
image
A popup will appear in the import widget type window, and you will be prompted to load the JSON file. Drag and drop a file from your computer and click "Import" to add a widget type to the bundle.