From aff6de761d9d07408b5821e5a59ea7f34e41a3b4 Mon Sep 17 00:00:00 2001 From: G Johansson Date: Sun, 8 Dec 2024 18:08:58 +0100 Subject: [PATCH] Add new vacuum state property and enum (#2360) * Add new vacuum state property and enum * Fix review comments * New date --- blog/2024-12-08-new-vacuum-state-property.md | 33 ++++++++++++++++++++ docs/core/entity/vacuum.md | 18 ++++++----- 2 files changed, 43 insertions(+), 8 deletions(-) create mode 100644 blog/2024-12-08-new-vacuum-state-property.md diff --git a/blog/2024-12-08-new-vacuum-state-property.md b/blog/2024-12-08-new-vacuum-state-property.md new file mode 100644 index 00000000..c74ecdfb --- /dev/null +++ b/blog/2024-12-08-new-vacuum-state-property.md @@ -0,0 +1,33 @@ +--- +author: G Johansson +authorURL: https://github.com/gjohansson-ST +authorImageURL: https://avatars.githubusercontent.com/u/62932417?v=4 +authorTwitter: GJohansson +title: "New vacuum state property" +--- + +As of Home Assistant Core 2025.1, the constants used to return state in `StateVacuumEntity` are deprecated and replaced by the `VacuumActivity` enum. + +Also with this change, integrations should set the `activity` property instead of directly setting the `state` property. + +There is a one-year deprecation period, and the constants will stop working from 2026.1 to ensure all custom integration authors have time to adjust. + +### Example + +```python + +from homeassistant.components.vacuum import VacuumActivity + +class MyVacuumCleaner(StateVacuumEntity): + """My vacuum cleaner.""" + + @property + def activity(self) -> VacuumActivity | None: + """Return the state of the vacuum.""" + if self.device.is_cleaning(): + return VacuumActivity.CLEANING + return VacuumActivity.DOCKED + +``` + +More details can be found in the [vacuum documentation](/docs/core/entity/vacuum#states). diff --git a/docs/core/entity/vacuum.md b/docs/core/entity/vacuum.md index 9129b22b..2aac63ca 100644 --- a/docs/core/entity/vacuum.md +++ b/docs/core/entity/vacuum.md @@ -22,18 +22,20 @@ Properties should always only return information from memory and not do I/O (lik | fan_speed | string | `none` | The current fan speed. | fan_speed_list | list | `NotImplementedError()`| List of available fan speeds. | name | string | **Required** | Name of the entity. -| state | string | **Required** | One of the states listed in the states section. +| activity | VacuumActivity | **Required** | Return one of the states listed in the states section. ## States -| State | Description +Setting the state should return an enum from VacuumActivity in the `activity` property. + +| Value | Description | ----- | ----------- -| `STATE_CLEANING` | The vacuum is currently cleaning. -| `STATE_DOCKED` | The vacuum is currently docked, it is assumed that docked can also mean charging. -| `STATE_IDLE` | The vacuum is not paused, not docked and does not have any errors. -| `STATE_PAUSED` | The vacuum was cleaning but was paused without returning to the dock. -| `STATE_RETURNING` | The vacuum is done cleaning and is currently returning to the dock, but not yet docked. -| `STATE_ERROR` | The vacuum encountered an error while cleaning. +| `CLEANING` | The vacuum is currently cleaning. +| `DOCKED` | The vacuum is currently docked, it is assumed that docked can also mean charging. +| `IDLE` | The vacuum is not paused, not docked and does not have any errors. +| `PAUSED` | The vacuum was cleaning but was paused without returning to the dock. +| `RETURNING` | The vacuum is done cleaning and is currently returning to the dock, but not yet docked. +| `ERROR` | The vacuum encountered an error while cleaning. ## Supported features