KNX Link

The KNX Link establish a connection to your KNX Net/IP device using the knx-core library and acts as a KNX gateway. The KNX Link project is based on two components: KNX Link Server and KNX Link Client.

The purpose of the KNX Link Server is to serve the requests from KNX Link Client and communicates with the KNX Net/IP device with almost no delay. This is achieved by avoiding establishing a connection to the KNX Net/IP device as a long-running systemd service and keeps the connection established. In this way we can avoid spending up to few seconds per connection ramp ups and tear downs.

The KNX Link Client is a lightweight commandline tool with a short life-cycle and comes with a much simplified protocol which has been designed for communication between the KNX Link Server and the KNX Link Client. The communication between those parties are done via TCP socket as illustrated below.

Prerequisites

Host
- A dedicated machine based on Linux (e.g. CentOS)
- curl for downloading the files for installation
- systemctl for setup for systemd service
Java 11+
- Make sure that you have Java 11+ installed and running as Java 11+

KNX Link Server

How to install KNX Link Server?

Execute and follow the instructions:

bash <(curl -s https://raw.githubusercontent.com/pitschr/knx-link/main/install.sh)

What it is doing? It is downloading the file install.sh I prepared for you and will prompt guide you through the installation and asking some questions which you may reply with 'yes' or 'no'.

In nutshell, the steps of install.sh script are:

Creating a technical user knx for systemd service
Downloading the knx-link-<version>.jar file to folder /opt/knx-link-<version>
Install knx.service to start and keep KNX Link server running (e.g. after reboot)
(Optional) Create a knx firewall rule for your firewalld, which opens the UDP port 3671 which is registered for KNX communication. Opens UDP ports 40001 (for Description Channel), 40002 (for Control Channel) and 40003 (for Data Channel) which are required for communication without NAT.
Check if the systemd service is running
(Optional) Check if the port of KNX Link server is open

How to start, stop or restart KNX Link Server?

After installation, the KNX Link Server is installed as a fully managed service by the systemd daemon and executed as technical user (knx). It is a long-running process and in normal reasons there is no need to start or stop it by yourself. However, in special cases you need to start/stop/restart the KNX Link Server; i.e. when you change the server configuration file (server.cfg, see below) and apply the change immediately.

Action	Command
Start	`systemctl start knx.service`
Stop	`systemctl stop knx.service`
Restart	`systemctl restart knx.service`

For further info, please check out the systemctl man page.

KNX Link Server Configuration

The configuration for KNX Link server is server.cfg and in folder /opt/knx-link-<version>/server.cfg.

By default, no server.cfg file exists which means the KNX Link Server will use default values. This is suitable for many cases, however, if a different configuration is required, then please go to folder /opt/knx-link-<version>/server.cfg and create a file server.cfg and apply the config key and values according your needs.

Config Key	Default Value	Description
`knx.mode`	`tunneling`	Defines the mode of communication how the KNX Link server should communicate with the KNX Net/IP device. Allowed values: `tunneling` or `routing`
`knx.nat`	`false`	Defines if the Network Address Translation (NAT) should be used. NAT is can be used for `tunneling` mode only. If `routing` mode is used then it has no effect and is ignored. Allowed values: `false` or `true`
`knx.address`	`0.0.0.0` (Auto Discovery)	If your KNX Net/IP device has a static IP address you can set the IP address that allows a faster start-up as it will skip the auto-discovery process. This setting might be also useful if you have more than one KNX Net/IP device and you want to specific one, otherwise the auto-discovery will choose a KNX Net/IP device in behalf of you otherwise. Allowed Pattern: `[0-255].[0-255].[0-255].[0-255]`
`knx.port`	`3671`	Set only if your KNX Net/IP device is using a port number that differs from the officially registered KNX port `3671` at IANA. If 'knx.address' is 'auto', then KNX port has no effect and will be ignored. Allowed Port Range: `1024 - 65535`
`server.port`	`3672`	Set only if you want to use a different port for your KNX Link server that opens a server socket channel for your clients. This is not the port communicating with your KNX Net/IP device. Allowed Port Range: `1024 - 65535`
`server.allowed.addresses`	`127.0.0.1` (localhost)	This setting is used to accept requests from your clients that are from a trusted IP address. Default is `127.0.0.1` which means it will only accept requests which are originated from the same machine. Localhost (`127.0.0.1`) is always accepted, therefore you do not need to whitelist the localhost. You can define multiple IP addresses which should be accepted as well; define them as comma-separated. Example: `10.0.1.2,192.168.1.4,192.168.2.8`. Allowed Pattern: `[0-255].[0-255].[0-255].[0-255]`

How to install the KNX Link Client?

Precondition to use the KNX Link Client is that KNX Link Server is running. Therefore, this section assumes that you already have KNX Link Server installed and running.

The KNX Link Client is implemented in Rust to allow a very quick cold-start and communication with the KNX Link Server. The biggest advantage is that no runtime (e.g. Java JDK) is required which runs the application natively.

How to install?

The pre-build executables can be found on the release page. Just download the latest version of knx-link-client and make sure that the file is executable.

For Linux, MacOs, Cygwin, MinGw

Execute the bash script below. It will check if curl is installed and detect which operating system you are using inclusive checking of the GCLIB version and it will download the latest KNX Link Client artifact.

bash <(curl -s https://raw.githubusercontent.com/pitschr/knx-link/main/install-client.sh)

For Windows

Go to release page and download the latest version of knx-link-client-windows.exe. After downloading you can rename the file to e.g. knx-link-client.exe and use it in your Windows Command Prompt (CMD) or in your powershell.

How to use it?

If you are struggling, try out one of those commands

General Help: * ./knx-link-client help
Help about read sub-command: ./knx-link-client help read
Help about write sub-command: ./knx-link-client help write

Reminder: If you are requesting the KNX Link Server from another machine, please make sure that the IP address of the machine list is white-listed on the KNX Link Server, otherwise your packets won't be accepted by the KNX Link Server for security reasons. See server.allowed.addresses setting of KNX Link Server.

Global Arguments

The KNX Link Client has following parameters which are available for all sub-commands. Each sub-command have their own parameters which are described in their own sections.

Parameter	Default Value	Description
`-h` `--host`	`127.0.0.1` (localhost)	The IP Address where the KNX Link Server is running
`-p` `--port`	`3672`	The port of the KNX Link Server is listening

Read Sub-Command

The read sub-command to send a read request packet to KNX Link Server

Parameter	Description
`-g` `--group_address`	The KNX group address that should receive the read request. Supported formats are Three-Level: Main, Middle and Sub (Range: `0/0/1 - 31/7/255`), Two-Level: Main and Sub (Range: `0/1 - 31/2047`) and Free-Level: Address (Range: `1 - 65535`)
`-d` `--data_point_type`	The KNX data point type that you are requesting for. Supported formats are `#`, `#.#`, `dpt-#` and `dpst-#-#`. Examples for 'Switch' Data Point Type: `1`, `1.1`, `1.001`, `dpt-1`, `dpst-1-1` Examples for 'Date' Data Point Type: `11`, `11.1`, `11.001`, `dpt-11`, `dpst-11-1`

Given examples requests the KNX Group Address 1/2/113 (which has a READ-Flag) the status of e.g. lamp. With given data point type 1.001 we may either get On or Off.

knx-link-client read -g 1/2/113 -d 1.001

Write Sub-Command

The write sub-command to send a write request packet to KNX Link Server

Parameter	Description
`-g` `--group_address`	The KNX group address that should receive the read request. Supported formats are Three-Level: Main, Middle and Sub (Range: `0/0/1 - 31/7/255`), Two-Level: Main and Sub (Range: `0/1 - 31/2047`) and Free-Level: Address (Range: `1 - 65535`)
`-d` `--data_point_type`	The KNX data point type that you are requesting for. Supported formats are `#`, `#.#`, `dpt-#` and `dpst-#-#`. Examples for 'Switch' Data Point Type: `1`, `1.1`, `1.001`, `dpt-1`, `dpst-1-1` Examples for 'Date' Data Point Type: `11`, `11.1`, `11.001`, `dpt-11`, `dpst-11-1`
`-v` `--value`	The value you want to send to KNX Link Server. The supported formats depends on the data point type you selected Examples for DPT-1: `on`, `off`, `true`, `false`, `1`, `0` Examples for DPT-3: `stop`, `"controlled stop"` Examples for DPT-5: `1`, `10`, `20` Examples for DPT-9: `1.23`, `123.456` Examples for DPT-10: `00:00:00`, `12:34:56` Examples for DPT-11: `2000-01-02`, `2050-03-04` Examples for DPT-13: `1234`, `-1234` Examples for DPT-16: `"Hello World"`

The example sets the lamp to On for given KNX Group Address 1/2/100. Based on the data point type 1.001 which stands for Switch which is a boolean representation the KNX know that on is meant to switch on the lamp. Alternatively to on you can use the true or 1 to switch on the lamp.

knx-link-client write -g 1/2/110 -d 1.001 -v on

Advanced: Command Alias (for Linux and MacOS)

If you do not want to enter the IP address of the KNX Link server everytime like ./knx-link-client -h 1.2.3.4 read ... or/and ./knx-link-client -h 1.2.3.4 write ... then you may add a command alias in your profile file which shortens the command to knx read ... and knx write ...:

alias knx='/path/to/knx-link-client -h 1.2.3.4'

Advanced: Functions (for Linux and MacOS)

In case you are working with same KNX Group Addresses and frequently you can implement a function wrapper which shortens the command further or to meet your needs.

Example:

r taken as short alias for read
w taken as short alias for write
In ETS defined KNX Group Addresses
- Kitchen: read address (1/2/113), write address (1/2/110)
- Garage: read address (1/1/33), write address (1/1/30)

#!/bin/bash
KNXLINKCLIENT=/path/to/knx-link-client

declare -A READ_GROUPS
READ_GROUPS[kitchen]="1/2/113"
READ_GROUPS[garage]="1/1/33"

declare -A WRITE_GROUPS
WRITE_GROUPS[kitchen]="1/2/110"
WRITE_GROUPS[garage]="1/1/30"

knx-lamp() {
  GROUP_ADDRESS=""
  if [[ "$1" == "r" ]]; then
    GROUP_ADDRESS="${READ_GROUPS[$2]}"
    if [[ -z "$GROUP_ADDRESS" ]]; then
      echo "Unsupported room"
      return
    fi
    echo "Read Request to '$2': $GROUP_ADDRESS"
    "$KNXLINKCLIENT" read -g "$GROUP_ADDRESS" -d 1
  elif [[ "$1" == "w" ]]; then
    GROUP_ADDRESS="${WRITE_GROUPS[$2]}"
    if [[ -z "$GROUP_ADDRESS" ]]; then
      echo "Unsupported room"
      return
    fi
    VALUE="$3"
    if [[ -z "$VALUE" ]]; then
      echo "No value provided?"
      return
    fi
    echo "Write Request to '$2' with value '$VALUE': $GROUP_ADDRESS"
    "$KNXLINKCLIENT" write -g "$GROUP_ADDRESS" -d 1 -v "$VALUE"
  else
    echo "Unknown command"
  fi
}

Given example above, the usage would be then like:

knx-lamp r garage to fetch lamp status from room 'garage'
knx-lamp w kitchen on to switch lamp on in room 'kitchen'
knx-lamp w kitchen off to switch lamp off in room 'kitchen'