From 8909249b49d1a678c22f12d164ee7369514bf006 Mon Sep 17 00:00:00 2001 From: Holger Friedrich Date: Sun, 25 Feb 2024 14:00:25 +0100 Subject: [PATCH] [knx] Add list of supported DPTs (#16452) * [knx] Add list of supported DPTs Signed-off-by: Holger Friedrich Signed-off-by: Ciprian Pascu --- bundles/org.openhab.binding.knx/README.md | 204 +++++++++++++++++++--- 1 file changed, 181 insertions(+), 23 deletions(-) diff --git a/bundles/org.openhab.binding.knx/README.md b/bundles/org.openhab.binding.knx/README.md index 8012f3d2784..3df35ecd204 100644 --- a/bundles/org.openhab.binding.knx/README.md +++ b/bundles/org.openhab.binding.knx/README.md @@ -47,7 +47,8 @@ as multicast traffic is typically not forwarded. ### IP Gateway -The IP Gateway is the most commonly used way to connect to the KNX bus. At its base, the _ip_ bridge accepts the following configuration parameters: +The IP Gateway is the most commonly used way to connect to the KNX bus. +At its base, the _ip_ bridge accepts the following configuration parameters: | Name | Required | Description | Default value | |---------------------|--------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------| @@ -86,9 +87,10 @@ The _serial_ bridge accepts the following configuration parameters: _basic_ Things are wrappers around arbitrary group addresses on the KNX bus. They have no specific function in the KNX binding, except that if the _address_ is defined, the binding will actively poll the Individual Address on the KNX bus to detect that the KNX actuator is reachable. Under normal real-world circumstances, either all devices on a bus are reachable, or the entire bus is down. -If line couplers are installed, physical device addressing might be filtered; in this case please do not specify the addresses for devices on this line. -When _fetch_ is set to true, the binding will read-out the memory of the KNX actuator in order to detect configuration data and so forth. -This is however an experimental feature, very prone to the actual on the KNX bus. +If line couplers are installed, physical device addressing might be filtered; in this case, please do not specify the addresses for devices on this line. +When _fetch_ is set to true, the binding will read out the memory of the KNX actuator in order to detect configuration data and so forth. +This is just for information and has no effect on the functionality of the binding. +It can safely be turned off to save bandwidth on the bus or avoid problems with older devices. | Name | Required | Description | Default value | |--------------|----------|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| @@ -98,7 +100,7 @@ This is however an experimental feature, very prone to the actual on the KNX bus | readInterval | N | Interval (in seconds) to actively request reading of values from the bus (0 if they should only be read once at startup) | 0 | Different kinds of channels are defined and can be used to group together Group Addresses. -All channels of a device share one configuration parameter defined on device level: _readInterval_, an optional parameter which indicates if 'readable' group addresses of that Channel should be read periodically at the given interval, in seconds. +All channels of a device share one configuration parameter defined at the device level: _readInterval_, an optional parameter that indicates if the 'readable' group addresses of that Channel should be read periodically at the given interval, in seconds. 'Readable' group addresses are marked with an `<` in the group address definition of a Channel, see below. 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). @@ -106,10 +108,10 @@ If readInterval is not specified or set to 0, no further periodic reading will b #### 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. +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 that "knows" whether the light is turned on or off, or by a temperature sensor that reports the room temperature regularly. 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. +This could be the case if, for example, 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 `color`, `color-control` @@ -126,10 +128,11 @@ The `hsb` address supports DPT 232.600 (RGB), 242.600 (xyY), and 251.600 (RGBW). Some RGB/RGBW products (e.g. MDT) use HSB values for DPT 232.600 instead of RGB. This is supported as "vendor-specific DPT" with a value of 232.60000. -RGBW (DPT 251.600) can either be converted to HSBType, or be represented two items: a HSBType for RGB and an additional PercentType for W channel. +RGBW (DPT 251.600) can either be converted to HSBType, or represented by two items: a HSBType for RGB and an additional PercentType for the W channel. Default handling for RGBW is to use separate items. -Note that this also requires two frames being sent out separately when these elements are sent to the bus, as the binary representation uses a partially populated KNX frame. -Alternatively, a single HSB item can be used. Conversion to a single HSBType will loose the exact setting for W, and will reconstruct it when a conversion to RGBW is required. +Note that this also requires two frames to be sent out separately when these elements are sent to the bus, as the binary representation uses a partially populated KNX frame. +Alternatively, a single HSB item can be used. +Conversion to a single HSBType will lose the exact setting for W, and will reconstruct it when a conversion to RGBW is required. This option can be selected using the special DPT 251.60600. ##### Channel Type `contact`, `contact-control` @@ -138,7 +141,7 @@ This option can be selected using the special DPT 251.60600. |-----------|---------------|-------------| | ga | Group address | 1.009 | -*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`). +*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 `datetime`, `datetime-control` @@ -167,10 +170,10 @@ Using the UoM feature of openHAB (QuantityType) requires that the DPT value is s 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`). +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). +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` @@ -196,7 +199,7 @@ Values from plain number channels are sent as-is (without any conversion). #### 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. +This could, for example, be the case if 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-control" @@ -238,7 +241,7 @@ 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. +For UoM support, see the explanations of the `number` channel. ##### Channel Type "string-control" @@ -266,16 +269,167 @@ where parts in brackets `[]` denote optional information. This is recommended if you have a dedicated status group address which is added as `listeningGA`. The optional `<` sign tells whether the group address of the datapoint accepts read requests on the KNX bus (it does, if the sign is there). -The group addresses marked with `<` are read by openHAB during startup. +The group addresses marked with `<` are read by openHAB during startup. Future versions might support reading from one GA only. With `*-control` channels, the state is not owned by any device on the KNX bus, therefore no read requests will be sent by the binding, i.e. `<` signs will be ignored for them. The element `dpt` is highly recommended and may change to a mandatory element in future versions. If omitted, the corresponding default value will be used (see the channel descriptions above). +## Mapping DPTs to openHAB Types + +Datapoint Types (DPTs) define how the content of a KNX telegram is interpreted. + +The following table is a complete list of DPTs currently supported by openHAB. +OpenHAB supports all DPTs supported by the corresponding release of the Calimero library, plus a few [specific additions](#special-dpts). + +The default mapping is given, however DPTs can be overwritten. +KNX frames do not contain information about the encoding or DPT, so any DPT with a compatible byte size and a useful encoding can be used. +A good example for this are bitfields represented as String which are mapped to a DPT of DecimalType for handling in rules. +For more details, see the KNX specification (section 3.7.2, System Specifications, Interworking, Datapoint Types). + +In case a missing DPT or subtype is needed, there is a good chance that a DPT of matching size and DecimalType is found. +Further DPTs and subtypes may be added later once implemented and released in the [Calimero library](https://github.com/calimero-project/calimero-core). + +| DPT | Primary openHAB type (things) (items with UOM) | Remark | +|-----------------|----------------------------------------------------|-----------------------------------| +| 1.001-1.007 | OnOffType (switch), OpenClosedType (contact) | | +| 1.008 | UpDownType (e.g. for dimmer, rollershutter) | | +| 1.009 | OnOffType (switch), OpenClosedType (contact) | Not according to spec, see above | +| 1.010 | StopMoveType (e.g. for rollershutter) | | +| 1.011-1.016 | OnOffType (switch), OpenClosedType (contact) | | +| 1.017 | OnOffType (switch), OpenClosedType (contact) | Trigger, use states OFF or CLOSED | +| 1.018-1.019 | OnOffType (switch), OpenClosedType (contact) | | +| 1.021 | OnOffType (switch), OpenClosedType (contact) | | +| 1.022 | DecimalType (number) | Counting from 0, use DPT if you need a DecimalType | +| 1.023-1.024 | OnOffType (switch), OpenClosedType (contact) | | +| 1.100 | OnOffType (switch), OpenClosedType (contact) | | +| 1.1200-1.1201 | OnOffType (switch), OpenClosedType (contact) | | +||| +| 2.001-2.012 | DecimalType (number) | | +||| +| 3.007 | IncreaseDecreaseType (e.g. dimmer) | | +| 3.008 | UpDownType (e.g. rollershutter) | | +||| +| 5.001 | QuantityType\<> (number) (Number:Percent) | Alternatively: PercentType | +| 5.003 | QuantityType\<> (number) (Number:Angle) | | +| 5.004 | QuantityType\<> (number) (Number:Percent) | 0-255%, no mapping to PercentType | +| 5.005 | DecimalType (number) | | +| 5.006 | DecimalType (number) | 255 is reserved | +| 5.010 | DecimalType (number) | | +||| +| 6.001 | QuantityType\<> (number) (Number:Percent) | -128..127%, no mapping to PercentType | +| 6.010 | DecimalType (number) | -128..127 | +| 6.020 | StringType (string) | Override with DPT5.010 if you need DecimalType | +||| +| 7.001 | DecimalType (number) | | +| 7.002-7.007 | QuantityType\<> (number) (Number:Time) | | +| 7.010 | DecimalType (number) | | +| 7.011 | QuantityType\<> (number) (Number:Length) | | +| 7.012 | QuantityType\<> (number) (Number:ElectricCurrent) | | +| 7.013 | QuantityType\<> (number) (Number:Length) | | +| 7.600 | QuantityType\<> (number) (Number:Temperature) | | +||| +| 8.001 | DecimalType (number) | | +| 8.002-7.007 | QuantityType\<> (number) (Number:Time) | | +| 8.010 | QuantityType\<> (number) (Number:Percent) | | +| 8.011 | QuantityType\<> (number) (Number:Angle) | | +| 8.012 | QuantityType\<> (number) (Number:Length) | | +||| +| 9.xxx | QuantityType\<> (number) (Number:...) | See [documentation on UOM](https://www.openhab.org/docs/concepts/units-of-measurement.html) | +| 9.001 | QuantityType\<> (number) (Number:...) | Lower values than absolute zero will be set to -273 °C | +| 9.002-9.003 | QuantityType\<> (number) (Number:...) | | +| 9.004-9.008 | QuantityType\<> (number) (Number:...) | No negative values allowed | +| 9.009-9.011 | QuantityType\<> (number) (Number:...) | | +| 9.020-9.027 | QuantityType\<> (number) (Number:...) | | +| 9.027-9.030 | QuantityType\<> (number) (Number:...) | No negative values allowed | +||| +| 10.001 | DateTimeType (datetime) | Time. Date is set to 1/Jan/1970 + ofs if weekday is given. KNX can represent year 1990..2089. | +||| +| 11.001 | DateTimeType (datetime) | Date only. | +||| +| 12.001 | DecimalType (number) | | +| 12.100-12.102 | QuantityType\<> (number) (Number:Time) | | +| 12.1200-12.1201 | QuantityType\<> (number) (Number:Volume) | | +||| +| 13.xxx | QuantityType\<> (number) (Number:...) | See [documentation on UOM](https://www.openhab.org/docs/concepts/units-of-measurement.html) | +| 13.001 | DecimalType (number) | | +| 13.002 | QuantityType\<> (number) (Number:VolumetricFlowRate) | | +| 13.010-13.016 | QuantityType\<> (number) (Number:...) | | +| 13.100 | QuantityType\<> (number) (Number:...) | | +| 13.1200-13.1201 | QuantityType\<> (number) (Number:Time) | | +||| +| 14.xxx | QuantityType\<> (number) (Number:...) | See [documentation on UOM](https://www.openhab.org/docs/concepts/units-of-measurement.html) | +| 14.000-14.080 | QuantityType\<> (number) (Number:...) | | +| 14.1200-14.1201 | QuantityType\<> (number) (Number:...) | | +||| +| 16.000 | StringType (string) | ASCII | +| 16.001 | StringType (string) | ISO 8859-1 | +||| +| 17.001 | DecimalType (number) | Scene 0..63 | +||| +| 18.001 | DecimalType (number) | Scene 0..63, add offset 0x80 (128) for storing scenes | +||| +| 19.001 | DateTimeType (datetime) (DateTime) | Date and Time, year can be 1900..2155 | +||| +| 20.xxx | | Incomplete, only subtypes given below are supported; override with DPT5.010 if you need enum as DecimalType | +| 20.001-20.009 | StringType (string) | | +| 20.011-20.014 | StringType (string) | | +| 20.017 | StringType (string) | | +| 20.020-20.021 | StringType (string) | | +| 20.100-20.114 | StringType (string) | | +| 20.120-20.122 | StringType (string) | | +| 20.600-20.610 | StringType (string) | | +| 20.801-20.804 | StringType (string) | | +| 20.1000-20.1005 | StringType (string) | | +| 20.1200 | StringType (string) | | +| 20.1202 | StringType (string) | | +||| +| 21.xxx | | Incomplete, only subtypes given below are supported; override with DPT5.010 if you need bitset as DecimalType | +| 21.001-20.002 | StringType (string) | | +| 21.100-20.106 | StringType (string) | | +| 21.601 | StringType (string) | | +| 21.1000-21.1002 | StringType (string) | | +| 21.1010 | StringType (string) | | +||| +| 22.xxx | | Incomplete, only subtypes given below are supported; override with DPT7.010 if you need bitset as DecimalType | +| 22.101 | StringType (string) | | +| 22.1000 | StringType (string) | | +||| +| 28.001 | StringType (string) | KNX representation is Null-terminated, do not include null characters | +||| +| 29.010-29.012 | QuantityType\<> (number) (Number:...) | | +||| +| 229.001 | DecimalType (number) | Scaling coded in KNX frame is regarded; for sending always encoded with flag "dimensionless" | +||| +| 232.600 | HSBType (color) | RGB | +| 232.60000 | HSBType (color) | Non-Standard, DPT 232.600 with HSB instead of RGB data | +||| +| 235.001 | QuantityType\<> (number) (Number:ActiveEnergy) | Composed DPT 235.001, first element ActiveEnergy (Wh), read only | +| 235.61001 | DecimalType (number) | Non-Standard, composed DPT 235.001, second element Tariff (plain number), read only | +||| +| 242.600 | HSBType (color) | xyY | +||| +| 243.600 | StringType (string) | | +||| +| 249.600 | StringType (string) | | +||| +| 250.600 | StringType (string) | | +||| +| 251.600 | HSBType (color) | RGBW, RGB part as HSBType | +| 251.600 | PercentType | RGBW, W part separately for Dimmer | +| 251.60600 | HSBType (color) | Non-Standard, lossy conversion from HSBType to RGBW | +||| +| 252.600 | StringType (string) | | +||| +| 253.600 | StringType (string) | | +||| +| 254.600 | StringType (string) | | +||| + ## Special DPTs -OpenHAB supports all DPTs supported by the corresponding release of Calimero library. +OpenHAB supports all DPTs supported by the corresponding release of the Calimero library. Additional DPTs have been introduced to add functionality: @@ -292,9 +446,9 @@ Additional DPTs have been introduced to add functionality: ### KNX IP Secure KNX IP Secure protects the traffic between openHAB and your KNX installation. -It **requires a KNX Secure Router or a Secure IP Interface** and a KNX installation **with security features enabled in ETS tool**. +It **requires a KNX Secure Router or a Secure IP Interface** and a KNX installation **with security features enabled in the ETS tool**. -For _Secure routing_ mode, the so called `backbone key` needs to be configured in openHAB. +For _Secure routing_ mode, the so-called `backbone key` needs to be configured in openHAB. It is created by the ETS tool and cannot be changed via the ETS user interface. - The backbone key can be extracted from Security report (ETS, Reports, Security, look for a 32-digit key) and specified in parameter `routerBackboneKey`. @@ -302,12 +456,16 @@ It is created by the ETS tool and cannot be changed via the ETS user interface. For _Secure tunneling_ with a Secure IP Interface (or a router in tunneling mode), more parameters are required. A unique device authentication key, and a specific tunnel identifier and password need to be available. -- All information can be looked up in ETS and provided separately: `tunnelDeviceAuthentication`, `tunnelUserPassword`. `tunnelUserId` is a number which is not directly visible in ETS, but can be looked up in keyring export or deduced (typically 2 for the first tunnel of a device, 3 for the second one, ...). `tunnelUserPasswort` is set in ETS in the properties of the tunnel (below the IP interface you will see the different tunnels listed) denoted as "Password". `tunnelDeviceAuthentication` is set in the properties of the IP interface itself, check for a tab "IP" and a description "Authentication Code". +- All information can be looked up in ETS and provided separately: `tunnelDeviceAuthentication`, `tunnelUserPassword`. + `tunnelUserId` is a number that is not directly visible in ETS, but can be looked up in keyring export or deduced (typically 2 for the first tunnel of a device, 3 for the second one, ...). + `tunnelUserPasswort` is set in ETS in the properties of the tunnel (below the IP interface, you will see the different tunnels listed) and denoted as "Password". + `tunnelDeviceAuthentication` is set in the properties of the IP interface itself; check for the tab "IP" and the description "Authentication Code". ### KNX Data Secure -KNX Data Secure protects the content of messages on the KNX bus. In a KNX installation, both classic and secure group addresses can coexist. -Data Secure does _not_ necessarily require a KNX Secure Router or a Secure IP Interface, but a KNX installation with newer KNX devices which support Data Secure and with **security features enabled in ETS tool**. +KNX Data Secure protects the content of messages on the KNX bus. +In a KNX installation, both classic and secure group addresses can coexist. +Data Secure does _not_ necessarily require a KNX Secure Router or a Secure IP Interface, but a KNX installation with newer KNX devices that support Data Secure and with **security features enabled in the ETS tool**. > NOTE: **openHAB currently ignores messages with secure group addresses.**