Folgend eine Schritt-für Schritt-Anleitung um Daten über die Developer-API von Viessmann mittels ioBroker abzurufen und zu setzen.
Die Intention in dieser Anleitung liegt darin, die Wartezeit auf eine Aktualisierung des Viessmannapi-Adapters zu überbrücken.
In meinem Beispiel greife ich die Daten einer Viessmann Vitocal 200 Wärmepumpenheizung über ioBroker ab und steuere die Kesseltemperatur.
Dieses Beispiel lässt sich anhand der Dokumentation, welche im Viessmann Developer Portal zu finden ist, auf viele andere Geräte und Datenpunkte übertragen.
Hier die aktuelle Kompatibilitätsliste:
Regelungen für Wand- oder Kompaktgeräte
Vitotronic 200, Typ HO1, HO1A, HO1B, HO1D, HO2B, HO2C
Vitotronic 200 RF, Typ HO1C, HO1E
Regelungen für bodenstehende Heizkessel
Vitotronic 200, Typ KO1B, KO2B, KW6, KW6A, KW6B, KW1, KW2, KW4, KW5
Vitotronic 300, Typ KW3
Regelungen für Wärmepumpen und Hybridgeräte
Vitotronic 200, Typ WO1A, WO1B, WO1C
Regelungen für Festbrennstoffkessel
Vitoligno 200-S mit Ecotronic (ab Softwarestand 2.03)
Vitoligno 250-S mit Ecotronic (ab Softwarestand 2.00)
Vitoligno 300-C mit Ecotronic (ab Softwarestand 2.12)
Vitoligno 300-P mit Vitotronic 200 FO1
Vitoligno 300-S mit Ecotronic (ab Softwarestand 2.04)
Anleitung:
Schritt 1 - Registrierung
Um vollen Zugriff auf die Developer-API zu bekommen müsst ihr euch unter folgender Adresse anmelden:
https://developer.viessmann.com/de
Die Login-Daten sind dieselben, die für die ViCare-App gebraucht werden.
In dem Web-Portal findet ihr die komplette Dokumentation der API und eine kleine Schnellstartanleitung, welche das wichtigste erklärt.
Nach der Anmeldung erscheint in der Navigation der Punkt "API-Schlüssel", hier müsst ihr einen OAuth Client anlegen.
Der Name spielt keine Rolle aber die Client-ID solltet ihr euch für später notieren.
Schritt 2 - Access-Token erzeugen
Um Zugriff auf die API zu bekommen muss man sich ein Token erzeugen lassen, dies habe ich mittels Postman gemacht.
Das Postman Environment und die Collection habe ich angehangen.
Tutorials wie man diese Importiert und wie man generell mit Postman umgeht findet ihr im Web.
2.1 Code erzeugen
Um mittel Postman ein Token erzeugen zu können muss erstmal ein Code angefordert werden.
Folgende Adresse über einen Web-Browser eurer Wahl aufrufen:
https://iam.viessmann.com/idp/v2/authorize?
client_id={{clientid}}
&redirect_uri=http://localhost:4200/
&response_type=code
&code_challenge=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c
&scope=IoT%20User%20offline_access
{{clientid}} ist in dem Fahll die Client-ID aus dem Developer- Portal, alle anderen Daten müssen nicht angepasst werden.
Info:
redirect_uri bezeichnet die Adresse auf die nach der Codererstellung weiter geleitet wird.
code_challenge ist im Grunde ein zufälliger Wert wird aber später nochmal gebraucht, also notieren.
Der Parameter offline_access unter scope erzeugt zusätzlich ein Refresh-Token, dazu später mehr.
Auf der folgenden Seite mit euren ViCare-Benutzerdaten anmelden, anschließend werden ihr auf die von euch angegebene URL weitergeleitet mit dem Code als Parameter in der Adresszeile.
Diesen Code bitte notieren.
2.2 Access-Token erzeugen
Nun Postman öffnen, das Environment und die Collection aus diesem Post importieren und aktivieren.
Anschließend im Environment euren Code, sowie Client-ID und die code-challenge in die entsprechenden Variablen eintragen.
Jetzt könnt ihr euch mit der ersten "GET_Token"-Abfrage ein Access-Token erzeugen.
Nachdem die Abfrage gelaufen ist, wird das Access-Token und das Refresh-Token im Environment als Variable für zukünftige Anfragen gespeichert.
Um alle übrigen Daten zu vervollständigen müssen noch die zwei Abfragen "GET_install_id" und "GET_gateway_serial" abgesendet werden.
Auch hier werden die Daten anschließend automatisch als Variable im Environment abgespeichert.
Info:
Zur späteren Abfrage wird auch die Device-ID benötigt, eine entsprechende Abfrage ist in der Collection.
Bei mir beziehen sich allerdings alle Abfragen auf die Device-ID "0", alle Device-ID`s seht ihr als Antwort auf die Abfrage "GET_device_id" falls ihr eine andere benötigen solltet.
Schritt 3 - Token automatisch verlängern lassen
Da das Token automatisch Abläuft, muss es zyklisch erneuert werden, in diesem Fall alle 45 Minuten.
Hierzu lasse ich ein ioBroker Script laufen, welches das Token in regelmäßigen Abständen erneuert und als Objekt im ioBroker speichert.
schedule("*/45 * * * *", function () {
var request = require('request');
var url = "https://iam.viessmann.com/idp/v2/token"
var payload = 'grant_type=refresh_token&client_id={{CLIENT-ID}}&refresh_token={{REFRESH-TOKEN}}'
var headers = {'Content-Type': 'application/x-www-form-urlencoded'}
var result;
var options = {url: url, method: 'POST', headers: headers, body: payload};
request(options, function(error, response, body)
{
if (!error && response.statusCode == 200) {
var info = JSON.parse(body); // info ist ein Objekt
var x = info.xy; // xy ist eine Eigenschaft des Objektes info
}
result = JSON.parse(body)
setState('0_userdata.0.Viessmann-API.Access-Token'/*Access-Token*/, result["access_token"], true);
console.log("Viessmann-API: Token erneuert.");
});
});
Unter payload die Platzhalter {{CLIENT-ID}} und {{REFRESH-TOKEN}} durch eure eigenen ersetzen.
Info:
Eine Erneuerung des Tokens funktioniert ohne Anmedung über die Website.
Sollte das Token aber dennoch mal Ablaufen muss erst wieder ein neues über das Web-Portal erzeugt werden und entsprechend euer Refresh-Token anpassen.
Schritt 4 - Daten abfragen
Da ioBroker nun immer ein gültiges Token kennt, können wir nun anfangen mit der API zu arbeiten.
In diesem Beispiel lese ich die Temperatur vom Außentemperatursensor in zyklischen Abständen (In diesem Fall alle 30 Minuten) aus und speichere die Daten in einem ioBroker-Objekt.
schedule("*/30 * * * *", function () {
var request = require('request');
var url = "https://api.viessmann.com/iot/v1/equipment/installations/{{INSTALL-ID}}/gateways/{{GATEWAY-ID}}/devices/0/features/heating.sensors.temperature.outside"
var access_token = getState('0_userdata.0.Viessmann-API.Access-Token'/*Access-Token*/).val
var headers = {'Authorization': 'Bearer ' + access_token}
var result;
var options = {url: url, method: 'GET', headers: headers};
request(options, function(error, response, body)
{
if (!error && response.statusCode == 200) {
var info = JSON.parse(body); // info ist ein Objekt
var x = info.xy; // xy ist eine Eigenschaft des Objektes info
}
result = JSON.parse(body)
setState('0_userdata.0.Viessmann-API.Außentemperatur'/*Außentemperatur*/, result["data"]["properties"]["value"]["value"], true);
console.log("Viessmann-API: Außentemperatur aktualisiert.");
});
});
Hier die Platzhalter durch eure eigenen Daten ersetzen.
Info:
Alle weiteren Datenpunkte findet ihr in der Dokumentation im Developer Portal oder über folgende Anfrage "Alle Datenpunkte" aus der Collection an die API.
Schritt 5 - Daten setzen
Über den Call "setWaterTermperature" aus der Collection lässt sich die Temperatur des Brauchwasserkessels setzen.
Der Call lässt sich wie unter Punkt 5 auch aus ioBroker absetzen um von dort aus die Kesseltemperatur steuern zu können.
Dies will ich später zusammen mit einer PV-Anlage nutzen um bei Energieüberschuss die Kesseltemperatur höher zu setzen damit der Eigenverbrauch gesteigert wird.
Postman Environment & Collection
Viessmann.postman_environment.json
Viessmann.postman_collection.json
Das ist alles Quick&Dirty aber läuft erstmal und deck alles ab, was ich vorher mit dem Viessmannapi-Adapter erledigt habe.
Ich bin kein Entwickler, daher sind Anregungen und Verbesserungen gerne gesehen 
Gruß
Christian
