Configuration

The HomeKit bridge for KNX includes a web user interface to configure and setup the system. You can access it through your browser by entering the ip address (or hostname) and port 8080.

When you are using the pre-configured Raspberry Pi disk image, the web user interface is available at http://hkknx.local:8080.

New Project

Create new project

The first step is to create a new project. The best way to get started is to import an existing ETS project.

Even though an ETS project is not required to use hkknx, it makes configuring the HomeKit accessories easier.

When you import an ETS project, all group address, communication objects and building parts (rooms, floors, …) are stored locally. If your ETS project is secured with a password, you have to enter the password in order to successfully decrypt it.

Passwords, which are used to import an ETS project, are not stored on disk.

If an ETS project is imported twice, all objects are also saved twice. This results in duplicates – e.g. a group address appears twice. If one of the two projects is deleted again, the group addresses of the other project remain.

HomeKit accessories are not altered when deleting an ETS project - all references to the group addresses remain.

KNX Connection

The connection to KNX is configured under Settings. The HomeKit bridge for KNX establishes an IP tunneling connection to the KNX installation. A KNXnet/IP gateway is required for this.

By default, the IP address of the gateway is determined automatically. If this is not possible for some reason, the IP address of the gateway can also be set.

The connection status can be determined by clicking on Check Connection.

Netzwerk Requirements

In order for the HomeKit bridge to establish a connection with HomeKit, multicast (for mDNS) must be allowed in the network. The multicast addresses 224.0.0.251 (IPv4) and ff02::fb (IPv6) as well as port 5353 are used for this.

Multicast is also required for the automatic search of the KNX IP gateway. The multicast address 224.0.23.12 and port 3671 are used for this.

The network must support IPv4 addresses. HomeKit does not work with IPv6-only networks.

Ports

Ports 5353 and 3671 are used for multicast requests. Unless further configured in the settings, the bridge communicates with HomeKit on a random port. However, this port can be set in the settings.

Secure Tunneling

Since version 2.4, KNX Secure Tunneling is supported to establish a secure connection between the HomeKit bridge and the KNX gateway. To do this, secure tunneling must be configured via the ETS and a compatible KNX gateway must be available.

The connection data is specified in the HomeKit bridge under Settings → KNX Gateway → Secure Connection.

Authentication Code

The authentication code can be found in the ETS under the properties of the KNX IP gateway.

Channel & Password

KNX gateways provide one or more secure tunnel connections. Each channel is assigned a number and a password. You can find the passwords in the ETS under the details of the KNX gateway.

This is what it looks like with a MDT IP interface with secure.

If you select a channel, you can see the associated password in the properties.

HomeKit Connection

KNX

To control the devices via HomeKit, the bridge must be added to HomeKit. To do this, the “Enable bridge” option must be active under Settings.

It is also necessary that there is a connection to the KNX IP gateway. As long as there is no connection, the bridge is not available for HomeKit.

Using the Home app, the bridge can be added to HomeKit as follows.

Open the Home app
Tap
Add device
Scan QR code or enter PIN (see Settings → HomeKit Bridge)

Connection problems?

Password Protection

Under Settings → Password Protection, access to the web interface can be protected with a password. This password is stored encrypted in the local database.

Password protection does not offer 100% protection of the data. When accessing the local database, for example via SSH, the password protection can be bypassed.

Lock Message

The lock message is displayed when the user is asked to enter the password. The Markdown notation can be used for formatting. This means that links and images can easily be embedded in the blocking message.

Here is an example of a blocking message.

1**Access not allowed**
2
3This project is password protected. Enter a password to continue.
4
5---
6
7If you have any problems, please call Mr. Hochgatterer at [+43 660 1234567](tel:+436601234567) or send an email to [hkknx@hochgatterer.me](mailto:hkknx@hochgatterer.me).

This message is displayed as follows when entering the password.

Access not allowed

This project is password protected. Enter a password to continue.

If you have any problems, please call Mr. Hochgatterer at +43 660 1234567 or send an email to hkknx@hochgatterer.me.

Backup

After the bridge has been put into operation, it makes sense to create a data backup. A data backup contains all of the bridge’s settings and devices in a .backup file. If data is lost, a data backup can be imported again. This will restore all settings and devices.

To create a backup, go to Settings → More → Create Backup. To restore a backup, select “Import Backup…”.

License

In order to use the software to its full extent, a license must be purchased in the web interface under Settings → License. After successful purchase, a license key will be generated that can only be used on one computer.

A license currently costs € 299.

If you want to transfer a license to another computer, you must first remove the license via the web interface.

The license key is then entered via the web interface under Settings → License → Enter license.

Did an error occur during purchase? Help →