Separate fan speeds into percentages and presets modes #45407

bdraco · 2021-01-21T23:55:07Z

Continuation of @Jc2k 's work in #39204

Architecture issue: home-assistant/architecture#127

WTH: https://community.home-assistant.io/t/wth-homekit-controller-support-for-4-fan-speeds/221305

Update developer documentation - Document fan entity model change to seperate fan speeds into percentages and presets modes developers.home-assistant#777
Update frontend to be a slider that calls fan.set_percentage or fan.set_preset_mode instead of a speed list. Separate fan speeds into percentages and presets modes frontend#8216

Breaking change

For users

The fan entity model has changed to split named speeds into percentages in the range from 0 (off)-100 and preset modes.

Why change?

This change allowed us to expand the number of supported speeds to accommodate additional fan models in Home Assistant. (#45407 (comment))

We had 3 fan speeds and that worked great as long as the fan had no more than 3 speeds

Over time we received a number of requests to add fans with 4, 5, or even more speeds and preset modes. This put us in the difficult position of having to reject this support because the underlying fan model didn’t support it.

Percentages were chosen because they can represent up to 100 speeds which should accommodate all fans. Additionally it’s a lot easier to ask your voice voice assistant to set the fan to 20% then remember that medium-low is actually low-medium or have to learn and remember how to say the speeds for every fan model you want to control.

Moving forward

Calls in automations and scripts to fan.set_speed should be replaced:

Calls that set a speed should use fan.set_percentage.
Calls that set a preset mode should use fan.set_preset_mode.

The following speeds existed in core integration and will now be automatically identified as preset modes: auto, smart, interval, idle, and favorite

Both of the new calls are backwards compatible.

Calls in automations and scripts to fan.turn_on that use the speed attribute should be switched to use the percentage or preset_mode attribute once the underly integration has been updated to support it.

All core fans have been updated to ensure that calls to the fan.turn_on service
map percentage or preset_mode to speed for backwards compatibility.

For developers

The core issues we are solving is:

non portable interface to speed for voice assistants
limited about of speeds
presets and speeds mixed together in speeds

Custom fan integrations should add the @fan_compat decorator to
async_turn_on or turn_on function to ensure backwards compatibility:

Example:

from homeassistant.components.fan import fan_compat

...

@fan_compat
async def async_turn_on(self, speed: Optional[str] = None, percentage: Optional[int] = None, preset_mode: Optional[str] = None, **kwargs: Any) -> None:

The function signature for async_turn_on is now:

async def async_turn_on(self, speed: str = None, percentage: int = None, preset_mode: Optional[str] = None, **kwargs) -> None:

The function signature for turn_on is now:

def turn_on(self, speed: str = None, percentage: int = None, preset_mode: Optional[str] = None, **kwargs) -> None:

Developers that are creating new integrations should review the updated fan entity model documentation at https://developers.home-assistant.io/docs/core/entity/fan

Proposed change

At its heart this PR adds support for a new method on fans, async_set_percentage (and its sync counterpart).

The goal is to provide a gradual transition and allow the existing interface to continue working by detecting when async_set_percentage and set_percentage have been overridden and provide a backwards compatible interface.

If a device supports async_set_percentage then it doesn't need to implement async_set_speed - HA provides a mapping function that converts medium into a percentage.

If a device does not support async_set_percentage then a mapping function will translate calls to that method into reasonable async_set_speed calls.

The speed attribute will always be available - using a mapping function if only a percentage is available.

A new percentage attribute is added and will also always be available - again using a mapping function where needed - turning low into 33% etc.

The mapping function is dynamic and tries to accommodates fans that don't follow the spec properly (e.g. they have added extra speeds) using a similar mechanism to the one in homekit.

The PR ports demo fans to the new API to test it out.

Type of change

Dependency upgrade
Bugfix (non-breaking change which fixes an issue)
New integration (thank you!)
New feature (which adds functionality to an existing integration)
Breaking change (fix/feature causing existing functionality to break)
Code quality improvements to existing code or addition of tests

Example entry for `configuration.yaml`:

# Example configuration.yaml

Additional information

This PR fixes or closes issue: fixes #
This PR is related to issue:
Link to documentation pull request: Update fan documentation for entity model separation of fan speeds into percentages and presets modes home-assistant.io#16265

Checklist

The code change is tested and works locally.
Local tests pass. Your PR cannot be merged unless tests pass
There is no commented out code in this PR.
I have followed the development checklist
The code has been formatted using Black (black --fast homeassistant tests)
Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

The manifest file has all fields filled out correctly.
Updated and included derived files by running: python3 -m script.hassfest.
New or updated dependencies have been added to requirements_all.txt.
Updated by running python3 -m script.gen_requirements_all.
Untested files have been added to .coveragerc.

The integration reached or maintains the following Integration Quality Scale:

No score or internal
🥈 Silver
🥇 Gold
🏆 Platinum

To help with the load of incoming pull requests:

I have reviewed two other open pull requests in this repository.

bdraco · 2021-01-22T04:17:00Z

Jc2k · 2021-01-22T04:37:41Z

I've only had a cursory look through so far but I like what I see. I am a big fan of the gradual transition approach.

What is the breaking change at this stage?

bdraco · 2021-01-22T04:38:40Z

I've only had a cursory look through so far but I like what I see. I am a big fan of the gradual transition approach.

What is the breaking change at this stage?

Custom integration will have to update their async_turn_on to be able to handle percentage otherwise it will be ignored when a user calls the fan.turn_on service with a percentage

Note that speed will still work with fan.turn_on as it did before so it only affects users who switch over and have a custom fan integration that hasn't updated their code.

Jc2k · 2021-01-22T04:57:57Z

Ah ok - that's not too onerous I don't think.

bdraco · 2021-01-22T05:37:36Z

Looks like coverage is needed for backcompat

https://github.com/home-assistant/core/pull/45407/checks?check_run_id=1746793288

bdraco · 2021-01-22T06:57:59Z

It might be better to make a '@fan_speed_compat' and '@fan_percentage_compat' decorator instead. Might need 4 of them though for async vs sync so not sure how much it saves but at least it's more dry

bdraco · 2021-01-22T06:58:29Z

Will pick this back up tomorrow, but it's at least ready to get feedback

homeassistant/components/fan/__init__.py

bdraco · 2021-01-22T17:27:17Z

I'm hoping to clean this up a bit to use a @speed_compat and @percentage_compat decorator to make this easier for devs who are transitioning their fans and make this a bit more DRY

Will probably rework the shared comment to something like

    #
    # The fan entity model has changed to use percentages.
    #
    # The @percentage_compat decorator will ensure the speed argument is set
    # when a percentage is passed in. When this entity is updated to use the
    # new model with `speed` and `set_speed` removed, switch the decorator to
    # @speed_compat to ensure the percentage argument will be filled for
    # places that still pass in speed instead of percentage.
    #
    @percentage_compat

bdraco · 2021-01-22T20:11:41Z

Managed to get this to 100% diff hit 👍

homeassistant/components/fan/__init__.py

MartinHjelmare · 2021-01-22T22:16:52Z

Do we need to limit the mqtt fan platform allowed speed values to make it compatible and have some valid speeds?

bdraco · 2021-01-22T22:33:07Z

Do we need to limit the mqtt fan platform allowed speed values to make it compatible and have some valid speeds?

I think we should remove the ability for mqtt to set a non-allowed speed value or one not in the speed_list. Right now its accepting an arbitrary string to async_set_speed

I opened a separate PR for this since we should document the breaking change in the release notes for MQTT in case someone is actively using this #45445

I'm not sure anyone actually does this in production (well except that one guy who does) since it looks like it was only added in #33584 to ensure there was full coverage since the code supported passing it.

bdraco · 2021-01-22T23:10:18Z

It looks like zha has a fan speed of on

ValueError: 'on' is not in list

bdraco · 2021-01-22T23:13:47Z

# Additional speeds in zigbee's ZCL
# Spec is unclear as to what this value means. On King Of Fans HBUniversal
# receiver, this means Very High.
SPEED_ON = "on"

apparently SPEED_ON means very high

bdraco · 2021-01-25T22:36:45Z

I pulled out Jc2k's original work to update homekit_controller from #39204 and updated it in #45547 to verify I didn't break anything in the 1:1 case.

bdraco · 2021-01-25T22:59:17Z

I've done all the manual testing I can think to do with this and ran though the code line by line again.

bdraco · 2021-01-26T06:24:27Z

Did another run though. Can't find anything else that needs to be adjusted.

bdraco · 2021-01-26T22:29:35Z

I've converted 14 out of the 26 fans in core in separate PRs.

I was able to make all 14 of them conform to the spec without having to the ability to set some speeds.

Jc2k · 2021-01-27T00:07:39Z

This is looking really good. My +1 doesn't mean much outside of homekit_controller, but you have it. I can't think of a better way we could handle the transition AND cope with the non compliant fans.

bdraco · 2021-01-27T04:34:36Z

I've got HomeKit updated in #45549

Alexa and Google both support the percentage model and they looks quite strait-forward to update

Alexa percentage controller

Google supportsFanSpeedPercent

https://developers.google.com/assistant/smarthome/traits/fanspeed

MartinHjelmare · 2021-01-27T04:59:49Z

I'll look at this again after the beta cut.

balloob

Changes look good!

balloob · 2021-01-27T10:21:05Z

This should not be merged until we cut the beta.

homeassistant/components/demo/fan.py

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

bdraco · 2021-01-27T23:42:22Z

Final testing looks good 👍

homeassistant added the cla-signed label Jan 21, 2021

probot-home-assistant bot added core integration: fan labels Jan 21, 2021

bdraco changed the title ~~Fan speed percentage~~ WIP: WTH: Support more than 3 fan speeds Jan 21, 2021

bdraco changed the title ~~WIP: WTH: Support more than 3 fan speeds~~ WIP: WTH: Convert fan speeds to use percentages Jan 22, 2021

bdraco added the breaking-change label Jan 22, 2021

bdraco changed the title ~~WIP: WTH: Convert fan speeds to use percentages~~ WTH: Convert fan speeds to use percentages Jan 22, 2021

bdraco added the WTH Issues & PRs generated from the "Month of What the Heck?" label Jan 22, 2021

bdraco marked this pull request as ready for review January 22, 2021 04:23

bdraco requested a review from Jc2k January 22, 2021 04:25

bdraco mentioned this pull request Jan 22, 2021

Document fan entity model change to seperate fan speeds into percentages and presets modes home-assistant/developers.home-assistant#777

Merged

5 tasks

bdraco mentioned this pull request Jan 22, 2021

Update fan documentation for entity model separation of fan speeds into percentages and presets modes home-assistant/home-assistant.io#16265

Merged

8 tasks

MartinHjelmare reviewed Jan 22, 2021

View reviewed changes

bdraco changed the title ~~WTH: Convert fan speeds to use percentages~~ Convert fan speeds to use percentages Jan 22, 2021

MartinHjelmare reviewed Jan 22, 2021

View reviewed changes

homeassistant/components/fan/__init__.py Outdated Show resolved Hide resolved

bdraco mentioned this pull request Jan 22, 2021

Remove the ability for mqtt to set speeds that are not in the speed_list #45445

Merged

21 tasks

bdraco mentioned this pull request Jan 25, 2021

Update homekit_controller to use new fan entity model #45547

Merged

21 tasks

This was referenced Jan 26, 2021

Update homekit to use new fan entity model #45549

Merged

Add support for bpup prystupa/bond-api#4

Merged

Add BPUP (push updates) support to bond #45550

Merged

This was referenced Jan 26, 2021

Update ozw to use new fan entity model #45577

Merged

Update wemo to use new fan entity model #45582

Merged

Update vesync to use new fan entity model #45585

Merged

This was referenced Jan 27, 2021

Update esphome to use new fan entity model #45590

Merged

Update smartthings to use new fan entity model #45592

Merged

Update comfoconnect to use new fan entity model #45593

Merged

balloob approved these changes Jan 27, 2021

View reviewed changes

MartinHjelmare reviewed Jan 27, 2021

View reviewed changes

homeassistant/components/demo/fan.py Outdated Show resolved Hide resolved

homeassistant/components/demo/fan.py Outdated Show resolved Hide resolved

bdraco and others added 2 commits January 27, 2021 08:21

Update homeassistant/components/demo/fan.py

007d835

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

Update homeassistant/components/demo/fan.py

dc3cc12

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

MartinHjelmare approved these changes Jan 27, 2021

View reviewed changes

bdraco merged commit 068d1b5 into dev Jan 27, 2021

bdraco deleted the fan_speed_percentage branch January 27, 2021 23:44

bdraco mentioned this pull request Jan 28, 2021

Why not make it official? mikelawrence/senseme-hacs#13

Closed

github-actions bot locked and limited conversation to collaborators Jan 29, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Separate fan speeds into percentages and presets modes #45407

Separate fan speeds into percentages and presets modes #45407

bdraco commented Jan 21, 2021 •

edited

Loading

bdraco commented Jan 22, 2021 •

edited

Loading

Jc2k commented Jan 22, 2021

bdraco commented Jan 22, 2021 •

edited

Loading

Jc2k commented Jan 22, 2021

bdraco commented Jan 22, 2021

bdraco commented Jan 22, 2021

bdraco commented Jan 22, 2021

bdraco commented Jan 22, 2021 •

edited

Loading

bdraco commented Jan 22, 2021

MartinHjelmare commented Jan 22, 2021

bdraco commented Jan 22, 2021 •

edited

Loading

bdraco commented Jan 22, 2021 •

edited

Loading

bdraco commented Jan 22, 2021

bdraco commented Jan 25, 2021

bdraco commented Jan 25, 2021

bdraco commented Jan 26, 2021

bdraco commented Jan 26, 2021 •

edited

Loading

Jc2k commented Jan 27, 2021

bdraco commented Jan 27, 2021 •

edited

Loading

MartinHjelmare commented Jan 27, 2021

balloob left a comment

balloob commented Jan 27, 2021

bdraco commented Jan 27, 2021

Separate fan speeds into percentages and presets modes #45407

Separate fan speeds into percentages and presets modes #45407

Conversation

bdraco commented Jan 21, 2021 • edited Loading

Breaking change

For users

Why change?

Moving forward

For developers

Proposed change

Type of change

Example entry for configuration.yaml:

Additional information

Checklist

bdraco commented Jan 22, 2021 • edited Loading

Jc2k commented Jan 22, 2021

bdraco commented Jan 22, 2021 • edited Loading

Jc2k commented Jan 22, 2021

bdraco commented Jan 22, 2021

bdraco commented Jan 22, 2021

bdraco commented Jan 22, 2021

bdraco commented Jan 22, 2021 • edited Loading

bdraco commented Jan 22, 2021

MartinHjelmare commented Jan 22, 2021

bdraco commented Jan 22, 2021 • edited Loading

bdraco commented Jan 22, 2021 • edited Loading

bdraco commented Jan 22, 2021

bdraco commented Jan 25, 2021

bdraco commented Jan 25, 2021

bdraco commented Jan 26, 2021

bdraco commented Jan 26, 2021 • edited Loading

Jc2k commented Jan 27, 2021

bdraco commented Jan 27, 2021 • edited Loading

MartinHjelmare commented Jan 27, 2021

balloob left a comment

Choose a reason for hiding this comment

balloob commented Jan 27, 2021

bdraco commented Jan 27, 2021

bdraco commented Jan 21, 2021 •

edited

Loading

Example entry for `configuration.yaml`:

bdraco commented Jan 22, 2021 •

edited

Loading

bdraco commented Jan 22, 2021 •

edited

Loading

bdraco commented Jan 22, 2021 •

edited

Loading

bdraco commented Jan 22, 2021 •

edited

Loading

bdraco commented Jan 22, 2021 •

edited

Loading

bdraco commented Jan 26, 2021 •

edited

Loading

bdraco commented Jan 27, 2021 •

edited

Loading