Fix thermostat fan modes to respect fanModeSequence

tests/data/devices/atlantic-group-adapter-zigbee-fujitsu.json

@@ -388,13 +388,15 @@
         "hvac_action": null,
         "hvac_mode": "off",
         "preset_mode": "none",
-        "fan_mode": "auto",
+        "fan_mode": "on",
         "max_temp": 30.0,
         "min_temp": 16.0,
         "supported_features": 395,
         "fan_modes": [
-          "auto",
-          "on"
+          "low",
+          "medium",
+          "high",
+          "auto"
         ],
         "preset_modes": [],
         "hvac_modes": [

tests/data/devices/centralite-systems-3156105-0x1418468c.json

@@ -454,8 +454,8 @@
         "min_temp": 7.0,
         "supported_features": 393,
         "fan_modes": [
-          "auto",
-          "on"
+          "on",
+          "auto"
         ],
         "preset_modes": [],
         "hvac_modes": [

tests/data/devices/enktro-acmidea.json

@@ -325,8 +325,10 @@
         "min_temp": 17.0,
         "supported_features": 395,
         "fan_modes": [
-          "auto",
-          "on"
+          "low",
+          "medium",
+          "high",
+          "auto"
         ],
         "preset_modes": [],
         "hvac_modes": [

tests/data/devices/zen-within-zen-01-0x0000021f.json

@@ -419,8 +419,8 @@
         "min_temp": 4.0,
         "supported_features": 395,
         "fan_modes": [
-          "auto",
-          "on"
+          "on",
+          "auto"
         ],
         "preset_modes": [],
         "hvac_modes": [

tests/test_climate.py

@@ -6,7 +6,7 @@
 from collections.abc import Iterator
 import logging
 from typing import Any
-from unittest.mock import AsyncMock, MagicMock, call, patch
+from unittest.mock import AsyncMock, MagicMock, PropertyMock, call, patch
 import zoneinfo
 
 from freezegun import freeze_time
@@ -46,7 +46,7 @@
     Thermostat as ThermostatEntity,
     ZehnderThermostat,
 )
-from zha.application.platforms.climate.const import FanState
+from zha.application.platforms.climate.const import FanState, HVACMode
 from zha.application.platforms.number import NumberConfigurationEntity
 from zha.application.platforms.sensor import (
     Sensor,
@@ -55,7 +55,7 @@
 )
 from zha.const import STATE_CHANGED
 from zha.exceptions import ZHAException
-from zha.quirks import DeviceMatch, DeviceRegistry, ModelInfo
+from zha.quirks import THERMOSTAT_FAN_ONLY_HVAC, DeviceMatch, DeviceRegistry, ModelInfo
 from zha.zigbee.device import Device
 
 _LOGGER = logging.getLogger(__name__)
@@ -1300,6 +1300,59 @@ async def test_set_fan_mode_not_supported(
     assert fan_cluster.write_attributes.await_count == 0
 
 
+async def test_set_fan_mode_no_zcl_mapping(
+    zha_gateway: Gateway,
+):
+    """Test fan mode with no ZCL mapping is rejected."""
+    device_climate_fan = await device_climate_mock(zha_gateway, CLIMATE_FAN)
+    fan_cluster = device_climate_fan.device.endpoints[1].fan
+    entity: ThermostatEntity = get_entity(
+        device_climate_fan, platform=Platform.CLIMATE, entity_type=ThermostatEntity
+    )
+
+    # Patch `fan_modes` to include a string that is intentionally absent from
+    # `FAN_MODE_TO_ZCL` so the defensive `.get(...) is None` branch in
+    # `async_set_fan_mode` is exercised (the earlier "mode not in fan_modes"
+    # rejection would otherwise short-circuit it).
+    with patch.object(
+        ThermostatEntity,
+        "fan_modes",
+        new_callable=PropertyMock,
+        return_value=["bogus"],
+    ):
+        await entity.async_set_fan_mode("bogus")
+        await zha_gateway.async_block_till_done()
+
+    assert fan_cluster.write_attributes.await_count == 0
+
+
+async def test_fan_only_hvac_mode_not_exposed_without_quirk_feature(
+    zha_gateway: Gateway,
+):
+    """Fan cluster alone must not expose HVACMode.FAN_ONLY."""
+    device_climate_fan = await device_climate_mock(zha_gateway, CLIMATE_FAN)
+    entity: ThermostatEntity = get_entity(
+        device_climate_fan, platform=Platform.CLIMATE, entity_type=ThermostatEntity
+    )
+
+    assert THERMOSTAT_FAN_ONLY_HVAC not in device_climate_fan.exposes_features
+    assert HVACMode.FAN_ONLY not in entity.hvac_modes
+
+
+async def test_fan_only_hvac_mode_exposed_with_quirk_feature(
+    zha_gateway: Gateway,
+):
+    """A quirk that opts in via exposes_features unlocks HVACMode.FAN_ONLY."""
+    device_climate_fan = await device_climate_mock(zha_gateway, CLIMATE_FAN)
+    device_climate_fan.exposes_features.add(THERMOSTAT_FAN_ONLY_HVAC)
+
+    entity: ThermostatEntity = get_entity(
+        device_climate_fan, platform=Platform.CLIMATE, entity_type=ThermostatEntity
+    )
+
+    assert HVACMode.FAN_ONLY in entity.hvac_modes
+
+
 async def test_set_fan_mode(
     zha_gateway: Gateway,
 ):

zha/application/platforms/climate/__init__.py

@@ -19,7 +19,6 @@
 )
 from zigpy.zcl.clusters.hvac import (
     Fan as FanCluster,
-    FanMode,
     RunningState,
     SystemMode,
     Thermostat as ThermostatCluster,
@@ -40,18 +39,22 @@
     ATTR_OCCP_COOL_SETPT,
     ATTR_OCCP_HEAT_SETPT,
     FAN_AUTO,
+    FAN_MODE_TO_ZCL,
     FAN_ON,
     HVAC_MODE_2_SYSTEM,
     PRECISION_TENTHS,
+    SEQ_FAN_MODES,
     SEQ_OF_OPERATION,
     SYSTEM_MODE_2_HVAC,
     ZCL_TEMP,
+    ZCL_TO_FAN_MODE,
     ClimateEntityFeature,
     HVACAction,
     HVACMode,
     Preset,
 )
 from zha.decorators import periodic
+from zha.quirks import THERMOSTAT_FAN_ONLY_HVAC
 from zha.units import UnitOfTemperature
 
 if TYPE_CHECKING:
@@ -598,6 +601,11 @@ def outdoor_temperature(self):
     @property
     def fan_mode(self) -> str | None:
         """Return current FAN mode."""
+        if self._fan_cluster is not None:
+            current = self._fan_cluster.get(FanCluster.AttributeDefs.fan_mode.name)
+            if current is not None:
+                return ZCL_TO_FAN_MODE.get(current, FAN_AUTO)
+
         running_state = self._running_state
         if running_state is None:
             return FAN_AUTO
@@ -610,12 +618,13 @@ def fan_mode(self) -> str | None:
             return FAN_ON
         return FAN_AUTO
 
-    @functools.cached_property
+    @property
     def fan_modes(self) -> list[str] | None:
         """Return supported FAN modes."""
         if self._fan_cluster is None:
             return None
-        return [FAN_AUTO, FAN_ON]
+        seq = self._fan_cluster.get(FanCluster.AttributeDefs.fan_mode_sequence.name)
+        return SEQ_FAN_MODES.get(seq, [FAN_ON, FAN_AUTO])
 
     @property
     def hvac_action(self) -> HVACAction | None:
@@ -673,7 +682,14 @@ def hvac_mode(self) -> HVACMode | None:
     @property
     def hvac_modes(self) -> list[HVACMode]:
         """Return the list of available HVAC operation modes."""
-        return SEQ_OF_OPERATION.get(self._ctrl_sequence_of_oper, [HVACMode.OFF])
+        modes = SEQ_OF_OPERATION.get(self._ctrl_sequence_of_oper, [HVACMode.OFF])
+        if (
+            self._fan_cluster is not None
+            and THERMOSTAT_FAN_ONLY_HVAC in self._device.exposes_features
+            and HVACMode.FAN_ONLY not in modes
+        ):
+            modes = [*modes, HVACMode.FAN_ONLY]
+        return modes
 
     @property
     def preset_mode(self) -> str:
@@ -804,10 +820,13 @@ async def async_set_fan_mode(self, fan_mode: str) -> None:
             self.warning("Unsupported '%s' fan mode", fan_mode)
             return
 
-        mode = FanMode.On if fan_mode == FAN_ON else FanMode.Auto
+        zcl_mode = FAN_MODE_TO_ZCL.get(fan_mode)
+        if zcl_mode is None:
+            self.warning("No ZCL mapping for fan mode '%s'", fan_mode)
+            return
 
         await write_attributes_safe(
-            self._fan_cluster, {FanCluster.AttributeDefs.fan_mode.name: mode}
+            self._fan_cluster, {FanCluster.AttributeDefs.fan_mode.name: zcl_mode}
         )
 
     async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:

zha/application/platforms/climate/const.py

@@ -3,7 +3,13 @@
 from enum import IntFlag, StrEnum
 from typing import Final
 
-from zigpy.zcl.clusters.hvac import ControlSequenceOfOperation, RunningMode, SystemMode
+from zigpy.zcl.clusters.hvac import (
+    ControlSequenceOfOperation,
+    FanMode,
+    FanModeSequence,
+    RunningMode,
+    SystemMode,
+)
 
 ATTR_SYS_MODE: Final[str] = "system_mode"
 ATTR_FAN_MODE: Final[str] = "fan_mode"
@@ -141,6 +147,24 @@ class HVACAction(StrEnum):
     PREHEATING = "preheating"
 
 
+SEQ_FAN_MODES: dict[int, list[str]] = {
+    FanModeSequence.Low_Med_High: [FAN_LOW, FAN_MEDIUM, FAN_HIGH],
+    FanModeSequence.Low_High: [FAN_LOW, FAN_HIGH],
+    FanModeSequence.Low_Med_High_Auto: [FAN_LOW, FAN_MEDIUM, FAN_HIGH, FAN_AUTO],
+    FanModeSequence.Low_High_Auto: [FAN_LOW, FAN_HIGH, FAN_AUTO],
+    FanModeSequence.On_Auto: [FAN_ON, FAN_AUTO],
+}
+
+FAN_MODE_TO_ZCL: dict[str, FanMode] = {
+    FAN_LOW: FanMode.Low,
+    FAN_MEDIUM: FanMode.Medium,
+    FAN_HIGH: FanMode.High,
+    FAN_ON: FanMode.On,
+    FAN_AUTO: FanMode.Auto,
+}
+
+ZCL_TO_FAN_MODE: dict[int, str] = {v: k for k, v in FAN_MODE_TO_ZCL.items()}
+
 RUNNING_MODE = {
     RunningMode.Off: HVACMode.OFF,
     RunningMode.Cool: HVACMode.COOL,

zha/quirks.py

@@ -37,6 +37,7 @@
 BEGA_LIGHT_SWITCHABLE_WHITE = "bega.light_switchable_white"
 SE_POLL_SUMMATION = "se_poll_summation"
 SIREN_BASIC = "siren_basic"
+THERMOSTAT_FAN_ONLY_HVAC = "thermostat_fan_only_hvac"
 
 
 class ModelInfo(NamedTuple):