Ihr Browser ist veraltet!

Aktualisieren Sie Ihren Browser. Jetzt Browser updaten

×

Cookies: Diese Website verwendet Cookies. Durch die Nutzung und weitere Navigation auf dieser Website akzeptieren Sie dies. Detaillierte Informationen über die Verwendung von Cookies auf dieser Website erhalten Sie, wenn Sie hier klicken. Weitere Informationen Schließen

in 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 Belimo Cloud Account credential and "__ClientIDPlaceHolder__" and "__ClientSecretPlaceHolder__" with the credential you received on your Belimo Cloud Account promotion as a Developer.

To access the complete documentation about our Cloud API log in http://cloud.belimo.com using your Developer account 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=cloud + '/oauth/token', username=user, password=passwd, client_id=client_id, client_secret=client_secret)

Get an overview over 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: