HomeKit Anbindung mit Raspberry Pi 3 + KNX IP Gateway

(Update für HomeKit 0.3.x, November 2016)

Dieser Artikel erläutert, wie man einen Raspberry Pi 3 einrichtet um eine Bridge für HomeKit zu installieren. Dadurch wird es möglich, auch mittels Siri, über sein iPhone seine KNX Installation zu Hause zu steuern.

Die Anleitung richtet sich an Anfänger (bin ich in Bezug auf Raspberry auch selber) und geht von einer Neuinstallation aus.

Wer es gerne etwas kompakter mag, darf sich gerne die Kurzanleitung ansehen.

Folgende Komponenten werden benötigt:

Hardware

• KNX IP Gateway
• Raspberry Pi 3

Software

• nodejs
• homebridge
• homebridge-knx
• knxd

Geräteauswahl

Ziel war es, hier kein Virtualisierung zu verwenden sondern ein Gerät irgendwo im Keller oder im Haus zu deponieren, welches brav seinen Dienst als KNX Bridge für HomeKit versieht. Ein Raspberry bietet sich an, und Angebot gibt es viele. Da ich noch etwas mehr experimentieren will, habe ich ein Raspberry Pi 3 Kit besorgt, bei dem schon alles dabei ist: Netzteil, Gehäuse, HDMI Kabel, Bastelset, Speicherkarte und der Raspberry. Passt. Mit Amazon Prime am nächsten Tag geliefert, so kann das Experimentieren schnell losgehen.

Ein netter Freund hat mich darauf hingewiesen, dass ich doch bitte dieses Bastelgehäuse sein lassen soll. Im Elektroversand gäbe es bspw. auch einen Raspberry Pi mit Gehäuse für die Hutschiene + Netzteil. Ist natürlich deutlich schicker für später im Einbau im Elektroschrank. (Beispielsweise bei Conrad Elektronik)

Installation

Der Raspberry wird einfach per HDMI an den Fernseher angeschlossen und los geht’s. SD Karte vorher einlegen, evtl. Ethernet anschliessen und los. Aber: Ethernet braucht man nicht mehr! Der Raspberry Pi 3 verwendet auch perfekt WLAN und tatsächlich ist auch die Installation und Performance über Ethernet im Vergleich zu WLAN identisch (nämlich SD Karten abhängig langsam). Bei mir waren nicht mehr als 500kB/sec Download + Installation möglich – und das liegt nicht an der Internetanbindung.

Hinweis: Bei der Eingabe des Kennwort für das WLAN sollte man darauf achten den richtigen Tastaturtyp eingestellt zu haben. Diese Möglichkeit wird ganz unten am Bildschirm als Auswahlmenü angeboten.

Nach ca. 1h meldet sich schliesslich der Raspberry als fertig installiert, und man kann Durchstarten.

Konfiguration des Raspberry

Eine erste Anmeldung erfolgt mit dem Standardnutzer und Passwort:

• Nutzername: pi
• Passwort: raspberry

Die schicke (nunja) PIXEL Oberfläche möchte man evtl. per VNC nutzen. Also aktiviert man unter dem Raspberry Menü -> Einstellungen den VNC Dienst und kann schon von seinem Mac aus direkt mit VNC Viewer auf seine Himbeere zugreifen. Alternativ kann man den Remotezugriff auch per Terminal einrichten:

sudo raspi-config

Effizienter wird im Folgenden aber der Zugriff per Terminal sein. Der nötige SSH Dienst ist von Haus aus aktiv.

Hinweis: es wird später nicht mehr erwähnt, aber es versteht sich von selbst, dass der Standardnutzer ein neues Passwort erhalten sollte!

Nach der Erstinstallation ist der Raspberry aber beileibe noch nicht mit aktuellen Paketen installiert. Eine Auffrischung aller installierten Komponenten schadet also nicht.

Man öffnet sich also ein Terminalfenster (Juhu!) und führt das Linux Debian Upgrade durch:

sudo apt-get update
sudo apt-get dist-upgrade

Hinweis: An dieser Stellt können wir getrost „dist-upgrade“ statt „upgrade“ verwenden, da wir eine Neuinstallation durchführen. Da danach einzelne Komponenten nicht mehr über apt installiert werden, sollte hier vorsichtigerweise auf apt-get upgrade umgestellt werden.

Installation der „HomeBridge“

Die HomeBridge ist ein OpenSource Projekt, welches eine Anbindung an HomeKit von Apple erlaubt.

Im Prinzip funktioniert die Heimkonfiguration von Apple nämlich wie folgt:

• zertifizierte Geräte können direkt am iPhone registriert werden
• Geräte anderen Typs, können über eine Bridge (Brücke) an HomeKit auf dem iPhone registriert werden. Über eine Bridge werden also alle Geräte für das iPhone zugänglich die selbst nicht HomeKit fähig sind. Dabei können das verschiedene Systeme sein. Für jedes System am Markt gibt es im HomeBridge Projekt eine Plugin oder auch hier SHIM genannt (weil es eine transparente Hardwarekompatibilitätserweiterung in Software darstellt).
• AppleTV oder ein an der Stromversorgung angeschlossenes iPad können als Remotezugang dienen.

Damit wir also unser KNX-Anlage zu Hause anbinden können, wird zwingend eine Bridge benötigt. Derzeit (Nov. 2016) gibt es keinen Anbieter am Markt, der eine Lösung in Hardware anbietet. Das Startup Thinka arbeitet allerdings bereits an einer Lösung, so dass dann diese „Bastelllösung“ mit einem Raspberry in Zukunft entfallen wird.

Konfiguration Homebridge

Nachfolgend benötigen wir weitere Pakete die für homebridge nötig sind. Namentlich node.js ist, welches bei meiner Raspberry version in einer veralteten 0.10.x Version installiert ist. Die aktuellste Version sollte es tun.

Der C-Compiler gcc wird in Version 4.9 oder höher benötigt, und sollte bereits installiert sein (durch das vorhergehende Upgrade). Überprüfung mittels gcc -v.

Nun benötigen wir also die aktuelle Version von Node.js. Die Homepage listet dafür folgende Kommandosequenz:

curl -sL https://deb.nodesource.com/setup_6.x | sudo -E bash -
sudo apt-get install -y nodejs

Anschliessend benötigt homebridge noch die AVAHI Bibliothek:

sudo apt-get install -y libavahi-compat-libdnssd-dev

Nun kann endlich homebridge installiert werden

sudo npm install -g homebridge homebridge-knx

Fertig. Die homebridge Installation findet sich nun unter /usr/lib/node_modules/.

Für den Autostart mit dem Raspberry Pi 3 (der unter Debian Jessie läuft), bietet Johann Richard eine Kurzanleitung für die Einbindung in den Systemstart mit systemd.

Wir benötigen einen Systemnutzer, welcher die Konfig-Datei config.json enthält:

sudo useradd --system homebridge
sudo mkdir /var/homebridge
sudo chown homebridge /var/homebridge

Unter /etc/default wird dabei die Datei homebridge neu angelegt und wie folgt gefüllt:

sudo nano /etc/default/homebridge

Inhalt:

# Defaults / Configuration options for homebridge
# The following settings tells homebridge where to find the config.json file and where to persist the data (i.e. pairing and others)
HOMEBRIDGE_OPTS=-U /var/homebridge

# If you uncomment the following line, homebridge will log more 
# You can display this via systemd's journalctl: journalctl -f -u homebridge
# DEBUG=*

Und für die Servicebeschreibung unter /etc/systemd/system die Datei homebridge.service angelegt:

sudo nano /etc/systemd/system/homebridge.service

Inhalt:

[Unit]
Description=Node.js HomeKit Server 
After=syslog.target network-online.target

[Service]
Type=simple
User=homebridge
EnvironmentFile=/etc/default/homebridge
ExecStart=/usr/lib/node_modules/homebridge/bin/homebridge $HOMEBRIDGE_OPTS
Restart=on-failure
RestartSec=10
KillMode=process

[Install]
WantedBy=multi-user.target

Und jetzt noch starten:

sudo systemctl daemon-reload
sudo systemctl enable homebridge
sudo systemctl start homebridge

Hinweis: Die Log-Daten können wieder über /var/log/syslog abgegriffen werden.

Nun kann man schon das iPhone (vorausgesetzt es befindet sich im selben Netz), mit der Bridge koppeln.

Der Initiale Code lautet: 031-45-154 (oder kann über syslog ausgelesen werden). Dieser Code ist der Default-Code der auch verfügbar ist, wenn noch keine Konfigurationsdatei verfügbar ist.

Konfiguration des KNX SHIM (Plugin)

Nun wollen wir aber endlich unsere KNX Installation zum Leben erwecken. Dazu erzeugen wir eine config.json Datei, welche im Homeverzeichnis des Systemnutzers „homebridge“ liegt. Nach dieser Vorgehensweise also unter /var/homebridge.

In der Version 0.3 wurde die Art der Konfiguration. Wer also bisher Version 0.2 verwendet hat, muss hier umstellen.

Es werden zwei Konfigurationsdateien benötigt. In der config.json Datei findet sich die Hauptkonfiguration der Bridge an sich, und in der knx-config.json die Gerätekonfiguration die über den KNX Bus erreicht werden sollen.

Beispielkonfiguration für die Bridge

sudo nano /var/homebridge/config.json

und folgende „Grundkonfiguration“ einfügen:

{
  "bridge": {
    "name": "Homebridge",
    "username": "CC:22:3D:E3:CE:30",
    "port": 51826,
    "pin": "031-45-154"
  },
  "description": "This is an example ....",
  "platforms": [ ],
  "accessories": [ ]
 }

Werden mehrere homebridge Installationen betrieben, sollte man auch die MAC-Adresse der virtuellen Hardware („username“) ändern, damit nicht Geräte doppelt im Netz auftauchen.

Die Konfiguration der KNX Geräte erfolgt nun über die Datei knx_config.json.

Eine ausführliche Beschreibung wie die Datei aufgebaut ist findet sich auf der Projektseite.

Die Grundkonfiguration dieser Datei sieht wie folgt aus:

{
    "knxd_ip": "127.0.0.1",
    "knxd_port": 6720,
    "AllowWebserver": true,
    "AllowKillHomebridge": false,
    "Devices": [ ]
}

Wichtig ist die Verbindung zum knxd, der auch auf dem Raspberry läuft, daher kann die Adresse 127.0.0.1 verwendet werden.

Spannend ist nun auch die Möglichkeit über ein kleines Webinterface auf die konfigurierten Geräte zuzugreifen. Im Moment ist das lediglich zum debuggen sinnvoll und für den Betrieb sollte der Webserver ausgeschalten (false)  werden. Aber vielleicht tut sich hier in Zukunft noch mehr.

Hier nun ein komplettes Beispiel für eine einfache Lampensteuerung.

sudo nano /var/homebridge/knx_config.json

Inhalt wie folgt (Achtung bei der Gruppenadresse!):

{
    "knxd_ip": "127.0.0.1",
    "knxd_port": 6720,
    "AllowKillHomebridge": true,
    "Devices": [
        {
            "DeviceName": "Wohnzimmer Lampe",
            "Services": [
                {
                    "ServiceType": "Lightbulb",
                    "ServiceName": "Wohnzimmerlampe",
                    "Characteristics": [
                        {
                            "Type": "On",
                            "Set": [
                                "1/3/5"
                            ],
                            "Listen": [
                                "1/3/5"
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Zum Schluss müssen wir noch die Schreibrechte an den Nutzer „homebridge“ übertragen, sonst kann die knx_config.json nicht verwaltete werden:

sudo chown -R homebridge.homebridge /var/homebridge/

Damit nun aber auch die Kommunikation zum KNX-Bus funktioniert, wird noch der Kommunikationsprozess benötigt, welcher leider nicht Bestandteil von homebridge ist: der knxd.

Installation des „knxd“ (aka „eibd“)

Ursprünglich wurde ein Projekt bzw. Diplomarbeit an der TU-Wien gestartet für die Anbindung an den KNX Bus. Als Teilprojekt wurde der eibd entwickelt, auf den noch immer viele Anleitungen verweisen. Wer Lust verspürt kann auch in der tollen Beschreibung von Martin Kögler, dem Autor, zu diesem Projekt schwelgen.

Da der Autor dann aber langsam die Unterstützung eingestellt hat, wurde ein Fork des ursprünglichen Quelltexts durchgeführt und es entstand der knxd. Dieser wird aktuell von einer engagierten Community gepflegt und ist daher die erste Wahl zur Kommunikation mit dem EIB Bus.

Installiert wird der knxd einfach nach der Anleitung der Projektseite, mit ein paar kleinen Ergänzungen, wie bspw die cdbs und andere Abhängigkeiten die noch installiert werden müssen. Mein modifiziertes Script sieht daher wie folgt aus:

# Do not use "sudo" unless told to do so.
# If "dpkg-buildpackage" complains about missing packages
# ("Unmet build dependencies"): install them
# (apt-get install …) and try that step again.
# If it wants "x | y", try just x; install y if that doesn't work.
# Also, if it complains about conflicting packages, remove them (duh).

# first, install build tools and get the source code
sudo apt-get install -y git-core build-essential cdbs autoconf automake libtool libsystemd-dev libsystemd-daemon-dev dh-systemd base-files libusb-1.0.0-dev
git clone https://github.com/knxd/knxd.git

# knxd requires libpthsem which unfortunately isn't part of Debian
wget https://www.auto.tuwien.ac.at/~mkoegler/pth/pthsem_2.0.8.tar.gz
tar xzf pthsem_2.0.8.tar.gz
cd pthsem-2.0.8
dpkg-buildpackage -b -uc
cd ..
sudo dpkg -i libpthsem*.deb

# now build+install knxd itself
cd knxd
dpkg-buildpackage -b -uc
cd ..
sudo dpkg -i knxd_*.deb knxd-tools_*.deb

Danach ist der knxd unter /var/lib/knxd installiert.

Die Konfigurationsdatei findet sich unter /etc/knxd.conf.

Konfiguration und Start des knxd

Die Konfiguration des knxd scheint der aufwändigste Teil zu sein. Technisch ist es wohl kein Problem, nur wird offenbar ein gewisses Know-How für die zahlreichen Optionen vorausgesetzt.

In meinem Szenario soll eine KNX Installation per IP Gateway angebunden werden. Die Installation beruht zum Großteil auf GIRA Komponenten und somit auch das Gateway. Das Gateway wurde schon vorher für die Konfiguration für den GIRA Homeserver benötigt und konfiguriert: es leitet alle Paket aus dem EIB BUS auf IP und umgekehrt. Das es funktioniert kann also sehr leicht über die ETS bzw. den Homeserver überprüft werden: die ETS kann darüber den Bus monitoren, und der Homeserver bringt seine Logik ein. Also diese Komponente kann dann als „funktionierend“ abgehakt werden. Bei anderen Gateways sollte das vorher überprüft werden!

Den knxd kann man auf verschieden Arten nutzen, daher kann es hilfreich sein, ein paar Daten bereit zu halten:

• Die IP des Gatways (bei mir 10.0.1.100)
• Die EIB ID des Geräte (bspw. 1.1.100)
• Die Multicast Adresse (Standard: 224.0.23.12)

Die Konfigurationsdatei für den knxd liegt unter /etc/knxd.conf und kann dort editiert werden.

 sudo nano /etc/knxd.conf

Hier kann man nun mit seiner eigenen Installation arbeiten, und bspw. das KNX/IP Tunneling einsetzen. Die Autoren des knxd empfehlen aber auch selbst den Einsatz als Multicast Server und das hat auch bei mir funktioniert. Alle obigen Daten braucht man dann nicht denn es funktioniert ganz einfach mit folgender Optionszeile:

KNXD_OPTS="-D -T -R -S"

Hinweis: wer den knxd debuggen will, kann beispielsweise folgende Optionen ergänzen:

KNXD_OPTS="--trace=1023 -D -T -R -S"

Wichtig ist hier die --trace Option. Mittels tail -f /var/log/syslog.d kann man dann in einem zweiten Terminalfenster hübsch mitlesen was so alles passiert. Alle Optionen sind auf der knxd Homepage gelistet.

Und nun kann man den knxd starten. Der Start erfolgt auf aktuellen Systemen wie dem Raspberry mittels dem systemd. Dadurch wird der Systemdienst im Hintergrund gestartet.

Kontrolliert wird der knxd wie folgt:

# Starten
sudo systemctl start knxd.service

# Stoppen
sudo systemctl stop knxd.service

# Konfig neu laden
sudo systemctl restart knxd.service

Hinweis: beim Raspberry Pi 3 ist es auf Grund der Verwendung des systemd nicht notwendig eine Socket-Datei  oder einen Port anzugeben oder zu nutzen. Das passiert automatisch durch den Systemdienst.

Herzlichen Glückwunsch! Nun sollte die KNX-IP Homebridge funktionieren!

Falls es nicht gleich klappt:

• Die Systemdienste neu starten, evtl. wurde ein Config-File noch nicht aktualisiert.
• Die config.json und knx_config.json Datei ist sehr empfindlich gegenüber Sonderzeichen, Zeilenumbrüchen, etc.
• das Caching könnte auch zuschlagen, gerade wenn man viel an den Dateien herumspielt. Wenn man es sich leisten kann
  • Homebridge stoppen (s.o.)
  • accessories/ leeren, evtl. auch das persist/ Verzeichnis
  • Homebridge neu starten
  • Haus neu anlegen

Die meisten Anmerkungen beziehen sich auf Unterschiede auf die benötigten Bibliotheken die zusätzlich oder anders eingebunden werden solle/müssen. Hier kann sich jeder schnell selber helfen. Einfach die entsprechenden Fehlerzeile durchlesen. Hier wird immer erwähnt, welche Bibliothek noch im System fehlt. Diese dann einfach in der sudo apt get install Zeile ergänzen.

Über Kommentare, Verbesserungsvorschläge freue ich mich!

Referenzen

• Homebridge Homepage
• Homebridge KNX SHIM (und bekannte Probleme)
  • Beschreibung der knx_config.json Datei
  • Änderungen zur Version 0.2.x
• KNXD Homepage
• Node.js Homepage
• Systemd Anleitung