Hat man erst einmal die ganze Infrastruktur zum Laufen gebracht, geht es ans Eingemachte.
Identifikation des Geräts
Es gibt einen einfachen und einen deutlich aufwändigeren Weg, die Identifikation vorzunehmen:
Der einfachere erfordert einen Account bei Viessmann – das ist aber derselbe, den du schon hast, wenn du das Vitoconnect Kästchen mit der ViCare App nutzt.
Der zweite Weg geht direkt über die Heizungsanlage: Hierzu hat Phil, der Entwickler des Optolink Splitters eine Anleitung zur Identifikation geschrieben, die für Laien nicht ganz einfach zu verstehen ist. Ich versuche einen alternativen Erklärungsansatz – eventuell hilft auch eine Kombination aus beidem. Bei meinen sonstigen Artikeln in diesem Blog versuche ich möglicht präzise Hinweise zu geben. Leider muß ich bei dieser Art der Geräte-Identifikation und, weiter unten, den Datenpunkten ziemlich vage bleiben. Das liegt auch daran, dass ich lediglich Nutzer einer Vitodens Therme von Viessmann bin, kein Heizungsbauer und auch kein Programmierer. Ich bitte um Nachsicht, wenn nicht alles sofort 100%ig klar wird. Zum Glück gibt es auch noch den Diskussionsbereich in Github, in dem Fragen in der Regel sehr freundlich und hilfsbereit beantwortet werden.
Easy: Identifikation – Abkürzung über API
Für alle diejenigen, die sich bisher mit der API in Verbindung mit oder ohne Node Red herumschlagen oder geschlagen haben, gibt es eine simple Abkürzung. Die Abfrage der Device ID gibt freundlicherweise auch den Gerätetyp im Klartext aus.
Die ganze Geschichte, wie man die Viessmann API mit Node-Red anspricht und nutzt habe ich hier beschrieben.
Hat man bisher nicht mit der API in Verbindung mit Node Red gearbeitet, ist dieser Weg aber vielleicht zu aufwendig, weshalb ich eine kleine Python Routine weiter unten zur Verfügung stelle. Da beschränkt sich der Aufwand auf die Anmeldung bei Viessmann – hat sowieso jeder, der die ViCare Appp nutzt – sowie die Online Erzeugung eines Access Tokens im Viessmann Developer Portal. Dort findet man eine Kachel, mit der das Token erzeugt werden kann.
Erweiterung der bestehenden Node-Red App
Hat hast du für Node-Red ein gültiges Access Token – es muss als flow Variable oder Global Variable vorliegen – erfolgt der bekannte dreischrittige Prozess, in dem erst die Installation ID, dann die Gateway Serial und darauf aufbauend die Device ID abgefragt wird.
Im Grunde wird der Abschnitt, in dem die statischen Parameter erzeugt werden um zwei Nodes erweitert (Nodes mit blauen Punkten)
Der Output sieht dann z.B. so aus: 
Der neue Funktionsnode sieht so aus:
Beschrieben ist das bei statische Parameter in der Viessmann API Anleitung Kapitel 2. Obiger Flow sucht nach dem Device Type "heating", hat man eine PV Anlage oder etwas derart, muss wahrscheinlich ein anderer Suchparameter angegeben werden.
Access Token from Scratch
Hast du dein Node-Red für die API nicht mehr oder noch nicht, kannst du das Access Token ganz einfach über das Viessmann Dashboard bei developer.viessmann.com generieren – vorausgesetzt, du hast einen Developer Account generiert.
Dort gibt es eine Kachel "Generate Access Token". Hier den Scope "IoT" auswählen. Das Access Token herauskopieren (Button) und in folgenden Flow (Inject Node) einsetzen:
Die Model ID steht dann im Debug Node.
Und hier das JSON File dazu
|
1 |
[{"id":"9035c726d63ee272","type":"http request","z":"5aa9caf601ca6486","name":"Installation ID","method":"GET","ret":"obj","paytoqs":"ignore","url":"https://api.viessmann.com/iot/v1/equipment/installations","tls":"","persist":false,"proxy":"","insecureHTTPParser":false,"authType":"","senderr":false,"headers":[],"x":760,"y":780,"wires":[["63ea985fa1fb6288"]]},{"id":"196e70331475247c","type":"function","z":"5aa9caf601ca6486","name":"Auth Header","func":"let atoken = flow.get('accessToken')\nmsg.headers = {\n Authorization: \"Bearer \"+ atoken\n}\nreturn msg;\n\n","outputs":1,"timeout":"","noerr":0,"initialize":"","finalize":"","libs":[],"x":530,"y":780,"wires":[["9035c726d63ee272"]]},{"id":"404b3869948d43b9","type":"http request","z":"5aa9caf601ca6486","name":"Gateway Serial","method":"GET","ret":"obj","paytoqs":"ignore","url":"https://api.viessmann.com/iot/v1/equipment/gateways","tls":"","persist":false,"proxy":"","insecureHTTPParser":false,"authType":"","senderr":false,"headers":[],"x":760,"y":820,"wires":[["9fe128f452a44b7c"]]},{"id":"63ea985fa1fb6288","type":"change","z":"5aa9caf601ca6486","name":"set flow.installationID","rules":[{"t":"set","p":"installationID","pt":"flow","to":"payload.data[0].id","tot":"msg"}],"action":"","property":"","from":"","to":"","reg":false,"x":960,"y":780,"wires":[["1245cba72eb078f3"]]},{"id":"9fe128f452a44b7c","type":"change","z":"5aa9caf601ca6486","name":"set flow.gatewaySerial","rules":[{"t":"set","p":"gatewaySerial","pt":"flow","to":"payload.data[0].serial","tot":"msg"}],"action":"","property":"","from":"","to":"","reg":false,"x":960,"y":820,"wires":[["adfe105d08faf8ac"]]},{"id":"1245cba72eb078f3","type":"function","z":"5aa9caf601ca6486","name":"Auth Header","func":"let atoken = flow.get('accessToken')\nmsg.headers = {\n Authorization: \"Bearer \"+ atoken\n}\nreturn msg;\n\n","outputs":1,"timeout":"","noerr":0,"initialize":"","finalize":"","libs":[],"x":530,"y":820,"wires":[["404b3869948d43b9"]]},{"id":"cbc458b37a8c1950","type":"http request","z":"5aa9caf601ca6486","name":"DeviceID","method":"GET","ret":"obj","paytoqs":"ignore","url":"https://api.viessmann.com/iot/v1/equipment/installations/{{iid}}/gateways/{{gws}}/devices/ ","tls":"","persist":false,"proxy":"","insecureHTTPParser":false,"authType":"","senderr":false,"headers":[],"x":740,"y":860,"wires":[["68cf237231231858"]]},{"id":"adfe105d08faf8ac","type":"function","z":"5aa9caf601ca6486","name":"extended auth header","func":"let atoken = flow.get('accessToken')\nmsg.headers = {\n Authorization: \"Bearer \"+ atoken\n}\nmsg.iid = flow.get('installationID');\nmsg.gws = flow.get('gatewaySerial');\nreturn msg;\n\n","outputs":1,"timeout":"","noerr":0,"initialize":"","finalize":"","libs":[],"x":560,"y":860,"wires":[["cbc458b37a8c1950"]]},{"id":"68cf237231231858","type":"function","z":"5aa9caf601ca6486","name":"locate Model ID","func":"const deviceArray=msg.payload.data;\nlet idx = deviceArray.findIndex( (element) => element.deviceType === 'heating');\nmsg.payload=msg.payload.data[idx].modelId;\n\nreturn msg;","outputs":1,"timeout":"","noerr":0,"initialize":"","finalize":"","libs":[],"x":900,"y":860,"wires":[["57f2e631d498c8c9"]]},{"id":"7a0c61fdd8a9b6ea","type":"inject","z":"5aa9caf601ca6486","name":"Inject Access Token","props":[{"p":"payload"},{"p":"topic","vt":"str"}],"repeat":"","crontab":"","once":false,"onceDelay":0.1,"topic":"","payload":"your Access Token goes here","payloadType":"str","x":550,"y":740,"wires":[["0bd4a1d4d248070c"]]},{"id":"57f2e631d498c8c9","type":"debug","z":"5aa9caf601ca6486","name":"ModelID","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","targetType":"msg","statusVal":"","statusType":"auto","x":1080,"y":860,"wires":[]},{"id":"0bd4a1d4d248070c","type":"change","z":"5aa9caf601ca6486","name":"","rules":[{"t":"set","p":"accessToken","pt":"flow","to":"payload","tot":"msg"}],"action":"","property":"","from":"","to":"","reg":false,"x":790,"y":740,"wires":[["196e70331475247c"]]}] |
Und dasselbe in Python…
…für den Fall, dass du dich nicht mit Node-Red beschäftigen willst – eigentlich schade, aber die Geschmäcker sind verschieden.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
import requests #In some cases the requests library needs to be installed prior to using thies routine print ("This little routine needs a valid Viessmann API Access Token in order to work.") print ("To generate it, you'll need a free Viessmann Developer Account.") print ("The token can be generated at https://app.developer.viessmann.com/") print ("Select Scope for IoT, press <Generate Token>, enter your credentials and") print ("afterwards click on the copy button.") print ("------------------------------------") print ("Please enter your Access Token below:") atoken = input() # fetch Installation ID r=requests.get("https://api.viessmann.com/iot/v1/equipment/installations", headers={"Authorization":"Bearer "+ atoken}) data = r.json() iid=data['data'][0]['id'] print ("Installation ID:", iid) #fetch gatewway serial number r=requests.get("https://api.viessmann.com/iot/v1/equipment/gateways", headers={"Authorization":"Bearer "+atoken}) data = r.json() #print (data) gws=data['data'][0]['serial'] print ("Gateway Serial:", gws) #fetch and locate model ID r=requests.get("https://api.viessmann.com/iot/v1/equipment/installations/"+str(iid)+"/gateways/"+str(gws)+"/devices/", headers={"Authorization":"Bearer "+ atoken}) data = r.json() # Index of first element with deviceType = 'heating' - in case of aircondition another keywoard is needed index = next((i for i, item in enumerate(data['data']) if item.get('deviceType') == 'heating'), None) print("Index:", index) modelId=data['data'][index]['modelId'] print ("ModelID=", modelId) |
Hast du dein Gerät identifiziert, geht es weiter bei Datenpunktliste
The hard way: Identifikation – zu Fuß
Das nachfolgende Kapitel hat eigentlich nur noch dokumentarischen Charakter.
Es sei denn, die oben beschriebene einfache Methode der Identifikation über die API funktioniert nicht. Dann musst du diesen hier beschriebenen, etwas beschwerlichen Weg gehen, um dein Gerät zu identifizieren.
Dazu brauchen wir den Wert von einer oder zwei Adressen in unserem Gerät:
Die Gerätekennung steht bei 0xF8. Die Kennung hat folgende Struktur:
Mit dem MQTT Explorer ist die Gerätekennung ganz einfach auszulesen:
Hierzu das Topic Vitodens/cmnd eintragen (es sei denn, ihr habt es in settings_ini.py geändert), Format raw auswählen, dann read;0xF8;8 und Publish anklicken. Das Ergebnis steht dann links unten.
Gegebenenfalls brauchen wir noch den Wert bei F0
Zusätzlich brauchen wir noch die Tabelle, anhand derer wir den Anlagentyp (hoffentlich) identifizieren: Die Tabelle steht hier: https://github.com/philippoo66/ViessData21/blob/master/DataPoints.txt
Beispiel 1
Im ersten Schritt benötigen wir die ersten 2 Byte der Kennung bei F8.Zum Beispiel: 204b01430000050c
Mit 204b schauen wir in der Datapoints Tabelle nach und haben Glück:
Gerätetyp 0x204B zeigt auf ein einzig möglliches Gerät (Zeilennummer 11). Mit der Angabe CU401B_G können wir jetzt die passende Datenpunktliste heranziehen – siehe weiter unten.
Leider ist die Identifikation nicht immer so einfach.
Beispiel 2
Phils Gerät hat die Kennung
20 CB 1F C9 00 00 01 14, an F0 steht: 01
Mit den ersten 2 Byte (20CB) gehen wir in die Datapoints Tabelle und finden eine Reihe verschiedene Geräte mit dieser Nummer (roter Rahmen).
Das nächste Byte (1F) können wir in der Regel ignorieren bzw. nehmen dafür den Wert 01 an. Das nächste Byte (Software Index Ident) ist C9.
Mit 01C9 schauen wir wieder in der Tabelle bei den gefundenen Geräten nach.
Uns interessiert die Spalte nach softwareIndexIdent: 01C9 liegt im Bereich zwischen 01C8 und 01FF. Damit haben wir die Auswahl (orangener Rahmen) weiter verkleinert.
Da nun wieder mehrere Geräte zur Auswahl stehen brauchen wir noch den Wert des Bytes an F0 (ecnsysDeviceIdentF0). Dort steht bei Phil "01". Eine Spalte weiter nach rechts schauen wir, wo 01 passt. Es passt zwischen 1 und 9 (Blauer Rahmen). Damit haben wir das Gerät identifiziert – es ist ein VScotHO1_200_01.
Beispiel 3
hier klappt es nicht so gut: Meine Vitodens 200 Baujahr 2019 zum Beispiel hat die Kennung 20cb28cb0000010a. Mit 0x20CB schauen wir jetzt in datapoints.txt nach und entdecken wie gerade eben ca. 15 Geräte dieses Typs.
Die 28 wird ignoriert bzw. als 01 gelesen. Zusammen mit dem nächsten Byte ergibt sich 01CB, das liegt wieder zwischen 01C8 und 01FF. Auch hier brauchen wir noch den Wert von F0. Dort steht bei mir "0b". Dummerweise passt das nirgendswo hin. Ende Gelände!
Hier hilft nur fragen. Ohne Hintergrundwissen ist diese Aufgabe nicht zu lösen. Es hat sich dann herausgestellt, dass es sich bei meinem Gerät um eine VScotHO1_200_11 handelt. Mit etwas Mut zum Risiko kann man auch eine der anderen halbwegs stimmigen GeräteIDs heranziehen. Die Datenpunktlisten innerhalb einer Familie unterscheiden sich zum Glück nur wenig.
Datenpunktliste
Jeder Gerätetyp hat seine eigene Datenpunktliste. Die Sammlung aller Datenpunktlisten findet ihr hier zum downloaden. (Auf der Seite rechts das Downloadsymbol anklicken.)
Wenn ihr das ZipFile aufmacht, findet ihr die zu eurem Gerät passende Datenpunktliste.
So eine Datenpunktliste hat locker über 700 Zeilen. Ganz oben stehen die Datenpunkte, die eher trivial sind – Außentemperatur, Kesseltemperatur etc.
Ein Wert, der in praktisch allen Gerätefamilien vorkommt ist die Außentemperatur:
- Aussentemperatur (5373) [TiefpassTemperaturwert_ATS~0x5525 (SInt)]
Der Wert, auf den es ankommt ist der hex Wert 0x5525 (SInt). Diesen könnten wir im Abschnitt Polling Datapoints der Datei settings_ini.py eintragen – tatsächlich gibt's den aber schon…
Das geschieht nach folgendem Schema:
Weitere Infos in Github.
Soweit, so gut. Jetzt beginnt das große Such- und Ratespiel. Die Datenpunkt Datei ist alles andere als übersichtlich. Zudem ist sie generisch aufgebaut. Das heißt, dein Gerät kann ja auf vielerlei Weise konfiguriert und gebaut werden. Mal hat es drei Heizkreise, mal einen, mal ist Solarthermie dabei, mal nicht und so weiter.
Diese Spezifikationen sind mit HIDDEN gekennzeichnet. Zum Beispiel so: HIDDEN:(00_WWS="7 M2 + M3" OR 00_WWS="8 M2 + M3 + WW" OR 00_WWS="3 M2" OR 00_WWS="4 M2 + WW")
Dieser spezielle HIDDEN Eintrag zieht sich bei meiner Datapoint Datei durch die ganze Liste. Für Laien absolut unlösbar, wenn man nicht weiß, dass WWS für "Warmwasserschema" steht. Das Warmwasserschema steht an Adresse 0x7700 im Kapitel Inbetriebnahme. Je nachdem, welchen Wert das Byte an dieser Stelle hat, greift HIDDEN oder nicht. Bei mir steht an dieser Stelle eine "8". Das heißt, die Werte von Heizkreis A1 (und M1) kann ich ignorieren. Da soll mal einer draufkommen. Bei Wärmepumpen dürfte das noch komplexer werden. Ein Glossar wäre nett, damit man sich nicht immer im Wald verirrt…
Also: Nicht verzagen, Trial und Error. Parameter mit dem MQTT Explorer ausprobieren und schauen, ob etwas Vernünftiges dabei herauskommt. Hilfreich sind auch die Beispielwerte, in Phil's Original settings_ini.py. Ich habe da eine Menge draus gelernt.
Übrigens: Nach jeder Änderung an der Datenpunkt Liste in settings_ini.py muss der Splitter mit sudo service optolink-splitter restart neu gestartet werden, damit neue Datenpunkte gepollt werden.
Und noch etwas: Habt ihr einen Fehler in der Pollingliste – zum Beispiel ein Semikolon als Trenner anstatt eines Kommas, versagt der Splitter komplett seinen Dienst. Auch Vicare funktioniert dann nicht.
Nachfolgend noch Phil's Tabelle, die ich um meine eigenen Datenpunkte (für die Vitodens 200) angereichert habe.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 |
# meine Viessdata Tabelle #088E;0800;0802;0804;0808;5525;5523;5527;0A82;0884;5738;088A;08A7;0A10;0C20;0A3C;0C24;555A;A38F;55D3;A152;6500;6513;6515;0xFFF4;0xFFFd; ("Anlagenzeit", 0x088E, 8, 'vdatetime'), ("AussenTemp", 0x0800, 2, 0.1, True), ("KesselTemp", 0x0802, 2, 0.1, False), ("SpeicherTemp", 0x0804, 2, 0.1, False), ("AbgasTemp", 0x0808, 2, 0.1, False), ("AussenTemp_fltrd", 0x5525, 2, 0.1, True), ("AussenTemp_dmpd", 0x5523, 2, 0.1, True), ("AussenTemp_mixed", 0x5527, 2, 0.1, True), # ("Eingang STB-Stoerung", 0x0A82, 1, 1, False), # ("Fehlerstatus Brennersteuergeraet", 0x5738, 1, 1, False), ("Brennerstarts", 0x088A, 4, 1, False), ("Betriebsstunden", 0x08A7, 4, 2.7777778e-4, False), # 1/3600 # ("Stellung Umschaltventil", 0x0A10, 1, 1, False), # ("Ruecklauftemp_calcd", 0x0C20, 2, 0.01, False), # ("Pumpenleistung", 0x0A3C, 1, 1, False), # ("Volumenstrom", 0x0C24, 2, 0.1, False), # eigentlich scale 1 aber für Viessdata Grafik ("KesselTemp_soll", 0x555A, 2, 0.1, False), ("BrennerLeistung", 0xA38F, 1, 0.5, False), ("BrennerModulation", 0x55D3, 1, 1, False), # ("Status", 0xA152, 2, 1, False), ("SpeicherTemp_soll_akt", 0x6500, 2, 0.1, False), ("Speicherladepumpe", 0x6513, 1, 1, False), ("Zirkulationspumpe", 0x6515, 2, 1, False), # bis hierher meine Viessdata Tabelle -------- # ab hier CaCicala ("WWTemp", 0x0812, 2, 0.1, False), ("KollektorTemp", 0x6564, 2, 0.1, True), ("GemVorlaufTemp", 0x081A, 2, 0.1, False), ("FBHVorlaufTemp", 0x3900, 2, 0.1, False), ("FBHPumpeStatus", 0x3906, 1, 1, False), ("HKPumpeStatus", 0x4906, 1, 1, False), ("HKVorlaufTemp", 0x4900, 2, 0.1, False), ("WWSolar", 0x6566, 2, 0.1, False), ("SolarpumpeStatus", 0x6552, 1, 1, False), ("SolarBetriebsstunden", 0x6568, 2, 1, False), ("OperatingModeHK1", 0x2323, 1, 1, False), ("OperatingModeFBH", 0x3323, 1, 1, False), ("OperatingModeHK", 0x4323, 1, 1, False), ("SollTempTagFBH", 0x3306, 1, 1, False), ("SollTempRedFBH", 0x3307, 1, 1, False), ("SollTempTagHK", 0x4306, 1, 1, False), ("SollTempRedHK", 0x4307, 1, 1, False), ("HeizgVerbrTag", 0x9000, 32, 'raw'), ("WWVerbrTag", 0x9134, 32, 'raw'), ("StromVerbrTag", 0x9268, 32, 'raw'), ("Frostgefahr", 0x2500, 22, 'b:16:16::raw'), ("Frostgefahr_HK2", 0x4500, 22, 'b:16:16::raw'), ("RTS_akt_HK2", 0x3500, 22, 'b:12:13', 0.1, False), ("RTS_akt_HK3", 0x4500, 22, 'b:12:13', 0.1, False), |
Bei Schwierigkeiten im Diskussionsforum nachfragen.
Das Viessmann Forum zu durchforsten ist ebenfalls hilfreich.
Weitere Datenquellen
für Datenpunkte von verschiedene Gerätetypen gibt es noch ein paar. Basiswerte wie Temeraturen etc. scheinen bei allen Gerätefamilien gleich zu sein, ebenso bei den neueren OneBase (3E) Geräten.
- Ggf. könnt ihr in der Viessmann Community den User FransOv auf englisch bitten, euch die Datenpunkte als Excel zu generieren. Diese Liste ist übersichtlicher und vollständiger. Der aktuelle Stand findet sich unter diesem Link.
- "openv" ist generell ein interessantes Projekt. Unter anderem auch eine Tabelle, die Datenpunkte für eine Vielzahl von Gerätetypen enthält – auch Wärmepumpen. Zusätzlich eine Linksammlung zu einer großen Anzahl von Viessmann Projekten.
- Achtung: Es gibt ein Viessmann Programm namens Vitosoft, in dessen SQL Datenbank und XML Tabellen die Werte drinstehen, die FransOv ins Excel überführt. Aber Vorsicht: Phil rät stark davon ab, dieses "Programmmonster" auf dem eigenen, produktiven PC zu installieren. Es handelt sich dabei um sehr alte SW Technologie (Windows 3.1) und es besteht die Gefahr, dass man sich seinen PC zerschießt.
Wie man die MQTT Daten in Node-Red verwurschtelt habe ich im nächsten Kapitel beschrieben.
