orchid tundra
Hi dear community!
I’m integrating a fan device into Matter and ran into an issue. In Home Assistant, I can only set states like on/off or discrete modes (Low, Medium, High, Auto). However, according to the Matter 1.4 specification, it should also support controlling the fan speed as a percentage.
When I connect the same device to Apple Home, I can indeed set the fan speed in percentages.
What am I doing wrong?
distant prawn
Hi dear community!
I’m integrating a fan device into Matter and ran into an iss...
Could you open an issue here?
https://github.com/home-assistant/core/issues
distant prawn
And attach your diagnostic file
orchid tundra
Yes, thanks! I’ll open a ticket.
distant prawn
Yes, thanks! I’ll open a ticket.
For a fan device using the Matter “Fan Control” cluster (ID 0x0202) that supports the PercentSetting (0x0002) and PercentCurrent (0x0003) attributes (i.e., a percentage‐settable fan mode), the manufacturer must enable the MultiSpeed feature bit (bit 0, coded as “SPD” or kMultiSpeed) in the FeatureMap.
In summary: enable bit 0 (MultiSpeed). That is not the case here.
You need to contact the manufacturer so that they can fix their defective firmware.
You device is not compliant
Is it this product? https://csa-iot.org/csa_product/atios-smartcore/
orchid tundra
Thank you for such a quick response!
If I understand correctly, the SPD bit is responsible specifically for discrete speed levels, which can range from 0 to 100 — meaning there can be, for example, 10, 25, or even 100 discrete speeds.
These are defined by the following attribute IDs:
• 0x0004 – SpeedMax
• 0x0005 – SpeedSetting
• 0x0006 – SpeedCurrent
If you look at the official Matter specification (CSA Matter 1.4 Application Cluster Specification, section 4.4. https://csa-iot.org/wp-content/uploads/2024/11/24-27350-005_Matter-1.4-Application-Cluster-Specification.pdf), I couldn’t find any indication that the SPD bit enables percentage-based control — only that it enables support for multiple discrete speeds.
Also, in section 4.4.6 (Attributes), the attributes 0x0002 – PercentSetting and 0x0003 – PercentCurrent are marked as Mandatory, meaning they must be present in all cases (please correct me if I’m mistaken).
Finally, if we look at the behavior descriptions for commands such as Off (4.4.6.1.1) and Auto (4.4.6.1.2), the specification explicitly states that we must write 0 and null respectively to PercentSetting and PercentCurrent in the first case, and only PercentSetting in the second case.
Meanwhile, SpeedSetting is described as optional — it is used only if the SPD bit is present — but PercentSetting and PercentCurrent must always be included.
distant prawn
I think the issue is here:
https://developers.home-assistant.io/docs/core/entity/fan#preset-modes
SET_SPEED feature: The fan supports setting the speed percentage and optional preset modes.
So there is a limit with HA. Fan device has to support optional preset modes.
orchid tundra
That’s why I opened the ticket. According to the Matter standard, the Fan entity supports speed control in percentages, so I expect Home Assistant to follow the Matter protocol. This means that when adding a Fan through the Matter integration, we should have percentage-based speed control and use attributes 0x0002 (PercentSetting) and 0x0003 (PercentCurrent) to set the desired speed and retrieve the current fan speed.
Since these attributes (0x0002 and 0x0003) are mandatory for the Fan cluster, any Matter-compliant device should implement them. I’m not trying to prove my point, I’m simply trying to understand where the issue lies — because to me, this approach seems simpler and more elegant.
distant prawn
This is a limitation of the fan entity that Matter integration inherits.
You can propose to develop the fan entity by specifying this case.
orchid tundra
Thank you, I’ll create a discussion as you suggested and describe the expected behavior in detail — but I’ll do it in the morning. Thanks again!
orchid tundra
Hi, I’ve opened the discussion. Thanks!
https://github.com/home-assistant/architecture/discussions/1304
distant prawn
Hi, I’ve opened the discussion. Thanks!
https://github.com/home-assistant/archit...
Maybe you can add screenshots for better understanding
The generic limit concerning the Fan entity and the associated feature should be explained.
The architecture discussions concern the basic entities of Home Assistant, so you need to explain the context as you have done, but also why the Fan entity needs to be modified.
orchid tundra
Maybe you can add screenshots for better understanding
Okay, no problem. Which screenshots should I add?
orchid tundra
The architecture discussions concern the basic entities of Home Assistant, so yo...
Okay, thank you! I’ll add a description for this specific topic.
distant prawn
Okay, no problem. Which screenshots should I add?
HA interface and smartphone to compare
orchid tundra
I’ve added the description and included the screenshots.
distant prawn
I will also add a comment when I have time.
orchid tundra
Thanks!