Add Fresh Air (ventilation) fan entity

Exposes the Fresh Air function for AC devices that advertise it, as a single
fan entity:
- fan.py: MideaFreshAirFan. The library exposes a single fresh_air_fan_speed
  (OFF/Low/Medium/High/Boost), so the fan derives on/off from the OFF value
  and uses speed_count with the ordered-list percentage helpers to map the
  fixed speeds to/from the HA fan percentage (no manual snapping).
- Registers the fan platform in __init__.py.
- en.json translation and a test (test_fan.py).

Gated on supports_fresh_air, so devices without the capability show nothing.

Requires msmart-ng with Fresh Air support (mill1000/midea-msmart#268, now
merged); the test skips until it is available in a release, and the manifest
requirement should be bumped to it.

Author: NotixOfficial

custom_components/midea_ac/__init__.py

@@ -30,6 +30,7 @@
     Platform.BINARY_SENSOR,
     Platform.BUTTON,
     Platform.CLIMATE,
+    Platform.FAN,
     Platform.NUMBER,
     Platform.SELECT,
     Platform.SENSOR,

custom_components/midea_ac/fan.py

@@ -0,0 +1,140 @@
+"""Fan platform for Midea Smart AC."""
+from __future__ import annotations
+
+import logging
+from typing import Any, Optional
+
+from homeassistant.components.fan import FanEntity, FanEntityFeature
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from homeassistant.util.percentage import (ordered_list_item_to_percentage,
+                                           percentage_to_ordered_list_item)
+
+from .const import DOMAIN
+from .coordinator import MideaCoordinatorEntity, MideaDeviceUpdateCoordinator
+
+_LOGGER = logging.getLogger(__name__)
+
+
+async def async_setup_entry(
+    hass: HomeAssistant,
+    config_entry: ConfigEntry,
+    add_entities: AddEntitiesCallback,
+) -> None:
+    """Setup the fan platform for Midea Smart AC."""
+
+    _LOGGER.info("Setting up fan platform.")
+
+    # Fetch coordinator from global data
+    coordinator = hass.data[DOMAIN][config_entry.entry_id]
+    device = coordinator.device
+
+    # Create fans for supported features
+    entities = []
+    if hasattr(device, "fresh_air_fan_speed") and getattr(device, "supports_fresh_air", False):
+        entities.append(MideaFreshAirFan(coordinator))
+
+    add_entities(entities)
+
+
+class MideaFreshAirFan(MideaCoordinatorEntity, FanEntity):
+    """Fresh air (ventilation) fan for Midea AC."""
+
+    _attr_translation_key = "fresh_air"
+    _enable_turn_on_off_backwards_compatibility = False
+
+    def __init__(self, coordinator: MideaDeviceUpdateCoordinator) -> None:
+        MideaCoordinatorEntity.__init__(self, coordinator)
+
+        self._enum_class = self._device.FreshAirFanSpeed
+        self._off = self._enum_class.OFF
+
+        # Ordered list of selectable (non-off) speed levels, ascending
+        self._speeds = [s for s in self._enum_class.list() if s != self._off]
+
+        self._supported_features = FanEntityFeature.SET_SPEED
+
+        # Attempt to add new TURN_OFF/TURN_ON features in HA 2024.8
+        try:
+            self._supported_features |= FanEntityFeature.TURN_OFF
+            self._supported_features |= FanEntityFeature.TURN_ON
+        except AttributeError:
+            pass
+
+    @property
+    def device_info(self) -> dict:
+        """Return info for device registry."""
+        return {
+            "identifiers": {
+                (DOMAIN, self._device.id)
+            },
+        }
+
+    @property
+    def has_entity_name(self) -> bool:
+        """Indicates if entity follows naming conventions."""
+        return True
+
+    @property
+    def unique_id(self) -> str:
+        """Return the unique ID of this entity."""
+        return f"{self._device.id}-fresh_air"
+
+    @property
+    def supported_features(self) -> FanEntityFeature:
+        """Return the supported features."""
+        return self._supported_features
+
+    @property
+    def available(self) -> bool:
+        """Check device availability."""
+        return super().available and self._device.power_state
+
+    @property
+    def is_on(self) -> bool:
+        """Return whether fresh air is on."""
+        return self._device.fresh_air_fan_speed != self._off
+
+    @property
+    def speed_count(self) -> int:
+        """Return the number of speeds the fan supports."""
+        return len(self._speeds)
+
+    @property
+    def percentage(self) -> int:
+        """Return the current speed as a percentage."""
+        speed = self._device.fresh_air_fan_speed
+        if speed == self._off:
+            return 0
+
+        return ordered_list_item_to_percentage(self._speeds, speed)
+
+    async def async_set_percentage(self, percentage: int) -> None:
+        """Set the speed of the fan, as a percentage."""
+        if percentage <= 0:
+            self._device.fresh_air_fan_speed = self._off
+        else:
+            self._device.fresh_air_fan_speed = percentage_to_ordered_list_item(
+                self._speeds, percentage)
+
+        await self.coordinator.apply()
+
+    async def async_turn_on(self,
+                            percentage: Optional[int] = None,
+                            preset_mode: Optional[str] = None,
+                            **kwargs: Any) -> None:
+        """Turn the fan on."""
+        if percentage is not None:
+            self._device.fresh_air_fan_speed = percentage_to_ordered_list_item(
+                self._speeds, percentage)
+        elif self._device.fresh_air_fan_speed == self._off and self._speeds:
+            # Default to the lowest supported speed when turning on from off
+            self._device.fresh_air_fan_speed = self._speeds[0]
+
+        await self.coordinator.apply()
+
+    async def async_turn_off(self, **kwargs: Any) -> None:
+        """Turn the fan off."""
+        self._device.fresh_air_fan_speed = self._off
+        await self.coordinator.apply()

custom_components/midea_ac/translations/en.json

@@ -204,6 +204,11 @@
         "name": "Start self clean"
       }
     },
+    "fan": {
+      "fresh_air": {
+        "name": "Fresh air"
+      }
+    },
     "number": {
       "fan_speed": {
         "name": "Fan speed"

tests/test_fan.py

@@ -0,0 +1,87 @@
+"""Tests for the fan platform."""
+
+import logging
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from homeassistant.config_entries import ConfigEntryState
+from homeassistant.const import Platform
+from homeassistant.core import HomeAssistant
+from homeassistant.helpers import entity_registry as er
+from msmart.device import AirConditioner as AC
+from pytest_homeassistant_custom_component.common import MockConfigEntry
+
+from custom_components.midea_ac.const import DOMAIN
+from custom_components.midea_ac.coordinator import MideaDeviceUpdateCoordinator
+
+logging.basicConfig(level=logging.DEBUG)
+_LOGGER = logging.getLogger(__name__)
+
+# Fresh air requires a msmart-ng with Fresh Air support
+# (see mill1000/midea-msmart#268); skip until that lands.
+pytestmark = pytest.mark.skipif(
+    not hasattr(AC, "FreshAirFanSpeed"),
+    reason="msmart-ng without Fresh Air support (mill1000/midea-msmart#268)",
+)
+
+
+async def test_fresh_air_fan(
+        hass: HomeAssistant,
+        entity_registry: er.EntityRegistry,
+        mock_config_entry: MockConfigEntry,
+) -> None:
+    """Test an AC device that supports fresh air creates a fresh air fan."""
+
+    mock_config_entry.mock_state(hass, ConfigEntryState.LOADED)
+    mock_config_entry.add_to_hass(hass)
+
+    # Create a dummy AC device and force fresh air support
+    mock_device = AC("0.0.0.0", 0, 0)
+    mock_device._online = True
+    mock_device.power_state = True
+    mock_device._capabilities.set(AC.Capability.FRESH_AIR, True)
+
+    # Create a mock coordinator
+    coordinator = MagicMock(spec=MideaDeviceUpdateCoordinator)
+    coordinator.device = mock_device
+    coordinator.apply = AsyncMock()
+
+    # Store coordinator in global data
+    hass.data.setdefault(DOMAIN, {})[mock_config_entry.entry_id] = coordinator
+
+    # Setup climate (to name the device) and fan platforms
+    await hass.config_entries.async_forward_entry_setups(
+        mock_config_entry, [Platform.CLIMATE]
+    )
+    await hass.async_block_till_done()
+
+    await hass.config_entries.async_forward_entry_setups(
+        mock_config_entry, [Platform.FAN]
+    )
+    await hass.async_block_till_done()
+
+    # Verify the fresh air fan exists and is off by default
+    entity_id = "fan.midea_ac_0_fresh_air"
+    state = hass.states.get(entity_id)
+    assert state
+    assert state.state == "off"
+    assert state.attributes["percentage"] == 0
+
+    entry = entity_registry.async_get(entity_id)
+    assert entry
+    assert entry.unique_id == "0-fresh_air"
+
+    # Setting a percentage turns it on. With 4 speeds the ordered-list buckets
+    # are 25/50/75/100, so 75% maps to the 3rd level (High).
+    await hass.services.async_call(
+        Platform.FAN, "set_percentage",
+        {"entity_id": entity_id, "percentage": 75}, blocking=True
+    )
+    assert mock_device.fresh_air_fan_speed == AC.FreshAirFanSpeed.HIGH
+    coordinator.apply.assert_awaited()
+
+    # Turning the fan off sets the speed to OFF
+    await hass.services.async_call(
+        Platform.FAN, "turn_off", {"entity_id": entity_id}, blocking=True
+    )
+    assert mock_device.fresh_air_fan_speed == AC.FreshAirFanSpeed.OFF