High-level Hub functions

Module for handling highlevel Cozify Hub operations.

cozify.hub.capability

Enum of known device capabilities. Alphabetically sorted, numeric value not guaranteed to stay constant between versions if new capabilities are added.

Type:capability
cozify.hub.autoremote(hub_id=None, new_state=None, commit=True)[source]

Get autoremote status of hub 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. Defaults to hub.default()
  • 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.
  • commit (bool) – True to commit new state after set. Defaults to True.
Returns:

True for a hub with autoremote enabled.
Return type:

bool
class cozify.hub.capability

An enumeration.

cozify.hub.default()[source]

Return id of default Hub.

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

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

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_exists(device_id, devs=None, state=None, **kwargs)[source]

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_off(device_id, **kwargs)[source]

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.device_on(device_id, **kwargs)[source]

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_reachable(device_id, devs=None, state=None, **kwargs)[source]

Check if device exists and is reachable.

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_state_replace(device_id, state, **kwargs)[source]

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_toggle(device_id, **kwargs)[source]

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.devices(*, capabilities=None, and_filter=False, devs=None, **kwargs)[source]

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.
  • devs (dict) – Optional devices dictionary to use. If not defined, will be retrieved live.
  • **hub_name (str) – optional name of hub to query.
  • **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 devices dictionary as returned by the API
Return type:

dict
cozify.hub.exists(hub_id=None)[source]

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.host(hub_id=None)[source]

Get hostname of hub

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.hub_id(hub_name)[source]

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.light_brightness(device_id, brightness, transition=0, **kwargs)[source]

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.light_color(device_id, hue, saturation=1.0, transition=0, **kwargs)[source]

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_temperature(device_id, temperature=2700, transition=0, **kwargs)[source]

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.name(hub_id=None)[source]

Get hub name

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.ping(autorefresh=True, **kwargs)[source]

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.remote(hub_id=None, new_state=None, commit=True)[source]

Get remote status of hub 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. Defaults to hub.default()
  • new_state (bool) – New remoteness state to set for hub. True means remote. Defaults to None when only the current value will be returned.
  • commit (bool) – True to commit new state after set. Defaults to True.
Returns:

True for a hub considered remote.
Return type:

bool
cozify.hub.token(hub_id=None, new_token=None, commit=True)[source]

Get hub_token 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.
  • commit (bool) – True to commit new state after set. Defaults to True.
Returns:

Hub authentication token.
Return type:

str
cozify.hub.tz(**kwargs)[source]

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