Installation

The HomeKit Bridge for KNX software is available as a binary file and can be installed on most operating systems. It can be installed using the pre-configured Raspberry Pi disk image, manually from the command line or Docker (brutella/hkknx).

Download

The software can be downloaded from GitHub → Releases and runs on macOS, Linux and Raspberry Pi OS.

Platform	Download
Mac 64-bit	hkknx-x.x.x_darwin_amd64.tar.gz
Mac with Apple Silicon 64-bit	hkknx-x.x.x_darwin_arm64.tar.gz
Linux 64-bit	hkknx-x.x.x_linux_amd64.tar.gz
Linux 32-bit	hkknx-x.x.x_linux_386.tar.gz
Raspberry Pi 32-bit	hkknx-x.x.x_linux_arm.tar.gz
Raspberry Pi Disk Image Compatible with Raspberry Pi 5, 4B, 3B, and 3B+	hkknx-x.x.x_rpi.zip

There is also the official Docker image brutella/hkknx.

A license is not required to run the software. But you can't use more than 15 HomeKit accessories. You can buy a license from the built-in web interface. Learn More

Raspberry Pi Image

Here you will learn how to install the Raspberry Pi image. This disk image contains a pre-configured installation of the HomeKit Bridge for KNX. You will only need to copy the data onto your sd card and insert it into the Raspberry Pi. Then connect your Raspberry Pi to the network via Ethernet and you are done.

The disk image is based on a stripped-down version of Linux – which means it uses less power, runs faster and needs less disk space than any previous versions.

This also means, that

ssh is not available
WiFi can only be enabled via the web interface under Settings → More → Open WiFi Settings. You need to plug in an Ethernet cable to enable WiFi. It is still recommended to only use ethernet.

Raspberry Pi Imager

In this guide the Raspberry Pi Imager is used to copy the image onto your sd card.

Download the latest disk image hkknx-{version}_rpi.zip from the project site under Releases. This image is suitable for 8GB SD cards and USB drives.
Launch the Raspberry Pi Imager software
Choose Device
Choose OS
- Use Custom
- Choose the downloaded disk image file
Choose Storage
Next
Would you like to apply OS customisation settings? → No
All existing data on ‘…’ will be erased. Are you sure you want to continue? → Yes
When the copying process is complete, insert the SD card into the Raspberry Pi and then connect the Ethernet cable and power supply.
Wait 1 minute and then open http://hkknx.local:8080 in the browser or find out the IP address via the router/switch and open http://{IP address}:8080.

WiFi

WiFi is disabled by default. If you need WiFi you can enable it with the following steps.

In the web interface go to Settings → More → Open WiFi Settings
Enter the WiFi credentials and save

The device will now restart and try to connect to the WiFi. This may take some minutes.

If you are runnning an the Raspberry Pi image before version 3, you have to do the following steps to enable WiFi.

Remove the entry dtoverlay=disable-wifi from config.txt on the boot partition.
Include the WiFi ssid and password in /etc/wpa_supplicant/wpa_supplicant.conf in the following format.

1# /etc/wpa_supplicant/wpa_supplicant.conf
2ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
3update_config=1
4network={
5ssid="<ssid>"
6psk="<password>"
7}

raspberrypi.org →

Internet Connection

The software has the requirement, that the system time on the computer is up to date.

Since the Raspberry Pi does not have a real-time clock, the time must be updated using NTP every time it restarts.

This happens automatically as soon as an Internet connection is established. Therefore an Internet connection is required, when using hkknx on a Raspberry Pi.

It is recommended to connect the Raspberry Pi to the home network via Ethernet before starting.

On other systems (Linux server, Mac), an Internet connection is not required as long as the system time is correct.

Command Line

When installing via the command line, the required files are downloaded and installed manually. In this article you will learn how to install hkknx on a Mac computer with Apple silicon from the command line.

Download the latest version of hkknx from the releases page. For the Mac we download and unarchive the file with suffix ..._darwin_arm64.tar.gz.

1wget https://github.com/brutella/hkknx-public/releases/download/3.1.0/hkknx-3.1.0_darwin_arm64.tar.gz
2tar -xzf hkknx-3.1.0_darwin_arm64.tar.gz
3ls
4# INSTALLATION.md  hkknx  hkknx-3.1.0_darwin_arm64.tar.gz

Installation

Once you have downloaded and unpacked the archive, you execute the file hkknx with the option --db=./database. The option db is mandatory and set the folder in which data is stored.

1./hkknx --db=./database

More useful commands are

--port is the port of the web ui (defaults to 8080)
-–verbose enables debug log outputs in the system log

The software only consists of the executable file "hkknx". There are no dependencies to other projects. knxd is not needed.

Update

Installing updates can easily be done through the web interface. Click on the version number at the bottom of the page and choose “Check for Update”. Then choose a version and click on “Install”.

Command Line

Installing a new version can only be done using the command line.

Check out the available downloads to see which operating systems are supported. You will find the latest version on GitHub → Releases.

Then you can download and unarchive a new version.

1wget https://github.com/brutella/hkknx-public/releases/download/3.1.0/hkknx-3.1.0_darwin_arm64.tar.gz
2tar -xzf hkknx-3.1.0_darwin_arm64.tar.gz
3ls
4# INSTALLATION.md  hkknx  hkknx-3.1.0_darwin_arm64.tar.gz

Once you have downloaded a version from GitHub, you have to replace the old hkknx file with the new one.

If you don’t know, where the executable is located, you can run the command which hkknx to find out.

Pre-Releases

Pre-releases are beta versions, and contain new changes and features. You can install them via the web interface but they might cause unexpected behaviour.