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.

Adressen - die Kommunikation mit dem Backend

Autor: Tobias Bräutigam

Verfügbar seit: 2022

Die meisten Widgets verwenden ein oder mehrere cv-address Elemente für die Kommunikation mit dem Backend, welches darüber die entsprechenden Informationen vom KNX-Bus, OpenHAB oder MQTT bereitstellt. Der Inhalt ist die Adresse selbst, über die Attribute lässt sich das Verhalten des Widgets im Bezug auf die Adresse einstellen:

Element	Attribut
	Name	Inhalt	Beschreibung
address	transform	Text	Legt den Datentyp im Backend fest, z.B. DPT:1.001 für den KNX Datenpunkttyp 1.001.
	mode	disable, read, write oder readwrite	Legt fest, ob auf dieser Adresse nur gelesen read, geschrieben write, beides readwrite oder nichts davon disable werden soll
	value	Text	Fixer Wert welcher an diese Adresse gesendet wird.
	on	click, down oder up	Event bei dem ein Wert and diese Adresse geschickt wird (nur in Verbindung mit value und mode=``read`` oder readwrite).
	target	Text	Ziel innerhalb der Eltern-Widgets für das die Werte dieser Adresse benutzt werden sollen. Die möglichen Werte hängen vom Eltern-Widget ab.
	format-pos	Zahl	Position für Format-String wenn mehrere Adressen gleichzeitig genutzt werden.
	qos	Zahl	Nur MQTT: QoS
	retain	true oder false	Nur MQTT: retain Flag
	selector	Text	Nur MQTT: JSON Selektor
	backend	Text	Optionaler Name des Backends zu dem diese Adresse gehört.
	mapping	Text	Ordnet den Werten vom Bus andere Werte, Texte oder Symbole zur Anzeige zu. Siehe auch Mapping
	format	Text	Formatierung des Wertes (printf-Syntax).
	delay	positiveInteger	Optionales delay in Millisekunden, um welches das Schreiben an diese Adresse verzögert wird.
	send-mode	on-change oder always	Normalerweise bekommen Elemente, die diese Adresse benutzen nur eine Update-Benachrichtigung, wenn sich der Wert tatsächlich geändert hat (on-change). Mit always wird diese Überprüfung umgangen und die Update-Benachrichtigung jedes Mal geschickt, wenn ein neuer Wert vom Backend empfangen wurde.

Bemerkung

Im KNX Umfeld ist es üblich, dass nur eine Adresse mit write definiert wird und eine oder mehrere Adressen, die in der Regel nicht mit der write Adresse übereinstimmen, als read.

Dieses Prinzip ist damit genau das gleiche wie bei allen anderen KNX Komponenten bei denen über eine Adresse der Wert gesetzt wird und über eine andere die Rückmeldung erfolgt.

Backend-Attribut

In der Tile-Struktur können mehrere Backends definiert werden, mit denen die CometVisu gleichzeitig kommunizieren kann. So kann zum Beispiel zusätzlich zu dem KNX-Backend eine Verbindung zu einem MQTT-Broker aufgenommen werden. Es ist sogar möglich gleichzeitig mit mehreren Backends des selben Typs verbunden zu sein. Jedes konfigurierte Backend hat einen eindeutigen Namen, welcher als name-Attribut festgelegt wird. Wird dieses nicht angegeben entspricht der Name dem Wert des type-Attributs. Hat man nun also folgende 3 Backends definiert:

<cv-backend type="openhab" username="..."/>
<cv-backend name="si" default="true" type="simulated"/>
<cv-backend name="mqtt-broker" type="mqtt" uri="ws://mqtt:9001/"/>

kann man diese in den <cv-address>-Elementen auf folgende Weise benutzen:

<!-- Default backend -->
<cv-address transform="DPT:1001">1/0/0</cv-address>

<!-- openHAB backend -->
<cv-address transform="OH:switch" backend="openhab">Switch_Item</cv-address>

<!-- MQTT backend -->
<cv-address transform="MQTT:number" backend="mqtt-broker">/topic/baz</cv-address>

Target-Attribut

Die möglichen Werte und deren Auswirkungen beim target-Attribut hängen immer von dem Element ab in dem das <cv-address>-Element benutzt wird. Daher werden hier nur einige Beispiele genannt die in allen Widgets/Komponenten funktionieren.

Sichtbarkeit steuern

Es gibt zwei Möglichkeiten die Sichtbarkeit zu beeinflussen:

• target="show-hide": Macht das Widget unsichtbar ändert aber nicht das Layout, es entsteht eine leere Fläche

• target="show-exclude": Entfernt as Widget aus dem Layout, es entsteht keine leere Fläche

In diesem Beispiel würde die komplette Kachel aus dem Layout gelöscht werden, wenn das Backend den Wert 0 auf der Adresse sendet. Wenn eine 1 gesendet wird, wird die Kachel wieder hinzugefügt und sichtbar.

<cv-widget>
    <cv-tile>
        <cv-address transform="DPT:1.001" mode="read" target="show-exclude">1/0/0</cv-address>
    </cv-tile>
<cv-widget>

Widgets deaktivieren

In diesem Beispiel würde die komplette Kachel inkl. aller Bedienelemente darin deaktiviert und reagiert dann nicht mehr auf Interaktionen des Benutzers wie z.B. Mausklicks.

<cv-widget>
    <cv-tile>
        <cv-address transform="DPT:1.001" mode="read" target="enabled">1/0/0</cv-address>
    </cv-tile>
</cv-widget>

Widget als veraltet markieren

Besonders bei Widgets die einen Wert anzeigen ist es wichtig zu wissen, dass dieser Wert aktuell ist. Sofern man die Möglichkeit hat den Zeitpunkt der letzten Aktualisierung vom Backend zu bekommen, kann man diesen nutzen um das Widget als veraltet zu markieren, wenn die letzte Aktualisierung zu lange zurückliegt.

<cv-info format="%.2f">
    <cv-address slot="address" mode="read" transform="DPT:9.001">1/4/2</cv-address>
    <cv-address slot="tileAddress" transform="DPT:10.001" mode="read" target="last-update:120">1/4/3</cv-address>
    <span slot="label">Wohnzimmer</span>
    <span slot="unit">°C</span>
</cv-info>

Das target="last-update:120" gibt an, dass die Zeit nicht länger als 120 Sekunden zurückliegen darf, ansonsten wird das Widget als veraltet markiert.

Dieses Feature steht in allen vordefinierten Widgets zur Verfügung. In eigenen Widgets kann man es ebenfalls nutzen, man muss lediglich das slot-Attribut aus dem Beispiel weglassen.

<cv-widget>
    <cv-tile>
        <cv-address transform="DPT:10.001" mode="read" target="last-update:120">1/4/3</cv-address>
    </cv-tile>
</cv-widget>

Transform

Bei den für das jeweilige Backend spezifischen gültigen Werte für transform wird der entsprechende „Namensraum“ per Doppelpunkt getrennt vor den jeweiligen Datentyp geschrieben. Die für das jeweilige Backend gültigen Werte sind:

KNX

transform	Name	Beschreibung	Einheit	Min	Max
DPT:1	1 bit	1 Bit	-	0	1
DPT:1.001	DPT_Switch	Aus-An-Schalter	-	0	1
DPT:1.002	DPT_Bool	Boolscher-Wert	-	0	1
DPT:1.003	DPT_Enable	Disable / Enable	-	0	1
DPT:1.008	DPT_UpDown	Hoch-Runter-Schalter	-	0	1
DPT:1.009	DPT_OpenClose	Auf-Zu-Schalter	-	0	1
DPT:2	2 bit	2 Bit	-	0	3
DPT:3	4 bit	4 Bit	-	-100	100
DPT:3.007	DPT_Control_Dimming	Dimmen	-	-100	100
DPT:3.008	DPT_Control_Blinds	Beschattungssteuerung	-	-100	100
DPT:4	char	Zeichen	-
DPT:4.001	DPT_Char_ASCII	Zeichen	-
DPT:5	8 bit unsigned	8 Bit vorzeichenloser Integer	-	0	255
DPT:5.001	DPT_Scaling	Prozentwert	%	0	100
DPT:5.003	DPT_Angle	Winkel	°	0	360
DPT:5.004	DPT_Percent_U8	Prozentwert	%	0	255
DPT:5.010	DPT_Value_1_Ucount	Zähler	-	0	255
DPT:6	8 bit signed	8 Bit vorzeichenbehafteter Integer	-	-128	127
DPT:6.001	DPT_Percent_V8	Prozentwert mit Vorzeichen	%	-128	127
DPT:6.010	DPT_Value_1_Count	Zähler mit Vorzeichen	-	-128	127
DPT:7	2 byte unsigned	2 Byte vorzeichenloser Integer	-	0	65535
DPT:7.001	DPT_Value_2_Ucount	2 Byte vorzeichenloser Integer	-	0	65535
DPT:7.600	DPT_Absolute_Colour_Temperature	2 Byte vorzeichenloser Integer	K	0	65535
DPT:8	2 byte signed	2 Byte vorzeichenbehafteter Integer	-	-32768	32767
DPT:8.001	DPT_Value_2_Count	2 Byte vorzeichenbehafteter Integer	-	-32768	32767
DPT:9	2 byte float	2 Byte Gleitkommazahl	-	-671088.64	670433.28
DPT:9.001	DPT_Value_Temp	Temperatur	°C	-671088.64	670433.28
DPT:9.004	DPT_Value_Lux	Beleuchtungsstärke	Lux	-671088.64	670433.28
DPT:9.007	DPT_Value_Humidity	Luftfeuchtigkeit	%	-671088.64	670433.28
DPT:9.008	DPT_Value_AirQuality	Luftqualität	ppm	-671088.64	670433.28
DPT:9.020	DPT_Value_Volt	Spannung	mV	-671088.64	670433.28
DPT:9.021	DPT_Value_Curr	Strom	mA	-671088.64	670433.28
DPT:10.001	DPT_TimeOfDay	Zeit	-
DPT:11.001	DPT_Date	Datum	-
DPT:12	4 byte unsigned	4 Byte vorzeichenloser Integer	-	0	4294967295
DPT:12.001	DPT_Value_4_Ucount	4 Byte vorzeichenloser Integer	-	0	4294967295
DPT:13	4 byte signed	4 Byte vorzeichenbehafteter Integer	-	-2147483648	2147483647
DPT:13.001	DPT_Value_4_Count	4 Byte vorzeichenbehafteter Integer	-	-2147483648	2147483647
DPT:14	4 byte float	4 Byte Gleitkommazahl IEEE 754 (nur Dekodieren)	-
DPT:14.001	DPT_Value_Acceleration_Angular	4 Byte Gleitkommazahl IEEE 754 (nur Dekodieren)	-
DPT:16	DPT_String_ASCII	14 Byte Text ASCII	-
DPT:16.000	DPT_String_ASCII	14 Byte Text ASCII	-
DPT:16.001	DPT_String_8859_1	14 Byte Text ISO-8859-1	-
DPT:17	DPT_SceneNumber	Szenen Nummer	-	1	64
DPT:17.001	DPT_SceneControl	Szenen Nummer	-	1	192
DPT:18	DPT_SceneControl	Szenen Nummer	-	1	192
DPT:18.001	DPT_SceneControl	Szenen Nummer	-	1	192
DPT:20.102	DPT_HVACMode	KONNEX Betriebsart	-
DPT:24.001	DPT_VarString_8859_1	Variabler String ISO-8859-1	-
DPT:26	DPT_SceneInfo	Szenen Nummer	-	1	128
DPT:26.001	DPT_SceneInfo	Szenen Nummer	-	1	128
DPT:225	3 byte unsigned	3 Byte vorzeichenloser Integer	-	0	16777215
DPT:225.001	DPT_ScalingSpeed	Skalierungsgeschwindigkeit	-
DPT:232	3xDPT_Scaling	Drei Prozentwerte	%	0	100
DPT:232.600	DPT_Colour_RGB	RGB-Farbe	%	0	100
DPT:232.600HSV	DPT_Colour_HSV_inofficial	HSV-Farbe (inoffiziell)	-
DPT:242.600	DPT_Colour_xyY	xyY-Farbe	-
DPT:251.600	DPT_Colour_RGBW	RGBW-Farbe	%	0	100

OpenHab

transform	Name	Beschreibung	Einheit	Min	Max
OH:color	OH_Color
OH:contact	OH_Contact
OH:datetime	OH_DateTime
OH:dimmer	OH_Dimmer
OH:number	OH_Number
OH:playPause	OH_PlayPause
OH:rollershutter	OH_RollerShutter
OH:string	OH_String
OH:switch	OH_Switch
OH:thing-status	OH_Thing
OH:time	OH_Time

MQTT

transform	Name	Beschreibung	Beispiel	Einheit	Min	Max
MQTT:color_h_s_l	MQTT_color_h_s_l	HSL-Farbe	{"h":360,"s":100,"l":100}	-
MQTT:color_h_s_v	MQTT_color_h_s_v	HSV-Farbe	{"h":360,"s":100,"v":100}	-
MQTT:color_hsl	MQTT_color_hsl	HSL-Farbe als Zeichenkette	"360,100,100"	-
MQTT:color_hsv	MQTT_color_hsv	HSV-Farbe als Zeichenkette	"360,100,100"	-
MQTT:color_r_g_b	MQTT_color_r_g_b	RGB-Farbe	{"r":100,"g":100,"b":100}	-
MQTT:color_r_g_b_w	MQTT_color_r_g_b_w	RGBW-Farbe	{"r":100,"g":100,"b":100,"w":100}	-
MQTT:color_rgb	MQTT_color_rgb	RGB-Farbe als Zeichenkette	"100,100,100"	-
MQTT:color_rgb_hex	MQTT_color_rgb_hex	RGB-Farbe	"#11FF88"	-
MQTT:color_rgbw	MQTT_color_rgbw	RGBW-Farbe als Zeichenkette	"100,100,100,100"	-
MQTT:color_rgbw_hex	MQTT_color_rgbw_hex	RGBW-Farbe	"#11FF88AA"	-
MQTT:color_xy	MQTT_color_xy	xy-Farbe	{"x":0.123,"y":0.123}	-
MQTT:color_xyY	MQTT_color_xyY	xyY-Farbe	{"x":0.123,"y":0.123,"Y":100}	-
MQTT:datetime	MQTT_datetime	ISO 8601 Zeit-String	"2022-01-01T16:30:00.000Z"	-
MQTT:number	MQTT_Number	Zahl	42	-
MQTT:string	MQTT_String	Zeichenkette	"abc"	-
MQTT:timestring	MQTT_timestring	Uhrzeit-String	"16:30:00"	-
MQTT:unixtime	MQTT_unixtime	UNIX Zeitstempel	1641054600	-

Über weitere Attribute im <address>-Element kann die Kommunikation mit MQTT weiter spezifiziert werden:

selector	Der JSON-Pfad, wenn das Kommunikationsobjekt als JSON übertragen wird.
retain	Setzt bei true das Retain-Flag, so dass die Daten auch neuen Kommunikationsteilnehmern am MQTT sofort bereit gestellt werden.
qos	Setzt den QOS-Wert.
ignore-error	Ignoriert Konvertierungsfehler, wenn auf dem MQTT Daten gesendet werden, die z.B. nicht zum selector passen.

Beispiel:

Um einen numerischen Wert am Topic /topic/baz zu adressieren, der in einem JSON wie

{
  "foo": [
    {"bar": 0}
    {"bar": 1}
  ]
}

übertragen wird, müsste das <cv-address>-Element aussehen wie:

<cv-address transform="MQTT:number" selector="foo[1].bar" retain="true">/topic/baz</cv-address>

Roh-Werte / Test:

Die transform-Werte ohne Namensraum dienen im Wesentlichen nur der Entwicklung der CometVisu, können aber in Spezialfällen auch im Produktivbetrieb relevant sein:

transform	Name	Beschreibung	Einheit	Min	Max
float	Cast to Float
int	Cast to Int
raw	Only the RAW value