Add fan entity for air conditioner to Home Connect (#155983)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Joostlek <joostlek@outlook.com>

homeassistant/components/home_connect/__init__.py

@@ -38,6 +38,7 @@ CONFIG_SCHEMA = cv.config_entry_only_config_schema(DOMAIN)
 PLATFORMS = [
     Platform.BINARY_SENSOR,
     Platform.BUTTON,
+    Platform.FAN,
     Platform.LIGHT,
     Platform.NUMBER,
     Platform.SELECT,

homeassistant/components/home_connect/common.py

@@ -19,7 +19,7 @@ from .coordinator import (
     HomeConnectApplianceData,
     HomeConnectConfigEntry,
 )
-from .entity import HomeConnectEntity, HomeConnectOptionEntity
+from .entity import HomeConnectEntity
 
 
 def should_add_option_entity(
@@ -48,7 +48,7 @@ def _create_option_entities(
     known_entity_unique_ids: dict[str, str],
     get_option_entities_for_appliance: Callable[
         [HomeConnectApplianceCoordinator, er.EntityRegistry],
-        list[HomeConnectOptionEntity],
+        list[HomeConnectEntity],
     ],
     async_add_entities: AddConfigEntryEntitiesCallback,
 ) -> None:
@@ -78,7 +78,7 @@ def _handle_paired_or_connected_appliance(
     ],
     get_option_entities_for_appliance: Callable[
         [HomeConnectApplianceCoordinator, er.EntityRegistry],
-        list[HomeConnectOptionEntity],
+        list[HomeConnectEntity],
     ]
     | None,
     changed_options_listener_remove_callbacks: dict[str, list[Callable[[], None]]],
@@ -161,7 +161,7 @@ def setup_home_connect_entry(
     async_add_entities: AddConfigEntryEntitiesCallback,
     get_option_entities_for_appliance: Callable[
         [HomeConnectApplianceCoordinator, er.EntityRegistry],
-        list[HomeConnectOptionEntity],
+        list[HomeConnectEntity],
     ]
     | None = None,
 ) -> None:

homeassistant/components/home_connect/fan.py

@@ -0,0 +1,235 @@
+"""Provides fan entities for Home Connect."""
+
+import contextlib
+import logging
+from typing import cast
+
+from aiohomeconnect.model import EventKey, OptionKey
+from aiohomeconnect.model.error import ActiveProgramNotSetError, HomeConnectError
+
+from homeassistant.components.fan import (
+    FanEntity,
+    FanEntityDescription,
+    FanEntityFeature,
+)
+from homeassistant.core import HomeAssistant, callback
+from homeassistant.exceptions import HomeAssistantError
+from homeassistant.helpers.entity_platform import AddConfigEntryEntitiesCallback
+
+from .common import setup_home_connect_entry
+from .const import DOMAIN
+from .coordinator import HomeConnectApplianceCoordinator, HomeConnectConfigEntry
+from .entity import HomeConnectEntity
+from .utils import get_dict_from_home_connect_error
+
+_LOGGER = logging.getLogger(__name__)
+
+PARALLEL_UPDATES = 1
+
+FAN_SPEED_MODE_OPTIONS = {
+    "auto": "HeatingVentilationAirConditioning.AirConditioner.EnumType.FanSpeedMode.Automatic",
+    "manual": "HeatingVentilationAirConditioning.AirConditioner.EnumType.FanSpeedMode.Manual",
+}
+FAN_SPEED_MODE_OPTIONS_INVERTED = {v: k for k, v in FAN_SPEED_MODE_OPTIONS.items()}
+
+
+AIR_CONDITIONER_ENTITY_DESCRIPTION = FanEntityDescription(
+    key="air_conditioner",
+    translation_key="air_conditioner",
+    name=None,
+)
+
+
+def _get_entities_for_appliance(
+    appliance_coordinator: HomeConnectApplianceCoordinator,
+) -> list[HomeConnectEntity]:
+    """Get a list of entities."""
+    return (
+        [HomeConnectAirConditioningFanEntity(appliance_coordinator)]
+        if appliance_coordinator.data.options
+        and any(
+            option in appliance_coordinator.data.options
+            for option in (
+                OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE,
+                OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE,
+            )
+        )
+        else []
+    )
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    entry: HomeConnectConfigEntry,
+    async_add_entities: AddConfigEntryEntitiesCallback,
+) -> None:
+    """Set up the Home Connect fan entities."""
+    setup_home_connect_entry(
+        hass,
+        entry,
+        _get_entities_for_appliance,
+        async_add_entities,
+        lambda appliance_coordinator, _: _get_entities_for_appliance(
+            appliance_coordinator
+        ),
+    )
+
+
+class HomeConnectAirConditioningFanEntity(HomeConnectEntity, FanEntity):
+    """Representation of a Home Connect fan entity."""
+
+    def __init__(
+        self,
+        coordinator: HomeConnectApplianceCoordinator,
+    ) -> None:
+        """Initialize the entity."""
+        self._attr_preset_modes = list(FAN_SPEED_MODE_OPTIONS.keys())
+        self._original_speed_modes_keys = set(FAN_SPEED_MODE_OPTIONS_INVERTED)
+        super().__init__(
+            coordinator,
+            AIR_CONDITIONER_ENTITY_DESCRIPTION,
+            context_override=(
+                EventKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE
+            ),
+        )
+        self.update_preset_mode()
+
+    @callback
+    def _handle_coordinator_update_preset_mode(self) -> None:
+        """Handle updated data from the coordinator."""
+        self.update_preset_mode()
+        self.async_write_ha_state()
+        _LOGGER.debug(
+            "Updated %s (fan mode), new state: %s", self.entity_id, self.preset_mode
+        )
+
+    async def async_added_to_hass(self) -> None:
+        """When entity is added to hass."""
+        await super().async_added_to_hass()
+        self.async_on_remove(
+            self.coordinator.async_add_listener(
+                self._handle_coordinator_update_preset_mode,
+                EventKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE,
+            )
+        )
+
+    def update_native_value(self) -> None:
+        """Set the speed percentage and speed mode values."""
+        option_value = None
+        option_key = OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE
+        if event := self.appliance.events.get(EventKey(option_key)):
+            option_value = event.value
+        self._attr_percentage = (
+            cast(int, option_value) if option_value is not None else None
+        )
+
+    @property
+    def supported_features(self) -> FanEntityFeature:
+        """Return the supported features for this fan entity."""
+        features = FanEntityFeature(0)
+        if (
+            OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE
+            in self.appliance.options
+        ):
+            features |= FanEntityFeature.SET_SPEED
+        if (
+            OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE
+            in self.appliance.options
+        ):
+            features |= FanEntityFeature.PRESET_MODE
+        return features
+
+    def update_preset_mode(self) -> None:
+        """Set the preset mode value."""
+        option_value = None
+        option_key = OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE
+        if event := self.appliance.events.get(EventKey(option_key)):
+            option_value = event.value
+        self._attr_preset_mode = (
+            FAN_SPEED_MODE_OPTIONS_INVERTED.get(cast(str, option_value))
+            if option_value is not None
+            else None
+        )
+        if (
+            (
+                option_definition := self.appliance.options.get(
+                    OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE
+                )
+            )
+            and (option_constraints := option_definition.constraints)
+            and option_constraints.allowed_values
+            and (
+                allowed_values_without_none := {
+                    value
+                    for value in option_constraints.allowed_values
+                    if value is not None
+                }
+            )
+            and self._original_speed_modes_keys != allowed_values_without_none
+        ):
+            self._original_speed_modes_keys = allowed_values_without_none
+            self._attr_preset_modes = [
+                key
+                for key, value in FAN_SPEED_MODE_OPTIONS.items()
+                if value in self._original_speed_modes_keys
+            ]
+
+    async def async_set_percentage(self, percentage: int) -> None:
+        """Set the speed of the fan, as a percentage."""
+        await self._async_set_option(
+            OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE,
+            percentage,
+        )
+        _LOGGER.debug(
+            "Updated %s's speed percentage option, new state: %s",
+            self.entity_id,
+            percentage,
+        )
+
+    async def async_set_preset_mode(self, preset_mode: str) -> None:
+        """Set new target fan mode."""
+        await self._async_set_option(
+            OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE,
+            FAN_SPEED_MODE_OPTIONS[preset_mode],
+        )
+        _LOGGER.debug(
+            "Updated %s's speed mode option, new state: %s",
+            self.entity_id,
+            self.state,
+        )
+
+    async def _async_set_option(self, key: OptionKey, value: str | int) -> None:
+        """Set an option for the entity."""
+        try:
+            # We try to set the active program option first,
+            # if it fails we try to set the selected program option
+            with contextlib.suppress(ActiveProgramNotSetError):
+                await self.coordinator.client.set_active_program_option(
+                    self.appliance.info.ha_id,
+                    option_key=key,
+                    value=value,
+                )
+                return
+
+            await self.coordinator.client.set_selected_program_option(
+                self.appliance.info.ha_id,
+                option_key=key,
+                value=value,
+            )
+        except HomeConnectError as err:
+            raise HomeAssistantError(
+                translation_domain=DOMAIN,
+                translation_key="set_option",
+                translation_placeholders=get_dict_from_home_connect_error(err),
+            ) from err
+
+    @property
+    def available(self) -> bool:
+        """Return True if entity is available."""
+        return super().available and any(
+            option in self.appliance.options
+            for option in (
+                OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE,
+                OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE,
+            )
+        )

homeassistant/components/home_connect/number.py

@@ -136,7 +136,7 @@ def _get_entities_for_appliance(
 def _get_option_entities_for_appliance(
     appliance_coordinator: HomeConnectApplianceCoordinator,
     entity_registry: er.EntityRegistry,
-) -> list[HomeConnectOptionEntity]:
+) -> list[HomeConnectEntity]:
     """Get a list of currently available option entities."""
     return [
         HomeConnectOptionNumberEntity(appliance_coordinator, description)

homeassistant/components/home_connect/select.py

@@ -355,7 +355,7 @@ def _get_entities_for_appliance(
 def _get_option_entities_for_appliance(
     appliance_coordinator: HomeConnectApplianceCoordinator,
     entity_registry: er.EntityRegistry,
-) -> list[HomeConnectOptionEntity]:
+) -> list[HomeConnectEntity]:
     """Get a list of entities."""
     return [
         HomeConnectSelectOptionEntity(appliance_coordinator, desc)

homeassistant/components/home_connect/strings.json

@@ -119,6 +119,18 @@
         "name": "Stop program"
       }
     },
+    "fan": {
+      "air_conditioner": {
+        "state_attributes": {
+          "preset_mode": {
+            "state": {
+              "auto": "[%key:common::state::auto%]",
+              "manual": "[%key:common::state::manual%]"
+            }
+          }
+        }
+      }
+    },
     "light": {
       "ambient_light": {
         "name": "Ambient light"

homeassistant/components/home_connect/switch.py

@@ -189,7 +189,7 @@ def _get_entities_for_appliance(
 def _get_option_entities_for_appliance(
     appliance_coordinator: HomeConnectApplianceCoordinator,
     entity_registry: er.EntityRegistry,
-) -> list[HomeConnectOptionEntity]:
+) -> list[HomeConnectEntity]:
     """Get a list of currently available option entities."""
     return [
         HomeConnectSwitchOptionEntity(appliance_coordinator, description)

tests/components/home_connect/conftest.py

@@ -241,8 +241,6 @@ def _get_set_setting_side_effect(
 def _get_set_program_options_side_effect(
     event_queue: asyncio.Queue[list[EventMessage | Exception]],
 ):
-    """Set programs side effect."""
-
     async def set_program_options_side_effect(ha_id: str, *_, **kwargs) -> None:
         await event_queue.put(
             [
@@ -289,25 +287,9 @@ def _get_specific_appliance_side_effect(
     pytest.fail(f"Mock didn't include appliance with id {ha_id}")
 
 
-@pytest.fixture(name="client")
+def _get_set_program_option_side_effect(
-def mock_client(
+    event_queue: asyncio.Queue[list[EventMessage]],
-    appliances: list[HomeAppliance],
+):
-    appliance: HomeAppliance | None,
-    request: pytest.FixtureRequest,
-) -> MagicMock:
-    """Fixture to mock Client from HomeConnect."""
-
-    mock = MagicMock(
-        autospec=HomeConnectClient,
-    )
-
-    event_queue: asyncio.Queue[list[EventMessage | Exception]] = asyncio.Queue()
-
-    async def add_events(events: list[EventMessage | Exception]) -> None:
-        await event_queue.put(events)
-
-    mock.add_events = add_events
-
     async def set_program_option_side_effect(ha_id: str, *_, **kwargs) -> None:
         event_key = EventKey(kwargs["option_key"])
         await event_queue.put(
@@ -331,6 +313,28 @@ def mock_client(
             ]
         )
 
+    return set_program_option_side_effect
+
+
+@pytest.fixture(name="client")
+def mock_client(
+    appliances: list[HomeAppliance],
+    appliance: HomeAppliance | None,
+    request: pytest.FixtureRequest,
+) -> MagicMock:
+    """Fixture to mock Client from HomeConnect."""
+
+    mock = MagicMock(
+        autospec=HomeConnectClient,
+    )
+
+    event_queue: asyncio.Queue[list[EventMessage | Exception]] = asyncio.Queue()
+
+    async def add_events(events: list[EventMessage | Exception]) -> None:
+        await event_queue.put(events)
+
+    mock.add_events = add_events
+
     appliances = [appliance] if appliance else appliances
 
     async def stream_all_events() -> AsyncGenerator[EventMessage]:
@@ -408,15 +412,9 @@ def mock_client(
         ),
     )
     mock.stop_program = AsyncMock()
-    mock.set_active_program_option = AsyncMock(
-        side_effect=_get_set_program_options_side_effect(event_queue),
-    )
     mock.set_active_program_options = AsyncMock(
         side_effect=_get_set_program_options_side_effect(event_queue),
     )
-    mock.set_selected_program_option = AsyncMock(
-        side_effect=_get_set_program_options_side_effect(event_queue),
-    )
     mock.set_selected_program_options = AsyncMock(
         side_effect=_get_set_program_options_side_effect(event_queue),
     )
@@ -437,10 +435,10 @@ def mock_client(
     mock.get_active_program_options = AsyncMock(return_value=ArrayOfOptions([]))
     mock.get_selected_program_options = AsyncMock(return_value=ArrayOfOptions([]))
     mock.set_active_program_option = AsyncMock(
-        side_effect=set_program_option_side_effect
+        side_effect=_get_set_program_option_side_effect(event_queue)
     )
     mock.set_selected_program_option = AsyncMock(
-        side_effect=set_program_option_side_effect
+        side_effect=_get_set_program_option_side_effect(event_queue)
     )
 
     mock.side_effect = mock

tests/components/home_connect/fixtures/appliances.json

@@ -109,7 +109,7 @@
       "haId": "123456789012345678"
     },
     {
-      "name": "AirConditioner",
+      "name": "Air conditioner",
       "brand": "BOSCH",
       "vib": "HCS000006",
       "connected": true,

tests/components/home_connect/snapshots/test_diagnostics.ambr

@@ -66,7 +66,7 @@
       'connected': True,
       'e_number': 'HCS000000/07',
       'ha_id': '8765432109876543210',
-      'name': 'AirConditioner',
+      'name': 'Air conditioner',
       'programs': list([
         'HeatingVentilationAirConditioning.AirConditioner.Program.ActiveClean',
         'HeatingVentilationAirConditioning.AirConditioner.Program.Auto',

tests/components/home_connect/test_fan.py

@@ -0,0 +1,665 @@
+"""Tests for home_connect fan entities."""
+
+from collections.abc import Awaitable, Callable
+from unittest.mock import AsyncMock, MagicMock
+
+from aiohomeconnect.model import (
+    ArrayOfEvents,
+    Event,
+    EventKey,
+    EventMessage,
+    EventType,
+    HomeAppliance,
+    OptionKey,
+    ProgramDefinition,
+    ProgramKey,
+)
+from aiohomeconnect.model.error import (
+    ActiveProgramNotSetError,
+    HomeConnectApiError,
+    HomeConnectError,
+    SelectedProgramNotSetError,
+)
+from aiohomeconnect.model.program import (
+    ProgramDefinitionConstraints,
+    ProgramDefinitionOption,
+)
+import pytest
+
+from homeassistant.components.fan import (
+    ATTR_PERCENTAGE,
+    ATTR_PRESET_MODE,
+    ATTR_PRESET_MODES,
+    DOMAIN as FAN_DOMAIN,
+    SERVICE_SET_PERCENTAGE,
+    SERVICE_SET_PRESET_MODE,
+    FanEntityFeature,
+)
+from homeassistant.components.home_connect.const import DOMAIN
+from homeassistant.config_entries import ConfigEntryState
+from homeassistant.const import (
+    ATTR_ENTITY_ID,
+    ATTR_SUPPORTED_FEATURES,
+    STATE_UNAVAILABLE,
+    Platform,
+)
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import HomeAssistantError
+from homeassistant.helpers import device_registry as dr, entity_registry as er
+
+from tests.common import MockConfigEntry
+
+
+@pytest.fixture
+def platforms() -> list[str]:
+    """Fixture to specify platforms to test."""
+    return [Platform.FAN]
+
+
+@pytest.fixture(autouse=True)
+def get_available_program_fixture(
+    client: MagicMock,
+) -> None:
+    """Mock get_available_program."""
+    client.get_available_program = AsyncMock(
+        return_value=ProgramDefinition(
+            ProgramKey.UNKNOWN,
+            options=[
+                ProgramDefinitionOption(
+                    OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE,
+                    "Enumeration",
+                ),
+                ProgramDefinitionOption(
+                    OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE,
+                    "Enumeration",
+                ),
+            ],
+        )
+    )
+
+
+@pytest.mark.parametrize("appliance", ["AirConditioner"], indirect=True)
+async def test_paired_depaired_devices_flow(
+    hass: HomeAssistant,
+    device_registry: dr.DeviceRegistry,
+    entity_registry: er.EntityRegistry,
+    client: MagicMock,
+    config_entry: MockConfigEntry,
+    integration_setup: Callable[[MagicMock], Awaitable[bool]],
+    appliance: HomeAppliance,
+) -> None:
+    """Test that removed devices are correctly removed from and added to hass on API events."""
+    assert await integration_setup(client)
+    assert config_entry.state is ConfigEntryState.LOADED
+
+    device = device_registry.async_get_device(identifiers={(DOMAIN, appliance.ha_id)})
+    assert device
+    entity_entries = entity_registry.entities.get_entries_for_device_id(device.id)
+    assert entity_entries
+
+    await client.add_events(
+        [
+            EventMessage(
+                appliance.ha_id,
+                EventType.DEPAIRED,
+                data=ArrayOfEvents([]),
+            )
+        ]
+    )
+    await hass.async_block_till_done()
+
+    device = device_registry.async_get_device(identifiers={(DOMAIN, appliance.ha_id)})
+    assert not device
+    for entity_entry in entity_entries:
+        assert not entity_registry.async_get(entity_entry.entity_id)
+
+    # Now that everything related to the device is removed, pair it again
+    await client.add_events(
+        [
+            EventMessage(
+                appliance.ha_id,
+                EventType.PAIRED,
+                data=ArrayOfEvents([]),
+            )
+        ]
+    )
+    await hass.async_block_till_done()
+
+    assert device_registry.async_get_device(identifiers={(DOMAIN, appliance.ha_id)})
+    for entity_entry in entity_entries:
+        assert entity_registry.async_get(entity_entry.entity_id)
+
+
+@pytest.mark.parametrize("appliance", ["AirConditioner"], indirect=True)
+async def test_connected_devices(
+    hass: HomeAssistant,
+    device_registry: dr.DeviceRegistry,
+    entity_registry: er.EntityRegistry,
+    client: MagicMock,
+    config_entry: MockConfigEntry,
+    integration_setup: Callable[[MagicMock], Awaitable[bool]],
+    appliance: HomeAppliance,
+) -> None:
+    """Test that devices reconnect.
+
+    Specifically those devices whose settings, status, etc. could
+    not be obtained while disconnected and once connected, the entities are added.
+    """
+    get_settings_original_mock = client.get_settings
+    get_all_programs_mock = client.get_all_programs
+
+    async def get_settings_side_effect(ha_id: str):
+        if ha_id == appliance.ha_id:
+            raise HomeConnectApiError(
+                "SDK.Error.HomeAppliance.Connection.Initialization.Failed"
+            )
+        return await get_settings_original_mock.side_effect(ha_id)
+
+    async def get_all_programs_side_effect(ha_id: str):
+        if ha_id == appliance.ha_id:
+            raise HomeConnectApiError(
+                "SDK.Error.HomeAppliance.Connection.Initialization.Failed"
+            )
+        return await get_all_programs_mock.side_effect(ha_id)
+
+    client.get_settings = AsyncMock(side_effect=get_settings_side_effect)
+    client.get_all_programs = AsyncMock(side_effect=get_all_programs_side_effect)
+
+    assert await integration_setup(client)
+    assert config_entry.state is ConfigEntryState.LOADED
+    client.get_settings = get_settings_original_mock
+    client.get_all_programs = get_all_programs_mock
+
+    device = device_registry.async_get_device(identifiers={(DOMAIN, appliance.ha_id)})
+    assert device
+    assert not entity_registry.async_get_entity_id(
+        Platform.FAN,
+        DOMAIN,
+        f"{appliance.ha_id}-air_conditioner",
+    )
+
+    await client.add_events(
+        [
+            EventMessage(
+                appliance.ha_id,
+                EventType.CONNECTED,
+                data=ArrayOfEvents([]),
+            )
+        ]
+    )
+    await hass.async_block_till_done()
+
+    assert entity_registry.async_get_entity_id(
+        Platform.FAN,
+        DOMAIN,
+        f"{appliance.ha_id}-air_conditioner",
+    )
+
+
+@pytest.mark.parametrize("appliance", ["AirConditioner"], indirect=True)
+async def test_fan_entity_availability(
+    hass: HomeAssistant,
+    client: MagicMock,
+    config_entry: MockConfigEntry,
+    integration_setup: Callable[[MagicMock], Awaitable[bool]],
+    appliance: HomeAppliance,
+) -> None:
+    """Test if fan entities availability are based on the appliance connection state."""
+    entity_ids = [
+        "fan.air_conditioner",
+    ]
+    assert await integration_setup(client)
+    assert config_entry.state is ConfigEntryState.LOADED
+
+    for entity_id in entity_ids:
+        state = hass.states.get(entity_id)
+        assert state
+        assert state.state != STATE_UNAVAILABLE
+
+    await client.add_events(
+        [
+            EventMessage(
+                appliance.ha_id,
+                EventType.DISCONNECTED,
+                ArrayOfEvents([]),
+            )
+        ]
+    )
+    await hass.async_block_till_done()
+
+    for entity_id in entity_ids:
+        assert hass.states.is_state(entity_id, STATE_UNAVAILABLE)
+
+    await client.add_events(
+        [
+            EventMessage(
+                appliance.ha_id,
+                EventType.CONNECTED,
+                ArrayOfEvents([]),
+            )
+        ]
+    )
+    await hass.async_block_till_done()
+
+    for entity_id in entity_ids:
+        state = hass.states.get(entity_id)
+        assert state
+        assert state.state != STATE_UNAVAILABLE
+
+
+@pytest.mark.parametrize("appliance", ["AirConditioner"], indirect=True)
+@pytest.mark.parametrize(
+    (
+        "set_active_program_options_side_effect",
+        "set_selected_program_options_side_effect",
+        "called_mock_method",
+    ),
+    [
+        (
+            None,
+            SelectedProgramNotSetError("error.key"),
+            "set_active_program_option",
+        ),
+        (
+            ActiveProgramNotSetError("error.key"),
+            None,
+            "set_selected_program_option",
+        ),
+    ],
+)
+async def test_speed_percentage_functionality(
+    hass: HomeAssistant,
+    client: MagicMock,
+    config_entry: MockConfigEntry,
+    integration_setup: Callable[[MagicMock], Awaitable[bool]],
+    appliance: HomeAppliance,
+    set_active_program_options_side_effect: ActiveProgramNotSetError | None,
+    set_selected_program_options_side_effect: SelectedProgramNotSetError | None,
+    called_mock_method: str,
+) -> None:
+    """Test speed percentage functionality."""
+    entity_id = "fan.air_conditioner"
+    option_key = OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE
+    if set_active_program_options_side_effect:
+        client.set_active_program_option.side_effect = (
+            set_active_program_options_side_effect
+        )
+    else:
+        assert set_selected_program_options_side_effect
+        client.set_selected_program_option.side_effect = (
+            set_selected_program_options_side_effect
+        )
+    called_mock: AsyncMock = getattr(client, called_mock_method)
+
+    assert await integration_setup(client)
+    assert config_entry.state is ConfigEntryState.LOADED
+    assert not hass.states.is_state(entity_id, "50")
+
+    await hass.services.async_call(
+        FAN_DOMAIN,
+        SERVICE_SET_PERCENTAGE,
+        {
+            ATTR_ENTITY_ID: entity_id,
+            ATTR_PERCENTAGE: 50,
+        },
+        blocking=True,
+    )
+    await hass.async_block_till_done()
+
+    called_mock.assert_called_once_with(
+        appliance.ha_id,
+        option_key=option_key,
+        value=50,
+    )
+    entity_state = hass.states.get(entity_id)
+    assert entity_state
+    assert entity_state.attributes[ATTR_PERCENTAGE] == 50
+
+
+async def test_set_speed_raises_home_assistant_error_on_api_errors(
+    hass: HomeAssistant,
+    client: MagicMock,
+    config_entry: MockConfigEntry,
+    integration_setup: Callable[[MagicMock], Awaitable[bool]],
+) -> None:
+    """Test that setting a fan mode raises HomeAssistantError on API errors."""
+    assert await integration_setup(client)
+    assert config_entry.state is ConfigEntryState.LOADED
+
+    client.set_active_program_option.side_effect = HomeConnectError("Test error")
+    with pytest.raises(HomeAssistantError, match="Test error"):
+        await hass.services.async_call(
+            FAN_DOMAIN,
+            SERVICE_SET_PERCENTAGE,
+            {
+                ATTR_ENTITY_ID: "fan.air_conditioner",
+                ATTR_PERCENTAGE: 50,
+            },
+            blocking=True,
+        )
+
+
+@pytest.mark.parametrize("appliance", ["AirConditioner"], indirect=True)
+@pytest.mark.parametrize(
+    (
+        "set_active_program_options_side_effect",
+        "set_selected_program_options_side_effect",
+        "called_mock_method",
+    ),
+    [
+        (
+            None,
+            SelectedProgramNotSetError("error.key"),
+            "set_active_program_option",
+        ),
+        (
+            ActiveProgramNotSetError("error.key"),
+            None,
+            "set_selected_program_option",
+        ),
+    ],
+)
+@pytest.mark.parametrize(
+    ("allowed_values", "expected_fan_modes"),
+    [
+        (
+            None,
+            ["auto", "manual"],
+        ),
+        (
+            [
+                "HeatingVentilationAirConditioning.AirConditioner.EnumType.FanSpeedMode.Automatic",
+                "HeatingVentilationAirConditioning.AirConditioner.EnumType.FanSpeedMode.Manual",
+            ],
+            ["auto", "manual"],
+        ),
+        (
+            [
+                "HeatingVentilationAirConditioning.AirConditioner.EnumType.FanSpeedMode.Automatic",
+            ],
+            ["auto"],
+        ),
+        (
+            [
+                "HeatingVentilationAirConditioning.AirConditioner.EnumType.FanSpeedMode.Manual",
+                "A.Non.Documented.Option",
+            ],
+            ["manual"],
+        ),
+    ],
+)
+async def test_preset_mode_functionality(
+    hass: HomeAssistant,
+    client: MagicMock,
+    config_entry: MockConfigEntry,
+    integration_setup: Callable[[MagicMock], Awaitable[bool]],
+    appliance: HomeAppliance,
+    allowed_values: list[str | None] | None,
+    expected_fan_modes: list[str],
+    set_active_program_options_side_effect: ActiveProgramNotSetError | None,
+    set_selected_program_options_side_effect: SelectedProgramNotSetError | None,
+    called_mock_method: str,
+) -> None:
+    """Test preset mode functionality."""
+    entity_id = "fan.air_conditioner"
+    option_key = (
+        OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE
+    )
+    if set_active_program_options_side_effect:
+        client.set_active_program_option.side_effect = (
+            set_active_program_options_side_effect
+        )
+    else:
+        assert set_selected_program_options_side_effect
+        client.set_selected_program_option.side_effect = (
+            set_selected_program_options_side_effect
+        )
+    called_mock: AsyncMock = getattr(client, called_mock_method)
+    client.get_available_program = AsyncMock(
+        return_value=ProgramDefinition(
+            ProgramKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_AUTO,
+            options=[
+                ProgramDefinitionOption(
+                    OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE,
+                    "Enumeration",
+                    constraints=ProgramDefinitionConstraints(
+                        allowed_values=allowed_values
+                    ),
+                )
+            ],
+        )
+    )
+
+    assert await integration_setup(client)
+    assert config_entry.state is ConfigEntryState.LOADED
+    entity_state = hass.states.get(entity_id)
+    assert entity_state
+    assert entity_state.attributes[ATTR_PRESET_MODES] == expected_fan_modes
+    assert entity_state.attributes[ATTR_PRESET_MODE] != expected_fan_modes[0]
+
+    await hass.services.async_call(
+        FAN_DOMAIN,
+        SERVICE_SET_PRESET_MODE,
+        {
+            ATTR_ENTITY_ID: entity_id,
+            ATTR_PRESET_MODE: expected_fan_modes[0],
+        },
+        blocking=True,
+    )
+    await hass.async_block_till_done()
+
+    called_mock.assert_called_once_with(
+        appliance.ha_id,
+        option_key=option_key,
+        value=allowed_values[0]
+        if allowed_values
+        else "HeatingVentilationAirConditioning.AirConditioner.EnumType.FanSpeedMode.Automatic",
+    )
+    entity_state = hass.states.get(entity_id)
+    assert entity_state
+    assert entity_state.attributes[ATTR_PRESET_MODE] == expected_fan_modes[0]
+
+
+async def test_set_preset_mode_raises_home_assistant_error_on_api_errors(
+    hass: HomeAssistant,
+    client: MagicMock,
+    config_entry: MockConfigEntry,
+    integration_setup: Callable[[MagicMock], Awaitable[bool]],
+) -> None:
+    """Test that setting a fan mode raises HomeAssistantError on API errors."""
+    assert await integration_setup(client)
+    assert config_entry.state is ConfigEntryState.LOADED
+
+    client.set_active_program_option.side_effect = HomeConnectError("Test error")
+    with pytest.raises(HomeAssistantError, match="Test error"):
+        await hass.services.async_call(
+            FAN_DOMAIN,
+            SERVICE_SET_PRESET_MODE,
+            {
+                ATTR_ENTITY_ID: "fan.air_conditioner",
+                ATTR_PRESET_MODE: "auto",
+            },
+            blocking=True,
+        )
+
+
+@pytest.mark.parametrize("appliance", ["AirConditioner"], indirect=True)
+@pytest.mark.parametrize(
+    ("option_key", "expected_fan_feature"),
+    [
+        (
+            OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE,
+            FanEntityFeature.PRESET_MODE,
+        ),
+        (
+            OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE,
+            FanEntityFeature.SET_SPEED,
+        ),
+    ],
+)
+async def test_supported_features(
+    hass: HomeAssistant,
+    client: MagicMock,
+    config_entry: MockConfigEntry,
+    integration_setup: Callable[[MagicMock], Awaitable[bool]],
+    appliance: HomeAppliance,
+    option_key: OptionKey,
+    expected_fan_feature: FanEntityFeature,
+) -> None:
+    """Test that supported features are detected correctly."""
+    client.get_available_program = AsyncMock(
+        return_value=ProgramDefinition(
+            ProgramKey.UNKNOWN,
+            options=[
+                ProgramDefinitionOption(
+                    option_key,
+                    "Enumeration",
+                )
+            ],
+        )
+    )
+
+    assert await integration_setup(client)
+    assert config_entry.state is ConfigEntryState.LOADED
+
+    entity_id = "fan.air_conditioner"
+    state = hass.states.get(entity_id)
+    assert state
+
+    assert state.attributes[ATTR_SUPPORTED_FEATURES] & expected_fan_feature
+
+    client.get_available_program = AsyncMock(
+        return_value=ProgramDefinition(
+            ProgramKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_AUTO,
+            options=[],
+        )
+    )
+    await client.add_events(
+        [
+            EventMessage(
+                appliance.ha_id,
+                EventType.NOTIFY,
+                data=ArrayOfEvents(
+                    [
+                        Event(
+                            key=EventKey.BSH_COMMON_ROOT_ACTIVE_PROGRAM,
+                            raw_key=EventKey.BSH_COMMON_ROOT_ACTIVE_PROGRAM.value,
+                            timestamp=0,
+                            level="",
+                            handling="",
+                            value=ProgramKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_AUTO,
+                        )
+                    ]
+                ),
+            )
+        ]
+    )
+    await hass.async_block_till_done()
+
+    state = hass.states.get(entity_id)
+    assert state
+    assert not state.attributes[ATTR_SUPPORTED_FEATURES] & expected_fan_feature
+
+    client.get_available_program = AsyncMock(
+        return_value=ProgramDefinition(
+            ProgramKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_AUTO,
+            options=[
+                ProgramDefinitionOption(
+                    option_key,
+                    "Enumeration",
+                )
+            ],
+        )
+    )
+    await client.add_events(
+        [
+            EventMessage(
+                appliance.ha_id,
+                EventType.NOTIFY,
+                data=ArrayOfEvents(
+                    [
+                        Event(
+                            key=EventKey.BSH_COMMON_ROOT_ACTIVE_PROGRAM,
+                            raw_key=EventKey.BSH_COMMON_ROOT_ACTIVE_PROGRAM.value,
+                            timestamp=0,
+                            level="",
+                            handling="",
+                            value=ProgramKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_AUTO.value,
+                        )
+                    ]
+                ),
+            )
+        ]
+    )
+    await hass.async_block_till_done()
+
+    state = hass.states.get(entity_id)
+    assert state
+    assert state.attributes[ATTR_SUPPORTED_FEATURES] & expected_fan_feature
+
+
+@pytest.mark.parametrize("appliance", ["AirConditioner"], indirect=True)
+async def test_added_entity_automatically(
+    hass: HomeAssistant,
+    client: MagicMock,
+    config_entry: MockConfigEntry,
+    integration_setup: Callable[[MagicMock], Awaitable[bool]],
+    appliance: HomeAppliance,
+) -> None:
+    """Test that no fan entity is created if no fan options are available but when they are added later, the entity is created."""
+    entity_id = "fan.air_conditioner"
+    client.get_available_program = AsyncMock(
+        return_value=ProgramDefinition(
+            ProgramKey.UNKNOWN,
+            options=[
+                ProgramDefinitionOption(
+                    OptionKey.LAUNDRY_CARE_WASHER_SPIN_SPEED,
+                    "Enumeration",
+                )
+            ],
+        )
+    )
+
+    assert await integration_setup(client)
+    assert config_entry.state is ConfigEntryState.LOADED
+
+    assert not hass.states.get(entity_id)
+
+    client.get_available_program = AsyncMock(
+        return_value=ProgramDefinition(
+            ProgramKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_AUTO,
+            options=[
+                ProgramDefinitionOption(
+                    OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_MODE,
+                    "Enumeration",
+                ),
+                ProgramDefinitionOption(
+                    OptionKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_FAN_SPEED_PERCENTAGE,
+                    "Enumeration",
+                ),
+            ],
+        )
+    )
+    await client.add_events(
+        [
+            EventMessage(
+                appliance.ha_id,
+                EventType.NOTIFY,
+                data=ArrayOfEvents(
+                    [
+                        Event(
+                            key=EventKey.BSH_COMMON_ROOT_ACTIVE_PROGRAM,
+                            raw_key=EventKey.BSH_COMMON_ROOT_ACTIVE_PROGRAM.value,
+                            timestamp=0,
+                            level="",
+                            handling="",
+                            value=ProgramKey.HEATING_VENTILATION_AIR_CONDITIONING_AIR_CONDITIONER_AUTO.value,
+                        )
+                    ]
+                ),
+            )
+        ]
+    )
+    await hass.async_block_till_done()
+
+    assert hass.states.get(entity_id)