Caution

This is the documentation for the current development branch of the CometVisu. It is possible that some of the described features are not yet available in the current release.

Also there might be lots of errors in this documentation as some parts of the content have been translated by an online translation service.

Chart

Description

The chart element allows the visualization of historical values as a diagram. For this, the chart element must contain at least one <dataset> child element. For each <dataset> a line is drawn in the chart.

<cv-widget size="2x1">
    <cv-tile>
        <cv-chart title="Living room" y-format="%.1f °C" series="day" refresh="300" colspan="3" rowspan="3">
            <dataset chart-type="line" src="openhab://Temperature_FF_Living"/>
        </cv-chart>
    </cv-tile>
</cv-widget>

The example shows the temperature curve of the last 24 hours, the exact, formatted temperature value for a point in the chart is displayed as a tooltip when hovering over the chart. In order for the chart to reach a certain size, a tile with double width <cv-tile size="2x1"> is used here and the chart itself should fill the entire tile <cv-chart ... colspan="3" rowspan="3">.

Configuring the data source

In the src attribute of the dataset element, a URL is specified that defines the data source. So far openHAB (Persistence), InfluxDB and RRD are supported as data sources.

configuring an openHAB-source

openhab://<Item-Name> where <Item-Name> can be any item name in openHAB for which historical data is recorded. It is also possible to specify a specific persistence service if you use multiple: openhab://<service-id>@<Item-Name>, if you do not specify this, the default persistence service configured in openHAB is used.

configuring einer InfluxDB-source

flux://<organization>@<bucket>/<measurement>/<field> Optional parameters for the aggregationWindow function can be added as query parameters. These require the prefix ag-. Example: flux://cometvisu@cv-bucket/Temperature/value?ag-every=1d&ag-fn=mean would send the following Flux query to the database:

from(bucket:"cv-bucket")
  |> range(start: <start-time>, stop: <end-time>)
  |> filter(fn: (r) => r._measurement == "Temperature" and r._field == "value")
  |> aggregateWindow(every: 1d, fn: mean)

If only ag-every is specified, “mean” is taken as the default value for ag-fn. If only ag-every is specified, the values are automatically determined based on the series used by the chart.

For more complex database queries, the code of the Flux query can also be specified directly as text content of the <dataset> element. In this case, only the organization and the note that the query was specified “inline” must be specified in the src attribute.

<dataset src="flux://openhab@inline">
    from(bucket:"openhab")
        |> range(start: -2d)
        |> filter(fn: (r) => r._measurement == "Counter" and r._field == "value")
        |> aggregateWindow(every: 1d, fn: last)
        |> difference()
</dataset>

With this query, the time range is set to the last 2 days (range(start: -2d)) and is therefore no longer variable and overwrites or deactivates the possibility to select other time series via selection. To use this feature, a placeholder must be inserted and the aggregateWindow must be omitted (this is automatically selected according to the selected time series). The upper query would look like this:

<dataset src="flux://openhab@inline">
    from(bucket:"openhab")
        |> range($$RANGE$$)
        |> filter(fn: (r) => r._measurement == "Counter" and r._field == "value")
        |> difference()
</dataset>

Hint

Since the CometVisu itself cannot check whether the Flux code is correct, it is recommended to compile the query in the UI of the InfluxDB and then copy the working code.

The URI of the InfluxDB server and a token for authenticating the requests must be specified in the hidden configurations under the section “influx”. The following key-value entries are required in this section.

Key	Value
uri	http://<influx-server>:8062
token	API Token (can be generated in the influxdb-UI)
config	flux

The values for “uri” and “token” must be adjusted accordingly, the value for “config” must be “flux” so that the communication can work correctly.

Configuring a RRD-source

rrd://<filename-without-rrd> For the RRD data source, the file name without the “.rrd” at the end must be specified. Additional query parameters can be added:

ds: Select one of the available Consolidation Functions of the RRDTools (http://rrdtool.org).
res: The default resolution for the data from the RRD file can be overridden with its own second value.

Example: rrd://<dateiname-ohne-rrd>?ds=AVERAGE&resolution=3600

More examples

It is also possible to display multiple lines in a chart and to color them differently.

<cv-widget size="2x1">
    <cv-tile>
        <cv-chart title="Power" y-format="%.1f kWh" series="month" refresh="300" colspan="3" rowspan="3" x-format="%d. %b">
            <dataset src="openhab://Meter_Energy_Grid_Import_Today" title="Grid withdrawal" color="#FF0000" show-area="false"/>
            <dataset src="openhab://PV_Energy_Today" color="#FF9900" title="Production"/>
          </cv-chart>
    </cv-tile>
</cv-widget>

The red line shows the daily withdrawal from the power grid in kWh and the orange area shows the daily PV production in kWh.

The chart element also offers the possibility to display a bar chart:

<cv-widget size="2x1">
    <cv-tile>
        <cv-chart title="Strom" y-format="%.1f kWh" series="month" refresh="300" colspan="3" rowspan="3" x-format="%d. %b">
            <dataset src="openhab://Meter_Energy_Grid_Import_Today" title="Grid withdrawal" color="#FF0000" show-area="false" chart-type="bar"/>
            <dataset src="openhab://PV_Energy_Today" color="#FF9900" title="Production" chart-type="bar"/>
          </cv-chart>
    </cv-tile>
</cv-widget>

If you want to switch to other time series and navigate within the currently selected one, you can unlock these with the selection attribute. This can be filled with a comma-separated list of allowed time series, or simply with all.

<cv-widget size="2x1">
    <cv-tile>
        <cv-chart title="Power" selection="week,month,year" y-format="%.1f kWh" series="month" refresh="300" colspan="3" rowspan="3" x-format="%d. %b">
            <dataset src="openhab://Meter_Energy_Grid_Import_Today" title="Grid withdrawal" color="#FF0000" show-area="false"/>
          </cv-chart>
    </cv-tile>
</cv-widget>

Allowed attributes

Element	Attribute
	Name	Content	Description
cv-chart	title	string	Title of the chart.
	y-format	string	Format of the y-axis.
	x-format	string	Format of the x-axis.
	series	hour, day, week, month or year	Time span of the data.
	selection	string	Type of the chart element.
	allow-fullscreen	true or false	Allows showing the chart in fullscreen size.
	show-x-axis	true or false	Show x-axis scale (default = true).
	show-y-axis	true or false	Show y-axis scale (default = true).
	refresh	decimal	Time interval in seconds this widget is being refreshed.
	show-grid	xy, x, y or false	Show grid lines.
	background	true or false	Show the chart in the background of a tile.
	min	decimal	Minimum value.
	max	decimal	Maximum value.
	visible-on	mobile or desktop	Controls this element’s visibility by screen size.
	class	string	Add this value to the CSS class so that it can be formatted by a user provided style sheet.
	style	string	Custom CSS style rules for this widget.

Allowed child elements and their attributes

Element	Attribute
Structure	Name	Content	Description
cv-chart dataset	src	anyURI	Data source for this chart element
	title	string	Title of the chart element.
	chart-type	line or bar	Type of the chart element.
	curve	linear, step or natural	Type of curve interpolation for line charts.
	color	string	Color of the chart element.
	show-area	true or false	Fill the area below a line diagram.
cv-chart dataset #text		string

Element	Attribute
Structure	Name	Content	Description
cv-chart h-line	src	string	Data source for this line
	value		Type of the chart element.
	format	string	Formatting of the value (printf syntax).
	color	string	Color of the line.
	show-value	true or false	Show value.
	value-color	string	Color of the value.