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 or manually from the command line.

Download

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

Raspberry Pi Image

Here you will learn how to install the Raspberry Pi OS 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.

Raspberry Pi Imager

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

1. Download the latest disk image 2023-02-27-raspio-lite_hkknx-2.7.1_linux_arm.img.gz from the project site under Releases.
2. Launch the Raspberry Pi Imager software
3. Choose Device
4. Choose OS
   • Use Custom
   • Choose the downloaded disk image file
5. Choose Storage
6. Next

When copying the data is completed, you insert the sd card into your Raspberry Pi.starten.

Internet Connection

It is recommended that your Raspberry Pi is connected to the internet via Ethernet. An internet connection is used to update the date and time of your Raspberry Pi.

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

1. Remove the entry dtoverlay=disable-wifi from config.txt on the boot partition.
2. 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
4
5network={
6ssid="<ssid>"
7psk="<password>"
8}

raspberrypi.org →

Once your Raspberry Pi is connected to your local network via Ethernet (or WiFi), you can access the web interface with the url http://hkknx.local:8080.

The disk image is based on the Raspberry Pi OS. For security reasons the following changes has been made.

• The user pi is deleted.
• A new user admin is created. The password for this user is homekitbridgeforknx.
• SSH is disabled for the user admin.
• The hostname is changed to hkknx.
• WiFi is disabled with the dtoverlay=disable-wifi in /boot/config.txt. Source

Manual Install

In this article you will learn how to install hkknx on a Raspberry Pi running Raspberry Pi OS from the command line.

First you have to connect to your Raspberry Pi via SSH. Raspbian has the default password for SSH set to raspberry.

1ssh pi@raspberrypi.local
2# pi@raspberrypi.local's password: raspberry

Then you download the latest version of hkknx from the releases page. For the Raspberry Pi we download and unarchive the file with suffix ..._linux_arm.tar.gz.

1wget https://github.com/brutella/hkknx-public/releases/download/2.6.0/hkknx-2.6.0_linux_arm.tar.gz
2tar -xzf hkknx-2.6.0_linux_arm.tar.gz
3ls
4# INSTALLATION.md  hkknx  hkknx-2.6.0_linux_arm.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

Configure as daemon

If you want to run hkknx continuously in the background, you have to create an service/daemon. On a Raspberry Pi you can configure a systemd service. The service will execute the command /home/pi/hkknx --db=/home/pi/database automatically when the operating system is started.

1. Create service file with vim

1$ vim /etc/systemd/system/hkknxd.service

2. Insert content

You can use the following content for the hkknx.service file.

 1[Unit]
 2Description=HomeKit Bridge for KNX
 3After=network.target
 4
 5[Service]
 6ExecStart=/home/pi/hkknx --db=/home/pi/database
 7WorkingDirectory=/home/pi
 8StandardOutput=inherit
 9StandardError=inherit
10Restart=always
11User=pi
12
13[Install]
14WantedBy=multi-user.target

It’s important to use the correct path to the hkknx executable file and the database folder. In the example above the executable file is expected to be at /home/pi/hkknx and the database folder at /home/pi/database.

3. Starting and stopping a service

You can start and stop a service by executing the following commands.

1$ systemctl start hkknxd.service
2$ systemctl stop hkknxd.service

The log outputs are shown when executing the status command.

1$ systemctl status hkknxd.service

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 Udate”. 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](/hkknx/docs/install/#download page 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/2.6.0/hkknx-2.6.0_linux_arm.tar.gz
2tar -xzf hkknx-2.6.0_linux_arm.tar.gz
3ls
4# INSTALLATION.md  hkknx  hkknx-2.6.0_linux_arm.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. If you are using the pre-configured Raspberry Pi image, the executable is stored at /usr/bin/hkknx.

1# Stop service
2sv stop hkknx
3
4# Replace executable file
5mv ./hkknx /usr/bin
6
7# Start service 
8sv start hkknx

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.