Generating the access token for the very first time is a pain in the neck. All the more since the authorization code parameter which has to be created and used to get the authorization token, has a very short 20 seconds time to live (TTL). So, you’d better hurry up and be nimble with ctrl-c and ctrl-v actions when using (semi-)manual solutions with Node-Red snippets, bash or Postman.
Once you’ve generated the access token, refreshing the access token by means of the refresh token every 59 minutes or so, is a snap. However, after 180 days the TTL of the refresh token has expired and you have to go through the cumbersome first-time generation process for the tokens again.
I felt kind of fed up with this – so I played around a bit and came to the solution described here. Please bear with me if my explanations seem a bit trivial or lengthy – I am an amateur not a professional. It took me quite a while to wrap my brain about this, so I’d like to walk you through my train of thought.
I guess there are other solutions around e.g. this one using php: https://www.viessmann-community.com/t5/Getting-started-programming-with/To-help-get-started/td-p/181.... However, I wanted to stay within Node-Red’s environment.
Walk Through
Node-Red has webserver capability by means of two http nodes: http in and http response. They exist under the local address of http://localhost:1880
Step 1 – Authorization Request
To create the first call, you’ll need the following parameters:
client_id and redirect_uri
Both are set by means of the Developer Dashboard at: https://app.developer.viessmann.com/.
I’m assuming that you have already created an account.
The client_id is static, and does not change when you change the redirect_uri setting. It will be created during the first client setting but can be deleted and re-created as you like.
In the generic example the redirect_uri http://localhost:4200 is used. This works fine as long as you use a browser to generate the authorization code which can be copied from the URL field of the browser’s error message.
For our purposes however, we need to change this to http://localhost:1880/authcode. The path authcode can be anything but must be the same as the one used in the URL field of the http in node we’re going to use further down.
Don’t forget to turn off the Google CAPTCHA setting.
Fixed parameters
Scope is set to scope = "IoT User" this is important otherwise you won’t be able to do much.
Response Type is set to response_type = "code".
Code Challenge is set to
code_challenge=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c which is identical to the one used in the “Getting Started” chapter of Viessmann’s documentation. In my opinion you can continue to use that and forget about hashing and encoding as required by the oAuth method. I never was able to grasp the concept.
And, finally we must add the parameter offline_access to also get the refresh token lateron.
The URL assembled to generate the authorization request looks like this (blanks are ecoded by %20) :
https://iam.viessmann.com/idp/v2/authorize?client_id=my_oauth_client_ID&redirect_uri=http://localhost:1880/authcode&response_type=code&code_challenge=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c&scope=IoT%20User%20offline_access
Now we can drag an http request node to the development area of Node-Red, additionally a Trigger node and a debug node
The request Node is configured as follows:
Method is GET, URL is the one shown above, Payload is ignored, Basic Authentication is used and is set to your Viessman Login Username and Password, the rest stays as it is.
To receive this request, we need to set up a minimal webserver by using the http in and http response nodes. This looks like so:
The http in node is configured like this:
The URL field has to correspond to the path used in the redirect URI – without server name and port number.
The response node is set to status code 200
Please note that the request part and the response part are not connected by a wire. This is where Internet magic happens.
If all goes well, debug node at the receiving end should show the authorization code after you hit the trigger at the request side. The authorization code can be accessed by using msg.payload.code - we will need it in the following steps.
You will find the complete generic JSON code at the end of this article.
Step 2 – Authorization Code Exchange – initial generation of access and refresh tokens
Having created the authorization code represented by msg.payload.code, we can now continue along the Authentication chapter of the Viessmann doc pages. In Node-Red this looks like this:
The top left part we have already covered above.
The function node set payload & headers is configured like this:
msg.payload = `grant_type=authorization_code&client_id=my_oauth_client_ID&redirect_uri=http://localhost:1880/authcode&code_verifier=2e21faa1-db2c-4d0b-a10f-575fd372bc8c-575fd372bc8c&code=${msg.payload.code}`;
msg.headers = {};
msg.headers['Content-Type'] = 'application/x-www-form-urlencoded';
return msg;
Watch out, the text after msg.payload is written as one single line only. Also observe the backtics which are necessary to concatenate the fixed part of the payload with the variable “msg.payload.code”. All in all, the JavaScript should consist of 4 lines. You will find the complete JSON (a pdf file) at the end of this article
The html request node 1st time token request looks like this:
Observe the setting: Return a parsed JSON object.
If all goes well, the JSON object contains both tokens which can be accessed by msg.payload.access_token and msg.payload.refresh_token.
Setting flow variables
In my implementation, I have everything concerning the ViCare API in one flow tab. Hence, I’m using flow variables. In case you have distributed the flows on several tabs, you should use global variables instead of flow variables.
Now it’s time to push our response into variables. I use a change node for that.
Retrieving Static values (once)
In addition, you will need the static values for InstallationID, gatewaySerial and deviceID.
You can either generate them once and hard-code them into your flow or re-request them every time, you’re running the initialization logic. In my example, I’m generating them during initialization. It’s a sequence of 3 requests, so we shouldn’t request these values too often – besides it’s unnecessary, they never change.
Refer to section IOT - Overview of the Viessman documentation for their creation or simply go through the JSON (pdf File) provided at the end of this article.
Notes
About refreshing the Access Token
Please note that the automatic Access Token refresh should occur every 59 minutes or so, just in time before the token expires. You could trigger the initialization routine described above. It would generate a new access token from scratch at regular intervals. However, this would eat into your requests allowance and also create extra load on Viessman’s servers.
I recommend to use a specialized refresh flow on the same tab that performs the refresh by using the refresh token. I have written about this in my article “Using Node-Red to visualize ViCare data”. The according JSON Routine is provided there as well.
About Triggering
How should you trigger this initialization process?
Manually
If your availability requirements are relaxed, you might as well trigger the initialization manually every time your application fails because of an expired refresh token i.e. every 180 days.
Automatically
As soon as the refresh token is no longer valid, the Viessmann server’s JSON response will contain a payload.error = "EXPIRED TOKEN" message. You can use this with a switch node to branch to the initialization routine in the rare event the refresh token is expired.
Using the API
Please refer to my article “Using Node-Red to visualize ViCare data”
I hope that you find this useful. Any comment is highly appreciated. The code can be found in the answer post below or at my website.
Christoph Krzikalla
2 AKZEPTIERTE LÖSUNGEN
Akzeptierte Lösungen
oops!!
Da hat mir der pdf Konverter einen Streich gesielt und zu lange Zeilen mit einem Zeilenumbruchzeichen "verschönert".
Abhilfe fürs Erste: Text mit Ctrl-C und Ctrl-V (bzw. Strg-...) kopieren und in einen Editor pasten. Dann bei den im Import angegebenen Zeilen
hier zum Beispiel Zeile 60 die Zeilen zusammenfügen:
Tut mir ausgesprichen leid. Ich versuche das in der kommenden Woche irgendwie zu beheben. Saublöd. dass man keine JSON oder TXT Dateien im Forum Hochladen kann...
VG
Chris
