Prana Integration - Refactoring

Author: Luca Dametto

homeassistant/components/prana/fan.py

@@ -26,55 +26,59 @@
 
 PARALLEL_UPDATES = 1
 
-# The Prana device API expects fan speed values in scaled units (tenths of a speed step)
-# rather than the raw step value used internally by this integration. This factor is
-# applied when sending speeds to the API to match its expected units.
+# The device API expects speeds in tenths of a step.
 PRANA_SPEED_MULTIPLIER = 10
 
+PRESET_AUTO = "auto"
+PRESET_AUTO_PLUS = "auto_plus"
+PRESET_NIGHT = "night"
+PRESET_BOOST = "boost"
+
+PRESET_MODES = [
+    PRESET_AUTO,
+    PRESET_AUTO_PLUS,
+    PRESET_NIGHT,
+    PRESET_BOOST,
+]
+
 
 class PranaFanType(StrEnum):
-    """Enumerates Prana fan types exposed by the device API."""
+    """Target fan on the Prana API."""
 
     SUPPLY = "supply"
     EXTRACT = "extract"
-    BOUNDED = "bounded"
+    VENTILATION = "bounded"
 
 
 @dataclass(frozen=True, kw_only=True)
 class PranaFanEntityDescription(FanEntityDescription):
     """Description of a Prana fan entity."""
 
-    key: PranaFanType
+    key: str
+    api_target: PranaFanType
     value_fn: Callable[[PranaCoordinator], FanState]
-    speed_range: Callable[[PranaCoordinator], tuple[int, int]]
 
 
-ENTITIES: tuple[PranaFanEntityDescription, ...] = (
+VENTILATION_DESCRIPTION = PranaFanEntityDescription(
+    key="ventilation",
+    translation_key="ventilation",
+    api_target=PranaFanType.VENTILATION,
+    name=None,
+    value_fn=lambda coord: coord.data.bounded,
+)
+
+SPLIT_DESCRIPTIONS: tuple[PranaFanEntityDescription, ...] = (
     PranaFanEntityDescription(
-        key=PranaFanType.SUPPLY,
+        key="supply",
         translation_key="supply",
-        value_fn=lambda coord: (
-            coord.data.supply if not coord.data.bound else coord.data.bounded
-        ),
-        speed_range=lambda coord: (
-            1,
-            coord.data.supply.max_speed
-            if not coord.data.bound
-            else coord.data.bounded.max_speed,
-        ),
+        api_target=PranaFanType.SUPPLY,
+        value_fn=lambda coord: coord.data.supply,
     ),
     PranaFanEntityDescription(
-        key=PranaFanType.EXTRACT,
+        key="extract",
         translation_key="extract",
-        value_fn=lambda coord: (
-            coord.data.extract if not coord.data.bound else coord.data.bounded
-        ),
-        speed_range=lambda coord: (
-            1,
-            coord.data.extract.max_speed
-            if not coord.data.bound
-            else coord.data.bounded.max_speed,
-        ),
+        api_target=PranaFanType.EXTRACT,
+        value_fn=lambda coord: coord.data.extract,
     ),
 )
 
@@ -85,17 +89,24 @@ async def async_setup_entry(
     async_add_entities: AddConfigEntryEntitiesCallback,
 ) -> None:
     """Set up Prana fan entities from a config entry."""
+    coordinator = entry.runtime_data
+    # Whether supply and extract fans are physically linked is a device
+    # capability reported in state: linked models expose one ventilation fan,
+    # split models expose independent supply and extract fans.
+    if coordinator.data.bound:
+        descriptions: tuple[PranaFanEntityDescription, ...] = (VENTILATION_DESCRIPTION,)
+    else:
+        descriptions = SPLIT_DESCRIPTIONS
     async_add_entities(
-        PranaFan(entry.runtime_data, entity_description)
-        for entity_description in ENTITIES
+        PranaFan(coordinator, description) for description in descriptions
     )
 
 
 class PranaFan(PranaBaseEntity, FanEntity):
     """Representation of a Prana fan entity."""
 
     entity_description: PranaFanEntityDescription
-    _attr_preset_modes = ["night", "boost"]
+    _attr_preset_modes = PRESET_MODES
     _attr_supported_features = (
         FanEntityFeature.SET_SPEED
         | FanEntityFeature.TURN_ON
@@ -104,43 +115,29 @@ class PranaFan(PranaBaseEntity, FanEntity):
     )
 
     @property
-    def _api_target_key(self) -> str:
-        """Return the correct target key for API commands based on bounded state."""
-        # If the device is in bound mode, both supply and extract fans control the same bounded fan speeds.
-        if self.coordinator.data.bound:
-            return PranaFanType.BOUNDED
-        # Otherwise, return the specific fan type (supply or extract) for API commands.
-        return self.entity_description.key
+    def _speed_range(self) -> tuple[int, int]:
+        return (1, self.entity_description.value_fn(self.coordinator).max_speed)
 
     @property
     def speed_count(self) -> int:
         """Return the number of speeds the fan supports."""
-        return int_states_in_range(
-            self.entity_description.speed_range(self.coordinator)
-        )
+        return int_states_in_range(self._speed_range)
 
     @property
     def percentage(self) -> int | None:
         """Return the current fan speed percentage."""
         current_speed = self.entity_description.value_fn(self.coordinator).speed
-        return ranged_value_to_percentage(
-            self.entity_description.speed_range(self.coordinator), current_speed
-        )
+        return ranged_value_to_percentage(self._speed_range, current_speed)
 
     async def async_set_percentage(self, percentage: int) -> None:
-        """Set fan speed (0-100%) by converting to device-specific speed steps."""
+        """Set fan speed (0-100%) by converting to device speed steps."""
         if percentage == 0:
             await self.async_turn_off()
             return
         await self.coordinator.api_client.set_speed(
-            math.ceil(
-                percentage_to_ranged_value(
-                    self.entity_description.speed_range(self.coordinator),
-                    percentage,
-                )
-            )
+            math.ceil(percentage_to_ranged_value(self._speed_range, percentage))
             * PRANA_SPEED_MULTIPLIER,
-            self._api_target_key,
+            self.entity_description.api_target,
         )
         await self.coordinator.async_refresh()
 
@@ -160,7 +157,9 @@ async def async_turn_on(
             await self.async_turn_off()
             return
 
-        await self.coordinator.api_client.set_speed_is_on(True, self._api_target_key)
+        await self.coordinator.api_client.set_speed_is_on(
+            True, self.entity_description.api_target
+        )
         if percentage is not None:
             await self.async_set_percentage(percentage)
         if preset_mode is not None:
@@ -170,19 +169,25 @@ async def async_turn_on(
 
     async def async_turn_off(self, **kwargs: Any) -> None:
         """Turn the fan off."""
-        await self.coordinator.api_client.set_speed_is_on(False, self._api_target_key)
+        await self.coordinator.api_client.set_speed_is_on(
+            False, self.entity_description.api_target
+        )
         await self.coordinator.async_refresh()
 
     async def async_set_preset_mode(self, preset_mode: str) -> None:
-        """Set the preset mode (e.g., night or boost)."""
+        """Activate a preset mode on the device.
+
+        Prana operating modes (auto/auto_plus/night/boost/winter) are
+        mutually exclusive on the device: activating one clears the rest.
+        """
         await self.coordinator.api_client.set_switch(preset_mode, True)
         await self.coordinator.async_refresh()
 
     @property
     def preset_mode(self) -> str | None:
-        """Return the current preset mode."""
-        if self.coordinator.data.night:
-            return "night"
-        if self.coordinator.data.boost:
-            return "boost"
+        """Return the current preset mode, if any."""
+        data = self.coordinator.data
+        for preset in PRESET_MODES:
+            if getattr(data, preset, False):
+                return preset
         return None

homeassistant/components/prana/icons.json

@@ -1,6 +1,20 @@
 {
   "entity": {
     "fan": {
+      "ventilation": {
+        "default": "mdi:fan",
+        "state_attributes": {
+          "preset_mode": {
+            "default": "mdi:tune",
+            "state": {
+              "auto": "mdi:fan-auto",
+              "auto_plus": "mdi:fan-auto",
+              "boost": "mdi:fan-plus",
+              "night": "mdi:weather-night"
+            }
+          }
+        }
+      },
       "extract": {
         "default": "mdi:arrow-expand-right"
       },
@@ -26,26 +40,11 @@
       "inside_temperature": {
         "default": "mdi:home-thermometer"
       },
-      "inside_temperature_2": {
-        "default": "mdi:home-thermometer"
-      },
       "outside_temperature": {
         "default": "mdi:thermometer"
-      },
-      "outside_temperature_2": {
-        "default": "mdi:thermometer"
       }
     },
     "switch": {
-      "auto": {
-        "default": "mdi:fan-auto"
-      },
-      "auto_plus": {
-        "default": "mdi:fan-auto"
-      },
-      "bound": {
-        "default": "mdi:link"
-      },
       "heater": {
         "default": "mdi:radiator"
       },

homeassistant/components/prana/sensor.py

@@ -35,9 +35,7 @@ class PranaSensorType(StrEnum):
     AIR_PRESSURE = "air_pressure"
     CO2 = "co2"
     INSIDE_TEMPERATURE = "inside_temperature"
-    INSIDE_TEMPERATURE_2 = "inside_temperature_2"
     OUTSIDE_TEMPERATURE = "outside_temperature"
-    OUTSIDE_TEMPERATURE_2 = "outside_temperature_2"
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -74,31 +72,32 @@ class PranaSensorEntityDescription(SensorEntityDescription):
         native_unit_of_measurement=CONCENTRATION_PARTS_PER_MILLION,
         device_class=SensorDeviceClass.CO2,
     ),
+    # Devices only have two physical probes (one inside, one outside), but
+    # the upstream library mislabels the secondary pair: `inside_temperature_2`
+    # actually contains the outside reading and `outside_temperature_2` the
+    # inside one. On models where the primary fields are populated we use
+    # them; otherwise we fall back to the swapped secondary. Remove this
+    # workaround once upstream fixes the field labeling:
+    # https://github.com/prana-dev-official/prana-local-api
     PranaSensorEntityDescription(
         key=PranaSensorType.INSIDE_TEMPERATURE,
         translation_key="inside_temperature",
-        value_fn=lambda coord: coord.data.inside_temperature,
-        native_unit_of_measurement=UnitOfTemperature.CELSIUS,
-        device_class=SensorDeviceClass.TEMPERATURE,
-    ),
-    PranaSensorEntityDescription(
-        key=PranaSensorType.INSIDE_TEMPERATURE_2,
-        translation_key="inside_temperature_2",
-        value_fn=lambda coord: coord.data.inside_temperature_2,
+        value_fn=lambda coord: (
+            coord.data.inside_temperature
+            if coord.data.inside_temperature is not None
+            else coord.data.outside_temperature_2
+        ),
         native_unit_of_measurement=UnitOfTemperature.CELSIUS,
         device_class=SensorDeviceClass.TEMPERATURE,
     ),
     PranaSensorEntityDescription(
         key=PranaSensorType.OUTSIDE_TEMPERATURE,
         translation_key="outside_temperature",
-        value_fn=lambda coord: coord.data.outside_temperature,
-        native_unit_of_measurement=UnitOfTemperature.CELSIUS,
-        device_class=SensorDeviceClass.TEMPERATURE,
-    ),
-    PranaSensorEntityDescription(
-        key=PranaSensorType.OUTSIDE_TEMPERATURE_2,
-        translation_key="outside_temperature_2",
-        value_fn=lambda coord: coord.data.outside_temperature_2,
+        value_fn=lambda coord: (
+            coord.data.outside_temperature
+            if coord.data.outside_temperature is not None
+            else coord.data.inside_temperature_2
+        ),
         native_unit_of_measurement=UnitOfTemperature.CELSIUS,
         device_class=SensorDeviceClass.TEMPERATURE,
     ),

homeassistant/components/prana/strings.json

@@ -26,24 +26,40 @@
   },
   "entity": {
     "fan": {
-      "extract": {
-        "name": "Extract fan",
+      "ventilation": {
         "state_attributes": {
           "preset_mode": {
             "state": {
+              "auto": "Auto",
+              "auto_plus": "Auto plus",
               "boost": "Boost",
               "night": "Night"
             }
           }
         }
       },
+      "extract": {
+        "name": "Extract fan",
+        "state_attributes": {
+          "preset_mode": {
+            "state": {
+              "auto": "[%key:component::prana::entity::fan::ventilation::state_attributes::preset_mode::state::auto%]",
+              "auto_plus": "[%key:component::prana::entity::fan::ventilation::state_attributes::preset_mode::state::auto_plus%]",
+              "boost": "[%key:component::prana::entity::fan::ventilation::state_attributes::preset_mode::state::boost%]",
+              "night": "[%key:component::prana::entity::fan::ventilation::state_attributes::preset_mode::state::night%]"
+            }
+          }
+        }
+      },
       "supply": {
         "name": "Supply fan",
         "state_attributes": {
           "preset_mode": {
             "state": {
-              "boost": "[%key:component::prana::entity::fan::extract::state_attributes::preset_mode::state::boost%]",
-              "night": "[%key:component::prana::entity::fan::extract::state_attributes::preset_mode::state::night%]"
+              "auto": "[%key:component::prana::entity::fan::ventilation::state_attributes::preset_mode::state::auto%]",
+              "auto_plus": "[%key:component::prana::entity::fan::ventilation::state_attributes::preset_mode::state::auto_plus%]",
+              "boost": "[%key:component::prana::entity::fan::ventilation::state_attributes::preset_mode::state::boost%]",
+              "night": "[%key:component::prana::entity::fan::ventilation::state_attributes::preset_mode::state::night%]"
             }
           }
         }
@@ -58,31 +74,16 @@
       "inside_temperature": {
         "name": "Inside temperature"
       },
-      "inside_temperature_2": {
-        "name": "Inside temperature 2"
-      },
       "outside_temperature": {
         "name": "Outside temperature"
-      },
-      "outside_temperature_2": {
-        "name": "Outside temperature 2"
       }
     },
     "switch": {
-      "auto": {
-        "name": "Auto"
-      },
-      "auto_plus": {
-        "name": "Auto plus"
-      },
-      "bound": {
-        "name": "Bound"
-      },
       "heater": {
         "name": "Heater"
       },
       "winter": {
-        "name": "Winter"
+        "name": "Winter mode"
       }
     }
   }