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 OAuth2SessionSet 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() / 3600000and 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:
