jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-13 04:16:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add new FanEntityFeature flags TURN_ON/OFF (#2243)

Browse Source 
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Franck Nijhof <frenck@frenck.nl>
This commit is contained in:
G Johansson 2024-07-19 11:40:01 +02:00 committed by GitHub
parent 63c1d3eb96
commit af0b8fa631
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
2 changed files with 28 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
blog/2024-07-19-fan-fanentityfeatures-turn-on_off.md Normal file
View File

@ -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.

15
docs/core/entity/fan.md
View File

@ -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):