Skip to main content

A aiohttp-based client for Genius Hub systems

Project description


This is a Python library to provide access to a Genius Hub via its RESTful API. It uses aiohttp and is therefore async-friendly.

This library can use either the offical v1 API with a hub token, or the latest v3 API (using your own username and password). In either case, the library will return v1-compatible results wherever possible (this is not a trivial task).

If you use the v3 API, you can interrogate the hub directly, rather than via Heat Genius' own servers. Note that the v3 API is undocumented, and so this functionality may break at any time.

It is a WIP, and is missing some functionality (e.g. schedules). In addition, there are some other limitations (see below).

It is based upon work by @GeoffAtHome - thanks!

Current limitations

Current limitations & to-dos include:

  • is not complete
  • minimal support for schedules (e.g. they can't be modified), and...
  • for v3, all zones have a empty schedule
  • for v3, some zones have the wrong value for occupied


Either clone this repository and run python install, or install from pip using pip install geniushub-client.

Using the Library

See for example code. You can also use for ad-hoc queries:

python -?

There are two distinct options for accessing a Genius Hub:

Option 1: hub token only:

  • requires a hub token obtained from
  • uses the v1 API - which is well-documented
  • interrogates Heat Genius' own servers (so is slower)

Option 2: hub hostname/address with user credentials:

  • requires your username & password, as used with
  • uses the v3 API - results are WIP and may not be what you expect
  • interrogates the hub directly (so is faster)

python ${HUB_TOKEN} issues

python ${HUB_ADDRESS} -u ${USERNAME} -p ${PASSWORD} zones -v

You can compare any output to the official API (v1 response):

curl -X GET -H "authorization: Bearer ${HUB_TOKEN}"
python ${HUB_TOKEN} zones -vv

curl -X GET -H "authorization: Bearer ${HUB_TOKEN}"
python ${HUB_ADDRESS} -u ${USERNAME} -p ${PASSWORD} devices

curl -X GET -H "authorization: Bearer ${HUB_TOKEN}"
python ${HUB_ADDRESS} -u ${USERNAME} -p ${PASSWORD} issues

You can obtain the actual v3 API responses (i.e. the JSON is not converted to the v1 schema):

python ${HUB_ADDRESS} -u ${USERNAME} -p ${PASSWORD} zones -vvvv
python ${HUB_ADDRESS} -u ${USERNAME} -p ${PASSWORD} devices -vvvv

To obtain the actual v3 API responses takes a little work. First, use python to obtain a HASH:

>>> from hashlib import sha256
>>> hash = sha256()
>>> hash.update(("my_username" + "my_password").encode('utf-8'))
>>> print(hash.hexdigest())

Then you can use curl:

curl --user ${USERNAME}:${HASH} -X GET http://${HUB_ADDRESS}:1223/v3/zones

Advanced Features

When used as a library, there is the option to utilize the rerencing module's own aiohttp.ClientSession() (recommended):

import asyncio
import aiohttp
from geniushubclient import GeniusHubClient, GeniusHub

session = aiohttp.ClientSession()


if not (username or password):
   client = GeniusHubClient(hub_id=hub_address, username, password, session=session)
   client = GeniusHubClient(hub_id=hub_token, session=my_session)
hub = GeniusHub(client, hub_id=args.hub_id[:20])

print(await hub.zones)

await session.close()

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

geniushub-client-0.3.6.tar.gz (12.5 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page