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 clients to connect to the same gateway.
***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.
| type | Yes | The IP connection type for connecting to the KNX bus (`TUNNEL`, `ROUTER`, `SECURETUNNEL` or `SECUREROUTER`) | - |
| ipAddress | for `TUNNEL` | Network address of the KNX/IP gateway. If type `ROUTER` is set, the IPv4 Multicast Address can be set. | for `TUNNEL`: \<nothing\>, for `ROUTER`: 224.0.23.12 |
| portNumber | for `TUNNEL` | Port number of the KNX/IP gateway | 3671 |
| localIp | No | Network address of the local host to be used to set up the connection to the KNX/IP gateway | the system-wide configured primary interface address |
| localSourceAddr | No | The (virtual) individual address for identification of this openHAB Thing within the KNX bus <br/><br/>Note: Use a free address, not the one of the interface. Or leave it at `0.0.0` and let openHAB decide which address to use.<br/>When using knxd, make sure _not to use_ one of the addresses reserved for tunneling clients. | 0.0.0 |
| useNAT | No | Whether there is network address translation between the server and the gateway | false |
| readingPause | No | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
| responseTimeout | No | Timeout in seconds to wait for a response from the KNX bus | 10 |
| readRetriesLimit | No | Limits the read retries while initialization from the KNX bus | 3 |
| autoReconnectPeriod | No | Seconds between connect retries when KNX link has been lost (0 means never). | 0 |
| routerBackboneKey | No | KNX secure: Backbone key for secure router mode | - |
| tunnelUserId | No | KNX secure: Tunnel user id for secure tunnel mode (if specified, it must be a number >0) | - |
| tunnelUserPassword | No | KNX secure: Tunnel user key for secure tunnel mode | - |
| tunnelDeviceAuthentication | No | KNX secure: Tunnel device authentication for secure tunnel mode | - |
| keyringFile | No | KNX secure: Keyring file exported from ETS and placed in openHAB config/misc folder. Mandatory to decode secure group addresses. | - |
| keyringPassword | No | KNX secure: Keyring file password (set during export from ETS) | - |
| tunnelSourceAddress | No | KNX secure: Physical KNX address of tunnel in secure mode to identify tunnel. If given, openHAB will read tunnelUserId, tunnelUserPassword, tunnelDeviceAuthentication from keyring. | - |
| serialPort | Y | The serial port to use for connecting to the KNX bus | - |
| readingPause | N | Time in milliseconds of how long should be paused between two read requests to the bus during initialization | 50 |
| responseTimeout | N | Timeout in seconds to wait for a response from the KNX bus | 10 |
| readRetriesLimit | N | Limits the read retries while initialization from the KNX bus | 3 |
| autoReconnectPeriod | N | Seconds between connect retries when KNX link has been lost, 0 means never retry | 0 |
| useCemi | N | Use newer CEMI message format, useful for newer devices like KNX RF sticks, kBerry, etc. | false |
| keyringFile | N | KNX secure: Keyring file exported from ETS and placed in openHAB config/misc folder. Mandatory to decode secure group addresses. | - |
| keyringPassword | N | KNX secure: Keyring file password (set during export from ETS) | - |
_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.
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.
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.
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.
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.
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.
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).
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.
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.
| 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 |
| frequency | Increase/Decrease frequency in milliseconds in case the binding should handle that (0 if the KNX device sends the commands repeatedly itself) | 0 |
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.
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 |
- The backbone key can be extracted from Security report (ETS, Reports, Security, look for a 32-digit key) and specified in parameter `routerBackboneKey`.
- The backbone key is included in ETS keyring export (ETS, project settings, export keyring). Keyring file is configured using `keyringFile` (put it in `config\misc` folder of the openHAB installation) and also requires `keyringPassword`.
- 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 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**.
This affects only the log of the binding and does not include Calimero library used for KNX communication.
In special cases, it might be useful to set both KNX logging and Calimero logging.
This can be done in the openHAB console:
```shell
log:set TRACE org.openhab.binding.knx
log:set TRACE calimero
```
Note that this will lead to a few lines in the log for each KNX frame received or sent.
Logging can be set back to normal, similarly using:
```shell
log:set DEFAULT org.openhab.binding.knx
log:set DEFAULT calimero
```
### Serial Devices
In case you experience communication errors like incomplete or dropped frames, BCU reset errors in the log, or similar problems:
- Make sure that no other service accesses the serial port (e.g., `knxd`, `hciuart`, etc.).
Use `ps aux` and make sure none of those are running in parallel.
- Increase the log level also for Calimero library, see above.
- If the problem relates only to KNX data secure, please note that very old KNX devices do not support long frames, which are required for KNX data secure. Check your interface and the couplers (technical reference manual, ETS, or openHAB device info when fetch is enabled).
### kBerry Module for Raspberry Pi
#### Configuration of the kBerry Module
Uploading an application to the module is not necessary for use with openHAB.
#### Configuration of the Serial Port
Configuration of the serial port is necessary.
This is done by editing text files in the folder `/boot/firmware` on the PI (for older distributions, it is `/boot`).
This can be done manually or using the tool `raspi-config`.
If something goes wrong, you can also recover using a Windows machine, as this partition is also accessible from Windows when using a micro SD card reader.
##### config.txt
The serial port (UART) needs to be activated on GPIO pins 14 and 15.
The configuration options have changed over time, depending on the Linux distribution and the hardware revision of the Raspberry Pi.
The following settings might work for you:
For PI 5, add `dtoverlay=disable-bt` and `dtoverlay=uart0`.
For PI 4, add `dtoverlay=disable-bt`.
For PI 3, add `dtoverlay=pi3-miniuart-bt`.
##### cmdline.txt
Remove the part that refers to the serial port, e.g. `console=serial0,115200`.
Finally, reboot the PI.
#### openHAB Configuration
Add a KNX Thing manually, KNX FT1.2 Interface, select `/dev/ttyAMA0` as port.
If you use file-based configuration, see the example above.
