demus/openhab-addons
1
0
Fork 0
mirror of https://github.com/openhab/openhab-addons.git synced 2025-01-10 15:11:59 +01:00
Code Issues Packages Projects Releases Wiki Activity

[knx] Add list of supported DPTs (#16452)

Browse Source 
* [knx] Add list of supported DPTs

Signed-off-by: Holger Friedrich <mail@holger-friedrich.de>
Signed-off-by: Ciprian Pascu <contact@ciprianpascu.ro>
This commit is contained in:
Holger Friedrich 2024-02-25 14:00:25 +01:00 committed by Ciprian Pascu
parent 10b76fbb31
commit 8909249b49
1 changed files with 181 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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.**