diff --git a/docs/entity_fan.md b/docs/entity_fan.md index 8eab84ad..7b1dc341 100644 --- a/docs/entity_fan.md +++ b/docs/entity_fan.md @@ -3,7 +3,7 @@ title: Fan Entity sidebar_label: Fan --- -A fan entity is a device that controls the different vectors of your fan such as speed, direction and oscillation. Derive enitity platforms from ['homeassistant.components.fan.FanDevice'](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/fan/__init__.py). +A fan entity is a device that controls the different vectors of your fan such as speed, direction and oscillation. Derive entity platforms from ['homeassistant.components.fan.FanDevice'](https://github.com/home-assistant/home-assistant/blob/dev/homeassistant/components/fan/__init__.py). ## Properties @@ -12,18 +12,17 @@ A fan entity is a device that controls the different vectors of your fan such as | Name | Type | Default | Description | ---- | ---- | ------- | ----------- | current_direction | str | None | Return the current direction of the fan | -|is_on| boolean | None |Return true if the entity is on | -| speed | str | None | Return the current speed | -| speed_list | list | None| Get the list of available speeds | -| state_attributes | dict | None | Return optional state attributes | -| supported_features | int | None | Flag supported features | +| is_on | boolean | None |Return true if the entity is on | +| speed | str | None | Return the current speed. One of the values in speed_list. | +| speed_list | list | None| Get the list of available speeds. The allowed values are "off", "low", "medium" and "high". Use the corresponding constants SPEED_OFF, SPEED_LOW, SPEED_MEDIUM, SPEED_HIGH. | +| supported_features | int | 0 | Flag supported features | ## Supported Features | Constant | Description | |----------|--------------------------------------| -| 'SUPPORT_DIRECTION' | The fan supports changing the direction of it. +| 'SUPPORT_DIRECTION' | The fan supports changing the direction. | 'SUPPORT_SET_SPEED' | The fan supports setting the speed. | 'SUPPORT_OSCILLATE' | The fan supports oscillation. @@ -42,7 +41,7 @@ class FanEntity(ToggleEntity): def set_direction(self, direction: str) -> None: """Set the direction of the fan.""" - async def async_set_direction(self, direction: str): + async def async_set_direction(self, direction: str) -> None: """Set the direction of the fan.""" ``` @@ -57,7 +56,7 @@ class FanEntity(ToggleEntity): def set_speed(self, speed: str) -> None: """Set the speed of the fan.""" - async def async_set_speed(self, speed: str): + async def async_set_speed(self, speed: str) -> None: """Set the speed of the fan.""" ``` @@ -67,13 +66,41 @@ class FanEntity(ToggleEntity): class FanEntity(ToggleEntity): # Implement one of these methods. - def turn_on(self, speed: str = None, **kwargs) -> None: + def turn_on(self, speed: Optional[str] = None, **kwargs: Any) -> None: """Turn on the fan.""" - async def async_turn_on(self, speed: str = None, **kwargs): + async def async_turn_on(self, speed: Optional[str] = None, **kwargs: Any) -> None: """Turn on the fan.""" ``` +### Turn off + +```python +class FanEntity(ToggleEntity): + # Implement one of these methods. + + def turn_off(self, **kwargs: Any) -> None: + """Turn the fan off.""" + + async def async_turn_off(self, **kwargs: Any) -> None: + """Turn the fan off.""" +``` + +### Toggle + +Optional. If not implemented will default to checking what method to call using the is_on property. + +```python +class FanEntity(ToggleEntity): + # Implement one of these methods. + + def toggle(self, **kwargs: Any) -> None: + """Toggle the fan.""" + + async def async_toggle(self, **kwargs: Any) -> None: + """Toggle the fan.""" +``` + ### Oscillate Only implement this method if the flag `SUPPORT_OSCILLATE` is set. @@ -85,7 +112,7 @@ class FanEntity(ToggleEntity): def oscillate(self, oscillating: bool) -> None: """Oscillate the fan.""" - def async_oscillate(self, oscillating: bool): + async def async_oscillate(self, oscillating: bool) -> None: """Oscillate the fan.""" ``` @@ -93,4 +120,3 @@ class FanEntity(ToggleEntity): -