jason0x43 / hubitatmaker Goto Github PK

A Python library for interfacing with a Hubitat hub via its Maker API

License: MIT License

Python 67.18% HTML 32.82%

hubitatmaker's Introduction

hubitatmaker

This library provides an async Python interface for Hubitat Elevation’s Maker API. It is primarily intended for use with Home Assistant.

Features

The main public API in hubitatmaker is the Hub class. This class represents a Maker API instance on a Hubitat hub. When started, a Hub instance will determine the Hubitat hub's MAC address and and download a list of available devices and details about each device.

The Hub instance caches state information about each device. It relies on events posted from the Hubitat hub to update its internal state. Each Hub instance starts a new event listener server to receive events from the hub, and updates the Maker API instance with an accessible URL for this listener server.

Basic usage

import asyncio
from hubitatmaker import Hub

async def print_devices(host, app_id, token):
	hub = Hub(host, app_id, token)
	await hub.start()
	for device in hub.devices:
		print(f"{device.name} ({device.id})")

if __name__ == '__main__':
	host = 'http://10.0.1.99'
	app_id = '1234'
	token = '<apitoken>'
	asyncio.run(print_devices(host, app_id, token))

API

See the API doc.

Developing

To get setup for development, run

$ pdm run init

To test the code, which will type check it and run unit tests, run

$ pdm run test

hubitatmaker's People

Contributors

Stargazers

Watchers

Forkers

spectre3ooo warrenguy clboles glimmerman1973 cdhawan kevdliu chrisk9eq

hubitatmaker's Issues

Allow event_url to be manually set

See jason0x43/hacs-hubitat#80

Add support for the ReleasableButton capability

PushableButton is supported. Also support ReleasableButton.

Support modes

See jason0x43/hacs-hubitat#42

Load hub metadata from UPNP endpoint

http://<hub_address>/api/hubitat.xml

<?xml version="1.0" encoding="UTF-8" ?>
<root xmlns="urn:schemas-upnp-org:device-1-0">
    <specVersion>
        <major>1</major>
        <minor>0</minor>
    </specVersion>
    <URLBase>http://<hub_address>:8080/</URLBase>
    <device>
        <deviceType>urn:Hubitat:device:Hub:1</deviceType>
        <friendlyName>Hubitat Hub [Home] (<hub_address>)</friendlyName>
        <manufacturer>Hubitat Inc.</manufacturer>
        <manufacturerURL>http://hubitat.com</manufacturerURL>
        <modelDescription>Hubitat Elevation Hub</modelDescription>
        <modelName>Rev C-7</modelName>
        <modelNumber>2.2.4.158</modelNumber>
        <modelURL>http://hubitat.com</modelURL>
        <serialNumber>...</serialNumber>
        <UDN>...</UDN>
        <presentationURL>index.html</presentationURL>
        <iconList>
            <icon>
                <mimetype>image/png</mimetype>
                <height>50</height>
                <width>50</width>
                <depth>8</depth>
                <url>/ui2/images/hub.png</url>
            </icon>
        </iconList>
    </device>
</root>

Run an event listener server by default

This package has the ability to run an event listener server, but doesn't by default as it seemed easier to let something else handle that. (The hacs-hubitat plugin uses a Home Assistant webhook for that purpose.)

The Home Assistant REST server may not always be a good choice, though, since it may be an external address. Instead, this package should use run its internal event listener server by default.

Support HSM state

See https://community.hubitat.com/t/announcing-rule-machine-3-0-hub-update-2-0-9-is-available/14758 for HSM API.

Listen on 0.0.0.0

Currently, the event server attempts to listen on the specific interface used to reach the hubitat hub. In at least some cases, it appears to detect the wrong interface (jason0x43/hacs-hubitat#120).

Consider having the server listen on 0.0.0.0.

Don't try to update devices with non-device events

Hub should not try to use non-device events, like SSDP messages, to update devices:

2020-09-21 07:55:20 DEBUG (MainThread) [hubitatmaker.hub] Received event: {'name': 'ssdpTerm', 'value': 'urn:schemas-upnp-org:device:basic:1', 'displayName': None, 'deviceId': None, 'descriptionText': None, 'unit': None, 'type': None, 'data': None}
2020-09-21 07:55:20 DEBUG (MainThread) [hubitatmaker.hub] Updating ssdpTerm of None to urn:schemas-upnp-org:device:basic:1
2020-09-21 07:55:20 WARNING (MainThread) [hubitatmaker.hub] Tried to update unknown device None

Integration Setup fails if HSM is not enabled in the MakerAPI

If "Allow control of modes" and "Allow control of HSM" are not enabled in Hubitat MakerAPI then the integration setup fails and never completes. The following is in the home assistant logs:

2020-11-30 14:49:32 DEBUG (MainThread) [hubitatmaker.hub] Loaded modes 2020-11-30 14:49:32 DEBUG (MainThread) [hubitatmaker.hub] Loaded hsm status 2020-11-30 14:49:32 ERROR (MainThread) [homeassistant.config_entries] Error setting up entry Hubitat for hubitat Traceback (most recent call last): File "/usr/src/homeassistant/homeassistant/config_entries.py", line 236, in async_setup result = await component.async_setup_entry(hass, self) # type: ignore File "/config/custom_components/hubitat/__init__.py", line 33, in async_setup_entry if not await hub.async_setup(): File "/config/custom_components/hubitat/device.py", line 184, in async_setup await self._hub.start() File "/usr/local/lib/python3.8/site-packages/hubitatmaker/hub.py", line 158, in start await self._load_hsm_status() File "/usr/local/lib/python3.8/site-packages/hubitatmaker/hub.py", line 336, in _load_hsm_status self._hsm_status = hsm["hsm"] KeyError: 'hsm'