Viessmann Developer-API mit ioBroker

[cheussen]

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

[butsch]

@cheussen danke schon Mal dafür!

[tombox]

@cheussen Was ist der Vorteil zu dem bestehenden Adapter.

@blauholsten Macht es den Sinn den bestehenden Adapter zu ersetzen? Hast du dafür Zeit, wenn nicht kann ich das schnell machen.

[ilovegym]

@tombox
der bestehende Adapter funktioniert ja seit der API Aenderung am 15.7. nicht mehr

und wenn du das machen wuerdest, waere super!

[tombox]

@ilovegym Kein Problem aber ich bräuchte temporär Zugang zu einem Account um zu überprüfen ob das wirklich funktioniert

[asblass]

Hi @cheussen

Vielen Dank für die Übergangslösung

Ich musste

if(!existsState('Viessmann-Temp-API.Access-Token')) createState('Viessmann-Temp-API.Access-Token', 0, {type: 'number'});

mit aufnehmen, damit der Datenpunkt angelegt wird und 0_userdata.0 ging bei mir nicht, daher liegen meine Datenpunkte jetzt unter javascript.0.

Viele Grüße
Andreas

[Hansi1234]

@tombox Hi, ich kann dir meine Daten zur Verfügung stellen. Ich hätte auch Interesse, wie du genau vorgehst. Klar, es gibt Tutorials aber an dem Beispiel von hier hätte ich besonderes Interesse.

Grüße

[tombox]

@hansi1234 Schreib mir einfach ein PN
der adapter ist auch fast fertig brauch nur nochmal echte daten zum abgleich

[tombox]

@Hansi1234
Adapter ist fertig bitte mal testen
https://forum.iobroker.net/topic/46778/test-viessmann-v2-0-0

[Andy61]

@tombox Einfach super, funktioniert prima. Vielen Dank für die Arbeit. Hat bei mir den alten Adapter viessmannapi schon ersetzt.

[tombox]

@andy61 Ja ich musste aber nochmal den name ändern weil ich gesehen habe ich habe viessmannapi und nicht viessmann ersetzt

[Unterstedter]

Läuft auch bei mir, ganz, ganz vielen Dank dafür!
Kurze Frage, gibt es eine maximale Anzahl abrufr, die viessmann zulässt? Habe leider selber dazu noch nichts gefunden.

[asblass]

Hi @unterstedter

Findest Du unter Preise: Freie API-Aufrufe pro Tag: 1450
Es gibt auch eine History Anzeige: https://developer.viessmann.com/de/clients/history

Grüße
Andreas

[tombox]

@asblass zur Zeit werden bei einer Anlage mit einem Gerät 3 Anfragen pro interval gemacht

Feature Gerät
Feature gateway was bisher leer ist
Events

[Unterstedter]

@tombox @asblass

also wenn ich das richtig verstehe:

1450 pro Tag
3x Abrufe pro zyklus
~500 Zyklen pro Tag
~20 Zyklen pro Stunde, also minimales intervall 3 Minuten, aber dann ist nix mehr übrig, um eigene Werte zu setzen, oder?

[Wing.Stefan]

@cheussen
Hallo, ich bräuchte etwas das mit VitoConnect und Loxone zusammen arbeitet über IOBroker, bis vor kurzem hatte ich sowas über Loxberry, leider gibt es dort nichts mehr und IOBroker wäre mir sowieso lieber
'Kannst du da etwas machen

[CBR-35]

Hallo zusammen,
ich bin die oberen Punkte durchgegangen und bekomme beim GET_Token folgende Rückmeldung:

{
    "error": "invalid-token-request"
}

Hat sich der Zugriff in der Zwischenzeit geändert?
Kann es sein das ich noch OAuth 2.0 bei Authorization einstellen muss und wenn ja, weiß jemand ich da alles eintragen muss?

Bin leider absoluter Anfänger in der Thematik.

Danke schon mal im Voraus.

[Test04]

@cbr-35

Ich hänge aktuell beim selben Punkt fest, was für Daten muss ich eingeben um den Token zu bekommen und wie funktioniert das dann mit dem GET_refresh_Token?

[tombox]

@test04 @CBR-35
was ist mit dem Adapter
https://forum.iobroker.net/topic/46778/test-viessmannapi-v2-0-0

[Rui Couto]

@cbr-35 Habe das gleiches Problem.
Konntest du das losen?