Skip to content

Commit

Permalink
[knx] Allow decoding of KNX Data Secure frames (openhab#12434)
Browse files Browse the repository at this point in the history 
* [knx] Allow decoding of KNX Data Secure frames

Signed-off-by: Holger Friedrich <[email protected]>
  • Loading branch information
@holgerfriedrich @matchews
holgerfriedrich authored and matchews committed Oct 18, 2024
1 parent d0a1e73 commit 3ed97a8
Show file tree
Hide file tree
Showing 23 changed files with 957 additions and 108 deletions.
68 changes: 43 additions & 25 deletions bundles/org.openhab.binding.knx/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -50,35 +50,40 @@ as multicast traffic is typically not forwarded.
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 |
|---------------------|--------------|--------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
| 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. 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 | - |
| Name | Required | Description | Default value |
|---------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| 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. | - |

### Serial Gateway

The _serial_ bridge accepts the following configuration parameters:

| Name | Required | Description | Default value |
|---------------------|----------|--------------------------------------------------------------------------------------------------------------|---------------|
| 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 |
| Name | Required | Description | Default value |
|---------------------|----------|----------------------------------------------------------------------------------------------------------------------------------|---------------|
| 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) | - |

## Things

Expand Down Expand Up @@ -452,24 +457,37 @@ It **requires a KNX Secure Router or a Secure IP Interface** and a KNX installat

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.
There are two possible ways to provide the key to openHAB:

- 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`.

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.
It can be provided to openHAB in two different ways:

- 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".
- All necessary information 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 `keyringPassword`.
In addition, `tunnelSourceAddress` needs to be set to uniquely identify the tunnel in use.

### 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 that support Data Secure and with **security features enabled in the ETS tool**.

> NOTE: **openHAB currently ignores messages with secure group addresses.**
**openHAB ignores messages with secure group addresses, unless data secure is configured.**

> NOTE: openHAB currently does fully support passive (listening) access to secure group addresses.
Write access to secure group addresses is currently disabled in openHAB.
Initial/periodic read will fail, avoid automatic read (< in thing definition).

All necessary information to decode secure group addresses 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`.

## Examples

Expand Down
3 changes: 3 additions & 0 deletions ...enhab.binding.knx/src/main/java/org/openhab/binding/knx/internal/KNXBindingConstants.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,13 @@ public class KNXBindingConstants {
public static final String PORT_NUMBER = "portNumber";
public static final String SERIAL_PORT = "serialPort";
public static final String USE_CEMI = "useCemi";
public static final String KEYRING_FILE = "keyringFile";
public static final String KEYRING_PASSWORD = "keyringPassword";
public static final String ROUTER_BACKBONE_GROUP_KEY = "routerBackboneGroupKey";
public static final String TUNNEL_USER_ID = "tunnelUserId";
public static final String TUNNEL_USER_PASSWORD = "tunnelUserPassword";
public static final String TUNNEL_DEVICE_AUTHENTICATION = "tunnelDeviceAuthentication";
public static final String TUNNEL_SOURCE_ADDRESS = "tunnelSourceAddress";

// The default multicast ip address (see <a
// href="http://www.iana.org/assignments/multicast-addresses/multicast-addresses.xml">iana</a> EIBnet/IP
Expand Down
Loading

0 comments on commit 3ed97a8

Please sign in to comment.