Blog post: Changes in setup entity platforms with group integration (#2157)

* Changes in setup entity platforms with group integration

* Changes to core PR

* Apply suggestions from code review

Co-authored-by: J. Nick Koston <nick@koston.org>

* Add comments on arguments

* Move to correct folder

* Update the date

---------

Co-authored-by: J. Nick Koston <nick@koston.org>

blog/2024-05-10-group-integration.md

@@ -0,0 +1,94 @@
+---
+author: Jan Bouwhuis
+authorURL: https://github.com/jbouwh
+authorImageURL: https://avatars.githubusercontent.com/u/7188918?s=96&v=4
+title: Changes in setup entity platforms with group integration
+---
+
+## Changes in setup entity platforms with group integration
+
+By default, the `group` integration allows entities to be grouped. If the default `ON`/`OFF` states for an entity default to `on` and `off`, then `grouping` is supported by default. The setup changes, though, for Entity platforms that can be grouped but have alternative states, e.g., `cover` (`open`/`closed`) or `person` (`home`/`not_home`), or platforms that are meant to be excluded, such as `sensor`. These entity platforms must implement `async_describe_on_off_states` in the `group.py` module.
+
+In `async_describe_on_off_states`, the `domain` needs to be the first argument passed to the `registry` methods `on_off_states` and `exclude_domain`. When registering alternative `ON`/`OFF` states with `registry.on_off_state`, in addition to the `ON` states, the default `ON` state needs to be passed.
+
+### Example registering alternative states
+
+New signature for `registry.on_off_states`:
+
+```python
+    @callback
+    def on_off_states(
+        self, domain: str, on_states: set[str], default_on_state:str, off_state: str
+    ) -> None:
+        """Register on and off states for the current domain."""
+    ...
+```
+
+Example `group.py` for the `vacuum` entity platform registering alternative `ON`/`OFF` states. Note the the first `ON` state now is considered to be the default `ON` state.
+
+```python
+"""Describe group states."""
+
+from typing import TYPE_CHECKING
+
+from homeassistant.const import STATE_OFF, STATE_ON
+from homeassistant.core import HomeAssistant, callback
+
+if TYPE_CHECKING:
+    from homeassistant.components.group import GroupIntegrationRegistry
+
+from .const import DOMAIN, STATE_CLEANING, STATE_ERROR, STATE_RETURNING
+
+
+@callback
+def async_describe_on_off_states(
+    hass: HomeAssistant, registry: "GroupIntegrationRegistry"
+) -> None:
+    """Describe group on off states."""
+    registry.on_off_states(
+        DOMAIN,  # domain
+        # set with all group ON states
+        {
+            STATE_ON,
+            STATE_CLEANING,
+            STATE_RETURNING,
+            STATE_ERROR,
+        },
+        STATE_ON, # Default group ON state 
+        STATE_OFF, # Group OFF state
+    )
+```
+
+### Example excluding an entity platform from group entities
+
+New signature for `registry.exclude_domain`:
+
+```python
+    @callback
+    def exclude_domain(self, domain: str) -> None:
+        """Exclude the current domain."""
+        ...
+```
+
+Example `group.py` for the `sensor` entity platform to exclude sensor entities from `group` entities.
+
+```python
+"""Describe group states."""
+
+from typing import TYPE_CHECKING
+
+from homeassistant.core import HomeAssistant, callback
+
+if TYPE_CHECKING:
+    from homeassistant.components.group import GroupIntegrationRegistry
+
+from .const import DOMAIN
+
+
+@callback
+def async_describe_on_off_states(
+    hass: HomeAssistant, registry: "GroupIntegrationRegistry"
+) -> None:
+    """Describe group on off states."""
+    registry.exclude_domain(DOMAIN)
+```