Skip to content

Jelloeater/hubitatcontrol

Repository files navigation

Hubitat Elevation Maker API Interface

Test CodeQL Libraries.io dependency status for latest release

hubitatcontrol PyPI - Status PyPI GitHub

Intro

This guide assumes you own a Hubitat Elevation home automation controller.

If you are interested in purchasing one, you can purchase a unit from the manufactures website at hubitat.com or from Amazon.com

Changes

See CHANGELOG.md for current changes

Setup

To get the required API keys, you will need to log in to your Hubitat admin interface.

See Maker API Documentation for how to add the MakerAPI application and to generate new API keys

If you are using the cloud API endpoint for access, you will ALSO need to include the Cloud API key when setting up a new Hub object.

Install

pip install hubitatcontrol

Or if you want a copy direct from source

pip install git+https://github.com/Jelloeater/hubitatcontrol.git

Usage

API

Local Example

import hubitatcontrol as hc

hub = hc.Hub(host='http://192.168.1.100', token='Maker_Token',
app_id='Maker_App_ID') # Get Hub object to auth and poll against

# If you have a cloud based maker API, you can include the cloud token
# hub = hc.get_hub(host='https://cloud.hubitat.com', token='Maker_Token',
#                  app_id='Maker_App_ID', cloud_token='Cloud_API_token')

TEST_DEVICE = '1RGB'

device = hc.GetSingleDevice(hub).name(TEST_DEVICE)

# Turn on all the switches (includes lights)
device.turn_on() # Send command to device
print(device.switch)

# Get temprature from all sensors
for i in hc.GetDevices(hub).TemperatureSensor():
    print(f"{i.name} - {i.temperature}")

CLI Interface

  • If you have all the needed API keys added to your .env file, all you need to do is add them to your keyring
  • Once loaded into the keyring, you can run the CLI from anywhere on your system
hubitatcontrol --help
hubitatcontrol load-env-to-keyring
hubitatcontrol ls
❯ hubitatcontrol

 Usage: hubitatcontrol [OPTIONS] COMMAND [ARGS]...

 Hubitat Control CLI Interface

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --install-completion        [bash|zsh|fish|powershell|pwsh]  Install completion for the specified shell. │
│                                                              [default: None]                             │
│ --show-completion           [bash|zsh|fish|powershell|pwsh]  Show completion for the specified shell, to │
│                                                              copy it or customize the installation.      │
│                                                              [default: None]                             │
│ --help                                                       Show this message and exit.                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────╮
│ clear-keyring                      Clear Keyring passwords                                               │
│ level                              Turn on a device via it's Device ID                                   │
│ load-env-to-keyring                Load .env file at exec location to keyring                            │
│ ls                                 Prints current devices from system keyring                            │
│ off                                Turn on a device via it's Device ID                                   │
│ on                                 Turn on a device via it's Device ID                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 Version: 1.1.2   Project: https://github.com/Jelloeater/hubitatcontrol

Docs

Located in /docs folder

You will need a .dot file browser for the class diagrams

WIP: Setup ReadTheDocs auto gen

Issues / Features

See:

https://github.com/Jelloeater/hubitatcontrol/issues

Structure

Class Model

flowchart LR
Specific_Device --> Abstract_Device_Class --> Device--> Hub
Loading

Development setup

Testing is done with PyTest, you will need to set up the correct env vars for your local (or cloud) Hubitat API See .env.example

If you are using a local API endpoint, please leave HUBITAT_CLOUD_ID blank in the .env file.

Setup

Install Go-Task --> https://taskfile.dev/installation/

task setup
task