increase documentation on hue_activate_scene service. (#1475)

This describes the hue_activate_scene service on the light.hue page,
including the answers to questions I've gotten since this went into
HomeAssistant. Hopefully a good start that can be improved on by
folks.
This commit is contained in:
Sean Dague 2016-11-22 09:40:12 -05:00 committed by Fabian Affolter
parent 5ab682ed67
commit fe4a822513

View File

@ -34,3 +34,56 @@ Configuration variables:
- **allow_unreachable** (*Optional*): This will allow unreachable bulbs to report their state correctly. By default *name* from the device is used.
- **filename** (*Optional*): Make this unique if specifying multiple Hue hubs.
### {% linkable_title Using Hue Scenes in Home Assistant %} ###
The Hue platform has it's own concept of Scenes for setting the colors
of a group of lights at once. Hue Scenes are very cheap, get created
by all kinds of apps (as it is the only way to have 2 or more lights
change at the same time), and are rarely deleted. A typical Hue hub
might have hundreds of scenes stored in them, many that you've never
used, almost all very poorly named.
To avoid user interface overload we don't expose Scenes
directly. Instead there is a
[light.hue_activate_scene]/(/components/light/#service-lighthue_activate_scene)
service which can be used by `automation` or `script` components. For
instance:
```
script:
porch_on:
sequence:
- service: light.hue_activate_scene
data:
group_name: "Porch"
scene_name: "Porch Orange"
```
*** Finding Group and Scene Names ***
How do you find these names?
The easiest way to do this is only use the scenes from the 2nd
generation Hue app. That is organized by Room (Group) and Scene
Name. Use the values of Room name and Scene name that you see in the
app. You can test these work on the `dev-service` console of your Home
Assistant instance.
Alternatively, you can dump all rooms and scene names using this
[gist](https://gist.github.com/sdague/5479b632e0fce931951c0636c39a9578). This
does **not** tell you which groups and scenes work together but it's
sufficient to get values that you can test in the `dev-service` console.
*** Caveats ***
The Hue API doesn't activate Scenes directly, only on a Hue Group
(typically Rooms, especially if using the 2nd gen app). But Hue Scenes
don't actually reference their group. So heuristic matching is used.
Neither Group names or Scene names are guarunteed unique in Hue. If
you are getting non deterministic behavior, adjust your Hue scenes via
the App to be more identifying.
The Hue hub has limitted spaces for Scenes, and will delete Scenes if
new ones get created that would overflow that space. The API docs say
this is based on Least Recently Used.