Update Hue docs (#20372)

Co-authored-by: Paulus Schoutsen <paulus@home-assistant.io>

source/_integrations/hue.markdown

@@ -12,6 +12,7 @@ ha_quality_scale: platinum
 ha_codeowners:
   - '@balloob'
   - '@frenck'
+  - '@marcelveldt'
 ha_domain: hue
 ha_ssdp: true
 ha_homekit: true
@@ -19,66 +20,40 @@ ha_platforms:
   - binary_sensor
   - light
   - sensor
+  - scene
 ha_zeroconf: true
 ---
 
-The Philips Hue integration allows you to control and monitor the lights and motion sensors connected to your Hue bridge.
+The Philips Hue integration allows you to control and monitor the lights and sensors connected to your Hue bridge.
 
 There is currently support for the following device types within Home Assistant:
 
 - Lights
 - Motion sensors (including temperature and light level sensors)
-- Hue switches (as device triggers for automations and also exposed as battery sensors when they are battery-powered)
-  - Hue Dimmer Switch
-  - Hue Tap Switch
-  - Hue Smart Button
-  - Hue Wall Switch Module
-  - Friends of Hue Switch
+- Hue remotes/switches (as device triggers for automations and also exposed as battery sensors when they are battery-powered)
 
 {% include integrations/config_flow.md %}
 
-## Options
+## Lights for Hue zones and rooms
 
-Options for the Hue integration can be set going to **Configuration** -> **Integrations** -> **Hue** -> **Options**.
+The Hue concept is based on Rooms and zones. Although the underlying Hue lights are exposed directly to Home Assistant it might also be useful to interact with the `grouped lights` of the Hue ecosystem, for example to turn all lights in a Hue group on/off at the same time.
 
-{% 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 %}
+Home Assistant creates lights for each Hue zone/room automatically but disables them by default.
+If you'd like to use those `grouped lights`, you can enable them from Configuration --> Integrations --> Hue --> entities.
 
-## Using Hue Scenes
+## Scenes
 
-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.
+In the Hue concept you can create (dynamic) scenes for the lights within rooms and zones. These Hue scenes are automatically imported in Home Assistant and available as scene entities. Creating or editing Hue scenes in Home Assistant is not supported.
 
-For instance:
 
-```yaml
-service: hue.hue_activate_scene
-data:
-  group_name: "Porch"
-  scene_name: "Porch Orange"
-```
+## Hue remotes and switches
 
-| Service data attribute | Optional | Description                                                           |
-| ---------------------- | -------- | --------------------------------------------------------------------- |
-| `group_name`           | no       | The group/room name of the lights. Find this in the official Hue app. |
-| `scene_name`           | no       | The name of the scene. Find this in the official Hue app.             |
-| `transition`           | yes      | The time in 100s of milliseconds to transition to the scene. For example, a value of 4 means 400 milliseconds.          |
+Hue remotes such as the Dimmer Switch are stateless devices, meaning that they do not have a on/off state like regular entities in Home Assistant. Instead, such devices emit the event `hue_event` when a button is pressed. You can test what events come in using the event {% my developer_events title="developer tools in Home Assistant" %} and subscribe to the `hue_event`. Once you know what the event data looks like, you can use this to create automations.
 
-_Note_: `group_name` is not a reference to a Home Assistant group name. It can only be the name of a group/room in the Hue app.
+## Support for legacy (V1) Hue bridges
 
-### Finding Group and Scene Names
+Philips/Signify released a new version of their Hue bridge (square shape) and their legacy/V1 bridge (round shape) is now end of life and no longer supported by them. Home Assistant will continue to support the V1 Hue bridge as long as it is technically possible, although with a few limitations:
 
-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, 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). 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.
-
-The Hue hub has limited space for scenes and will delete scenes if new ones get created that would overflow that space. The API documentation says this is based on the scenes that are "least recently used."
+- Scene entities are not automatically created for V1 bridges. To call a Hue scene on a V1 bridge from Home Assistant we provide a service call to call a Hue scene by name.
+- State updates for devices/entities on a V1 bridges are not received instantly but polled on interval.
+- Light entities for Hue rooms are not automatically created for V1 bridges, you can opt-in for creating entities for rooms within the Integration's options.