From c09fd7c78130126f6232dbaf696693a2b81bcdf6 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sat, 13 Feb 2021 16:06:58 -1000 Subject: [PATCH 1/3] Document percentage_step and the utility --- docs/core/entity/fan.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/docs/core/entity/fan.md b/docs/core/entity/fan.md index e5cd50b0..f974a144 100644 --- a/docs/core/entity/fan.md +++ b/docs/core/entity/fan.md @@ -17,10 +17,48 @@ Properties should always only return information from memory and not do I/O (lik | is_on | boolean | None |Return true if the entity is on | | oscillating | boolean | None | Return true if the fan is oscillating | | percentage | int | None | Return the current speed percentage. Must be a value between 0 (off) and 100 | +| percentage_step | float | 1 | The supported step size a speed percentage can be increased/decreased | | supported_features | int | 0 | Flag supported features | | preset_mode | str | None | Return the current preset_mode. One of the values in preset_modes. | | preset_modes | list | None | Get the list of available preset_modes. This is an arbitrary list of str and should not contain any speeds. | + +:::tip Converting speeds + +Home Assistant includes a utility to calculate step sizes. + +If the device has a list of named speeds: + +```python +from homeassistant.util.percentage import ordered_list_percentage_step_size + +ORDERED_NAMED_FAN_SPEEDS = ["one", "two", "three", "four", "five", "six"] # off is not included + +... + + @property + def percentage_step(self) -> Optional[float]: + """Return the step size for percentage.""" + return ordered_list_percentage_step_size(ORDERED_NAMED_FAN_SPEEDS) +``` + +If the device has a numeric range of speeds: + +```python +from homeassistant.util.percentage import range_percentage_step_size + +SPEED_RANGE = (1, 7) # off is not included + +... + + @property + def percentage_step(self) -> Optional[float]: + """Return the step size for percentage.""" + return range_percentage_step_size(SPEED_RANGE) +``` + +::: + ## Deprecated Properties The fan entity model has changed to use percentages in the range from 0 (off) to 100 instead From f49da21decb9342c41b0914f54e7bda12feda2ad Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sat, 13 Feb 2021 21:56:51 -1000 Subject: [PATCH 2/3] Update fan.md --- docs/core/entity/fan.md | 63 ++++++++++++++++------------------------- 1 file changed, 25 insertions(+), 38 deletions(-) diff --git a/docs/core/entity/fan.md b/docs/core/entity/fan.md index f974a144..dc408122 100644 --- a/docs/core/entity/fan.md +++ b/docs/core/entity/fan.md @@ -17,48 +17,11 @@ Properties should always only return information from memory and not do I/O (lik | is_on | boolean | None |Return true if the entity is on | | oscillating | boolean | None | Return true if the fan is oscillating | | percentage | int | None | Return the current speed percentage. Must be a value between 0 (off) and 100 | -| percentage_step | float | 1 | The supported step size a speed percentage can be increased/decreased | +| speed_count | int | 100 | The number of speeds the fan supports | | supported_features | int | 0 | Flag supported features | | preset_mode | str | None | Return the current preset_mode. One of the values in preset_modes. | | preset_modes | list | None | Get the list of available preset_modes. This is an arbitrary list of str and should not contain any speeds. | - -:::tip Converting speeds - -Home Assistant includes a utility to calculate step sizes. - -If the device has a list of named speeds: - -```python -from homeassistant.util.percentage import ordered_list_percentage_step_size - -ORDERED_NAMED_FAN_SPEEDS = ["one", "two", "three", "four", "five", "six"] # off is not included - -... - - @property - def percentage_step(self) -> Optional[float]: - """Return the step size for percentage.""" - return ordered_list_percentage_step_size(ORDERED_NAMED_FAN_SPEEDS) -``` - -If the device has a numeric range of speeds: - -```python -from homeassistant.util.percentage import range_percentage_step_size - -SPEED_RANGE = (1, 7) # off is not included - -... - - @property - def percentage_step(self) -> Optional[float]: - """Return the step size for percentage.""" - return range_percentage_step_size(SPEED_RANGE) -``` - -::: - ## Deprecated Properties The fan entity model has changed to use percentages in the range from 0 (off) to 100 instead @@ -141,6 +104,18 @@ ORDERED_NAMED_FAN_SPEEDS = ["one", "two", "three", "four", "five", "six"] # off percentage = ordered_list_item_to_percentage(ORDERED_NAMED_FAN_SPEEDS, "three") named_speed = percentage_to_ordered_list_item(ORDERED_NAMED_FAN_SPEEDS, 23) + +... + + @property + def percentage(self) -> Optional[int]: + """Return the current speed percentage.""" + return ordered_list_item_to_percentage(ORDERED_NAMED_FAN_SPEEDS, current_speed) + + @property + def speed_count(self) -> Optional[int]: + """Return the number of speeds the fan supports.""" + return len(ORDERED_NAMED_FAN_SPEEDS) ``` If the device has a numeric range of speeds: @@ -153,6 +128,18 @@ SPEED_RANGE = (1, 255) # off is not included percentage = ranged_value_to_percentage(SPEED_RANGE, 127) value_in_range = math.ceil(percentage_to_ranged_value(SPEED_RANGE, 50)) + +... + + @property + def percentage(self) -> Optional[int]: + """Return the current speed percentage.""" + return ranged_value_to_percentage(SPEED_RANGE, current_speed) + + @property + def speed_count(self) -> Optional[int]: + """Return the number of speeds the fan supports.""" + return SPEED_RANGE[1] - SPEED_RANGE[0] + 1 ``` ::: From a64d3fe28d664786a968ab5d3140307b82d0d77b Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Sun, 14 Feb 2021 11:15:42 -1000 Subject: [PATCH 3/3] Make this a by more DRY by adding int_states_in_range util --- docs/core/entity/fan.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/entity/fan.md b/docs/core/entity/fan.md index dc408122..7fdadaa2 100644 --- a/docs/core/entity/fan.md +++ b/docs/core/entity/fan.md @@ -121,7 +121,7 @@ named_speed = percentage_to_ordered_list_item(ORDERED_NAMED_FAN_SPEEDS, 23) If the device has a numeric range of speeds: ```python -from homeassistant.util.percentage import ranged_value_to_percentage, percentage_to_ranged_value +from homeassistant.util.percentage import int_states_in_range, ranged_value_to_percentage, percentage_to_ranged_value SPEED_RANGE = (1, 255) # off is not included @@ -139,7 +139,7 @@ value_in_range = math.ceil(percentage_to_ranged_value(SPEED_RANGE, 50)) @property def speed_count(self) -> Optional[int]: """Return the number of speeds the fan supports.""" - return SPEED_RANGE[1] - SPEED_RANGE[0] + 1 + return int_states_in_range(SPEED_RANGE) ``` :::