diff --git a/blog/2024-07-19-fan-fanentityfeatures-turn-on_off.md b/blog/2024-07-19-fan-fanentityfeatures-turn-on_off.md new file mode 100644 index 00000000..157ca25f --- /dev/null +++ b/blog/2024-07-19-fan-fanentityfeatures-turn-on_off.md @@ -0,0 +1,17 @@ +--- +author: G Johansson +authorURL: https://github.com/gjohansson-ST +title: "New entity feature flags in FanEntity" +--- + +As of Home Assistant Core 2024.8, we have added two new flags to `FanEntityFeature`: `TURN_ON`, `TURN_OFF`. + +Integrations implementing the `turn_on` service call need to set the `TURN_ON` feature flag. +Integrations implementing the `turn_off` service call need to set the `TURN_OFF` feature flag. + +There will be a 6-month deprecation period (2025.2) during which `FanEntity` will set these on behalf of the integrations implementing the respective methods. From 2025.2, integrations will be unable to use the respective methods if entity features have not been set accordingly. + +Implementing the methods without setting the respective feature flag, will create a warning log entry guiding the user to create an issue for the integration. + +Integrations should set the attribute `_enable_turn_on_off_backwards_compatibility` in your `FanEntity` subclass instance to `False` once it has been migrated into using or not using the new feature flags. +This will stop the automatic setting of the new feature flags during the deprecation period, and should be removed once deprecation has ended. diff --git a/docs/core/entity/fan.md b/docs/core/entity/fan.md index d5cbaff5..d7d30215 100644 --- a/docs/core/entity/fan.md +++ b/docs/core/entity/fan.md @@ -40,12 +40,14 @@ and are combined using the bitwise or (`|`) operator. | `OSCILLATE` | The fan supports oscillation. | | `PRESET_MODE` | The fan supports preset modes. | | `SET_SPEED` | The fan supports setting the speed percentage and optional preset modes. | +| `TURN_OFF` | The fan supports turning off. | +| `TURN_ON` | The fan supports turning on. | ## Methods ### Set direction -Only implement this method if the flag `SUPPORT_DIRECTION` is set. +Only implement this method if the flag `FanEntityFeature.DIRECTION` is set. ```python class FanEntity(ToggleEntity): @@ -60,7 +62,7 @@ class FanEntity(ToggleEntity): ### Set preset mode -Only implement this method if the flag `SUPPORT_PRESET_MODE` is set. +Only implement this method if the flag `FanEntityFeature.PRESET_MODE` is set. ```python class FanEntity(ToggleEntity): @@ -75,7 +77,7 @@ class FanEntity(ToggleEntity): ### Set speed percentage -Only implement this method if the flag `SUPPORT_SET_SPEED` is set. +Only implement this method if the flag `FanEntityFeature.SET_SPEED` is set. ```python class FanEntity(ToggleEntity): @@ -144,6 +146,8 @@ value_in_range = math.ceil(percentage_to_ranged_value(SPEED_RANGE, 50)) ### Turn on +Only implement this method if the flag `FanEntityFeature.TURN_ON` is set. + ```python class FanEntity(ToggleEntity): # Implement one of these methods. @@ -163,6 +167,8 @@ For new intergrations, `speed` should not be implemented and only `percentage` a ### Turn off +Only implement this method if the flag `FanEntityFeature.TURN_OFF` is set. + ```python class FanEntity(ToggleEntity): # Implement one of these methods. @@ -177,6 +183,7 @@ class FanEntity(ToggleEntity): ### Toggle Optional. If not implemented will default to checking what method to call using the is_on property. +Only implement this method if the flags `FanEntityFeature.TURN_ON` and `FanEntityFeature.TURN_OFF` are set. ```python class FanEntity(ToggleEntity): @@ -191,7 +198,7 @@ class FanEntity(ToggleEntity): ### Oscillate -Only implement this method if the flag `SUPPORT_OSCILLATE` is set. +Only implement this method if the flag `FanEntityFeature.OSCILLATE` is set. ```python class FanEntity(ToggleEntity):