Data points charting widget

⚠️ This project is no longer under development. Please use cumulocity-datapoints-charting-widget-plugin for Application Builder >=2.x.x and Cumulocity >=1016.x.x⚠️

The Data Points Charting Widget allows you to create real time graphs showing customizable amounts of data from one or more devices.

Features

Chart Types

The widget currently supports the following chart types

line and spline
- supporting multiple plots on the same graph
bar & horizontal bar
- supporting stacked
pie & doughnut
- aggregated by time or value range buckets
radar
scatter and bubble
There will be more added in the future depending on demand (E.G histogram)_

Customization

Selected data ranges configurable (# of measurements, time range)
precision of data configurable
Choose which Axes are displayed and scaled
Show Aggregate data (Moving average, Bollinger Bands, or both)
Choose colours for plotted data, data point visibility
configurable legend
show and hide data by clicking legend items, tool tips
configurable label format for times

Installation

Runtime Widget Deployment?

This widget supports runtime deployment. Download the Runtime Binary.

User guide

This guide will teach you how to add the widget in your existing or new dashboard.

NOTE: This guide assumes that you have followed the installation instructions

Open the Application Builder application from the app switcher (Next to your username in the top right)
Add a new dashboard or navigate to an existing dashboard
Click Add Widget
Search for Data Points Charting
See below for the configuration options

The widget configuration page contains a number of configuration attributes.

Title : Enter the title which will display at the top of your widget

Device and Measurement Configuration section

Device : Select one or more devices, once you do you will then be able to select measurements. Deselect options in the dropdown or click the 'x' to remove them.
- The list contains devices, as well as groups defined in the cumulocity application.
- When choosing a group (Such as Laboratory in the picture below) The measurements will be labeled to indicate that they are part of that group.

You will now be able to choose to plot an extra series for the group by checking a box shown at the top of the list in the config

Measurement : Select the measurement fragment and series from the dropdown. You can deselect them in a similar way to the devices.
- define the range of data points to use by changing the Amount, Unit
- define the accuracy and display of data values by changing the number of decimal points to show.
Group measurements within time unit: This allows you to show raw data, or average or sum measurements them when received within the unit of the range you chose (E.G average values by minute).
- The time unit you chose for the range will determine how the measurements are grouped. The sum measurements in group checkbox will change from the default of averaging to summing the values.
- This can be disabled in certain circumstances (See 'Plotting one series against another below')
Clear Measurement Cache: We store data for charts within the browser so that if you choose a large volume of historic data we can avoid the delay of retrieving it every time you load the chart. This button will clear ALL data for all the charts.
Global Chart Options : Here you can choose things like chart type and display options for axes and the legend. Note the global section will only appear once you have selected the devices and measurements.

NOTE: Once the Target Assets or Devices and Measurement information has been populated, you can click the 'Save' button to configure the widget with the default settings

Series Settings : Below the global settings you will see a row for each measurement series you selected. By clicking on the row you will expand options that can be set per series. Depending on the chart type there may be further options which can be exposed by clicking the show advanced options checkbox.

Change the series display name (reflected in the legend)
Change the series plot colour.
Currently the line chart has advanced options

hide measurements will hide the plot of the source data
choose an option from the display aggregate drop down to show the colour and averaging period (number of measurements)
display aggregate allows you to choose to plot a moving average and/or Bollinger Bands

Pie & Doughnut Charts

When plotting a single series you have the option of choosing a pie or doughnut chart. If you do then you need to aggregate or bucket the data to allow it to be displayed.

After choosing your series, change the chart type to pie or doughnut
The Amount of data chosen and it's unit will determine the time buckets (categories) in the chart.
The following is a pie chart showing counts of measurements within time periods

We can also create a chart showing the number of measurements within value ranges
- These are defined in the config
The number of buckets will determine the bucket ranges when aggregating by value.

Plotting one series against another

The example shown here is a plot of the PH measured against a measure of PO4 (Phosphate) in a boiler. The relationship in this made up example is linear and so we should see a straight line when they are plotted against each other.

It is important to make sure that the data you wish to plot is related in some way, and that the measurements will arrive approximately at the same time.

After choosing your series, check the Plot data points from one series against another
This will change the display so you can choose the x and y of the chart.
Select the color and tolerance of what time stamps should match.

When you choose the 2 series and decide to plot them against each other the configuration will automatically switch on the "group measurements" option.

It will be disabled so that it cannot be turned off.

The above chart is a basic line chart, but you can use the ability to plot data against another series in other types:

radar
scatter
bubble (x,y,r) r = diameter of plotted point

Build Instructions

Note: It is only necessary to follow these instructions if you are modifying/extending this widget, otherwise see the Installation Guide.

Requirements:

Git
NodeJS (release builds are currently built with v12.19.0)
NPM (Included with NodeJS)

Instructions

Clone the repository:


git clone https://github.com/SoftwareAG/cumulocity-datapoints-charting-widget.git

Change directory:


cd cumulocity-datapoints-charting-widget

(Optional) Checkout a specific version:
```
git checkout <your version>
```
Install the dependencies:
```
npm install
```
(Optional) Local development server:
```
npm run start
```
Build the app:
```
npm run build
```
Deploy the app:
```
npm run deploy
```
Run gulp command to create a binary file under dist folder. Run npm install -g gulp to install gulp if not already:
```
npm run gulp
```

These tools are provided as-is and without warranty or support. They do not constitute part of the Software AG product suite. Users are free to use, fork and modify them, subject to the license agreement. While Software AG welcomes contributions, we cannot guarantee to include every contribution in the master project.

For more information you can Ask a Question in the Tech Community Forums.

You can find additional information in the Software AG Tech Community.