README.md

Cloogy

Python client for Cloogy

See Demo.ipynb for a working Jupyter Notebook

0. Install cloogy

In your terminal: pip3 install cloogy

or in a python shell or notebook:

import pip
pip.main(['install', 'cloogy'])

import yaml

from cloogy import CloogyClient

1. Get your credentials

Get your login and password.

In this example we'll load it from a YAML file.

with open('credentials.yaml', 'r') as f:
    credentials = yaml.load(f)

login = credentials['login']
password = credentials['password']

2. Create a CloogyClient

If you supply a login and password, authentication will be handled for you.

client = CloogyClient(login=login, password=password)

3. List your Units

units = client.get_units()

units

4. Get a specific Unit by ID

# Lets grab the first ID from the list above
unit_id = units[0]['Id']
print(unit_id)

unit = client.get_unit(unit_id=unit_id)

unit

5. Find out some stuff about your unit

The Unit class is an extension to the regular python dict. This means it behaves like a normal dict, but adds some extra features.

# Get date and time of the last communication
unit.get_last_communication_date()

6. List all available Tags for your login

client.get_tags()

7. List available Tags for a Unit

tags = unit.get_tags()

tags

[tag['Id'] for tag in tags]

8. Get a specific Tag directly

tag_id = tags[0]['Id']
print(tag_id)

tag = client.get_tag(tag_id=tag_id)

tag

tag.get_last_communication_date()

9. Get consumptions

# pick a start and end time, as POSIX timestamp

import pandas as pd
start = int(pd.Timestamp('20180414').timestamp() * 1000)
end = int(pd.Timestamp('20180416').timestamp() * 1000)
print(start, end)

client.get_consumptions(
    granularity='hourly', # can be Instant, Hourly, Daily, Monthly, Yearly
    start=start,
    end=end,
    tags=[tag_id], # List of tag Id's
    instants_type=None  # How instant measurements should be aggregated. Can be Avg, Max, Min, Stdev. Default is Avg.
)

10. Get consumptions as a DataFrame

For some easy analysis, methods to get data as a Pandas DataFrame are included

Let's say we want to analyse the active energy consumption, which has TagTypeId 20001

tags = client.get_tags(where='TagTypeId=20001')
tag_ids = [tag['Id'] for tag in tags]

start = pd.Timestamp('20180101')
end = pd.Timestamp('20180417')

client.get_consumptions_dataframe(granularity='monthly', start=start, end=end, tags=tag_ids)

A flat table like this is nice, but it can contain multiple TagIds, and it has way to many columns we don't need.

We can also get a table for only the readings:

df = client.get_readings_dataframe(granularity='monthly', start=start, end=end, tags=tag_ids, metric='Read')

df

# make a plot!

%matplotlib inline
df.plot.bar()