Limited Fan Speed Control in Home Assistant (Matter Integration)

[kshypachov]

The problem

Hello, dear community.

• When a Matter-based Fan device is paired with Home Assistant, the speed control is limited to discrete levels defined by the FanModeSequence (e.g., Off-Low-Med-High-Auto).
• When the device is paired with Apple Home, percentage-based fan speed control (0–100%) is available through the Apple Home interface, while Home Assistant only provides step-based control.

Matter Fan (Cluster 0x0202 – Fan Control)

I expect that Home Assistant will support setting the PercentSetting attribute (ID 0x0002) the same way Apple Home currently does — allowing the user to adjust fan speed in percentages rather than only through discrete FanMode levels.

HA Core - 2025.11.1

Matter server
Python Matter Server
FabricId: 2
Compressed FabricId: 11648580358009635000
SDK Wheels Version: 2025.7.0
Schema Version: 11
Node count: 1

What version of Home Assistant Core has the issue?

core-2025.11.1

What was the last working version of Home Assistant Core?

No response

What type of installation are you running?

Home Assistant OS

Integration causing the issue

Matter server

Link to integration documentation on our website

No response

Diagnostics information

matter-01K88SCNJQS5WN10BY7XB5B9JM-Atios SmartCore-0f03938e9968f53cdf8c7099f89b533a.json

Example YAML snippet

Anything in the logs that might be useful for us?

Additional information

No response

[home-assistant]

Hey there @home-assistant/matter, mind taking a look at this issue as it has been labeled with an integration (matter) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of matter can trigger bot actions by commenting:

• @home-assistant close Closes the issue.
• @home-assistant rename Awesome new title Renames the issue.
• @home-assistant reopen Reopen the issue.
• @home-assistant unassign matter Removes the current integration label and assignees on the issue, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the issue.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the issue.

_{^{(message by CodeOwnersMention)}}

---

matter documentation
matter source
_{^{(message by IssueLinks)}}

[lboue]

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.

[kshypachov]

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.

[backcountrymountains]

I have a Govee air purifier that controls fan speed using PercentSetting, although the fan only has 3 speeds (and off) with the following PercentSettings: 0,33,66,100.

The created Home Assistant entity only lets me set the FanMode cluster attribute, which has no effect on the device. Is there a way to force HA to allow me to control the PercentSetting of the entity?

I'm sure this is an issue with the firmware of the device, but I doubt I'll have much success convincing the company to fix the firmware. It would be nice if I could force HA to allow control of the PercentSetting attribute.

[backcountrymountains]

Hello again.
I do think @kshypachov is correct about PercentSetting and PercentCurrent being mandatory according to the Matter Application Cluster Specification Version 1.4.2-adopted. I could only find the document on manuals.plus, so take it with a grain of salt, but here is the relevant section:

As an aside it is possible to interact with the Matter Server Add-on using the Websockets API:
Websocket Documentation

class APICommand(str, Enum):
    """Enum with all known API commands."""

    START_LISTENING = "start_listening"
    SERVER_DIAGNOSTICS = "diagnostics"
    SERVER_INFO = "server_info"
    GET_NODES = "get_nodes"
    GET_NODE = "get_node"
    COMMISSION_WITH_CODE = "commission_with_code"
    COMMISSION_ON_NETWORK = "commission_on_network"
    SET_WIFI_CREDENTIALS = "set_wifi_credentials"
    SET_THREAD_DATASET = "set_thread_dataset"
    OPEN_COMMISSIONING_WINDOW = "open_commissioning_window"
    DISCOVER = "discover"
    INTERVIEW_NODE = "interview_node"
    DEVICE_COMMAND = "device_command"
    REMOVE_NODE = "remove_node"
    GET_VENDOR_NAMES = "get_vendor_names"
    READ_ATTRIBUTE = "read_attribute"
    WRITE_ATTRIBUTE = "write_attribute"
    PING_NODE = "ping_node"
    GET_NODE_IP_ADDRESSES = "get_node_ip_addresses"
    IMPORT_TEST_NODE = "import_test_node"
    CHECK_NODE_UPDATE = "check_node_update"
    UPDATE_NODE = "update_node"
    SET_DEFAULT_FABRIC_LABEL = "set_default_fabric_label"
    SET_ACL_ENTRY = "set_acl_entry"
    SET_NODE_BINDING = "set_node_binding"

I stole and hacked up this code to make a script that reads and writes some attributes by connecting to the Matter Server Add-on and sending some JSON:

#!/usr/bin/env python3

import json
import websocket

messageID = 0

def next_message_id():
    global messageID
    messageID += 1
    return str(messageID)

def raise_on_error(response):
    if "error_code" in response:
        raise ValueError(f"Error {response['error_code']}: {response.get('details')}")

def get_node_info(url, sender):
    try:
        ws = websocket.create_connection(url)
        print(f"Connection successful to {url}")

        # Read initial message and save fabric_id locally
        initial_message = ws.recv()
        initial_data = json.loads(initial_message)
        node_info = initial_data
        print(f"Node Info: {node_info}\n")

        read_percent_setting(ws, sender)

        ws.close()
    except Exception as e:
        print(f"An error occurred: {e}\n")

def read_percent_setting(ws, sender):
    print("Read PercentSetting...")
    # pdb.set_trace()
    """Parse AttributePath string into tuple of endpoint_id, cluster_id, attribute_id."""
    read_bindings = {
        "message_id": next_message_id(),
        "command": "read_attribute",
        "args": {
            "node_id": sender["node"],
            "attribute_path": f"{sender['endpoint']}/514/2"
        }
    }
    ws.send(json.dumps(read_bindings))

    read_response = ws.recv()
    bindings_data = json.loads(read_response)
    raise_on_error(bindings_data)
    binding_entries = bindings_data.get("result", {})
    print(f"Matter Server Response: {json.dumps(binding_entries, indent=2)}\n")

    write_percent_setting(ws, sender)
    
    ws.close()


def write_percent_setting(ws, sender):
    print("Write PercentSetting...")
    # pdb.set_trace()
    """Parse AttributePath string into tuple of endpoint_id, cluster_id, attribute_id."""
    write_percent = {
        "message_id": next_message_id(),
        "command": "write_attribute",
        "args": {
            "node_id": sender["node"],
            "attribute_path": f"{sender['endpoint']}/514/2",
            "value": 33
        }
    }
    ws.send(json.dumps(write_percent))

    read_response = ws.recv()
    bindings_data = json.loads(read_response)
    raise_on_error(bindings_data)
    binding_entries = bindings_data.get("result", {})
    print(f"Matter Server Response: {json.dumps(binding_entries, indent=2)}\n")
    
    read_ip(ws, sender)

    ws.close()

def read_ip(ws, sender):
    print("read info...")
    # pdb.set_trace()
    """Parse AttributePath string into tuple of endpoint_id, cluster_id, attribute_id."""
    read_bindings = {
        "message_id": next_message_id(),
        "command": "get_node_ip_addresses",
        "args": {
            "node_id": sender["node"]
        }
    }
    ws.send(json.dumps(read_bindings))

    read_response = ws.recv()
    bindings_data = json.loads(read_response)
    raise_on_error(bindings_data)
    binding_entries = bindings_data.get("result", {})
    print(f"Matter Server Response: {json.dumps(binding_entries, indent=2)}\n")
    
    ws.close()

if __name__ == "__main__":

    # This is the node_id and endpoint of the device
    sender = {"node": 2, "endpoint": 1} 
    # This is the url of your HA and the port specified in the Matter Server Add-on config
    url = "ws://192.168.1.xxx:5580/ws"

    get_node_info(url, sender)

I'm not a programmer but this is enough for me to control my fan. Yay!

I set the port in the Add-on config, but I think I'm using the default anyway:

[Apollon77]

Hehe, yeah the spec is a bit confusing here. When I understand it right, especially this part:

It is up to the server implementation to map between ranges of the SpeedSetting attribute, the PercentSetting
attribute, and the FanMode attribute enumerated values that are supported as indicated
in the FanModeSequence attribute per the requirements below.

That means that it should be always possible to write any value as "percentage" ... it could just be that if you write 25% that the server directly adjusts that to 33% or such because he might only support 3 speeds. or maybe the server leaves the 25% but internally uses 33% because same reason.

Then the currentSpeed should be adjusted ... and if you set speed the percentage should be adjusted because also both are writable. comparable for FanMode.

@lboue I think the best is to allow controlling "FancMode" as "enum style" but also Percentage directly ... it should can happen that percent is directly adjusted to something else if the device does not support "all levels 0..100"

[backcountrymountains]

What's great about my device is that PercentSetting is the only thing that changes when I manually (literally on the device, with my hand) change the fan modes (FanMode is 0, always, and PercentCurrent is 0, always). Setting The fan preset mode in the HA frontend doesn't work.

As a side note, I can use PercentSetting to set the fan to any value between 0-100 on my fan, despite the buttons only setting 0,33,66,100, so that's neat.

Anyway, it would be great if PercentSetting is mandatory and the HA entity created had the ability to use PercentSetting to set the fan speeds, since that's all that works for me. I don't understand the code well enough to know how HA decides to enable set_percentage for fan entities.

[kshypachov]

Hello everyone. Thanks for responding — I’m glad this discussion has generated interest.
@backcountrymountains I’ll attach the relevant part of the specification here. You can also download these documents at https://csa-iot.org/developer-resource/specifications-download-request/

As I mentioned earlier, HomeAssistant currently expects the SPD bit in the FeatureMap to be enabled before it shows the speed control slider. And even when SPD is enabled, HomeAssistant uses attribute 0x0005 – SpeedSetting to set the fan speed.

If you look at how Apple Home behaves, it immediately displays the speed control slider and uses the PercentSetting (ID 0x0002) attribute to set the fan speed.

My view:
When a Fan device is added via Matter, the speed control slider should be available right away. For fine-grained speed control, the PercentSetting (ID 0x0002) attribute should be used. At the same time, step-based speed control should remain available (as it is now) using the elements of FanModeSequence (this part currently works correctly).

@Apollon77 Regarding percentage ranges and how they map to Low/Med/High speeds — this is entirely up to the device manufacturer and how they implement this logic. It shouldn’t concern HomeAssistant; it simply displays whatever the device writes into the cluster. Also keep in mind that a Matter device can be connected to multiple ecosystems simultaneously, so its parameters may be changed by another system, and HomeAssistant will need to follow these changes.

23-27350-005_matter-1-4-application-cluster-specification.pdf

Once again, thank you for engaging and helping to resolve this issue.

[backcountrymountains]

I'm still not a programmer, but would it be possible to change:

@callback
    def _calculate_features(
        self,
    ) -> None:
        """Calculate features for HA Fan platform from Matter FeatureMap."""
        feature_map = int(
            self.get_matter_attribute_value(clusters.FanControl.Attributes.FeatureMap)
        )
        # NOTE: the featuremap can dynamically change, so we need to update the
        # supported features if the featuremap changes.
        # work out supported features and presets from matter featuremap
        if self._feature_map == feature_map:
            return
        self._feature_map = feature_map
        self._attr_supported_features = FanEntityFeature(0)
        if feature_map & FanControlFeature.kMultiSpeed:
            self._attr_supported_features |= FanEntityFeature.SET_SPEED
            self._attr_speed_count = int(
                self.get_matter_attribute_value(clusters.FanControl.Attributes.SpeedMax)
            )

And move the self._attr_supported_features |= FanEntityFeature.SET_SPEED outside of the if feature_map & FanControlFeature.kMultiSpeed: conditional, assuming that Matter fans should all use PercentSetting for speed settings?

@callback
    def _calculate_features(
        self,
    ) -> None:
        """Calculate features for HA Fan platform from Matter FeatureMap."""
        feature_map = int(
            self.get_matter_attribute_value(clusters.FanControl.Attributes.FeatureMap)
        )
        # NOTE: the featuremap can dynamically change, so we need to update the
        # supported features if the featuremap changes.
        # work out supported features and presets from matter featuremap
        if self._feature_map == feature_map:
            return
        self._feature_map = feature_map
        self._attr_supported_features = FanEntityFeature(0)
        self._attr_supported_features |= FanEntityFeature.SET_SPEED
        if feature_map & FanControlFeature.kMultiSpeed:
            self._attr_speed_count = int(
                self.get_matter_attribute_value(clusters.FanControl.Attributes.SpeedMax)
            )

Is there a way to test this change in my HA installation without setting up a whole development environment?

[kshypachov]

Hi @backcountrymountains

Thank you for the suggested changes. I’m not yet sure how feasible it is to run this without setting up the environment, but I will try to test your changes.

Thanks!