matter: enable fan percentage speed control for all FanControl devices#164546
matter: enable fan percentage speed control for all FanControl devices#164546ldkud50 wants to merge 3 commits intohome-assistant:devfrom
Conversation
home-assistant
bot
added
cla-needed
integration: matter
small-pr
![home-assistant[bot]](https://cdn.statically.io/img/avatars.githubusercontent.com/in/97978?s=60&v=4){kind=small}
|
Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍 |
|
Hey there @home-assistant/matter, mind taking a look at this pull request as it has been labeled with an integration ( Code owner commandsCode owners of
|
home-assistant
bot
added
cla-recheck
cla-signed
and removed
cla-recheck
cla-needed
labels
There was a problem hiding this comment.
Pull request overview
This PR updates the Matter fan platform so percent-based speed control is exposed for all devices implementing the FanControl cluster, aligning Home Assistant behavior with the Matter spec and making the percentage slider available even when kMultiSpeed is not present.
Changes:
- Enable
FanEntityFeature.SET_SPEEDunconditionally for Matter FanControl devices so percentage control is always available. - Only derive
speed_countfromSpeedMaxwhen thekMultiSpeedfeature flag is present. - Include
PercentSettingin the discovery schema’soptional_attributesso it is subscribed to when present.
| # FIX: PercentSetting/PercentCurrent are MANDATORY on all FanControl clusters | ||
| # per the Matter spec. Enable SET_SPEED unconditionally so the percentage | ||
| # slider is always shown regardless of whether kMultiSpeed is set. | ||
| self._attr_supported_features |= FanEntityFeature.SET_SPEED | ||
|
|
||
| if feature_map & FanControlFeature.kMultiSpeed: |
There was a problem hiding this comment.
Enabling FanEntityFeature.SET_SPEED unconditionally changes the supported-features bitmask for fans without kMultiSpeed/kRocking/kAirflowDirection set. The existing Matter fan tests (e.g., tests/components/matter/test_fan.py::test_fan_supported_features) currently assert that SET_SPEED is only present when kMultiSpeed is set, so CI will fail unless those expectations (and any snapshots that include supported features) are updated to match the new behavior.
| self._attr_supported_features = FanEntityFeature(0) | ||
|
|
||
| # FIX: PercentSetting/PercentCurrent are MANDATORY on all FanControl clusters | ||
| # per the Matter spec. Enable SET_SPEED unconditionally so the percentage | ||
| # slider is always shown regardless of whether kMultiSpeed is set. | ||
| self._attr_supported_features |= FanEntityFeature.SET_SPEED | ||
|
|
||
| if feature_map & FanControlFeature.kMultiSpeed: | ||
| self._attr_supported_features |= FanEntityFeature.SET_SPEED | ||
| self._attr_speed_count = int( | ||
| # kMultiSpeed devices also expose SpeedMax for step granularity | ||
| speed_max = int( | ||
| self.get_matter_attribute_value(clusters.FanControl.Attributes.SpeedMax) | ||
| ) | ||
| if speed_max > 0: | ||
| self._attr_speed_count = speed_max | ||
|
|
There was a problem hiding this comment.
_attr_speed_count is only set when kMultiSpeed is present, but it is never cleared when the feature map changes and kMultiSpeed is removed (or when SpeedMax becomes 0). Since the feature map is treated as dynamic in this method, a previously populated speed count can linger and incorrectly affect percentage_step/UI behavior. Reset _attr_speed_count (e.g., to None) when recalculating features before conditionally setting it for kMultiSpeed.
Description
PercentSetting(0x0002) andPercentCurrent(0x0003) are MANDATORY attributes on all Matter FanControl clusters (0x0202) per the Matter specification section 4.4.6. However,FanEntityFeature.SET_SPEEDwas only enabled when the device also had thekMultiSpeedfeature flag, making the percentage slider unreachable for devices that only support percent-based control.Changes
FanEntityFeature.SET_SPEEDunconditionally for all FanControl devicesspeed_countwhenkMultiSpeedis present (usesSpeedMax)PercentSettingtooptional_attributesin the discovery schemaFixes
Fixes #138430
Fixes #156285