Use configured speed ranges for HomeSeer FC200+ fan controllers in zwave_js

homeassistant/components/zwave_js/discovery.py

@@ -44,6 +44,7 @@ from homeassistant.helpers.device_registry import DeviceEntry
 from .const import LOGGER
 from .discovery_data_template import (
     BaseDiscoverySchemaDataTemplate,
+    ConfigurableFanSpeedDataTemplate,
     CoverTiltDataTemplate,
     DynamicCurrentTempClimateDataTemplate,
     NumericSensorDataTemplate,
@@ -259,6 +260,21 @@ DISCOVERY_SCHEMAS = [
             type={"number"},
         ),
     ),
+    # HomeSeer HS-FS200+
+    ZWaveDiscoverySchema(
+        platform="fan",
+        hint="configured_fan_speed",
+        manufacturer_id={0x000C},
+        product_id={0x0001},
+        product_type={0x0203},
+        primary_value=SWITCH_MULTILEVEL_CURRENT_VALUE_SCHEMA,
+        data_template=ConfigurableFanSpeedDataTemplate(
+            configuration_option=ZwaveValueID(
+                5, CommandClass.CONFIGURATION, endpoint=0
+            ),
+            configuration_value_to_speeds={0: [33, 66, 99], 1: [24, 49, 74, 99]},
+        ),
+    ),
     # Fibaro Shutter Fibaro FGR222
     ZWaveDiscoverySchema(
         platform="cover",

homeassistant/components/zwave_js/discovery_data_template.py

@@ -251,3 +251,101 @@ class CoverTiltDataTemplate(BaseDiscoverySchemaDataTemplate, TiltValueMix):
     def current_tilt_value(resolved_data: dict[str, Any]) -> ZwaveValue | None:
         """Get current tilt ZwaveValue from resolved data."""
         return resolved_data["tilt_value"]
+
+
+@dataclass
+class FanSpeedDataTemplate:
+    """Mixin to define get_speed_config."""
+
+    def get_speed_config(self, resolved_data: dict[str, Any]) -> list[int] | None:
+        """
+        Get the fan speed configuration for this device.
+
+        Values should indicate the highest allowed device setting for each
+        actual speed.
+        """
+        return None
+
+
+@dataclass
+class FixedFanSpeedDataTemplate(BaseDiscoverySchemaDataTemplate, FanSpeedDataTemplate):
+    """
+    Specifies a fixed set of fan speeds.
+
+    Example:
+      ZWaveDiscoverySchema(
+          platform="fan",
+          hint="configured_fan_speed",
+          ...
+          data_template=FixedFanSpeedDataTemplate(
+              speeds=[32,65,99]
+          ),
+      ),
+
+    `speeds` indicates the maximum setting on the underlying fan controller
+    for each actual speed.
+    """
+
+    speeds: list[int] = field(default_factory=list)
+
+    def get_speed_config(self, resolved_data: dict[str, Any]) -> list[int] | None:
+        """Get the fan speed configuration for this device."""
+        return self.speeds
+
+
+@dataclass
+class ConfigurableFanSpeedDataTemplate(
+    BaseDiscoverySchemaDataTemplate, FanSpeedDataTemplate
+):
+    """
+    Gets fan speeds based on a configuration value.
+
+    Example:
+      ZWaveDiscoverySchema(
+          platform="fan",
+          hint="configured_fan_speed",
+          ...
+          data_template=ConfigurableFanSpeedDataTemplate(
+            configuration_option=ZwaveValueID(
+                5, CommandClass.CONFIGURATION, endpoint=0
+            ),
+            configuration_value_to_speeds={0: [32, 65, 99], 1: [24, 49, 74, 99]},
+          ),
+      ),
+
+    `configuration_option` is a reference to the setting that determines how
+    many speeds are supported.
+
+    `configuration_value_to_speeds` maps the values from `configuration_option`
+    to a list of speeds.  The specified speeds indicate the maximum setting on
+    the underlying switch for each actual speed.
+    """
+
+    configuration_option: ZwaveValueID | None = None
+    configuration_value_to_speeds: dict[int, list[int]] = field(default_factory=dict)
+
+    def resolve_data(self, value: ZwaveValue) -> dict[str, Any]:
+        """Resolve helper class data for a discovered value."""
+        if not self.configuration_option:
+            raise ValueError("Invalid discovery data template")
+
+        data: dict[str, Any] = {
+            "configuration_value": self._get_value_from_id(
+                value.node, self.configuration_option
+            ),
+        }
+        return data
+
+    def values_to_watch(self, resolved_data: dict[str, Any]) -> Iterable[ZwaveValue]:
+        """Return list of all ZwaveValues that should be watched."""
+        return [
+            resolved_data["configuration_value"],
+        ]
+
+    def get_speed_config(self, resolved_data: dict[str, Any]) -> list[int] | None:
+        """Get current speed configuration from resolved data."""
+        configuration_value: ZwaveValue | None = resolved_data["configuration_value"]
+        if configuration_value:
+            return self.configuration_value_to_speeds.get(configuration_value.value)
+
+        return None

homeassistant/components/zwave_js/fan.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 import math
-from typing import Any
+from typing import Any, cast
 
 from zwave_js_server.client import Client as ZwaveClient
 from zwave_js_server.const import TARGET_VALUE_PROPERTY
@@ -24,11 +24,12 @@ from homeassistant.util.percentage import (
 
 from .const import DATA_CLIENT, DOMAIN
 from .discovery import ZwaveDiscoveryInfo
+from .discovery_data_template import FanSpeedDataTemplate
 from .entity import ZWaveBaseEntity
 
 SUPPORTED_FEATURES = SUPPORT_SET_SPEED
 
-SPEED_RANGE = (1, 99)  # off is not included
+DEFAULT_SPEED_RANGE = (1, 99)  # off is not included
 
 
 async def async_setup_entry(
@@ -43,7 +44,11 @@ async def async_setup_entry(
     def async_add_fan(info: ZwaveDiscoveryInfo) -> None:
         """Add Z-Wave fan."""
         entities: list[ZWaveBaseEntity] = []
+        if info.platform_hint == "configured_fan_speed":
+            entities.append(ConfiguredSpeedRangeZwaveFan(config_entry, client, info))
+        else:
             entities.append(ZwaveFan(config_entry, client, info))
+
         async_add_entities(entities)
 
     config_entry.async_on_unload(
@@ -68,7 +73,9 @@ class ZwaveFan(ZWaveBaseEntity, FanEntity):
         elif percentage == 0:
             zwave_speed = 0
         else:
-            zwave_speed = math.ceil(percentage_to_ranged_value(SPEED_RANGE, percentage))
+            zwave_speed = math.ceil(
+                percentage_to_ranged_value(DEFAULT_SPEED_RANGE, percentage)
+            )
 
         await self.info.node.async_set_value(target_value, zwave_speed)
 
@@ -101,7 +108,9 @@ class ZwaveFan(ZWaveBaseEntity, FanEntity):
         if self.info.primary_value.value is None:
             # guard missing value
             return None
-        return ranged_value_to_percentage(SPEED_RANGE, self.info.primary_value.value)
+        return ranged_value_to_percentage(
+            DEFAULT_SPEED_RANGE, self.info.primary_value.value
+        )
 
     @property
     def percentage_step(self) -> float:
@@ -111,9 +120,90 @@ class ZwaveFan(ZWaveBaseEntity, FanEntity):
     @property
     def speed_count(self) -> int:
         """Return the number of speeds the fan supports."""
-        return int_states_in_range(SPEED_RANGE)
+        return int_states_in_range(DEFAULT_SPEED_RANGE)
 
     @property
     def supported_features(self) -> int:
         """Flag supported features."""
         return SUPPORTED_FEATURES
+
+
+class ConfiguredSpeedRangeZwaveFan(ZwaveFan):
+    """A Zwave fan with a configured speed range (e.g., 1-24 is low)."""
+
+    def __init__(
+        self, config_entry: ConfigEntry, client: ZwaveClient, info: ZwaveDiscoveryInfo
+    ) -> None:
+        """Initialize the fan."""
+        super().__init__(config_entry, client, info)
+        self.data_template = cast(
+            FanSpeedDataTemplate, self.info.platform_data_template
+        )
+
+    async def async_set_percentage(self, percentage: int | None) -> None:
+        """Set the speed percentage of the fan."""
+        target_value = self.get_zwave_value(TARGET_VALUE_PROPERTY)
+
+        # Entity should be unavailable if this isn't set
+        assert self.speed_configuration
+
+        if percentage is None:
+            # Value 255 tells device to return to previous value
+            zwave_speed = 255
+        elif percentage == 0:
+            zwave_speed = 0
+        else:
+            assert percentage >= 0 and percentage <= 100
+            zwave_speed = self.speed_configuration[
+                math.ceil(percentage / self.percentage_step) - 1
+            ]
+
+        await self.info.node.async_set_value(target_value, zwave_speed)
+
+    @property
+    def available(self) -> bool:
+        """Return whether the entity is available."""
+        return super().available and self.speed_configuration is not None
+
+    @property
+    def percentage(self) -> int | None:
+        """Return the current speed percentage."""
+        if self.info.primary_value.value is None:
+            # guard missing value
+            return None
+
+        if self.info.primary_value.value == 0:
+            return 0
+
+        # Entity should be unavailable if this isn't set
+        assert self.speed_configuration
+
+        percentage = 0.0
+        for speed_limit in self.speed_configuration:
+            percentage += self.percentage_step
+            if self.info.primary_value.value <= speed_limit:
+                break
+
+        return int(percentage)
+
+    @property
+    def percentage_step(self) -> float:
+        """Return the step size for percentage."""
+        # This is the same implementation as the base fan type, but
+        # it needs to be overridden here because the ZwaveFan does
+        # something different for fans with unknown speeds.
+        return 100 / self.speed_count
+
+    @property
+    def speed_configuration(self) -> list[int] | None:
+        """Return the speed configuration for this fan."""
+        return self.data_template.get_speed_config(self.info.platform_data)
+
+    @property
+    def speed_count(self) -> int:
+        """Return the number of speeds the fan supports."""
+
+        # Entity should be unavailable if this isn't set
+        assert self.speed_configuration
+
+        return len(self.speed_configuration)

tests/components/zwave_js/conftest.py

@@ -332,6 +332,12 @@ def in_wall_smart_fan_control_state_fixture():
     return json.loads(load_fixture("zwave_js/in_wall_smart_fan_control_state.json"))
 
 
+@pytest.fixture(name="hs_fc200_state", scope="session")
+def hs_fc200_state_fixture():
+    """Load the HS FC200+ node state fixture data."""
+    return json.loads(load_fixture("zwave_js/fan_hs_fc200_state.json"))
+
+
 @pytest.fixture(name="gdc_zw062_state", scope="session")
 def motorized_barrier_cover_state_fixture():
     """Load the motorized barrier cover node state fixture data."""
@@ -697,6 +703,14 @@ def in_wall_smart_fan_control_fixture(client, in_wall_smart_fan_control_state):
     return node
 
 
+@pytest.fixture(name="hs_fc200")
+def hs_fc200_fixture(client, hs_fc200_state):
+    """Mock a fan node."""
+    node = Node(client, copy.deepcopy(hs_fc200_state))
+    client.driver.controller.nodes[node.node_id] = node
+    return node
+
+
 @pytest.fixture(name="null_name_check")
 def null_name_check_fixture(client, null_name_check_state):
     """Mock a node with no name."""

tests/components/zwave_js/test_fan.py

@@ -4,13 +4,14 @@ from zwave_js_server.event import Event
 
 from homeassistant.components.fan import ATTR_SPEED, SPEED_MEDIUM
 
-FAN_ENTITY = "fan.in_wall_smart_fan_control"
+STANDARD_FAN_ENTITY = "fan.in_wall_smart_fan_control"
+HS_FAN_ENTITY = "fan.scene_capable_fan_control_switch"
 
 
-async def test_fan(hass, client, in_wall_smart_fan_control, integration):
+async def test_standard_fan(hass, client, in_wall_smart_fan_control, integration):
     """Test the fan entity."""
     node = in_wall_smart_fan_control
-    state = hass.states.get(FAN_ENTITY)
+    state = hass.states.get(STANDARD_FAN_ENTITY)
 
     assert state
     assert state.state == "off"
@@ -19,7 +20,7 @@ async def test_fan(hass, client, in_wall_smart_fan_control, integration):
     await hass.services.async_call(
         "fan",
         "turn_on",
-        {"entity_id": FAN_ENTITY, "speed": SPEED_MEDIUM},
+        {"entity_id": STANDARD_FAN_ENTITY, "speed": SPEED_MEDIUM},
         blocking=True,
     )
 
@@ -52,7 +53,7 @@ async def test_fan(hass, client, in_wall_smart_fan_control, integration):
         await hass.services.async_call(
             "fan",
             "set_speed",
-            {"entity_id": FAN_ENTITY, "speed": 99},
+            {"entity_id": STANDARD_FAN_ENTITY, "speed": 99},
             blocking=True,
         )
 
@@ -62,7 +63,7 @@ async def test_fan(hass, client, in_wall_smart_fan_control, integration):
     await hass.services.async_call(
         "fan",
         "turn_on",
-        {"entity_id": FAN_ENTITY},
+        {"entity_id": STANDARD_FAN_ENTITY},
         blocking=True,
     )
 
@@ -94,7 +95,7 @@ async def test_fan(hass, client, in_wall_smart_fan_control, integration):
     await hass.services.async_call(
         "fan",
         "turn_off",
-        {"entity_id": FAN_ENTITY},
+        {"entity_id": STANDARD_FAN_ENTITY},
         blocking=True,
     )
 
@@ -142,7 +143,7 @@ async def test_fan(hass, client, in_wall_smart_fan_control, integration):
     )
     node.receive_event(event)
 
-    state = hass.states.get(FAN_ENTITY)
+    state = hass.states.get(STANDARD_FAN_ENTITY)
     assert state.state == "on"
     assert state.attributes[ATTR_SPEED] == "high"
 
@@ -167,6 +168,39 @@ async def test_fan(hass, client, in_wall_smart_fan_control, integration):
     )
     node.receive_event(event)
 
-    state = hass.states.get(FAN_ENTITY)
+    state = hass.states.get(STANDARD_FAN_ENTITY)
     assert state.state == "off"
     assert state.attributes[ATTR_SPEED] == "off"
+
+
+async def test_hs_fan(hass, client, hs_fc200, integration):
+    """Test a fan entity with configurable speeds."""
+
+    async def assert_speed_translation(percentage, zwave_speed, reported_percentage):
+        """Assert that a percentage input is translated to a specific Zwave speed."""
+        await hass.services.async_call(
+            "fan",
+            "turn_on",
+            {"entity_id": HS_FAN_ENTITY, "percentage": percentage},
+            blocking=True,
+        )
+
+        assert len(client.async_send_command.call_args_list) == 1
+        args = client.async_send_command.call_args[0][0]
+        assert args["command"] == "node.set_value"
+        assert args["nodeId"] == 39
+        assert args["value"] == zwave_speed
+
+        client.async_send_command.reset_mock()
+
+    await assert_speed_translation(1, 32)
+    await assert_speed_translation(31, 32)
+    await assert_speed_translation(32, 32)
+    await assert_speed_translation(33, 32)
+    await assert_speed_translation(34, 66)
+    await assert_speed_translation(65, 66)
+    await assert_speed_translation(66, 66)
+    await assert_speed_translation(67, 99)
+    await assert_speed_translation(68, 99)
+    await assert_speed_translation(99, 99)
+    await assert_speed_translation(100, 99)