Viessmann API und Node Red – Teil 4

Einstellungen ändern

Nachdem wir in den vorherigen Kapiteln gelernt haben, wie der Zugriff auf die API erfolgt und wie man Daten daraus auslesen kann, sehen wir jetzt, wie man die Einstellung der Heizung – z.B. die Temperatur oder den Betriebsmodus über die API verändern kann.

Dieses Tutorial ist auf die geänderte API von Februar 2023 angepasst. Anstatt dem  Endpoint equipment wird jetzt der Endpoint features verwendet.

Schauen wir uns zuerst einmal das JSON Objekt aus der Feature Abfrage an. Der hier dargestellte Auszug zeigt bzw. setzt die Normaltemperatur des Heizkreises 2 (Feature: heating.circuits.2.operating.programs.normal): Ein Feature fängt immer mit “properties” an und läuft bis zur nächsten “properties” Zeile.

Beispiel: Normaltemperatur Heizkreis 2 einstellen

Die eingestellte Solltemperatur beträgt 17 Grad Celsius – wie man sie ausliest, ist im vorigen Kapitel beschrieben.

Jedes Feature, das bei “commands” einen nicht leeren Inhalt hat, kann – theoretisch – manipuliert werden. In unserem Beispiel ist das der Fall. Dort steht "commands": { "setTemperature": {... gefolgt von einer URL und einigen Constraints (Einschränkungen).

Der Parameter “isExecutable” gibt an, ob sich ein Befehl in einem Feature unter den aktuellen Gegebenheiten ausführen lässt oder nicht. Bei “isExecutable” = true lässt sich der Befehl ausführen, ansonsten nicht. Beispiel: Du kannst das Betriebsprogramm “Eco” nicht einstellen, weil sich die Anlage im Standby Modus befindet.

Wie stellen wir nun die Normaltemperatur von Heizkreis 2 ein?

Straight forward

Zuerst kommt ein Dashboard Slider Node, den wir so einstellen, dass er “Output only on release” liefert. Der Zielwert steckt jetzt in msg.payload. Der Function Node, der den http-Reuest Header entsprechend aufbereitet, wird wie folgt programmiert:

bzw. als Javascript Snippet zum copy&paste:

Noch ein HInweis: Die in msg.header steckende Information ist ziemlich “klebrig”, was bedeutet, dass da oft  Informationen aus vorherigen http-Requests drin stehen bleiben. Um eine saubere Basis zu haben, sollte man vor jedem Setzen des Headers diesen mit einem msg.headers = {};  löschen.

Der http Rquest Node “set feature” enthält die für die Normaltemperatur Heizkreis 2 erforderliche URI:

Fertig! Oder nicht?

Flow Betriebssicher machen

Bedient man das Dashboard mit einem Mobilgerät, kann es schnell passieren, dass man den Slider Temperaturwähler versehentlich verstellt. Das ist natürlich nicht im Sinne des Erfinders. Ich habe deshalb den Slider und den Befehl enkoppelt. Zum Abschicken der neuen Temperatur muss noch ein Bestätigungsbutton geklickt werden.

Das sieht insgesamt wie folgt aus:

Die oberen drei grau unterlegten Nodes aus dem Feature Request hast du sicher schon; sie dienen lediglich der Rückkopplung des aktell in der Heizung eingestellten Werts. Da unsere Applikation ja nicht die einzige Eingabemöglichkeit ist – es gibt ja noch die ViCare App oder die Tasten am Gerät selbst – ist die Rückkopplung sehr wichtig um immer die aktuell geltende Einstellung zu sehen.

Der Function Node mit Namen “HK Soll Temp normal” wird einfach mit dem bereits existierenden “Feature auslesen” http Request verdrahtet. Dieser Node macht nichts Anderes als sich den in der Heizanlage geltenden Wert aus dem JSON File herauszusuchen. Die Logik ist aus dem vorigen Kapitel bekannt.

Danach kommt der Dashboard Slider Node – Einstellung wie oben. Letzter Node in diesem Strang ist noch ein Change Node, der die Flow Variable gemäß des Slider Werts zur Verwendung im nächsten Schritt abspeichert. Wenn nun der Slider bewegt wird, passiert wie gewollt erst einmal nichts. Das geschieht erst im nächsten Schritt, denn erst die unteren drei Nodes nehmen nach dem Auslösen des Dashboard Buttons die Einstellung vor.

Der Dashboard Button Node wird wie unten gezeigt eingestellt – wobei ich die Darstellung des Button Icons geändert habe:

Die Payload enhält die Flow Variable mit der eingestellten Temperatur.

Der Function Node Headers & Parameter sieht fast so aus, wie der beim “straight forward” Beispiel. Lediglich Zeile 2 ist unterschiedlich

Der http Requst Node “Set Feature” ist identisch zum straight forward Beispiel

Und hier noch die Darstellung des Dashboards mit Auswahl Betriebsart, Slider für normale und reduzierte Temperatur. Die gelben “OK Haken” lösen aus.

 

Beispiel: Betriebsart einstellen

Je nach Anlage gibt es mehrere Betriebsarten: Bei mir sind dies Aus, Nur Warmwasser, Zeitprogramm Heizung und Warmwasser, dauernd reduziert und dauernd normal.

Diese stellt man je nach Heizkreis wie folgt ein; in unserem Beispiel für Heizkreis 2:

Im Prinzip funktioniert alles so wie bei der Temperatureinstellung. Der Function Node HK Betriebsart ist wieder die Rückkopplung aus der Feature Abfrage Betriebsart. Die Einstellung erfolgt über einen Dashboard Dropdown Node, der Headers & Parameter Node setzt die Payload auf einen der vorgeschriebenen Werte “mode: standby”,
“mode: dhw”, “mode: dhwAndHeating”, “mode: forcedReduced”, “mode: forcedNormal” .
Der http Request hat die URL

Das zugehörige JSON File für Node-Red findest du hier:

Beispiel: “Ich möchte Warmwasser”

Hinter dieser Schnellwahlfunktion der App verbirgt sich die Ausführung des Befehls “Warmwasser einmal bereitstellen” bzw. heating.dhw.oneTimeCharge . Damit wird dann der Warmwasserboiler einmalig bis zu gewählten Temperatur aufgeheizt, egal in welchem Betriebsmodus sich die Heizung befindet – auch wenn sie auf AUS steht.

Der Befehl ist einerseits etwas anders als die oben beschriebenen, andererseits auch nicht schwieriger – man muss nur drauf kommen!

Ich schildere hier nur das Prinzip. Einbauen in deine Anwendung und mit Schalterchen versehen darfst du das selbst – inzwischen kannst du das ja, oder?

Die beiden Trigger schicken einen String und zwar entweder “activate” oder “deactivate”. Im folgenden Function Node wird daraus die aufzurufende URL aufgebaut und an den http Request Node weitergeben.

Was passiert da: Der Function Node setzt die Payload auf eine leere Menge msg.payload={} , das ist wichtig, da der http Request keine Payload übermittelt bekommen soll. In der vorletzten Zeile wird die URL zusammengebastelt, d.h. erweitert um den gewünschten Aktivierungsstatus.

Die Funktion bzw. der Status ergibt sich hier also aus der URL und nicht wie sonst aus einem Parameter im http-Request Header, der übergeben wird.

Der http Request Node wird als POST konfiguriert und hat in der URL Zeile nichts drin stehen.

Schickt man zweimal denselben Status ab – z.B. zweimal activate, dann gibt es eine Fehlermeldung der Art:

Hier noch das JSON Snippet zum importieren

That’s it.

Kommentare, Fehlermeldungen und ein kleines Dankeschön würden mich glücklich machen.

4 Gedanken zu „Viessmann API und Node Red – Teil 4

  1. Hallo Chris,
    Läuft alles so, wie gewünscht.
    Danke für die tolle, verständliche und detaillierte Anleitung.
    Viele Grüße Jürgen

  2. Moin, wie kann ich “Schnellwahlen” wie zum Beispiel “Ich möchte Warmwasser” aktivieren? Das wäre eine tolle Ergänzung Deiner/Eurer großartigen Serie, über die ich nun meine Heizung in meine NodeRed-Installation erfolgreich eingebunden habe. Vielen Dank für Deine/Eure Arbeit!
    Viele Grüße
    Thilo

    1. Hi,
      freut mich, wenn ich dir helfen konnte. Ich knoble, experimentiere allein und schreibe das alles selbst auf. Ein “Team” habe ich nicht. Gelegentlich hilft mir Michael Hanna von Viessmann, wenn ich mal Fragen habe.
      Schnellwahlen kannst du dir selbst zusammenbauen, indem du z.B. für “ich möchte einmalig Warmwasser” einen bzw. mehrere Nodes hernimmst: Der erste setzt die Zieltemperatur auf 60°C oder so, den zweiten lässt du alle 90 Sekunden (empfohlenes Intervall) die Wassertemperatur messen. Wenn Zieltemperatur erreicht, stellt der darauffolgende Node (aktiviert durch einen Switch Node) die Zieltemperatur auf den “Standby Wert” zurück. Alternativ kannst du das auch in zwei Function Nodes packen.
      Im Prinzip macht die App bzw. die Viessmann Logik dahinter auch nichts Anderes. Aber, Danke für den Tipp. Ich werde bei nächster Gelegenheit was darüber schreiben.

      Was ich da oberhalb geschrieben habe ist zwar nicht ganz falsch, aber es gibt tatsächlich einen Parameter in der API mit dem ich einmalig Heißwasser erzeugen kann:
      heating.dhw.oneTimeCharge
      In der Viessmann Dokumentation steht: Shows whether one time charge of dhw is active. Also provides the commands to activate/deactivate it
      Ist im Umfang des Basispakets enthalten. Die Anleitung dazu findet sich jetzt am Ende dieses upgedateten Artikels.
      Viel Spaß noch.
      Chris

      1. Moin Chris, ich wollte mich noch mal für die Lösung “im möchte Warmwasser” bedanken. Das hat mir sehr geholfen! Funzt echt prima. Ich hoffe, Du machst weiter …
        Viele Grüße
        Thilo

Schreibe einen Kommentar

Ich freue mich über Lob und Kritik.
Falls du Probleme mit der hier vorgestellten Anleitung hast und nicht weiter kommst:
Bitte das Problem oder die Fehlermeldung(en) möglichst genau beschreiben, auch an welcher Stelle (z.B. in welchem Node oder Befehl) und unter welchen Umständen der Fehler auftritt.
Gerne kannst du mir auch ein Mail schreiben. Die Adresse findest du im Impressum.
Ich gebe mir viel Mühe, meinen Lesern weiterzuhelfen. Je konkreter du bist, desto einfacher und schneller kann ich versuchen zu helfen.
Deine E-Mail-Adresse wird nicht veröffentlicht.
"
Erforderliche Felder sind mit * markiert