### 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 |
|---------------------|--------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
_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 |
|--------------|----------|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| 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).
#### 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`
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`
|-----------|---------------|-------------|
| 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`
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`
#### 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"
|-----------|---------------|-------------|
| 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"
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:
### 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`.
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.**
projects / openhab-addons.git / commitdiff