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.

Addresses - communication with the backend

Author: Tobias Bräutigam
Available since: 2022

Most widgets use one or more cv-address elements to communicate with the backend, which provides the relevant information from the KNX bus, OpenHAB or MQTT. The content is the address itself. The attributes can be used to determine the behavior of the widget in relation to the address:

Element

Attribute

Name

Content

Description

address

transform

string

Defines the datatype in the backend, e.g. DPT:1.001 for KNX datapoint type 1.001.

mode

disable, read, write or readwrite

Defines if this address is only used to read, write, both readwrite or none of them ``disable`.

value

string

Fixed value sent to this address.

on

click, down or up

Event on which a value should be sent to this address (only useful in mode=``write or readwrite`), also needs ``value.

target

string

Target in the parent widget the value if this address should be use for. The possible values depend on the parent widget.

format-pos

decimal

Position for format string when multiple addresses are used.

qos

decimal

Only MQTT: QoS

retain

true or false

Only MQTT: retain flag

selector

string

Only MQTT: JSON selector

backend

string

Optional name of the backend this address belongs to.

mapping

string

Map the bus value to a different value, text or symbol for displaying. See also mapping

format

string

Formatting of the value (printf syntax).

delay

positiveInteger

Optional delay in milliseconds that a write-request to this address is delayed.

send-mode

on-change or always

Usually the elements that are using this address receive an update-event only when that value hast changed (on-change). This check can be disabled always to send the update-event every time when a new value has been received from the backend.

Note

In the KNX environment it is common that only one address is defined as write and one or more addresses as read. Usually different addresses are used for read and write.

This principle is exactly the same as with all other KNX components where the value is set via one address and the feedback is received via another address.

Backend attribute

Several backends can be defined in the tile structure with which the CometVisu can communicate at the same time. For example, a connection to an MQTT broker can be established in addition to the KNX backend. It is even possible to be connected to multiple backends of the same type at the same time. Each configured Backend has a unique name, which is set by the name attribute. If this is not specified, the name corresponds to the value of the type attribute. So if you have defined the following 3 backends:

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

you can use them in the <cv-address> elements in the following way:

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

The possible values and their effects for the target attribute always depend on the element in which the <cv-address> element is used. Therefore, only a few examples are given here that work in all widgets/components.

Control visibility

There are two ways to influence visibility:

  • target="show-hide": Makes the widget invisible but does not change the layout, it creates an empty area

  • target="show-exclude": Removes the widget from the layout, no empty space is created

In this example, the entire tile would be deleted from the layout if the backend sends the value 0 for that address If a 1 is sent, the tile will be shown again.

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

Deactivate widgets

In this example, the entire tile, including all controls within it would be deactivated and no longer respond to user interactions such as mouse clicks.

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

Mark widget as outdated

Especially with widgets that display a value, it is important to know that this value is current. If you have the opportunity to get the time of the last update from the backend, you can use that to mark the widget as outdated if it has been too long since the last update.

../../../_images/cv-info-outdated.png 
<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">Living room</span>
    <span slot="unit">°C</span>
</cv-info>

The target="last-update:120" indicates that the time cannot be more than 120 seconds ago, otherwise the widget will be marked as obsolete.

This feature is available in all predefined widgets. You can also use it in your own widgets, you just have to leave out the slot attribute from the example.

<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

For the backend specific valid values of the respective backend for transform the corresponding “namespace” is separated by a colon in front of the respective data type written. The valid values for the backends are:

KNX

transform

name

description

unit

min

max

DPT:1

1 bit

1 bit

-

0

1

DPT:1.001

DPT_Switch

off on switch

-

0

1

DPT:1.002

DPT_Bool

boolean value

-

0

1

DPT:1.003

DPT_Enable

disable / enable

-

0

1

DPT:1.008

DPT_UpDown

up down switch

-

0

1

DPT:1.009

DPT_OpenClose

open close switch

-

0

1

DPT:2

2 bit

2 bit

-

0

3

DPT:3

4 bit

4 bit

-

-100

100

DPT:3.007

DPT_Control_Dimming

dimming

-

-100

100

DPT:3.008

DPT_Control_Blinds

blind control

-

-100

100

DPT:4

char

char

-

DPT:4.001

DPT_Char_ASCII

char

-

DPT:5

8 bit unsigned

8 bit unsigned integer

-

0

255

DPT:5.001

DPT_Scaling

percentage

%

0

100

DPT:5.003

DPT_Angle

angle

°

0

360

DPT:5.004

DPT_Percent_U8

percentage

%

0

255

DPT:5.010

DPT_Value_1_Ucount

counter

-

0

255

DPT:6

8 bit signed

8 bit signed integer

-

-128

127

DPT:6.001

DPT_Percent_V8

percentage with sign

%

-128

127

DPT:6.010

DPT_Value_1_Count

counter with sign

-

-128

127

DPT:7

2 byte unsigned

2 byte unsigned integer

-

0

65535

DPT:7.001

DPT_Value_2_Ucount

2 byte unsigned integer

-

0

65535

DPT:7.600

DPT_Absolute_Colour_Temperature

2 byte unsigned integer

K

0

65535

DPT:8

2 byte signed

2 byte signed integer

-

-32768

32767

DPT:8.001

DPT_Value_2_Count

2 byte signed integer

-

-32768

32767

DPT:9

2 byte float

2 byte float value

-

-671088.64

670433.28

DPT:9.001

DPT_Value_Temp

temperature

°C

-671088.64

670433.28

DPT:9.004

DPT_Value_Lux

illuminance

Lux

-671088.64

670433.28

DPT:9.007

DPT_Value_Humidity

humidity

%

-671088.64

670433.28

DPT:9.008

DPT_Value_AirQuality

air quality

ppm

-671088.64

670433.28

DPT:9.020

DPT_Value_Volt

voltage

mV

-671088.64

670433.28

DPT:9.021

DPT_Value_Curr

current

mA

-671088.64

670433.28

DPT:10.001

DPT_TimeOfDay

time

-

DPT:11.001

DPT_Date

date

-

DPT:12

4 byte unsigned

4 byte unsigned integer

-

0

4294967295

DPT:12.001

DPT_Value_4_Ucount

4 byte unsigned integer

-

0

4294967295

DPT:13

4 byte signed

4 byte signed integer

-

-2147483648

2147483647

DPT:13.001

DPT_Value_4_Count

4 byte signed integer

-

-2147483648

2147483647

DPT:14

4 byte float

4 byte float IEEE 754 (only decode)

-

DPT:14.001

DPT_Value_Acceleration_Angular

4 byte float IEEE 754 (only decode)

-

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

Scene Number

-

1

64

DPT:17.001

DPT_SceneControl

Scene Number

-

1

192

DPT:18

DPT_SceneControl

Scene Number

-

1

192

DPT:18.001

DPT_SceneControl

Scene Number

-

1

192

DPT:20.102

DPT_HVACMode

HVAC mode

-

DPT:24.001

DPT_VarString_8859_1

variable String ISO-8859-1

-

DPT:26

DPT_SceneInfo

Scene Number

-

1

128

DPT:26.001

DPT_SceneInfo

Scene Number

-

1

128

DPT:225

3 byte unsigned

3 byte unsigned integer

-

0

16777215

DPT:225.001

DPT_ScalingSpeed

scaling speed

-

DPT:232

3xDPT_Scaling

three percentages

%

0

100

DPT:232.600

DPT_Colour_RGB

rgb color

%

0

100

DPT:232.600HSV

DPT_Colour_HSV_inofficial

hsv color (inofficial)

-

DPT:242.600

DPT_Colour_xyY

xyY color

-

DPT:251.600

DPT_Colour_RGBW

rgbw color

%

0

100

OpenHab

transform

name

description

unit

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

description

example

unit

min

max

MQTT:color_h_s_l

MQTT_color_h_s_l

HSL color

{"h":360,"s":100,"l":100}

-

MQTT:color_h_s_v

MQTT_color_h_s_v

HSV color

{"h":360,"s":100,"v":100}

-

MQTT:color_hsl

MQTT_color_hsl

HSL color as string

"360,100,100"

-

MQTT:color_hsv

MQTT_color_hsv

HSV color as string

"360,100,100"

-

MQTT:color_r_g_b

MQTT_color_r_g_b

RGB color

{"r":100,"g":100,"b":100}

-

MQTT:color_r_g_b_w

MQTT_color_r_g_b_w

RGBW color

{"r":100,"g":100,"b":100,"w":100}

-

MQTT:color_rgb

MQTT_color_rgb

RGB color as string

"100,100,100"

-

MQTT:color_rgb_hex

MQTT_color_rgb_hex

RGB color

"#11FF88"

-

MQTT:color_rgbw

MQTT_color_rgbw

RGBW color as string

"100,100,100,100"

-

MQTT:color_rgbw_hex

MQTT_color_rgbw_hex

RGBW color

"#11FF88AA"

-

MQTT:color_xy

MQTT_color_xy

xy color

{"x":0.123,"y":0.123}

-

MQTT:color_xyY

MQTT_color_xyY

xyY color

{"x":0.123,"y":0.123,"Y":100}

-

MQTT:datetime

MQTT_datetime

ISO 8601 time string

"2022-01-01T16:30:00.000Z"

-

MQTT:number

MQTT_Number

number

42

-

MQTT:string

MQTT_String

string

"abc"

-

MQTT:timestring

MQTT_timestring

time string

"16:30:00"

-

MQTT:unixtime

MQTT_unixtime

UNIX timestamp

1641054600

-

Communication with MQTT can be specified further via additional attributes in the <address> element:

selector

The JSON path, if the communication object is transmitted as JSON.

retain

If true sets the retain flag so that the data is immediately made available to new communication participants on the MQTT.

qos

Sets the QOS value.

ignore-error

Ignores conversion errors that e.G. do not match to the selector.

Example:

To address a numeric value at the topic /topic/baz that is transmitted in a JSON like

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

the <cv-address> element would look like this:

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

Raw-values / Test:

The transform values without a namespace are essentially just for the development of CometVisu, but in special cases can also be relevant in productive environments:

transform

name

description

unit

min

max

float

Cast to Float

int

Cast to Int

raw

Only the RAW value