light.hue

light.hue#

Description#

Philips Hue lights plugin.

Configuration#

light.hue:
  # [Required]
  # Bridge address or hostname
  bridge:   # type=str

  # [Optional]
  # Default lights to be controlled (default: all)
  # lights:   # type=Optional[Iterable[str]]

  # [Optional]
  # Default groups to be controlled (default: all)
  # groups:   # type=Optional[Iterable[str]]

  # [Optional]
  # How often the plugin should check the bridge for light
  # updates (default: 20 seconds).
  # poll_interval: 20.0  # type=float

  # [Optional]
  # Path to the phue configuration file containing the
  # access token to authenticate to the Hue bridge and the bridge
  # configuration (default: ``<WORKDIR>/light.hue/config.json``).
  # config_file:   # type=Optional[str]

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Dependencies#

pip

pip install phue

Triggered events#

Actions#

Module reference#

class platypush.plugins.light.hue.LightHuePlugin(*_, **__)[source]#

Bases: RunnablePlugin, LightEntityManager

Philips Hue lights plugin.

class Animation(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Inner class to model light animations.

__init__(bridge: str, lights: Iterable[str] | None = None, groups: Iterable[str] | None = None, poll_interval: float = 20.0, config_file: str | None = None, **kwargs)[source]#
Parameters:

  • bridge – Bridge address or hostname

  • lights – Default lights to be controlled (default: all)

  • groups – Default groups to be controlled (default: all)

  • poll_interval – How often the plugin should check the bridge for light updates (default: 20 seconds).

  • config_file – Path to the phue configuration file containing the access token to authenticate to the Hue bridge and the bridge configuration (default: <WORKDIR>/light.hue/config.json).

animate(animation, duration=None, hue_range=None, sat_range=None, bri_range=None, lights=None, groups=None, hue_step=1000, sat_step=2, bri_step=1, transition_seconds=1.0)[source]#

Run a lights animation.

Parameters:

  • animation (str) – Animation name. Supported types: color_transition and blink

  • duration (float) – Animation duration in seconds (default: None, i.e. continue until stop)

  • hue_range (list[int]) – If you selected a color_transition, this will specify the hue range of your color color_transition. Default: [0, 65535]

  • sat_range (list[int]) – If you selected a color color_transition, this will specify the saturation range of your color color_transition. Default: [0, 255]

  • bri_range (list[int]) – If you selected a color color_transition, this will specify the brightness range of your color color_transition. Default: [254, 255]

  • lights – Lights to control (names, IDs or light objects). Default: plugin default lights

  • groups – Groups to control (names, IDs or group objects). Default: plugin default groups

  • hue_step (int) – If you selected a color color_transition, this will specify by how much the color hue will change between iterations. Default: 1000

  • sat_step (int) – If you selected a color color_transition, this will specify by how much the saturation will change between iterations. Default: 2

  • bri_step (int) – If you selected a color color_transition, this will specify by how much the brightness will change between iterations. Default: 1

  • transition_seconds (float) – Time between two transitions or blinks in seconds. Default: 1.0

bri(value, lights=None, groups=None, **kwargs)[source]#

Set lights/groups brightness.

Parameters:

  • lights – Lights to control (names or light objects). Default: plugin default lights

  • groups – Groups to control (names or group objects). Default: plugin default groups

  • value – Brightness value (range: 0-255)

connect()[source]#

Connect to the configured Hue bridge. If the device hasn’t been paired yet, uncomment the .connect() and .get_api() lines and retry after clicking the pairing button on your bridge.

ct(value, lights=None, groups=None, **kwargs)[source]#

Set lights/groups color temperature.

Parameters:

  • value (int) – Temperature value (range: 154-500)

  • lights – List of lights.

  • groups – List of groups.

delta_bri(delta, lights=None, groups=None, **kwargs)[source]#

Change lights/groups brightness by a delta [-100, 100] compared to the current state.

Parameters:

  • lights – Lights to control (names or light objects). Default: plugin default lights

  • groups – Groups to control (names or group objects). Default: plugin default groups

  • delta – Brightness delta value (range: -100, 100)

delta_hue(delta, lights=None, groups=None, **kwargs)[source]#

Change lights/groups hue by a delta [-100, 100] compared to the current state.

Parameters:

  • lights – Lights to control (names or light objects). Default: plugin default lights

  • groups – Groups to control (names or group objects). Default: plugin default groups

  • delta – Hue delta value (range: -100, 100)

delta_sat(delta, lights=None, groups=None, **kwargs)[source]#

Change lights/groups saturation by a delta [-100, 100] compared to the current state.

Parameters:

  • lights – Lights to control (names or light objects). Default: plugin default lights

  • groups – Groups to control (names or group objects). Default: plugin default groups

  • delta – Saturation delta value (range: -100, 100)

get_animations()[source]#

Get the list of running light animations.

Returns:

dict.

Structure:

{
    "groups": {
        "id_1": {
            "type": "color_transition",
            "hue_range": [0,65535],
            "sat_range": [0,255],
            "bri_range": [0,255],
            "hue_step": 10,
            "sat_step": 10,
            "bri_step": 2,
            "transition_seconds": 2

        }

    },

    "lights": {
        "id_1": {}

    }

}
get_groups()[source]#

Get the list of configured light groups.

Returns:

List of configured light groups as id->dict.

Example:

{
    "1": {
        "name": "Living Room",
        "lights": [
            "16",
            "13",
            "12",
            "11",
            "10",
            "9",
            "1",
            "3"
        ],

        "type": "Room",
        "state": {
            "all_on": true,
            "any_on": true
        },

        "class": "Living room",
        "action": {
            "on": true,
            "bri": 241,
            "hue": 37947,
            "sat": 221,
            "effect": "none",
            "xy": [
                0.2844,
                0.2609
            ],

            "ct": 153,
            "alert": "none",
            "colormode": "hs"
        }
    }
}
get_lights()[source]#

Get the configured lights.

Returns:

List of available lights as id->dict.

Example:

{
    "1": {
        "state": {
            "on": true,
            "bri": 254,
            "hue": 1532,
            "sat": 215,
            "effect": "none",
            "xy": [
                0.6163,
                0.3403
            ],

            "ct": 153,
            "alert": "none",
            "colormode": "hs",
            "reachable": true
        },

        "type": "Extended color light",
        "name": "Lightbulb 1",
        "modelid": "LCT001",
        "manufacturername": "Philips",
        "uniqueid": "00:11:22:33:44:55:66:77-88",
        "swversion": "5.105.0.21169"
    }
}
get_scenes()[source]#

Get the available scenes on the devices.

Returns:

The scenes configured on the bridge.

Example output:

{
    "scene-id-1": {
        "name": "Scene 1",
        "lights": [
            "1",
            "3"
        ],

        "owner": "owner-id",
        "recycle": true,
        "locked": false,
        "appdata": {},
        "picture": "",
        "lastupdated": "2018-06-01T00:00:00",
        "version": 1
    }
}
hue(value, lights=None, groups=None, **kwargs)[source]#

Set lights/groups color hue.

Parameters:

  • lights – Lights to control (names or light objects). Default: plugin default lights

  • groups – Groups to control (names or group objects). Default: plugin default groups

  • value – Hue value (range: 0-65535)

is_animation_running()[source]#
Returns:

True if there is an animation running, false otherwise.

main()[source]#

Implementation of the main loop of the plugin.

off(lights=None, groups=None, **kwargs)[source]#

Turn lights/groups off.

Parameters:

  • lights – Lights to turn off (names or light objects). Default: plugin default lights

  • groups – Groups to turn off (names or group objects). Default: plugin default groups

on(lights=None, groups=None, **kwargs)[source]#

Turn lights/groups on.

Parameters:

  • lights – Lights to turn on (names or light objects). Default: plugin default lights

  • groups – Groups to turn on (names or group objects). Default: plugin default groups

publish_entities(entities: Collection[Any] | None, callback: Callable[[Entity], Any] | None = None, **kwargs) → Collection[Entity]#

Publishes a list of entities. The downstream consumers include:

It also accepts an optional callback that will be called when each of the entities in the set is flushed to the database.

You usually don’t need to override this class (but you may want to extend transform_entities() instead if your extension doesn’t natively handle Entity objects).

sat(value, lights=None, groups=None, **kwargs)[source]#

Set lights/groups saturation.

Parameters:

  • lights – Lights to control (names or light objects). Default: plugin default lights

  • groups – Groups to control (names or group objects). Default: plugin default groups

  • value – Saturation value (range: 0-255)

scene(name, lights=None, groups=None, **kwargs)[source]#

Set a scene by name.

Parameters:

  • lights – Lights to control (names or light objects). Default: plugin default lights

  • groups – Groups to control (names or group objects). Default: plugin default groups

  • name – Name of the scene

set(entity: str, value: Any, **kwargs)#

Set the value of an entity.

Parameters:

  • entity – The entity to set the value for. It’s usually the ID of the entity provided by the plugin.

  • value – The value to set the entity to.

set_group(group, **kwargs)[source]#

Set a group (or groups) property.

Parameters:

  • group – Group or groups to set. Can be a string representing the group name, a group object, a list of strings, or a list of group objects.

  • kwargs – key-value list of parameters to set.

Example call:

{
    "type": "request",
    "action": "light.hue.set_group",
    "args": {
        "light": "Living Room",
        "sat": 255
    }
}
set_lights(lights, *_, **kwargs)[source]#

Set a set of properties on a set of lights.

Parameters:

  • light – List of lights to set. Each item can represent a light name or ID.

  • kwargs – key-value list of the parameters to set.

Example call:

{
    "type": "request",
    "action": "light.hue.set_lights",
    "args": {
        "lights": ["Bulb 1", "Bulb 2"],
        "sat": 255
    }
}
start()#

Start the plugin.

status(*_, **__) → Iterable[Light][source]#

All derived classes should implement this method.

At the very least, this method should refresh the current state of the integration’s entities and call publish_entities().

It should also return the current state of the entities as a list of serialized entities, if possible.

stop()#

Stop the plugin.

stop_animation()[source]#

Stop a running animation.

toggle(lights=None, groups=None, **kwargs)[source]#

Toggle lights/groups on/off.

Parameters:

  • lights – Lights to turn off (names or light objects). Default: plugin default lights

  • groups – Groups to turn off (names or group objects). Default: plugin default groups

transform_entities(entities: Iterable[dict | Entity] | Mapping[Any, dict]) → Collection[Entity][source]#

This method takes a list of entities in any (plugin-specific) format and converts them into a standardized collection of Entity objects. Since this method is called by publish_entities() before entity updates are published, you may usually want to extend it to pre-process the entities managed by your extension into the standard format before they are stored and published to all the consumers.

wait_stop(timeout=None)#

Wait until a stop event is received.

xy(value, lights=None, groups=None, **kwargs)[source]#

Set lights/groups XY colors.

Parameters:

  • value (list[float] containing the two values) – xY value

  • lights – List of lights.

  • groups – List of groups.