Improvements to Hue documentation (#17290)

source/_integrations/hue.markdown

@@ -21,7 +21,7 @@ ha_platforms:
   - sensor
 ---
 
-The Philips Hue integration allows you to control and monitor the lights and motion sensors connected to your Hue bridge. The Hue integration is automatically discovered. If not, add it via the add integration menu.
+The Philips Hue integration allows you to control and monitor the lights and motion sensors connected to your Hue bridge.
 
 There is currently support for the following device types within Home Assistant:
 
@@ -35,53 +35,28 @@ There is currently support for the following device types within Home Assistant:
 
 {% include integrations/config_flow.md %}
 
-## Using Hue Groups in Home Assistant
+## Options
 
-The Hue API allows you to group lights. Home Assistant also supports grouping of entities natively, but sometimes it can be useful to use Hue groups to group light bulbs. By doing so, Home Assistant only needs to send one API call to change the state of all the bulbs in those groups instead of one call for every light in the group. This causes all the bulbs to change state simultaneously.
+Options for the Hue integration can be set going to **Configuration** -> **Integrations** -> **Hue** -> **Options**.
 
-These Hue groups can be a `Luminaire`, `Lightsource`, `LightGroup`, or `Room`. The `Luminaire` and `Lightsource` can't be created manually since the Hue bridge manages these automatically based on the discovered bulbs. The `Room` and `LightGroup` can be created manually through the API or the mobile app. A bulb can only exist in one `Room`, but can exist in more than one `LightGroup`. The `LightGroup` can be useful if you want to link certain bulbs together.
+{% configuration_basic %}
+Allow Hue groups:
+  description: "Enabling this option, will create entities for each Hue group, so you can control your Hue light groups from Home Assistant."
+Allow unreachable bulbs to report their state correctly:
+  description: "If a light is unavailable, it will show up as unavailable in Home Assistant as well. Enabling this option, will not mark the light unavailable, but instead show the last state known to the Hue bridge."
+{% endconfiguration_basic %}
 
-The 2nd generation Hue app only has the ability to create a `Room`. You need to use the first generation app or the API to create a `LightGroup`.
+## Using Hue Scenes
 
-Example:
-
-To create a `LightGroup` named `Ceiling lights` that contains the lights 1, 2, and 3, execute the following command:
-
-```bash
-curl -XPOST -d '{"name": "Ceiling lights", "lights": ["1", "2", "3"]}' http://<bridge>/api/<username>/groups
-```
-
-The `<username>` is the string that is used to register Home Assistant with the bridge. You can find it in the `core.config_entries` file in `/PATH-TO-YOUR-CONFIGURATION/.storage/`. `<bridge>` is the IP address or hostname of your Hue bridge.
-
-You can find the IDs of your lights by executing the following command:
-
-```bash
-curl http://<bridge>/api/<username>/lights
-```
-
-Home Assistant will automatically detect your new `LightGroup` and add it to the interface.
-
-<div class='note warning'>
-  To support Hue light groups, your bridge needs to have at least firmware 1.13 (released on June 3, 2016).
-</div>
-
-More information can be found on the [Philips Hue API documentation](https://www.developers.meethue.com/documentation/groups-api#22_create_group) website.
-
-## Using Hue Scenes in Home Assistant
-
-The Hue platform has its own concept of scenes for setting the colors of a group of lights simultaneously. A Hue bridge could potentially have dozens of scenes stored on it, and many scenes across different rooms might share the same name (the default scenes, for example). To avoid user interface overload, we don't expose scenes directly. Instead there is a `hue.hue_activate_scene` service which can be used in an automation or script.
-This will have all the bulbs transitioned at once, instead of one at a time like when using standard scenes in Home Assistant.
+The Hue platform has its own concept of scenes for setting the colors of a group of lights simultaneously. A Hue bridge could potentially have dozens of scenes stored on it, and many scenes across different rooms might share the same name (the default scenes, for example). To avoid user interface overload, we don't expose scenes directly. Instead there is a `hue.hue_activate_scene` service which can be used in an automation or script. This will have all the bulbs transitioned at once, instead of one at a time like when using standard scenes in Home Assistant.
 
 For instance:
 
 ```yaml
-script:
-  porch_on:
-    sequence:
-      - service: hue.hue_activate_scene
-        data:
-          group_name: "Porch"
-          scene_name: "Porch Orange"
+service: hue.hue_activate_scene
+data:
+  group_name: "Porch"
+  scene_name: "Porch Orange"
 ```
 
 | Service data attribute | Optional | Description                                                           |
@@ -96,11 +71,11 @@ _Note_: `group_name` is not a reference to a Home Assistant group name. It can o
 
 The easiest way to find Hue scene names is to only use the scenes from the 2nd generation Hue app, which are organized by room (group) and scene name. Use the room name and scene name that you see in the app. You can test that these work at Developer Tools > Services in 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 is sufficient to get values that you can test at Developer Tools > Services.
+Alternatively, a more advanced method can be used to 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 is sufficient to get values that you can test at Developer Tools > Services.
 
 ### Caveats
 
-The Hue API doesn't activate scenes directly; rather, they must be associated with a Hue group (typically rooms, especially if using the 2nd generation Hue app). But Hue scenes don't actually reference their group, so heuristic matching is used.
+The Hue API doesn't activate scenes directly; rather, they must be associated with a Hue group (typically rooms). But Hue scenes don't actually reference their group, so heuristic matching is used.
 
 Neither group names nor scene names are guaranteed unique in Hue. If you are observing unexpected behavior from calling Hue scenes in Home Assistant, make the names of your Hue scenes more specific in the Hue app.