High-level Hub functions

Module for handling highlevel Cozify Hub operations.

cozify.hub.capability

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

cozify.hub.autoremote(hub_id, new_state=None)[source]

Get autoremote status 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: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_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_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, **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.
  • **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()[source]

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

cozify.hub.getDevices(**kwargs)[source]

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

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

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.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 an AttributeError 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 an AttributeError is raised.
  • saturation (float) – Saturation in the range of [0, 1]. If outside the range an AttributeError 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)[source]

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.ping(**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:
  • **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, new_state=None)[source]

Get remote status 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:True for a hub considered remote.
Return type:bool
cozify.hub.token(hub_id, new_token=None)[source]

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.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()

Args: **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