From 147a5adb0c8cd0ce5bad50772d3ea224aa40e513 Mon Sep 17 00:00:00 2001
From: Erik Montnemery <erik@montnemery.com>
Date: Tue, 22 Mar 2022 08:45:42 +0100
Subject: [PATCH] Update binary sensor group documentation (#22110)

---
 .../binary_sensor.group.markdown              | 20 ++++++++++++++++---
 1 file changed, 17 insertions(+), 3 deletions(-)

diff --git a/source/_integrations/binary_sensor.group.markdown b/source/_integrations/binary_sensor.group.markdown
index dbb98c88394..eeaeef86a91 100644
--- a/source/_integrations/binary_sensor.group.markdown
+++ b/source/_integrations/binary_sensor.group.markdown
@@ -11,13 +11,12 @@ 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.
 
-## Group behavior
-
-By default when any member of a group is `on` then the group will also be `on`. 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.
+## 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
@@ -50,3 +49,18 @@ device_class:
   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`(the default):
+- 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`