Manual Install

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

Download

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

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

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