Plot your first graph in Python

In a few simple steps you can build your fully-functional application, main focus is on:

Gain access to the Service User Space
Select data
Acquire data
Plot

To have the complete example just cut and paste in a single file the code shown in the next paragraphs.

This example has been designed for the demo environment so you will replace "__UserPlaceHolder__" and "__PasswordPlaceHolder__" with your BelimoID Account credential and "__ClientIDPlaceHolder__" and "__ClientSecretPlaceHolder__" with the credential you received for the Developer Space.

To access the complete documentation about our Cloud API log in http://cloud.belimo.com using your BelimoID and then chose "support" -> "Documentation"

Python Libraries import

import requests
import json
import pandas as pd
import matplotlib.pyplot as plt
# enable inline pictures in Jupyter Notebook
%matplotlib inline
from oauthlib.oauth2 import LegacyApplicationClient
from requests_oauthlib import OAuth2Session

Set up the OAuth2.0 session

# OAuth Client
client_id = '__ClientIDPlaceHolder__'
client_secret = '__ClientSecretPlaceHolder__'
# OAuth user
user = '__UserPlaceHolder__'
passwd = '__PasswordPlaceHolder__'

# shorthand url
cloud = 'https://cloud.belimo.com'
oauth = OAuth2Session(client=LegacyApplicationClient(client_id=client_id))
token = oauth.fetch_token(
token_url='https://id.belimo.com/oauth/token',
username=user,
password=passwd,
client_id=client_id,
client_secret=client_secret,
include_client_id=True,
audience="https://api.cloud.belimo.com/",
scope=['public.read', 'offline_access', 'read:dataprofile'])

Get an overview of your devices

oauth.get(url=cloud + '/api/v3/devices/stats').json()

The output is then something like:

{
    'totalDevices': 36, 
    'connection': 
        {
         'offline': 1, 
         'online': 35
         }, 
    'health': 
        {
         'problem': 1, 
         'ok': 35
        }, 
    'transfer': 
        {
         'incoming': 0, 
         'outgoing': 0
        } 
}

Now we examine in more detail the devices seen and filter for those which are associated with heating:

# The id of the device (unique name)
# DisplayName: set during commissioning (allows for easy identification) (we will filter according to that one)
# Dataprofile: Where to find the information how to interprete data from the device
# url parameters
params = {
    'state': 'REGISTERED', # only get registered devices
    'limit': '100' # page size
}
# call API and print information
for device in oauth.get(url=cloud + '/api/v3/devices', params=params).json()['data']:
    if 'Heizung' in device['displayName']: # german word for 'Heating'
        print('id: ' + device['id'])
        print('name: ' + device['displayName'])
        print('dataprofile: ' + device['dataprofile']['entityId'])

The output is something like:

id: 5a430aa2-1d46-4776-bfe1-a10b6c567230
    name: Energieventil Heizung 2.OG Sued-Ost
    dataprofile: energyvalve3/1.2
    id: 3c563d80-48f0-4a7a-8701-65d65aefdd9c
    name: Energieventil Heizung 2.OG Nord-Ost
    dataprofile: energyvalve3/1.2
    id: 3c6f7077-a147-4d25-865f-e72901d9de62
    name: Energieventil Heizung 2.OG Nord-West
    dataprofile: energyvalve3/1.2
    id: b69b0b32-03ca-4ec4-8850-2a1b474fbd83
    name: Energieventil Heizung 1.OG Sued-West
    dataprofile: energyvalve3/1.2
    id: 0cc5b932-c7b0-4eab-87ae-153aec6a7f90
    name: Energieventil Heizung 2.OG Sued-West
    dataprofile: energyvalve3/1.2

Now let's download the Dataprofile and find the datapoint of interest

let's say we are interested in the following device

id: 3c6f7077-a147-4d25-865f-e72901d9de62
name: Energieventil Heizung 2.OG Nord-West
dataprofile: energyvalve3/1.2

deviceid = '3c6f7077-a147-4d25-865f-e72901d9de62'
dataprofileid = 'energyvalve3/1.2'

dataprofiledef  = oauth.get(url=cloud + '/api/v3/definitions/dataprofiles/' + dataprofileid).json()
# Extract relevant datapoints
# Let's say we are interested in energy consumption
print('Energy related datapoints:')
for dp in dataprofiledef['datapoints']:
    if 'Energy' in dp['featureValues']['default.description']: # get those datapoints which are related to Energy
        print('id: ' + dp['id'])
        print('description: ' + dp['featureValues']['default.description'])

The output will be something like this:

    Energy related datapoints:
    id: evcloud.200
    description: Cooling Energy in J
    id: evcloud.210
    description: Heating Energy in J

let's get the state and historical values for the heating energy:

# Current state
# First we the current state of the device, and extract from it e.g. location
state = oauth.get(url=cloud + '/api/v3/devices/' + deviceid).json()
# We can print current Value
state['state']['datapoints']['evcloud.210']
# Set parameters to access the historical data
params = {
    'datapointIds': 'evcloud.210',
    'resolution': '1d',
    'from': '2017-12-01T00:00:00Z',
    'to': '2018-12-01T00:00:00Z'
}
data = oauth.get(url=cloud + '/api/v3/devices/' + deviceid + '/data/history/timeseries', params=params).json()
# Extract the time series
# We only queried for one series
# We are interested in the values, not the metadata
# construct pandas DataFrame from data
heatingEnergy = pd.DataFrame(data['series'][0]['values'])
# convert timestamp to pandas datetime
heatingEnergy['timestamp'] = pd.to_datetime(heatingEnergy.timestamp)
# Energy is cumulative -- here we compute the difference between timepoints and convert to kWh
heatingEnergy['DiffEnergyConsumption'] = heatingEnergy.value.diff() / 3600000

and then plot the energy consumption

heatingEnergy.plot(x='timestamp', y='DiffEnergyConsumption', marker='o', alpha=0.5, stacked=True, figsize=(20,10))

plt.show()

The outcome should look like this:

Americas

Europe, Middle East & Africa

Asia Pacific