Introduction

The other pages on this site which describe using scripts to interact with the NIBE Uplink API have proved quite popular, especially in explaining the requirements for OAuth2 Authentication. In late 2023, the NIBE Uplink service is being decommissioned and NIBE heat pump owners are being encouraged to move to the alternative myUplink service, so this page specifically covers that alternative API instead.

It was only the older NIBE F-series heat pumps that used NIBE Uplink anyway; the newer S-series have always used myUplink. Other people have had good success using variants of the NIBE Uplink scripts to access myUplink since the APIs are similar and the authentication requirements are the same, but the structure of the API calls is different (arguably better and simpler – more logical and fewer calls required to return the same data).

This page intentionally duplicates a lot of the content from the earlier NIBE Heat Pump Monitoring via NIBE Uplink API (Python Version) since I expect most new users will arrive at this page and it’s less confusing if the instructions are self-contained and if the screenshots reflect the myUplink look-and-feel.

Disclaimer

This procedure works for me and I’m publishing it here as a Proof of Concept in case it helps other people trying to accomplish the same objective. It may not work for you. It may not get updated in line with changes to the myUplink API service. You are responsible for complying with the terms of the myUplink API Services Agreement and for keeping the application Identifier, Secret and any generated user Tokens confidential.

My Use Case

I have an 8kW NIBE F1145 Ground Source Heat Pump which was installed in 2016 and was originally configured to send data to the NIBE Uplink service. Towards the end of 2023 NIBE have been migrating NIBE Uplink users over to the newer myUplink service and these notes were written in support of that migration.

The uploaded data is accessible via the myUplink website and the myUplink smartphone app, but those apps use the API ‘under the covers’ and it’s possible to call the API directly from a custom program or script to access all the same data – and then do more interesting things with it.

I have a script which invokes the myUplink API on a timed schedule (every few minutes) to download the parameters I’m interested in which I then re-publish using MQTT (my personal preference; in no sense essential) to integrate them with data from other sources (Meter-Bus electricity and heat meters, Dallas Semiconductor One-Wire sensors, Oregon Scientific temperature / humidity sensors – see other pages on this Blog for more details of those if you’re interested). Everything then gets loaded into an InfluxDB time-series database from which it can be extracted and graphed with Grafana (again my personal preferences but these tools work well for me).

At the risk of straying even further off-topic, some of my myUplink data gets further re-published to HeatpumpMonitor.org (a community dashboard of heat pump performance data). Since that also needs a feed of Electricity Consumption and Heat Output data, which are not part of the myUplink dataset, I found it easier to source the data from InfluxDB and upload to emoncms.org (which drives HeatPumpMonitor.org) in one go.

Pre-Requisites

At a bare minimum you will need the following to use this procedure:

A myUplink account with at least one NIBE heat pump registered to it and reporting data which is viewable via the website or one of the smartphone apps.
- Anyone can use the “Register an account” button on the main myUplink page to create an account if you don’t have one, but unless you have a heat pump linked to the account the API won’t return any meaningful data.
- It doesn’t strictly have to be your own heat pump; other people can grant your myUplink account ‘Viewer’ access to their heat pump.
A computer which is able to access the Internet and which will run the Python script to download data via the API.
- It doesn’t need to be particularly powerful – an old Raspberry Pi or similar single-board-computer is perfectly adequate. It could also be a virtual server hosted in the Cloud, or a Windows desktop or laptop.
- It doesn’t need to run a web browser or have a graphical display attached – remote access via a terminal window using a tool like PuTTY or ‘ssh’ is sufficient.
An Internet-connected computer with a standard graphical web browser (Firefox, Chrome, Edge, Safari etc.) which can be used to complete Steps 1 and 2 in the procedure described below. This can be any platform you like – potentially even a Smartphone – and certainly could be the same computer described at Item 2 above if that meets the requirements, though typically it will be a different machine.
- If the computer running the browser is not the same as the one running the script, then ensure you can connect to the computer running the script, since you will need to copy-and-paste a long text string between the two, accurately and quickly.
A basic knowledge of the Python scripting language, editing files and installing software packages on your chosen platform.

myUplink API – Documentation and Underpinning Technologies

The official documentation for the myUplink API is at https://dev.myuplink.com/ (note you need to login to access that page). The detail is described on those pages but in summary:

It’s a RESTful API accessed over HTTPS
Data is encoded using JSON
Requests are authenticated using OAuth2
OAuth2 presents the single biggest challenge for using the API because you need to obtain a valid Token and then Refresh that whenever it Expires

The older NIBE Uplink API only supported OAuth2’s Authorization Code Grant Flow (also known as the Web Application Flow); the myUplink API also supports OAuth2’s Client Credentials Grant Flow (also known as the Backend Application Flow) which appears somewhat simpler. The current page concentrates on the Authorization Code Grant Flow since that replicates the old NIBE Uplink behaviour. There’s more info on the Authentication options at https://dev.myuplink.com/auth and probably the simpler Client Credentials Grant Flow would be a better match to the requirements of most hobbyist users. Maybe I’ll address that in a future update to this page.

Personally I found the biggest barrier to getting the API working was understanding what the OAuth2 Callback URL was all about and what would be an acceptable value to use for that (there are several constraints). Actually it’s not all that complicated and it only needs to be used once, in order to initially get an Access Token. Importantly, it’s possible to run some steps in the procedure on different machines (as long as they’re done in quick succession). Here’s a summary of how it works:

When one of your application’s users (most likely yourself in this scenario) enters their myUplink credentials in a browser window and agrees to grant your application access to their data, the myUplink website redirects them to the Callback URL, attaching an Authorization Code which is only valid for a limited time and can only be presented once
Before the code expires, it’s necessary to present it to the myUplink Token URL together with other application-specific parameters in order to be allocated an Access Token and an accompanying Refresh Token
As long as you can get the Authentication Code presented to the Token URL before it expires, you can do that from anywhere – it doesn’t need to be from the same machine as is hosting the Callback URL though that is typically the scenario described in other OAuth2 documentation

I believe it’s necessary for the Callback URL to use HTTPS and since that can be problematic to configure I’m hosting a simple script on the same server as this Blog which anyone should be able to specify as their Callback URL – it will simply print out the generated Authorization Code (or any error message). That URL is: https://www.marshflattsfarm.org.uk/nibeuplink/oauth2callback/index.php (which will complain unless you call it with the right parameters – see later).

If you want to host your own installation of the Callback URL the PHP script code I’m using can be download from GitHub here.

The Python library Requests-OAuthlib is used to hide much of the complexity of OAuth2 processing. The documentation at that link explains how to use it though in principle if you exactly follow the procedure outlined below you don’t need to understand in detail how it works.

Step-By-Step Procedure

Step 0 – Prepare the Python Computer

The computer which will run the script that calls the myUplink API needs some preparation to ensure the Python environment and the necessary supporting Python libraries are available.

The first requirement is a working Python3 environment
- On Windows, follow the instructions at Python Releases for Windows
- On Raspberry Pi OS, run: sudo apt-get install python3
The second requirement is the Requests-OAuthlib library
- On Windows, use a Command Prompt to run: pip3 install requests-oauthlib
- On Raspberry Pi OS, can install this with: sudo pip3 install requests-oauthlib
  - If that doesn’t work, you might need to first run: sudo apt-get install python3-pip

Step 1 – Register your ‘Application’

The Python script you are about to create that will call the myUplink API is what the API calls an ‘Application’ so start by Registering a new Application at the myUplink website so that you get allocated your various unique ID strings which will be required later.

Connect to https://dev.myuplink.com/ using your favourite web browser on any machine you like (it does not need to be the machine which will later run the Python script)
Login with your myUplink username and password
Click on the Applications tab (or go to https://dev.myuplink.com/apps)
Press the grey Create New Application button on the left
Populate the Name, Description and Callback URL fields
- Choose your own values for Name (maybe “Python API Script” as shown) and Description and either specify your own Callback URL (if you’ve set one up hosting the PHP code mentioned above) or use https://www.marshflattsfarm.org.uk/nibeuplink/oauth2callback/index.php
Read the Services Agreement, click to confirm your acceptance of that – at this point the screen should look like the image below:
Press the Create button
Record the allocated Client Identifier and Client Secret credentials and keep them secret! (you can view them later under Applications if required)

Step 2 – Create an Access Token using an Authorization Code

Download the first sample Python script from the GitHub repository
- If you’re familiar with Git(Hub) and you have the ‘git’ client software installed, you might wish to ‘clone’ the repository (don’t worry if those words don’t mean anything to you – do one of the following instead)
- Alternatively, browse to the GitHub repository page and download the request_token.py file
- Alternatively, run this command in a terminal window: wget https://github.com/MarshFlattsFarm/myUplink-API/raw/main/request_token.py
Edit the downloaded Python script with whichever editor you prefer and replace the definitions of client_id and client_secret with the Client Identifier and Client Secret strings from Step 1
This next bit (as far as Step 9) is the time-sensitive bit: In a terminal window, run the command: python3 request_token.py
The script will display a long URL which you should copy and paste into a Web Browser window
If you’re already logged in to the myUplink API website (e.g. having just created your Application) in the same Browser you might not be prompted for your credentials, otherwise expect to have to enter your myUplink Username and Password
Expect to see a page like the screenshot below (you’ll see the Name you specified rather than “Python API Script” if you changed it). This is myUplink asking you to grant permission for your script to act on behalf of your user account.
Press the Yes, Allow button
If everything works you’ll see a very simple web page which looks like the following (which is generated by the Callback URL):
That value for Parameter ‘code’ (pixelized in the screenshot) is your Authorization Code which you’ll need to copy-and-paste into the terminal window where the Python script will still be waiting – before the code expires
The script should confirm to which file it has written the Token obtained using the Code – if you see an error message instead the code might have expired, so try the procedure again but paste the code as soon as you see it in the browser
Once you get confirmation the Token has been written to file, that’s the time-sensitive part of the procedure completed. The file includes both a ‘currently-valid’ token and also a second token which can be used to refresh the token when it expires.
Note that anyone who can read the file containing the Token will be able to access the myUplink API as your account; if it’s on a shared computer you will want to change the permissions to ensure nobody else can read it

Step 3 – Call the NIBE Uplink API

Now we have an Access Token we can actually call the API – and now things are less time-critical because the Token will be automatically renewed as required.

Download the second sample Python script from the GitHub repository – this one is called: simple_call_to_protected_api.py
Edit this sample script to set client_id and client_secret as before
Run the script with: python3 simple_call_to_protected_api.py
If it works as expected it will list out the systemId number(s) and name(s) of the heat pump(s) assigned to your myUplink account

If that worked OK then you can also try the third sample Python script in the GitHub repository, called: get_DevicePoints_for_Devices_for_Systems.py

You will have to edit client_id and client_secret as before (the first part of this script is identical to the previous script). This third script:

Retrieves the list of Systems defined for the authorized User, together with their associated Devices
For each of those Devices, retrieves the associated DataPoints (like BT1, the Outdoor Temperature)

These details are simply printed out but the script could be adapted to publish them as MQTT messages or re-formatted as XML or JSON or similar and sent to a Home Automation system or database.

Next Steps

If this procedure works for you, great! Please leave a Comment to let me know. If it doesn’t work or doesn’t makes sense please also leave a Comment and I’ll try to help.

Clearly just printing out the systemIds isn’t very interesting but the myUplink API Documentation describes the other API calls in some detail.

Marsh Flatts Farm Self Build Diary

It will be nice when it's finished

NIBE Heat Pump Monitoring via myUplink API