Vorsicht

Dies ist die Dokumentation des aktuellen Entwicklungszweigs der CometVisu. Es besteht daher die Möglichkeit, dass einige der hier beschriebenen Features mit dem aktuellsten Release der CometVisu nicht genutzt werden können.

Chart

Beschreibung

Das Chart-Element ermöglicht die Visualisierung von historischen Werten als Diagramm. Dazu muss das Chart-Element mindestens ein <dataset> Kind-Element enthalten. Für jedes <dataset> wird in dem Chart z.B. eine Linie eingezeichnet.

<cv-widget size="2x1">
    <cv-tile>
        <cv-chart title="Wohnzimmer" 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>

Das Beispiel zeigt den Temperaturverlauf der letzten 24 Stunden, der exakte, formatierte Temperaturwert für einen Zeitpunkt im Chart wird als Tooltip angezeigt, wenn man mit dem Mauszeiger über den Chart fährt. Damit der Chart eine gewisse Größe erreicht wird hier eine Kachel mit doppelter Breite <cv-tile size="2x1"> benutzt und der Chart selbst soll die gesamte Kachel ausfüllen <cv-chart ... colspan="3" rowspan="3">.

Konfiguration der Datenquelle

Im src-Attribute des dataset-Elements wird eine URL angegeben die die Datenquelle definiert. Bisher werden openHAB (Persistence), InfluxDB und RRD als Datenquellen unterstützt.

Konfiguration einer openHAB-Quelle

openhab://<Item-Name> wobei <Item-Name> ein beliebiger Item-Name in openHAB sein kann, für den historische Daten aufgezeichnet werden. Es ist zusätzlich möglich einen spezielle Persistence-Service anzugeben, falls man mehrere benutzt: openhab://<service-id>@<Item-Name>, gibt man diesen nicht an wird der in openHAB konfigurierte default-Persistence Service benutzt.

Konfiguration einer InfluxDB-Quelle

flux://<organization>@<bucket>/<measurement>/<field> Optional können Angaben für die aggregationWindow-Funktion als Query-Parameter angehängt werden. Diese benötigen den Präfix ag-. Beispiel: flux://cometvisu@cv-bucket/Temperature/value?ag-every=1d&ag-fn=mean würde in folgende Flux-Query an die Datenbank geschickt:

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

Wird nur ag-every angegeben, dann wird „mean“ als Standard-Wert für ag-fn genommen. Wird beides nicht angeben, werden die Werte anhand der vom Chart benutzen series automatisch bestimmt.

Für komplexere Datenbankanfragen kann auch direkt der Code der Flux-Query als Text-Inhalt des <dataset>-Elements angegeben werden. Im src-Attribute muss dann lediglich noch die Organisation und der Hinweis, dass die Query „inline“ angegeben wurde angegeben werden.

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

Mit dieser Anfrage wird der Zeitbereich allerdings auf die letzten 2 Tage (range(start: -2d)) festgelegt und ist somit nicht mehr variabel und überschreibt bzw. deaktiviert die Möglichkeit per selection andere Zeitserien auswählen zu können. Um dieses Feature nutzen zu können muss man einen Platzhalter einfügen und auch das aggregateWindow weglassen (dieses wird automatisch passend zu ausgewählten Zeitserie gewählt). Die obere Anfrage würde also so aussehen:

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

Hinweis

Da die CometVisu selbst nicht prüfen kann, ob der Flux-Code korrekt ist, empfiehlt es sich die Query in der UI der InfluxDB zusammenzustellen und den funktionieren Code dann zu kopieren.

Die URI des InfluxDB-Servers und ein Token für die Authentifizierung der Anfragen müssen in der Versteckten Konfigurationen unter der Sektion „influx“ angegeben werden. In dieser Sektion sind folgende Schlüssel-Wert Einträge erforderlich.

Schlüssel	Wert
uri	http://<influx-server>:8062
token	API Token (kann in der Influx-UI generiert werden)
config	flux

Die Werte für „uri“ und „token“ müssen entsprechend angepasst werden, der Wert für „config“ muss „flux“ sind damit die Kommunikation korrekt funktionieren kann.

Konfiguration einer RRD-Quelle

rrd://<dateiname-ohne-rrd> Für die RRD-Datenquelle muss der Dateiname ohne das „.rrd“ am Ende angegeben werden. Zusätzlich können als Query-Parameter hinzugefügt werden:

ds: Auswählen einer der verfügbaren Consolidation Functions des RRDTools (http://rrdtool.org).
res: Die Standard-Auflösung für die Daten aus der RRD-Datei kann überschrieben werden mit einem eigenen Sekunden-Wert.

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

Weitere Beispiele

Es ist auch möglich mehrere Linien in einem Chart darzustellen und diese farblich von einander abzugrenzen.

<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="Netzbezug" color="#FF0000" show-area="false"/>
            <dataset src="openhab://PV_Energy_Today" color="#FF9900" title="Produktion"/>
          </cv-chart>
    </cv-tile>
</cv-widget>

Die rote Linie zeigt den täglichen Bezug aus dem Stromnetz in kWh und der orange Bereich stellt dem die täglich PV-Produktion in kWh gegenüber.

Das Chart-Element bietet auch die Möglichkeit ein Balkendiagramm darzustellen:

<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="Netzbezug" color="#FF0000" show-area="false" chart-type="bar"/>
            <dataset src="openhab://PV_Energy_Today" color="#FF9900" title="Produktion" chart-type="bar"/>
          </cv-chart>
    </cv-tile>
</cv-widget>

Möchte man auf andere Zeitserien wechseln und innerhalb der gerade ausgewählten navigieren, so kann man diese mit dem selection-Attribut freischalten. Dieses kann man mit einer Komma-separierten Listen der erlaubten Zeitserien füllen, oder einfach mit all for alle.

<cv-widget size="2x1">
    <cv-tile>
        <cv-chart title="Strom" 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="Netzbezug" color="#FF0000" show-area="false"/>
          </cv-chart>
    </cv-tile>
</cv-widget>

Erlaubte Attribute

Element	Attribut
	Name	Inhalt	Beschreibung
cv-chart	title	Text	Titel des Charts.
	y-format	Text	Formatierung der y-Achse.
	x-format	Text	Formatierung der x-Achse.
	series	hour, day, week, month oder year	Zeitspanne der Daten.
	selection	Text	Typ des Chart-Elements.
	allow-fullscreen	true oder false	Erlaubt die Vergrößerung des Charts auf volle Bildschirmgröße.
	show-x-axis	true oder false	X-Achsen Skala anzeigen (default = true).
	show-y-axis	true oder false	Y-Achsen Skala anzeigen (default = true).
	refresh	Zahl	Zeitintervall in Sekunden in dem dieses Widget aktualisiert wird.
	show-grid	xy, x, y oder false	Zeige Gitterlinien.
	background	true oder false	Zeigt den Chart im Hintergrund einer Kachel.
	min	Zahl	Minimaler Wert.
	max	Zahl	Maximaler Wert.
	visible-on	mobile oder desktop	Steuert die Sichtbarkeit dieses Elements anhand der Bildschirmgröße.
	class	Text	Füge dieses Attribut der CSS Klasse hinzu, so dass das Widget durch ein eigenes Stylesheet zusätzlich formatiert werden kann.
	style	Text	Individuelle CSS style Regeln für dieses Widget.

Erlaubte Kind-Elemente und deren Attribute

Element	Attribut
Struktur	Name	Inhalt	Beschreibung
cv-chart dataset	src	anyURI	Datenquelle für dieses Chart-Element.
	title	Text	Titel des Chart-Elements.
	chart-type	line oder bar	Typ des Chart-Elements.
	curve	linear, step oder natural	Typ der Kurven-Interpolation eines Linien-Charts.
	color	Text	Farbe des Chart-Elements.
	show-area	true oder false	Bereich unterhalb eines Liniendiagramms ausfüllen.
cv-chart dataset #text		Text

Element	Attribut
Struktur	Name	Inhalt	Beschreibung
cv-chart h-line	src	Text	Datenquelle für diese Linie
	value		Typ des Chart-Elements.
	format	Text	Formatierung des Wertes (printf-Syntax).
	color	Text	Farbe der Linie.
	show-value	true oder false	Wert anzeigen
	value-color	Text	Farbe des Werts.