Update and consolidate group documentation (#22137)

Co-authored-by: Erik Montnemery <erik@montnemery.com>
This commit is contained in:
Franck Nijhof 2022-03-24 09:25:00 +01:00 committed by GitHub
parent 3b3bbb220a
commit 74f75b4a20
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 200 additions and 393 deletions

View File

@ -1,66 +0,0 @@
---
title: "Binary Sensor Group"
description: "Instructions for how to setup binary_sensor groups within Home Assistant."
ha_category:
- Binary Sensor
ha_release: 2021.10
ha_iot_class: Local Push
ha_quality_scale: internal
ha_domain: group
---
The group binary_sensor platform lets you combine multiple binary_sensors into one entity. This integration presents itself as a single binary sensor in the UI. This allows the UI to use the text and icon of the type of sensor you are grouping. The sensor doesn't know what device class it should be, so this should be set to match the device class of the items in the group.
## Configuration
To enable this platform in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: group
name: Patio Doors
device_class: opening
entities:
- binary_sensor.door_left_contact
- binary_sensor.door_right_contact
```
{% configuration %}
entities:
description: A list of entities to be included in the group.
required: true
type: [string, list]
name:
description: The name of the group. Defaults to "Binary Sensor Group".
required: false
type: string
unique_id:
description: An ID that uniquely identifies this group. If two binary_sensors have the same unique ID, Home Assistant will raise an error.
required: false
type: string
all:
description: Set this to `true` if the group state should only turn *on* if **all** grouped entities are *on*.
required: false
type: boolean
default: false
device_class:
description: Sets the [device class](/integrations/binary_sensor/) of this binary sensor group, changing the device state and icon that is displayed in the frontend.
required: false
type: string
{% endconfiguration %}
## Group behavior
Group behavior differs depending on if the `all` option is `false` (the default) or `true`.
If `all` is `false`(the default):
- Group state is `unavailable` if all group members are `unavailable`
- Otherwise, group state is `unknown` if all group members are `unknown`
- Otherwise, group state is `on` if at least one group member is `on`
- Otherwise, group state is `off`
If `all` is `true`:
- Group state is `unavailable` if all group members are `unavailable`
- Otherwise, group state is `unknown` if at least one group member is `unknown` or `unavailable`
- Otherwise, group state is `off` if at least one group member is `off`
- Otherwise, group state is `on`

View File

@ -1,43 +0,0 @@
---
title: "Cover Group"
description: "Instructions how to setup grouped covers in Home Assistant."
ha_category:
- Cover
ha_release: 0.66
ha_iot_class: Local Push
ha_quality_scale: internal
ha_domain: group
---
The `group` platform can create a cover that combines several cover entities into one.
To enable `Cover Groups` in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
cover:
- platform: group
entities:
- cover.hall_window
- cover.living_room_window
```
{% configuration %}
entities:
description: List of all cover entities you want to control.
required: true
type: [string, list]
name:
description: Name to use in the frontend.
required: false
type: string
default: "Cover Group"
unique_id:
description: An ID that uniquely identifies this cover group. If two covers have the same unique ID, Home Assistant will raise an error.
required: false
type: string
{% endconfiguration %}
## Functionality
It works best if you group covers with the same supported features together (like support for `open`/`close`/`stop`/`position`/`tilt controls`), but is not limited to it. In case you have bundled covers with different features together, the controls will only affect those covers that support the actions.

View File

@ -1,44 +0,0 @@
---
title: "Fan Group"
description: "Instructions how to setup grouped fans in Home Assistant."
ha_category:
- Fan
ha_release: 2021.11
ha_iot_class: Local Push
ha_quality_scale: internal
ha_domain: group
---
The `group` platform can create a fan that combines several fan entities into one.
To enable `Fan Groups` in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
fan:
- platform: group
entities:
- fan.lanai_west
- fan.lanai_south
- fan.lanai_east
```
{% configuration %}
entities:
description: List of all fan entities you want to control.
required: true
type: [string, list]
name:
description: Name to use in the frontend.
required: false
type: string
default: "Fan Group"
unique_id:
description: An ID that uniquely identifies this fan group. If two fans have the same unique ID, Home Assistant will raise an error.
required: false
type: string
{% endconfiguration %}
## Functionality
It works best if you group fans with the same supported features together (like support for `percentage`/`direction`/`oscillation`), but is not limited to it. In case you have bundled fans with different features together, the controls will only affect those fans that support the actions.

View File

@ -2,6 +2,12 @@
title: Group
description: Instructions on how to setup groups within Home Assistant.
ha_category:
- Binary Sensor
- Cover
- Fan
- Light
- Media Player
- Notifications
- Organization
ha_release: pre 0.7
ha_iot_class: Calculated
@ -9,6 +15,7 @@ ha_quality_scale: internal
ha_codeowners:
- '@home-assistant/core'
ha_domain: group
ha_config_flow: true
ha_platforms:
- binary_sensor
- cover
@ -18,24 +25,184 @@ ha_platforms:
- notify
---
Groups allow the user to combine multiple entities into one.
The group integration lets you combine multiple entities into a single entity. Entities that are members of a group can be controlled and monitored as a whole.
Check **Developer Tools** -> **States** and browse the **Current entities:** listing for all available entities.
This can be useful for cases where you want to control, for example, the
multiple bulbs in a light fixture as a single light in Home Assistant.
Home Assistant can group multiple binary sensors, covers, fans, light, media players as a single entity, with the option of hiding the individual member entities.
{% include integrations/config_flow.md %}
## Group behavior
By default, when any group member entity is `on`, the group will also be `on`. A complete overview of how groups behave:
- The group state is `on` if at least one group member is `on`.
- Otherwise, the group state is `unavailable` if all group members are `unavailable`.
- Otherwise, the group state is `unknown` if all group members are `unknown`.
- Otherwise, the group state is `off`.
Some groups, like the binary sensors and lights, allow you set the "All entities" option. When enabled, this behavior is inverted, and all members of the group have to be `on` for the group to turn `on` as well. A complete overview of how groups behave when the "All entities" option is enabled:
- The group state is `off` if at least one group member is `off`.
- Otherwise, the group state is `unavailable` if all group members are `unavailable`.
- Otherwise, the group state is `unknown` if at least one group member is `unknown` or `unavailable`.
- Otherwise, the group state is `on`.
## YAML Configuration
Alternatlively, this integration can be configured and set up manually via YAML
instead. Here are example of how to configure groups when using the `configuration.yaml` file.
Example YAML configuration of a binary sensor group:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: group
name: "Patio Doors"
device_class: opening
entities:
- binary_sensor.door_left_contact
- binary_sensor.door_right_contact
```
Example YAML configuration of a cover group:
```yaml
# Example configuration.yaml entry
cover:
- platform: group
name: "Window Covers"
entities:
- cover.hall_window
- cover.living_room_window
```
Example YAML configuration of a fan group:
```yaml
# Example configuration.yaml entry
fan:
- platform: group
name: "Downstairs Fans"
entities:
- fan.lanai_west
- fan.lanai_south
- fan.lanai_east
```
Example YAML configuration of a light group:
```yaml
# Example configuration.yaml entry
light:
- platform: group
name: "Kitchen Lights"
entities:
- light.kitchen_ceiling_lights
- light.kitchen_under_cabinet_lights
- light.kitchen_spot_lights
- light.pendant_lights
```
Example YAML configuration of a media_player group:
```yaml
# Example configuration.yaml entry
media_player:
- platform: group
entities:
- media_player.kitchen_tv
- media_player.livivng_room_tv
```
{% configuration %}
entities:
description: A list of entities to be included in the group.
required: true
type: [string, list]
name:
description: The name of the group.
required: false
type: string
unique_id:
description: An ID that uniquely identifies this group. If two groups have the same unique ID, Home Assistant will raise an error. Giving an group a unique ID allow the group name, icon and area to be customized via the UI.
required: false
type: string
all:
description: Only available for `binary_sensor` and `light` groups. Set this to `true` if the group state should only turn *on* if **all** grouped entities are *on*.
required: false
type: boolean
default: false
{% endconfiguration %}
## Notify Groups
This group is a special case of groups currently only available via YAML configuration.
Notify groups are used to combine multiple notification services into a single service. This allows you to send notification to multiple devices with a single call.
```yaml
# Example configuration.yaml entry
notify:
- platform: group
name: "My notification group"
services:
- service: html5
data:
target: "macbook"
- service: html5_nexus
```
{% configuration %}
name:
description: Setting the parameter `name` sets the name of the group.
required: true
type: string
services:
description: A list of all the services to be included in the group.
required: true
type: list
keys:
service:
description: The service part of an entity ID, e.g., if you use `notify.html5` normally, just put `html5`. Note that you must put everything in lower case here. Although you might have capitals written in the actual notification services!
required: true
type: string
data:
description: A dictionary containing parameters to add to all notify payloads. This can be anything that is valid to use in a payload, such as `data`, `message`, `target` or `title`.
required: false
type: string
{% endconfiguration %}
## Old style groups
**We don't recommend using these old-style groups anymore.** They are still supported, but we recommend using the groups as described above.
Back in the day, Home Assistant used groups to visually groups entities in the Home Assistant UI; it was the only way to tell which entities would show up in a single card on your Dashboard. This is no longer the case, as we now have fantastic UI editors and Dashboarding.
However, the old-style groups are still there in the roots of Home Assistant.
On the one hand, they are more versatile (they can use more entity types right now); but on the other hand, they are also more limited and complicated to use.
The limited use is that these old-style groups are written to be universal, while the new style groups described above are designed to be a full replacement of their members (e.g., a light group, as described above, has all light features). Besides being only available via manual YAML configuration, they also have limited UI support in terms of customizing.
Example old-style groups YAML configuration:
```yaml
# Example configuration.yaml entry
group:
kitchen:
name: Kitchen
name: "Kitchen Group"
entities:
- switch.kitchen_pin_3
climate:
name: Climate
name: "Climate Group"
entities:
- sensor.bedroom_temp
- sensor.porch_temp
awesome_people:
name: Awesome People
name: "Awesome People"
entities:
- device_tracker.dad_smith
- device_tracker.mom_smith
@ -47,7 +214,7 @@ name:
required: false
type: string
entities:
description: Array or comma delimited string, list of entities to group.
description: A list of entities to group.
required: true
type: list
all:
@ -61,37 +228,26 @@ icon:
type: string
{% endconfiguration %}
## Group behavior
Old style groups can calculate group state with entities from the following domains:
By default when any member of a group is `on` then the group will also be `on`. Similarly with a device tracker, when any member of the group is `home` then the group is `home`. If you set the `all` option to `true` though, this behavior is inverted and all members of the group have to be `on` for the group to turn on as well.
- `alarm_control_panel`
- `binary_sensor`
- `climate`
- `cover`
- `device_tracker`
- `fan`
- `humidifier`
- `light`
- `lock`
- `media_player`
- `person`
- `plant`
- `remote`
- `switch`
- `vacuum`
- `water_heater`
## Group state update
The group's state is updated when any group member's state is updated. Calling `homeassistant.update_entity` with the target set to the group will not be forwarded to the group members, instead the `expand()` template function can be used to force all group members to update state.
## Group state calculation
The system can calculate group state with entities from the following domains:
* alarm_control_panel
* binary_sensor
* climate
* cover
* device_tracker
* fan
* humidifier
* light
* lock
* media_player
* person
* plant
* remote
* switch
* vacuum
* water_heater
When entities all have a single on and off state, the group state will
be calculated as follows:
When member entities all have a single `on` and `off` state, the group state will be calculated as follows:
| Domain | on | off |
|-------------------|----------|----------|
@ -101,11 +257,8 @@ be calculated as follows:
| person | home | not_home |
| media_player | ok | problem |
When a group contains entities from domains that have multiple `on` states or only use `on`
and `off`, the group state will be `on` or `off`.
When a group contains entities from domains that have multiple `on` states or only use `on` and `off`, the group state will be `on` or `off`.
It is possible to create a group that the system cannot calculate a group state.
Groups with entities from unsupported domains will always have an unknown state.
It is possible to create a group that the system cannot calculate a group state. Groups with entities from unsupported domains will always have an unknown state.
These groups can still be in templates with the `expand()` directive, called using the
`homeassistant.turn_on` and `homeassistant.turn_off` services, etc.
These groups can still be in templates with the `expand()` directive, called using the `homeassistant.turn_on` and `homeassistant.turn_off` services, etc.

View File

@ -1,86 +0,0 @@
---
title: "Light Group"
description: "Instructions for how to setup light groups within Home Assistant."
ha_category:
- Light
ha_release: 0.65
ha_iot_class: Local Push
ha_quality_scale: internal
ha_domain: group
---
The light group platform lets you combine multiple lights into one entity. All child lights of a light group can still be used as usual, but controlling the state of the grouped light will forward the command to each child light.
## Configuration
To enable this platform in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
light:
- platform: group
name: Kitchen Lights
entities:
- light.kitchen_ceiling_lights
- light.kitchen_under_cabinet_lights
- light.kitchen_spot_lights
- light.pendant_lights
```
{% configuration %}
entities:
description: A list of entities to be included in the light group.
required: true
type: [string, list]
name:
description: The name of the light group. Defaults to "Light Group".
required: false
type: string
unique_id:
description: An ID that uniquely identifies this light group. If two lights have the same unique ID, Home Assistant will raise an error.
required: false
type: string
all:
description: Set this to `true` if the group state should only turn *on* if **all** grouped entities are *on*.
required: false
type: boolean
default: false
{% endconfiguration %}
<p class='img'>
<img src='/images/integrations/light/group.png'>
Example of the light group "Kitchen Lights".
</p>
The supported features of all lights will be added together. For example, if you have one RGB light in a group of otherwise brightness-only lights, the light group will be shown with a color picker.
## Script Example
Here's an example of a script using the above light group.
```yaml
script:
turn_on_kitchen_lights:
alias: "Kitchen lights on"
sequence:
service: light.turn_on
target:
entity_id: light.kitchen_lights
data:
brightness: 100
```
## Group behavior
Group behavior differs depending on if the `all` option is `false` (the default) or `true`.
If `all` is `false`(the default):
- Group state is `unavailable` if all group members are `unavailable`
- Otherwise, group state is `unknown` if all group members are `unknown`
- Otherwise, group state is `on` if at least one group member is `on`
- Otherwise, group state is `off`
If `all` is `true`:
- Group state is `unavailable` if all group members are `unavailable`
- Otherwise, group state is `unknown` if at least one group member is `unknown` or `unavailable`
- Otherwise, group state is `off` if at least one group member is `off`
- Otherwise, group state is `on`

View File

@ -1,53 +0,0 @@
---
title: "Media Player Group"
description: "Instructions for how to setup Media player groups within Home Assistant."
ha_category:
- Media Player
ha_release: "2021.7"
ha_iot_class: Local Push
ha_quality_scale: internal
ha_domain: group
---
The group media player platform lets you combine multiple media players into one entity. All child media players of a media player group can still be used as usual, but controlling the state of the grouped media player will forward the command to each child media player.
To enable this platform in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
media_player:
- platform: group
entities:
- media_player.kitchen_tv
- media_player.livivng_room_tv
```
{% configuration %}
entities:
description: A list of entities to be included in the media player group.
required: true
type: [string, list]
name:
description: The name of the media player group. Defaults to "Media Group".
required: false
type: string
unique_id:
description: An ID that uniquely identifies this media player group. If two media players have the same unique ID, Home Assistant will raise an error.
required: false
type: string
{% endconfiguration %}
## Script Example
Here's an example of a script using the above media player group.
```yaml
script:
tts:
alias: Run TTS
sequence:
service: tts.google_translate_say
entity_id: media_player.media_group
data:
message: 'The cake is a lie.'
```

View File

@ -1,60 +0,0 @@
---
title: "Notify Group"
description: "Instructions on how to setup the notify group platform."
ha_category:
- Notifications
ha_release: 0.26
ha_quality_scale: internal
ha_domain: group
---
The `group` notification platform allows you to combine multiple `notify` platforms into a single service.
## Configuration
```yaml
# Example configuration.yaml entry
notify:
- name: NAME_OF_NOTIFIER_GROUP
platform: group
services:
- service: html5
data:
target: "macbook"
- service: html5_nexus
```
{% configuration %}
name:
description: Setting the parameter `name` sets the name of the group.
required: true
type: string
services:
description: A list of all the services to be included in the group.
required: true
type: list
keys:
service:
description: The service part of an entity ID, e.g., if you use `notify.html5` normally, just put `html5`. Note that you must put everything in lower case here. Although you might have capitals written in the actual notification services!
required: true
type: string
data:
description: A dictionary containing parameters to add to all notify payloads. This can be anything that is valid to use in a payload, such as `data`, `message`, `target` or `title`.
required: false
type: string
{% endconfiguration %}
## Example
An example on how to use it in an automation:
{% raw %}
```yaml
action:
service: notify.NAME_OF_NOTIFIER_GROUP
data:
message: "The sun is {% if is_state('sun.sun', 'above_horizon') %}up{% else %}down{% endif %}!"
```
{% endraw %}

View File

@ -142,6 +142,12 @@
/integrations/notify.mysensors /integrations/mysensors#notify
/integrations/sensor.mysensors /integrations/mysensors#sensor
/integrations/switch.mysensors /integrations/mysensors#switch
/integrations/binary_sensor.group /integrations/group
/integrations/cover.group /integrations/group
/integrations/fan.group /integrations/group
/integrations/light.group /integrations/group
/integrations/media_player.group /integrations/group
/integrations/notify.group /integrations/group#notify-groups
/components/air_pollutants.* /integrations/:splat
/components/air_quality.* /integrations/:splat