public/openhab-addons
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[knx] Refactoring of KnxCoreTypeMapper and UOM Support (#14534)

Browse Source 
* [knx] Refactoring, add basic support for UOM

Preparation for refactoring KnxCoreTypeMapper.
Carryover from smarthomej/addons#107.
Merge UOM implementations.

* [knx] Adapt tests

DPT strings for QuantityType now strip off a tailing .0 when decimals
are converted.

* [knx] Refactoring

Use pattern matching with instanceof operator (new Java17 feature).

* [knx] Refactoring, performance improvements

Introduce KNXChannel class.
Carryover from smarthomej/addons#114.

* [knx] Add warning for incompatible DPT type

Configuring incompatible DPT/channel combinations (e.g. DPT 1.005 (alarm) on Contact channels
or DPT 1.019 (windows/door) on Switch channels) is not allowed but was silently ignored.
This PR adds a warning in case incompatible configurations are detected.

Carryover from smarthomej/addons#203.

* [knx] Add full support for UoM

Replace UoM handling with the implementation from smarthome/j.
Carryover from smarthomej/addons#206.

* [knx] Refactor KNXCoreTypeMapper, add RGBW and xyY

Carryover from smarthomej/addons#208.

* [knx] Fix RGB conversion

Carryover from smarthomej/addons#219.

* [knx] Remove workarounds obsoleted by Calimero 2.5

Carryover from smarthomej/addons#226.

* [knx] Add parameter for disabling incoming UoM

Carryover from smarthomej/addons#230.

* [knx] Fix fallback to DecimalType in number conversion

Carryover from smarthomej/addons#279.

* [knx] Fix DPT 251.600 decoding

Carryover from smarthomej/addons#349.

* [knx] Fix UoM handling for special types
* [knx] Add test for KNXChannelFactory
* [knx] Update CODEOWNERS for knx
* [knx] Default conversion for DPT 5.001 and 6.001
* [knx] Fix write blocked forever after read from bus

Carryover from smarthomej/addons#299 and smarthomej/addons#330.

* [knx] Use new class ColorUtil from core for HSB conversion

Also-by: Jan N. Klug <github@klug.nrw>
Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>
This commit is contained in:
Holger Friedrich
2023-03-17 12:50:13 +01:00
committed by GitHub
parent b395d0e227
commit aae63e9488
45 changed files with 2505 additions and 2757 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
bundles/org.openhab.binding.knx/README.md
View File

@@ -9,6 +9,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.
@@ -16,7 +28,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
@@ -76,45 +89,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 |
|-----------|---------------|-------------|
@@ -123,32 +121,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"
@@ -165,14 +194,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"
@@ -197,6 +218,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 |
@@ -340,14 +363,14 @@ Bridge knx:ip:bridge [
knx.items:
```java
Switch demoSwitch "Light [%s]" <light> { channel="knx:device:bridge:generic:demoSwitch" }
Color demoColorLight "Color [%s]" <light> { channel="knx:device:bridge:generic:demoColorLight" }
Dimmer demoDimmer "Dimmer [%d %%]" <light> { channel="knx:device:bridge:generic:demoDimmer" }
Rollershutter demoRollershutter "Shade [%d %%]" <rollershutter> { channel="knx:device:bridge:generic:demoRollershutter" }
Contact demoContact "Front Door [%s]" <frontdoor> { channel="knx:device:bridge:generic:demoContact" }
Number demoTemperature "Temperature [%.1f °C]" <temperature> { 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]" <light> { channel="knx:device:bridge:generic:demoSwitch" }
Color demoColorLight "Color [%s]" <light> { channel="knx:device:bridge:generic:demoColorLight" }
Dimmer demoDimmer "Dimmer [%d %%]" <light> { channel="knx:device:bridge:generic:demoDimmer" }
Rollershutter demoRollershutter "Shade [%d %%]" <rollershutter> { channel="knx:device:bridge:generic:demoRollershutter" }
Contact demoContact "Front Door [%s]" <frontdoor> { channel="knx:device:bridge:generic:demoContact" }
Number:Temperature demoTemperature "Temperature [%.1f °C]" <temperature> { 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: