diff --git a/_addons_bindings/knx/readme.md b/_addons_bindings/knx/readme.md index dcb0b54db..ab5a3f2e5 100644 --- a/_addons_bindings/knx/readme.md +++ b/_addons_bindings/knx/readme.md @@ -24,6 +24,18 @@ The KNX binding then can communicate directly with this gateway. Alternatively, a PC running [KNXD](https://github.com/knxd/knxd) (free open source component software) can be put in between which then acts as a broker allowing multiple client to connect to the same gateway. Since the protocol is identical, the KNX binding can also communicate with it transparently. +***Attention:*** With the introduction of Unit of Measurement (UoM) support, some data types have changed (see `number` channel below): + +- Data type for DPT 5.001 (Percent 8bit, 0 -> 100%) has changed from `PercentType` to `QuantityType`for `number` channels (`dimmer`, `color`, `rollershutter` channels stay with `PercentType`). +- Data type for DPT 5.004 (Percent 8bit, 0 -> 255%) has changed from `PercentType` to `QuantityType`. +- Data type for DPT 6.001 (Percent 8bit -128 -> 127%) has changed from `PercentType` to `QuantityType`. +- Data type for DPT 9.007 (Humidity) has changed from `PercentType` to `QuantityType`. + +Rules that check for or compare states and transformations that expect a raw value might need adjustments. +If you run into trouble with that and need some time, you can disable UoM support on binding level via the `disableUoM` parameter. +UoM are enabled by default and need to be disabled manually. +A new setting is activated immediately without restart. + ## Supported Things The KNX binding supports two types of bridges, and one type of things to access the KNX bus. @@ -31,7 +43,8 @@ There is an _ip_ bridge to connect to KNX IP Gateways, and a _serial_ bridge for ## Bridges -The following two bridge types are supported. Bridges don't have channels on their own. +The following two bridge types are supported. +Bridges don't have channels on their own. ### IP Gateway @@ -91,45 +104,30 @@ All channels of a device share one configuration parameter defined on device lev All readable group addresses are queried by openHAB during startup. If readInterval is not specified or set to 0, no further periodic reading will be triggered (default: 0). -#### Standard Channel Types +#### Channel Types Standard channels are used most of the time. They are used in the common case where the physical state is owned by a device within the KNX bus, e.g. by a switch actuator who "knows" whether the light is turned on or off, or by a temperature sensor which reports the room temperature regularly. -Note: After changing the DPT of already existing Channels, openHAB needs to be restarted for the changes to become effective. +Control channel types (suffix `-control`) are used for cases where the KNX bus does not own the physical state of a device. +This could be the case if e.g. a lamp from another binding should be controlled by a KNX wall switch. +When a `GroupValueRead` telegram is sent from the KNX bus to a *-control Channel, the bridge responds with a `GroupValueResponse` telegram to the KNX bus. -##### Channel Type "switch" - -| Parameter | Description | Default DPT | -|-----------|-------------------------------------|-------------| -| ga | Group address for the binary switch | 1.001 | - -##### Channel Type "dimmer" +##### Channel Type `color`, `color-control` | Parameter | Description | Default DPT | |------------------|----------------------------------------|-------------| +| hsb | Group address for the color | 232.600 | | switch | Group address for the binary switch | 1.001 | -| position | Group address of the absolute position | 5.001 | -| increaseDecrease | Group address for relative movement | 3.007 | +| position | Group address brightness | 5.001 | +| increaseDecrease | Group address for relative brightness | 3.007 | -##### Channel Type "color" +The `hsb` address supports DPT 242.600 and 251.600. -| Parameter | Description | Default DPT | -|------------------|----------------------------------------|-------------| -| hsb | Group address for color | 232.600 | -| switch | Group address for the binary switch | 1.001 | -| position | Group address of the absolute position | 5.001 | -| increaseDecrease | Group address for relative movement | 3.007 | +Some RGB/RGBW products (e.g. MDT) support HSB values for DPT 232.600 instead of RGB. +This is supported as "vendor-specific DPT" with a value of 232.60000. -##### Channel Type "rollershutter" - -| Parameter | Description | Default DPT | -|-----------|-----------------------------------------|-------------| -| upDown | Group address for relative movement | 1.008 | -| stopMove | Group address for stopping | 1.010 | -| position | Group address for the absolute position | 5.001 | - -##### Channel Type "contact" +##### Channel Type `contact`, `contact-control` | Parameter | Description | Default DPT | |-----------|---------------|-------------| @@ -138,32 +136,63 @@ Note: After changing the DPT of already existing Channels, openHAB needs to be r *Attention:* Due to a bug in the original implementation, the states for DPT 1.009 are inverted (i.e. `1` is mapped to `OPEN` instead of `CLOSE`). A change would break all existing installations and is therefore not implemented. -##### Channel Type "number" - -| Parameter | Description | Default DPT | -|-----------|---------------|-------------| -| ga | Group address | 9.001 | - -Note: Using the Units Of Measurement feature of openHAB (Quantitytype) requires that the DPT value is set correctly. -Automatic type conversion will be applied if required. - -##### Channel Type "string" - -| Parameter | Description | Default DPT | -|-----------|---------------|-------------| -| ga | Group address | 16.001 | - -##### Channel Type "datetime" +##### Channel Type `datetime`, `datetime-control` | Parameter | Description | Default DPT | |-----------|---------------|-------------| | ga | Group address | 19.001 | +##### Channel Type `dimmer`, `dimmer-control` + +| Parameter | Description | Default DPT | +|------------------|----------------------------------------|-------------| +| switch | Group address for the binary switch | 1.001 | +| position | Group address of the absolute position | 5.001 | +| increaseDecrease | Group address for relative movement | 3.007 | + +##### Channel Type `number`, `number-control` + +| Parameter | Description | Default DPT | +|-----------|---------------|-------------| +| ga | Group address | 9.001 | + +Note: The `number` channel has full support for Units Of Measurement (UoM). + +Using the UoM feature of openHAB (QuantityType) requires that the DPT value is set correctly. +Automatic type conversion will be applied if required. + +Incoming values from the KNX bus are converted to values with units (e.g. `23 °C`). +If the channel is linked to the correct item-type (`Number:Temperature` in this case) the display unit can be controlled by item metadata (e.g. `%.1f °F` for 1 digit of precision in Fahrenheit). +The unit is stripped if the channel is linked to a plain number item (type `Number`). + +Outgoing values with unit are first converted to the unit associated with the DPT (e.g. a value of `10 °F` is converted to `-8.33 °C` if the channel has DPT 9.001). +Values from plain number channels are sent as-is (without any conversion). + +##### Channel Type `rollershutter`, `rollershutter-control` + +| Parameter | Description | Default DPT | +|-----------|-----------------------------------------|-------------| +| upDown | Group address for relative movement | 1.008 | +| stopMove | Group address for stopping | 1.010 | +| position | Group address for the absolute position | 5.001 | + +##### Channel Type `string`, `string-control` + +| Parameter | Description | Default DPT | +|-----------|---------------|-------------| +| ga | Group address | 16.001 | + +##### Channel Type `switch`, `switch-control` + +| Parameter | Description | Default DPT | +|-----------|-------------------------------------|-------------| +| ga | Group address for the binary switch | 1.001 | + #### Control Channel Types In contrast to the standard channels above, the control channel types are used for cases where the KNX bus does not own the physical state of a device. This could for example be the case if a lamp from another binding should be controlled by a KNX wall switch. -If from the KNX bus a `GroupValueRead` telegram is sent to a *-control Channel, the bridge responds with a `GroupValueResponse` telegram to the KNX bus. +When a `GroupValueRead` telegram is sent from the KNX bus to a *-control Channel, the bridge responds with a `GroupValueResponse` telegram to the KNX bus. ##### Channel Type "switch-control" @@ -180,14 +209,6 @@ If from the KNX bus a `GroupValueRead` telegram is sent to a *-control Channel, | increaseDecrease | Group address for relative movement | 3.007 | | frequency | Increase/Decrease frequency in milliseconds in case the binding should handle that (0 if the KNX device sends the commands repeatedly itself) | 0 | -##### Channel Type "color-control" - -| Parameter | Description | Default DPT | -|------------------|----------------------------------------|-------------| -| hsb | Group address for color | 232.600 | -| switch | Group address for the binary switch | 1.001 | -| position | Group address of the absolute position | 5.001 | -| increaseDecrease | Group address for relative movement | 3.007 | ##### Channel Type "rollershutter-control" @@ -212,6 +233,8 @@ A change would break all existing installations and is therefore not implemented |-----------|---------------|-------------| | ga | Group address | 9.001 | +For UoM support see the explanations of the `number` channel. + ##### Channel Type "string-control" | Parameter | Description | Default DPT | @@ -355,14 +378,14 @@ Bridge knx:ip:bridge [ knx.items: ```java -Switch demoSwitch "Light [%s]" { channel="knx:device:bridge:generic:demoSwitch" } -Color demoColorLight "Color [%s]" { channel="knx:device:bridge:generic:demoColorLight" } -Dimmer demoDimmer "Dimmer [%d %%]" { channel="knx:device:bridge:generic:demoDimmer" } -Rollershutter demoRollershutter "Shade [%d %%]" { channel="knx:device:bridge:generic:demoRollershutter" } -Contact demoContact "Front Door [%s]" { channel="knx:device:bridge:generic:demoContact" } -Number demoTemperature "Temperature [%.1f °C]" { channel="knx:device:bridge:generic:demoTemperature" } -String demoString "Message of the day [%s]" { channel="knx:device:bridge:generic:demoString" } -DateTime demoDatetime "Alarm [%1$tH:%1$tM]" { channel="knx:device:bridge:generic:demoDatetime" } +Switch demoSwitch "Light [%s]" { channel="knx:device:bridge:generic:demoSwitch" } +Color demoColorLight "Color [%s]" { channel="knx:device:bridge:generic:demoColorLight" } +Dimmer demoDimmer "Dimmer [%d %%]" { channel="knx:device:bridge:generic:demoDimmer" } +Rollershutter demoRollershutter "Shade [%d %%]" { channel="knx:device:bridge:generic:demoRollershutter" } +Contact demoContact "Front Door [%s]" { channel="knx:device:bridge:generic:demoContact" } +Number:Temperature demoTemperature "Temperature [%.1f °C]" { channel="knx:device:bridge:generic:demoTemperature" } +String demoString "Message of the day [%s]" { channel="knx:device:bridge:generic:demoString" } +DateTime demoDatetime "Alarm [%1$tH:%1$tM]" { channel="knx:device:bridge:generic:demoDatetime" } ``` knx.sitemap: diff --git a/_addons_transformations/vat/readme.md b/_addons_transformations/vat/readme.md new file mode 100644 index 000000000..defdffd47 --- /dev/null +++ b/_addons_transformations/vat/readme.md @@ -0,0 +1,55 @@ +--- +id: vat +label: VAT +title: VAT - Transformation Services +type: transform +description: "The VAT Transformation Service adds VAT (Value-Added Tax) to a given input amount." +since: 3x +install: manual +--- + + + +{% include base.html %} + +# VAT Transformation Service + +The VAT Transformation Service adds VAT (Value-Added Tax) to a given input amount. +The input string must be either an ISO 3166 alpha-2 country code or a percentage, i.e. numerical format. + +## Examples + +### Display + +```java +Number CurrentSpotPrice "Current Spot Price incl. VAT [VAT(12.5):%s]" +``` + +### In a Rule + +Add Danish VAT to price: + +```java +var Number price = 499 +logInfo("Price", "Price incl. VAT: " + transform("VAT", "DK", price.toString)) +``` + +## Usage as a Profile + +The functionality of this `TransformationService` can also be used in a `Profile` on an `ItemChannelLink`. +This is the most powerful usage since VAT will be added without providing any explicit country code, percentage or configuration. +To use this, an `.items` file can be configured as follows: + +```java +Number CurrentSpotPrice "Current Spot Price" { channel="" [profile="transform:VAT"] } +``` + +To override VAT percentage for configured system country: + +```java +Number CurrentSpotPrice "Current Spot Price" { channel="" [profile="transform:VAT", percentage="12.5"] } +``` + +If VAT is not known for the configured country or the provided percentage is invalid, the default is 0%, so the input value will be put into the transformation without any changes. + +Please note: This profile is a one-way transformation, i.e. only values from a device towards the item are changed, the other direction is left untouched.