Das folgende Dokument beschreibt in einer einfachen Schritt für Schritt Anleitung, wie mit Hilfe der Open Source Applikation HtREST eine Heliotherm Wärmepumpe an eine Loxone Steuerung angebunden werden kann.

Benötigte Hardware & Anbindung

Benötigt wird für die Kopplung nur

• ein Raspberry Pi

• mit Netzwerkanbindung (kabelgebunden oder per WLAN spielt dabei keine Rolle) und

• serieller Verbindung zur Heliotherm Wärmepumpe, z.B. mittels USB auf RS232 Adapter.

Für die serielle Verbindung zur Regeleinheit der Wärmepumpe (D-Sub Stecker -X26 "Modem COM") wird ein ausgekreuztes 9-poliges RS232-Kabel (Nullmodemkabel) benötigt.

Einen möglichen Aufbau zeigen z.B. die folgenden beiden Fotos:

Open

Open

Der Aufbau besteht hier aus einem

• Raspberry Pi Zero mit

• Zero4U 4-Port USB Hub an dem

• ein USB auf RS232 Adapter für die serielle Verbindung zur Wärmepumpe und

• ein USB auf RJ45 Ethernet Netzwerkadapter für die Anbindung ans Heimnetz

angeschlossen ist.

Das ganze montiert auf dem noch freien Platz auf der Hutschiene in der Wärmepumpe.

Natürlich ist es auch möglich den Raspberry Pi außerhalb der Wärmepumpe zu platzieren und nur das serielle RS232-Kabel in die Wärmepumpe zu führen.

Vorbereitung

Als Betriebssystem am Raspberry Pi reicht das Raspbian Buster Lite (Minimal image based on Debian Buster) ohne Desktop-Unterstützung, rein nur mit Konsole.

Für den Zugriff auf den Raspberry Pi wird weiters ein ssh-Zugang benötigt.

Wie dieser aktiviert werden kann ist z.B. hier beschrieben:

    https://www.raspberrypi.org/documentation/remote-access/ssh/

Zu empfehlen ist es, dem Raspberry Pi auch gleich eine statische IP-Adresse zu spendieren und ihm einen geeigneten Hostnamen zuzuweisen.

Anleitungen dazu finden sich zur genüge im Netz:

• https://www.elektronik-kompendium.de/sites/raspberry-pi/1912151.htm

• https://www.elektronik-kompendium.de/sites/raspberry-pi/2007021.htm

Des Weiteren sollte man dann auch gleich kontrollieren, ob Datum und Uhrzeit stimmt oder noch besser die automatische Synchronisierung per NTP einrichten.

Zu beachten ist hier, dass man die richtige Zeitzone verwendet.

Eine ausführliche Beschreibung dazu findet man z.B. hier:

    https://raspberrytips.com/time-sync-raspberry-pi/

Installation & Test

Sind diese Grundvoraussetzungen erfüllt, kann auch gleich mit der eigentlichen Installation der benötigten Softwarepakete begonnen werden.

Zuerst verbinden wir uns mittels ssh mit dem Raspberry Pi und führen eine Aktualisierung aller Paketquellen und der installierten Pakete durch:

Anschließend installieren wir noch das benötigte Paket zum Erstellen von virtual environments unter Python:

Somit können wir die benötigte HtREST Applikation in einer eigenen, isolierten Umgebung installieren und bewahren uns somit vor möglichen Versionskonflikten installierter Python Pakete.

Python 3.7 oder neuer sollte bereits installiert sein, was ganz einfach mittels folgendem Aufruf überprüft werden kann:

Danach erstellen wir uns die bereits oben erwähnte virtuelle Arbeitsumgebung (virtual environment) für die HtREST Applikation:

Diese virtuelle Arbeitsumgebung muss dann noch mittels

aktiviert werden.

Ob eine virtuelle Arbeitsumgebung gerade aktiv ist, lässt sich sehr schön daran erkennen, dass der Name der aktiven (virtuellen) Arbeitsumgebung in Klammern dem Kommandozeilen-Prompt vorangestellt wird:

Verlassen lässt sich die virtuelle Arbeitsumgebung einfach mittels:

Zum Installieren der HtREST Applikation innerhalb der virtuelle Arbeitsumgebung muss diese aber natürlich aktiviert sein.

Zur Installation selber reicht dann der folgende Aufruf:

Hat das alles ohne Probleme funktioniert, kann die HtREST Applikation auch schon mal testhalber händisch gestartet werden:

Hier muss natürlich der richtige Pfad des seriellen Device und die IP-Adresse des Raspberry Pi auf dem die Applikation läuft entsprechend angepasst werden.

Die USB auf RS232 Adapter sind dabei meist unter /dev/ttyUSB0, /dev/ttyUSB1, usw. zu finden, einige wenige Typen allerdings auch unter /dev/ttyACM0, /dev/ttyACM1, usw.:

Sollte ein anderer Port als der standardmäßig verwendete Port 8777 verwendet werden, so muss dieser natürlich auch noch mittels dem Argument "--port" angegeben werden.

Zu beachten ist auch, dass die verwendete Baudrate der seriellen Verbindung mit der Einstellung auf der Wärmepumpe übereinstimmen muss.

Diese lässt sich im Menü der Wärmepumpe unter "Modem", "Baud Rate" ändern.

Die Einstellung "Verbindungsart" unter "Modem" muss dabei auf "Direkt" gesetzt sein.

Diese Einstellungen lassen sich allerdings nicht als normaler Benutzer vornehmen, weshalb man sich vorher unter dem Menüpunkt "Benutzerebene" als "Fachmann" anmelden muss.

Die HtREST Applikation besitzt noch weitere Aufrufargumente, welche mit dem folgenden Kommando aufgelistet werden können:

Des Weiteren sind diese auch auf der GitHub-Seite des Projekts unter dem Abschnitt "Usage" zu finden.

Lässt sich die HtREST Applikation wie hier ohne Fehler starten,

kann auch schon mittels Webbrowser auf die Swagger UI Seite der HtREST Applikation unter

    http://192.168.11.99:8777/api/v1/

gewechselt und die einzelnen Funktionalitäten getestet werden.

Natürlich ist auch hier die IP-Adresse (und Port-Nummer) wieder entsprechend anzupassen.

Innerhalb dieser Swagger UI Seite lassen sich alle unterstützten Kommandos interaktiv ausprobieren und testen.

Eine detaillierte Beschreibung aller Kommandos findet sich wieder auf der GitHub-Seite des Projekts.

Des Weiteren muss für die Zusammenarbeit mit Loxone das Argument "--bool-as-int" angegeben werden, damit die HtREST Applikation boolesche Werte (true/false) als numerische Werte (0/1) interpretiert und auch zurückliefert.

Die Loxone Steuerung kann nämlich leider keine boolesche Werte verarbeiten.

Zugriff von Loxone aus

Als nächstes kann man sich daran machen, die gewünschten Parameter der Heliotherm Wärmepumpe auf der Loxone mittels "Virtuellen HTTP Ein- bzw. Ausgängen" verfügbar zu machen.

Lesender Zugriff

Zuerst erstellen wir uns zum Lesen einer oder mehrerer Parameter von der Wärmepumpe einen "Virtuellen HTTP Eingang" unter den "Virtuellen Eingängen" in der Loxone Config.

Unter den Eigenschaften des "Virtuellen HTTP Eingang" vergeben wir diesem erst einmal eine ordentliche Bezeichnung, wie z.B. "HT alle Parameter" (zum Lesen des gesamten Parametersatz von der Wärmepumpe).

Als URL geben wir den Link zur Abfrage aller bekannten Heliotherm Parameter lt. Beschreibung auf der HtREST GitHub-Seite an, wobei IP-Adresse und Portnummer natürlich wieder entsprechend angepasst werden muss:

Abfragezyklus, Timeout und Anzahl erlaubte Timeouts kann entsprechend den eigenen Vorstellungen gewählt werden.

Hier wird z.B. alle 60 Sekunden der gesamte bekannte Parametersatz von der Wärmepumpe gelesen, wobei das Timeout bei 4 Sekunden liegt.

Was dabei unter "gesamte bekannte Parametersatz" zu verstehen ist, wird etwas später genauer erläutert.

Anschließend fügen wir einen "Virtueller HTTP Eingang Befehl" zum Extrahieren der empfangenen Daten von der HtREST Applikation ein.

Die angefragten Parameter kommen von der HtREST Applikation im JSON-Format zurück, für die obige Anfrage unter http://192.168.0.156:8080/api/v1/param/ also z.B.:

Um nun z.B. den Wert für den Parameter "HKR RLT Soll_0 (Heizkurve)" aus der JSON-Antwort zu extrahieren, geben wir gemäß der Loxone Dokumentation unter "Befehlserkennung" des "Virtueller HTTP Eingang Befehl" folgendes ein:

Wichtig dabei ist zwischen den beiden \i Kennungen der Parametername inklusive den doppelten Anführungszeichen oben, dem Doppelpunkt und dem Leerzeichen!

Nur so kann die Loxone durch einen passenden Match den zugehörigen Parameterwert ermitteln.

Es sei nochmals kurz erwähnt, dass die Loxone hier nur Zahlenwerte verarbeiten kann, weshalb auch die Verwendung des Arguments "--bool-as-int" beim Aufruf der HtREST Applikation erforderlich ist.

Zusätzlich lassen sich über die Einstellungen unter dem Punkt "Validierung" des "Virtueller HTTP Eingang Befehl" die empfangenen Werte noch auf ihre Gültigkeit hin überprüfen.

Minimal und Maximalwert der gängigsten Parameter findet man z.B. hier:

    https://htheatpump.readthedocs.io/en/latest/htparams.html

Mit welcher Einheit der ausgelesene Parameterwert dargestellt werden soll, lässt sich über den Punkt "Einheit" im "Virtueller HTTP Eingang Befehl" definieren:

^{<v.1> °C}

Für alle weiteren Parameter sind einfach die soeben beschriebene Schritte zum Anlegen eines "Virtueller HTTP Eingang Befehl" zu wiederholen.

Schreibender Zugriff

Das Schreiben eines Parameters von der Loxone Steuerung aus läuft recht ähnlich ab.

Dazu erstellen wir uns einen "Virtuellen Ausgang" unter den "Virtuellen Ausgängen" in der Loxone Config.

Dann vergeben wir diesem wieder einen ordentlichen Namen und tragen unter der Adresse in den Einstellungen die URL ein, unter der die HtREST Applikation erreichbar ist:

Anschließend fügen wir für jeden zu schreibenden Parameter einen "Virtueller Ausgang Befehl" ein.

Unter "Befehl bei EIN" tragen wir für jeden Parameter die Zeichenfolge /api/v1/param/ gefolgt vom Parameternamen ein, also z.B.:

Da die Parameterwerte wieder im JSON-Format übertragen werden, geben wir unter "HTTP-Erweiterung bei EIN" noch

an und als "HTTP-Post-Befehl bei EIN" den folgenden Format-String:

Somit ist gewährleistet, dass der Parameterwert im JSON-Format an die HtREST Applikation übertragen wird.

Abschließend muss nur noch unter "HTTP Methode bei EIN" die Methode "PUT" ausgewählt werden.

Unter "Einheit" beim "Virtueller Ausgang Befehl" lässt sich dann noch analog zum "Virtueller HTTP Eingang Befehl" die Einheit des zu schreibenden Parameterwertes definieren:

Somit wäre das Lesen und Schreiben von Parameterwerten von der Loxone Steuerung aus abgeschossen.

Eine Loxone Vorlage mit den soeben beschriebenen "Virtuellen HTTP Ein- bzw. Ausgängen" für den Zugriff auf die Heliotherm Wärmepumpe findet sich zum Download im Anhang dieses Dokuments.

Was jetzt noch fehlt ist die Einrichtung der HtREST Applikation als Service, damit diese bei jedem Neustart des Raspberry Pi automatisch startet.

Automatischer Start

Damit die HtREST Applikation mit den von uns gewünschten Argumenten automatisch beim Reboot des Raspberry Pi startet, verpacken wir den Aufruf in einen systemd Service.

Dazu erstellen wir uns zuerst mittels nano eine passende System Unit-Datei:

Anschließend fügen wir den Inhalt der Datei unter

    https://github.com/dstrigl/HtREST/blob/master/htrest.service

in die soeben erstellte Datei ein (Copy & Paste) und passen die Aufrufargumente in der Zeile 8

entsprechend unseren Vorgaben an (Pfad zum seriellen Device, Baudrate, Portnummer, usw.).

Dann verlassen wir den nano Editor mittels "CTRL-X" und Drücken der Taste "Y" zum Speichern des Inhalts.

Danach aktivieren wir die gerade erstellte System Unit mittels:

Damit ist gewährleistet, dass diese automatisch beim Bootvorgang gestartet wird.

Um zum Testen des erstellen Service jetzt nicht zwingend einen Neustart durchführen zu müssen kann dieser gleich in der aktuellen Session mittels

gestartet werden.

Gestoppt werden kann der Service mittels:

Ein Neustart des Service kann mittels

erzwungen werden.

Recht hilfreich ist auch noch das status Kommando, mit dessen Hilfe der aktuelle Status des Service ermittelt werden kann:

Weiterführende Dokumentation zu systemd und Service Units findet sich z.B. hier:

• https://www.linode.com/docs/quick-answers/linux/start-service-at-boot/

• https://fedoramagazine.org/what-is-an-init-system/

• https://www.raspberrypi.org/documentation/linux/usage/systemd.md

• http://man7.org/linux/man-pages/man1/init.1.html

Bei Problemen mit dem HtREST systemd Service, sollte man sich zuerst einmal immer den aktuellen Status des Service ansehen und dann noch mittels folgendem Kommando den zugehörigen Log:

Hat das alles soweit funktioniert, sollte man vielleicht noch mittels

einen Neustart des Raspberry Pi durchführen und sich anschließend den Status des erstellten Service ansehen, um sicherzugehen, dass der Service auch wirklich ohne Fehler startet.

Parametersatz & -definitionen

Abschließend soll noch kurz erläutert werden, was sich mit dem oben angesprochenen "bekannten Parametersatz" auf sich hat.

Der Zugriff auf die einzelnen Parameter der Heliotherm Wärmepumpe läuft über nummerierte SP- und MP-Datenpunkte ab.

So ist z.B. die aktuelle Vorlauftemperatur unter dem Datenpunkt "MP,NR=3" zu finden.

Unter welchem SP- bzw. MP-Datenpunkt nun ein Parameter zu finden ist, ist in der CSV-Datei htparams.csv festgehalten.

Das htheatpump Paket, auf dem die HtREST Applikation aufbaut, liefert standardmäßig bereits eine CSV-Datei mit einigen der gängigsten Parametern mit.

Zu finden ist diese auch auf der GitHub-Seite des Projekts unter

    https://github.com/dstrigl/htheatpump/blob/master/htheatpump/htparams.csv

oder der Projektdokumentation unter

    https://htheatpump.readthedocs.io/en/latest/htparams.html.

Des Weiteren ist es möglich seine eigene benutzerspezifische CSV-Datei mit den Parameter-Definitionen unter ~/.htheatpump/htparams.csv anzulegen.

Wenn vorhanden, greift die htheatpump Bibliothek darauf zu, ansonsten wird die mitgelieferte Datei verwendet.

Innerhalb dieser CSV-Datei unter ~/.htheatpump/htparams.csv ist es nun möglich sich seinen eigenen "bekannten Parametersatz" zusammenzustellen, wenn einem der mitgelieferte nicht passen sollte.

Grund könnte z.B. sein, dass man den einzelnen Parametern andere Namen zuweisen möchte um Leerzeichen in Parameternamen zu vermeiden.

Ein anderer Grund könnte sein den Parametersatz um bestimmte Parameter zu erweitern.

Wie bereits weiter oben beschrieben, ist es auch möglich sich eine vollständige Liste aller verfügbaren Parameter seiner Heliotherm Wärmepumpe (inkl. deren Minimal- und Maximalwert) mit Hilfe des Python Scripts htcomplparams.py zu erstellen.

Siehe dazu auch die Beschreibung unter:

    https://htheatpump.readthedocs.io/en/latest/htscripts.html#htcomplparams

Ein kompletter Auszug der verfügbaren Parameter einer Heliotherm HP08S10W-WEB findet sich z.B. hier:

    Parameterdefinition Heliotherm HP08S10W-WEB, SW 3.0.20 (273)

Weiterführende Links

• HtREST GitHub: https://github.com/dstrigl/HtREST

• htheatpump GitHub: https://github.com/dstrigl/htheatpump

• htheatpump Dokumentation: https://htheatpump.readthedocs.io/en/latest/

• loxforum Diskussion: https://www.loxforum.com/forum/hardware-zubeh%C3%B6r-sensorik/10565-heliotherm-rs232-anbindung

Anhang

Open

Unterstützung

Du möchtest den Autor unterstützen?

Über einen Kaffee würde er sich sehr freuen: