cozify.hub

Module for handling highlevel Cozify Hub operations.

Module Contents

Functions

devices(capabilities=None, and_filter=False, **kwargs)

Get up to date full devices data set as a dict. Optionally can be filtered to only include certain devices.

device(device_id, **kwargs)

Get up to date device data set as a dict.

await_state(device_id, state, timeout=10, **kwargs)

Wait for a device to reach a desired state

has_state(device_id, state, **kwargs)

Check if device state matches the provided state keys. Keys not provided are ignored.

device_reachable(device_id, **kwargs)

Check if device is reachable.

device_exists(device_id, devs=None, state=None, **kwargs)

Check if device exists.

device_eligible(device_id, capability_filter, devs=None, state=None, **kwargs)

Check if device matches a AND devices filter.

device_toggle(device_id, **kwargs)

Toggle power state of any device capable of it such as lamps. Eligibility is determined by the capability ON_OFF.

device_state_replace(device_id, state, **kwargs)

Replace the entire state of a device with the provided state. Useful for example for returning to a stored state.

device_on(device_id, **kwargs)

Turn on a device that is capable of turning on. Eligibility is determined by the capability ON_OFF.

device_off(device_id, **kwargs)

Turn off a device that is capable of turning off. Eligibility is determined by the capability ON_OFF.

light_temperature(device_id, temperature=2700, transition=0, **kwargs)

Set temperature of a light.

light_color(device_id, hue, saturation=1.0, transition=0, **kwargs)

Set color (hue & saturation) of a light.

light_brightness(device_id, brightness, transition=0, **kwargs)

Set brightness of a light.

scenes(filters=None, **kwargs)

Get full scene data set as a dict. Optionally filters scenes by on/off status.

scene(scene_id, **kwargs)

Get scene data set as a dict.

scene_toggle(scene_id, **kwargs)

Toggle on/off state of given scene.

scene_on(scene_id, **kwargs)

Turn on a scene.

scene_off(scene_id, **kwargs)

Turn off a scene.

remote(hub_id, new_state=None)

Get remote status of matching hub_id or set a new value for it. Always returns current state at the end.

autoremote(hub_id, new_state=None)

Get autoremote status of matching hub_id or set a new value for it. Always returns current state at the end.

tz(**kwargs)

Get timezone of given hub or default hub if no id is specified. For more optional kwargs see cozify.hub_api.get()

ping(autorefresh=True, **kwargs)

Perform a cheap API call to trigger any potential APIError and return boolean for success/failure. For optional kwargs see cozify.hub_api.get()

name(hub_id)

Get hub name by it's id.

host(hub_id)

Get hostname of matching hub_id

token(hub_id, new_token=None)

Get hub_token of matching hub_id or set a new value for it.

hub_id(hub_name)

Get hub id by it's name.

exists(hub_id)

Check for existance of hub in local state.

default()

Return id of default Hub.

_getAttr(hub_id, attr, default=None, boolean=False)

Get hub state attributes by attr name. Optionally set a default value if attribute not found.

_setAttr(hub_id, attr, value, commit=True)

Set hub state attributes by hub_id and attr name

_get_id(**kwargs)

Get a hub_id from various sources, meant so that you can just throw kwargs at it and get a valid id.

_fill_kwargs(kwargs)

Check that common items are present in kwargs and fill them if not.

_clean_state(state)

Return purged state of values so only wanted values can be modified.

_in_range(value, low, high, description='undefined')

Check that the value is in the given range, raise an error if not.

getDevices(**kwargs)

Deprecated, will be removed in v0.3. Get up to date full devices data set as a dict.

getDefaultHub()

Deprecated, use default(). Return id of default Hub.

getHubId(hub_name)

Deprecated, use hub_id(). Return id of hub by it's name.

Attributes

capability

cozify.hub.capability
cozify.hub.devices(capabilities=None, and_filter=False, **kwargs)

Get up to date full devices data set as a dict. Optionally can be filtered to only include certain devices.

Parameters

  • capabilities (cozify.hub.capability) – Single or list of cozify.hub.capability types to filter by, for example: [ cozify.hub.capability.TEMPERATURE, cozify.hub.capability.HUMIDITY ]. Defaults to no filtering.

  • and_filter (bool) – Multi-filter by AND instead of default OR. Defaults to False.

  • **hub_name (str) – optional name of hub to query. Will get converted to hubId for use.

  • **hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.

  • **remote (bool) – Remote or local query.

  • **hubId (str) – Deprecated. Compatibility keyword for hub_id, to be removed in v0.3

  • **hubName (str) – Deprecated. Compatibility keyword for hub_name, to be removed in v0.3

Returns

full live device state as returned by the API

Return type

dict

cozify.hub.device(device_id, **kwargs)

Get up to date device data set as a dict.

Parameters

  • device_id (str) – ID of the device to retrieve.

  • **hub_name (str) – optional name of hub to query. Will get converted to hub_id for use.

  • **hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.

  • **remote (bool) – Remote or local query.

Returns

full live device data as returned by the API

Return type

dict

cozify.hub.await_state(device_id, state, timeout=10, **kwargs)

Wait for a device to reach a desired state

Parameters

  • device_id (str) – ID of the device to check.

  • state (dict) – Full state dictionary to expect. Timestamp fields are ignored.

  • timeout (int) – Timeout of wait time.

Returns

True when state matches or False on timeout.

Return type

bool

cozify.hub.has_state(device_id, state, **kwargs)

Check if device state matches the provided state keys. Keys not provided are ignored.

Parameters

  • device_id (str) – ID of the device to check.

  • state (dict) – State dictionary to expect. Only provide keys you care about.

Returns

If given state values match.

Return type

bool

cozify.hub.device_reachable(device_id, **kwargs)

Check if device is reachable.

Parameters

device_id (str) – ID of the device to check.

Returns

Reachability as defined by the API.

Return type

bool

cozify.hub.device_exists(device_id, devs=None, state=None, **kwargs)

Check if device exists.

Parameters

  • device_id (str) – ID of the device to check.

  • devs (dict) – Optional devices dictionary to use. If not defined, will be retrieved live.

  • state (dict) – Optional state dictionary, will be updated with state of checked device if device is eligible. Previous data in the dict is preserved unless it’s overwritten by new values.

Returns

True if filter matches.

Return type

bool

cozify.hub.device_eligible(device_id, capability_filter, devs=None, state=None, **kwargs)

Check if device matches a AND devices filter.

Parameters

  • device_id (str) – ID of the device to check.

  • capability_filter (hub.capability) – Single hub.capability or a list of them to match against.

  • devs (dict) – Optional devices dictionary to use. If not defined, will be retrieved live.

  • state (dict) – Optional state dictionary, will be updated with state of checked device if device is eligible. Previous data in the dict is preserved unless it’s overwritten by new values.

Returns

True if filter matches.

Return type

bool

cozify.hub.device_toggle(device_id, **kwargs)

Toggle power state of any device capable of it such as lamps. Eligibility is determined by the capability ON_OFF.

Parameters

  • device_id (str) – ID of the device to toggle.

  • **hub_id (str) – optional id of hub to operate on. A specified hub_id takes presedence over a hub_name or default Hub.

  • **hub_name (str) – optional name of hub to operate on.

  • **remote (bool) – Remote or local query.

cozify.hub.device_state_replace(device_id, state, **kwargs)

Replace the entire state of a device with the provided state. Useful for example for returning to a stored state.

Parameters

  • device_id (str) – ID of the device to toggle.

  • state (dict) – State dictionary to push out.

  • **hub_id (str) – optional id of hub to operate on. A specified hub_id takes presedence over a hub_name or default Hub.

  • **hub_name (str) – optional name of hub to operate on.

  • **remote (bool) – Remote or local query.

cozify.hub.device_on(device_id, **kwargs)

Turn on a device that is capable of turning on. Eligibility is determined by the capability ON_OFF.

Parameters

device_id (str) – ID of the device to operate on.

cozify.hub.device_off(device_id, **kwargs)

Turn off a device that is capable of turning off. Eligibility is determined by the capability ON_OFF.

Parameters

device_id (str) – ID of the device to operate on.

cozify.hub.light_temperature(device_id, temperature=2700, transition=0, **kwargs)

Set temperature of a light.

Parameters

  • device_id (str) – ID of the device to operate on.

  • temperature (float) – Temperature in Kelvins. If outside the operating range of the device the extreme value is used. Defaults to 2700K.

  • transition (int) – Transition length in milliseconds. Defaults to instant.

cozify.hub.light_color(device_id, hue, saturation=1.0, transition=0, **kwargs)

Set color (hue & saturation) of a light.

Parameters

  • device_id (str) – ID of the device to operate on.

  • hue (float) – Hue in the range of [0, Pi*2]. If outside the range a ValueError is raised.

  • saturation (float) – Saturation in the range of [0, 1]. If outside the range a ValueError is raised. Defaults to 1.0 (full saturation.)

  • transition (int) – Transition length in milliseconds. Defaults to instant.

cozify.hub.light_brightness(device_id, brightness, transition=0, **kwargs)

Set brightness of a light.

Parameters

  • device_id (str) – ID of the device to operate on.

  • brightness (float) – Brightness in the range of [0, 1]. If outside the range a ValueError is raised.

  • transition (int) – Transition length in milliseconds. Defaults to instant.

cozify.hub.scenes(filters=None, **kwargs)

Get full scene data set as a dict. Optionally filters scenes by on/off status.

Parameters

  • filters (dict) – Filter scenes by their values by defining key value pairs as a dict. Defaults to all scenes.

  • **hub_name (str) – optional name of hub to query. Will get converted to hubId for use.

  • **hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.

  • **remote (bool) – Remote or local query.

  • **hubId (str) – Deprecated. Compatibility keyword for hub_id, to be removed in v0.3

  • **hubName (str) – Deprecated. Compatibility keyword for hub_name, to be removed in v0.3

Returns

scene data as returned by the API

Return type

dict

cozify.hub.scene(scene_id, **kwargs)

Get scene data set as a dict.

Parameters

  • scene_id (str) – ID of the scene to retrieve.

  • **hub_name (str) – optional name of hub to query. Will get converted to hub_id for use.

  • **hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.

  • **remote (bool) – Remote or local query.

Returns

scene data as returned by the API

Return type

dict

cozify.hub.scene_toggle(scene_id, **kwargs)

Toggle on/off state of given scene.

Parameters

  • scene_id (str) – ID of the scene to toggle.

  • **hub_id (str) – optional id of hub to operate on. A specified hub_id takes presedence over a hub_name or default Hub.

  • **hub_name (str) – optional name of hub to operate on.

  • **remote (bool) – Remote or local query.

cozify.hub.scene_on(scene_id, **kwargs)

Turn on a scene.

Parameters

scene_id (str) – ID of the scene to operate on.

cozify.hub.scene_off(scene_id, **kwargs)

Turn off a scene.

Parameters

scene_id (str) – ID of the scene to operate on.

cozify.hub.remote(hub_id, new_state=None)

Get remote status of matching hub_id or set a new value for it. Always returns current state at the end.

Parameters

  • hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.

  • new_state (bool) – New remoteness state to set for hub. True means remote. Defaults to None when only the current value will be returned.

Returns

True for a hub considered remote.

Return type

bool

cozify.hub.autoremote(hub_id, new_state=None)

Get autoremote status of matching hub_id or set a new value for it. Always returns current state at the end.

Parameters

  • hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.

  • new_state (bool) – New autoremoteness state to set for hub. True means remote will be automanaged. Defaults to None when only the current value will be returned.

Returns

True for a hub with autoremote enabled.

Return type

bool

cozify.hub.tz(**kwargs)

Get timezone of given hub or default hub if no id is specified. For more optional kwargs see cozify.hub_api.get()

Parameters

**hub_id (str) – Hub to query, by default the default hub is used.

Returns

Timezone of the hub, for example: ‘Europe/Helsinki’

Return type

str

cozify.hub.ping(autorefresh=True, **kwargs)

Perform a cheap API call to trigger any potential APIError and return boolean for success/failure. For optional kwargs see cozify.hub_api.get()

Parameters

  • autorefresh (bool) – Wether to perform a autorefresh after an initially failed ping. If successful, will still return True. Defaults to True.

  • **hub_id (str) – Hub to ping or default if neither id or name set.

  • **hub_name (str) – Hub to ping by name.

Returns

True for a valid and working hub authentication state.

Return type

bool

cozify.hub.name(hub_id)

Get hub name by it’s id.

Parameters

hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.

Returns

Hub name or None if the hub wasn’t found.

Return type

str

cozify.hub.host(hub_id)

Get hostname of matching hub_id

Parameters

hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.

Returns

ip address of matching hub. Be aware that this may be empty if the hub is only known remotely and will still give you an ip address even if the hub is currently remote and an ip address was previously locally known.

Return type

str

cozify.hub.token(hub_id, new_token=None)

Get hub_token of matching hub_id or set a new value for it.

Parameters

hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.

Returns

Hub authentication token.

Return type

str

cozify.hub.hub_id(hub_name)

Get hub id by it’s name.

Parameters

hub_name (str) – Name of hub to query. The name is given when registering a hub to an account.

Returns

hub_id on success, raises an attributeerror on failure.

Return type

str

cozify.hub.exists(hub_id)

Check for existance of hub in local state.

Parameters

hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.

cozify.hub.default()

Return id of default Hub.

If default hub isn’t known an AttributeError will be raised.

cozify.hub._getAttr(hub_id, attr, default=None, boolean=False)

Get hub state attributes by attr name. Optionally set a default value if attribute not found.

Parameters

  • hub_id (str) – Id of hub to query. The id is a string of hexadecimal sections used internally to represent a hub.

  • attr (str) – Name of hub attribute to retrieve

  • default – Optional default value to set for unset attributes. If no default is provided these raise an AttributeError.

  • boolean – Retrieve and return value as a boolean instead of string. Defaults to False.

Returns

Value of attribute or exception on failure.

Return type

str

cozify.hub._setAttr(hub_id, attr, value, commit=True)

Set hub state attributes by hub_id and attr name

Parameters

  • hub_id (str) – Id of hub to store for. The id is a string of hexadecimal sections used internally to represent a hub.

  • attr (str) – Name of cloud state attribute to overwrite. Attribute will be created if it doesn’t exist.

  • value (str) – Value to store

  • commit (bool) – True to commit state after set. Defaults to True.

cozify.hub._get_id(**kwargs)

Get a hub_id from various sources, meant so that you can just throw kwargs at it and get a valid id. If no data is available to determine which hub was meant, will default to the default hub. If even that fails, will raise an AttributeError.

Parameters

  • **hub_id (str) – Will be returned as-is if defined.

  • **hub_name (str) – Name of hub.

  • hubName (str) – Deprecated. Compatibility keyword for hub_name, to be removed in v0.3

  • hubId (str) – Deprecated. Compatibility keyword for hub_id, to be removed in v0.3

cozify.hub._fill_kwargs(kwargs)

Check that common items are present in kwargs and fill them if not.

Args: kwargs(dict): kwargs dictionary to fill. Operated on directly.

cozify.hub._clean_state(state)

Return purged state of values so only wanted values can be modified.

Args: state(dict): device state dictionary. Original won’t be modified.

cozify.hub._in_range(value, low, high, description='undefined')

Check that the value is in the given range, raise an error if not. None is always considered a valid value.

Returns

True if value in range. Otherwise a ValueError is raised.

Return type

bool

cozify.hub.getDevices(**kwargs)

Deprecated, will be removed in v0.3. Get up to date full devices data set as a dict.

Parameters

  • **hub_name (str) – optional name of hub to query. Will get converted to hubId for use.

  • **hub_id (str) – optional id of hub to query. A specified hub_id takes presedence over a hub_name or default Hub. Providing incorrect hub_id’s will create cruft in your state but it won’t hurt anything beyond failing the current operation.

  • **remote (bool) – Remote or local query.

  • **hubId (str) – Deprecated. Compatibility keyword for hub_id, to be removed in v0.3

  • **hubName (str) – Deprecated. Compatibility keyword for hub_name, to be removed in v0.3

Returns

full live device state as returned by the API

Return type

dict

cozify.hub.getDefaultHub()

Deprecated, use default(). Return id of default Hub.

cozify.hub.getHubId(hub_name)

Deprecated, use hub_id(). Return id of hub by it’s name.

Parameters

  • hub_name (str) – Name of hub to query. The name is given when registering a hub to an account.

  • str – hub_id on success, raises an attributeerror on failure.

Returns

Hub id or raises

Return type

str