How to work with Widgets

Introduction #

All IoT dashboards are constructed using Controllino Cloud widgets that are displayed in Widget library. Each widget provides end-user functions such as data visualization, remote device control, alarms management and displaying other custom content.

Widget Types #

There are several types of widgets that Controllino Cloud offers.

Time series widgets #

Display data for a specific time window. The time window may be real-time (e.g., for the last 24 hours) or historical (January 2021). Examples of time series widgets are chart widgets. Obviously, time series widgets are designed to display time series and not attributes.

Latest values widgets #

These widgets display the latest values of a particular attribute or time series keys. For example the latest temperature or distance sensor reading.

Control widgets #

Control widgets enable you to send RPC commands to your devices. For example, control the temperature on a thermostat.

Alarm widgets #

These widgets display alarms that you have set up in the Controllino Cloud.

Static widgets #

If you just want to display some text or image information or similar, that doesn’t get data from anywhere, you can use static widgets.

Adding a widget to the dashboard #

If you want to add a widget to a dashboard, start by clicking the pencil icon in the bottom right corner of the screen to go do Edit mode. Then, follow these steps:

  1. Click on the “+” icon (“Add new widget”) in the bottom right corner of the screen. Click “Create new widget” to open the “widget selection” dialog box
  2. Select widget bundle, for instance, “Charts”
  3. To find the widget you want as quickly as possible, use the search bar by clicking a magnifying glass icon and inputting the name of the widget there. Select a widget, for example, “Timeseries Line Chart”, and click on it to open the “Add Widget” dialog box.

The anatomy of a widget #

A widget consists of the widget type, one or multiple data sources, basic and advanced settings, and actions that you can add.

Therefore, the “Add widget” dialog contains four tabs for defining a widget. 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.

Data #

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) the widget should use and what data keys to fetch for those entities.

For example, let’s configure a data source to fetch temperature and humidity values for all “Thermometer” devices that have model “Temp Sensor A”, and their battery level is less than 20 percent. We will use “Thermometer” alias and “Temp Sensor A Battery Low” filter configured in the previous paragraphs of this doc (see alias and filter correspondingly).

In the above example, “temperature” and “humidity” are two time series data keys. The data keys list for data source depends on the widget type:

  • Time series widgets allow choosing time series data keys in the data source and the time window
  • Latest values widgets allow choosing time series, attributes and entity fields
  • Static and Control widgets do not require a data source
  • Alarm widgets allow choosing all data keys: time series, attributes, entity and alarm fields. Additionally, you can configure time window and alarm filter.

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

Datasources #

Type #

Here you pick the type of your datasource. Details are explained below.

Entity #

The Entity 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 a dashboard and start by adding an entity alias:

Enter dashboard edit mode by clicking the pencil icon in the lower-right of the screen.

Click the “Entity alias” button on the toolbar, click “Add alias” in the lower-left corner of the Entity alias dialog box.

In the opened Add alias dialog, enter an alias name, select Entity type filter type, and choose an entity type (in the given example, use Device entity type). Click “Add”.

Save the created alias by clicking the “Save” button in the lower right corner of the dialog.

After adding an alias, you need to add a widget to display data:

Click the big sign in the middle of the screen “Add new widget”.

Select Cards widget bundle. For viewing a list of entities, the Entity table widget is most suitable, so select it.

Now, it is time to add a data source:

Select Entity type, choose the previously added entity alias. Click “Save” in the lower-left corner of the dialog window.

After customizing a data source, click “Add” in the lower-left corner of the Add widget dialog box.

Widget that displays all devices through entity data source has been added.

Function #

Function data source is used when you do not have any date, 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.

Firstly, to display data, you need to add a widget:

Click the big sign in the middle of the screen “Add new widget”.

Select Cards widget bundle. For viewing entities, the Entity table widget is most suitable, so select it.

Now, it is time to add a data source:

Select Entity type, choose the previously added entity alias. Click “Save” in the lower-left corner of the dialog window.

After customizing a data source, click “Add” in the lower-left corner of the Add widget dialog box.

By dint of the widget with the function data source, we know how specific widget displays data.

3. 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 Controllino Cloud 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:

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.

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

5. 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 StyleCopy to clipboard

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.

Widget style from the screen above:

{

  “border”: “3px solid #2E86C1”,

  “cursor”: “pointer”

}

Copy to clipboard

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:

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.

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.

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