Merge pull request #1212 from liudger/Optimize-hotwater-requests

Author: liudger

examples/control.py

@@ -1,5 +1,13 @@
 # pylint: disable=W0621
-"""Asynchronous Python client for BSBLan."""
+"""Asynchronous Python client for BSBLan.
+
+This example demonstrates the optimized hot water functionality:
+- HotWaterState: Essential parameters for frequent polling (6 fields)
+- HotWaterConfig: Configuration parameters checked less frequently (15 fields)
+- HotWaterSchedule: Time program schedules checked occasionally (8 fields)
+
+This three-tier approach reduces API calls by 79% for regular monitoring.
+"""
 
 from __future__ import annotations
 
@@ -13,6 +21,8 @@
     BSBLANConfig,
     Device,
     DeviceTime,
+    HotWaterConfig,
+    HotWaterSchedule,
     HotWaterState,
     Info,
     Sensor,
@@ -145,11 +155,11 @@ async def print_static_state(static_state: StaticState) -> None:
 
 
 async def print_hot_water_state(hot_water_state: HotWaterState) -> None:
-    """Print hot water state information.
+    """Print essential hot water state information.
 
     Args:
-        hot_water_state (HotWaterState): The hot water state information from the
-            BSBLan device.
+        hot_water_state (HotWaterState): The essential hot water state information
+            from the BSBLan device (optimized for frequent polling).
 
     """
     attributes = {
@@ -163,41 +173,82 @@ async def print_hot_water_state(hot_water_state: HotWaterState) -> None:
             hot_water_state.reduced_setpoint, "value", "N/A"
         ),
         "Release": await get_attribute(hot_water_state.release, "desc", "N/A"),
+        "Current Temperature": await get_attribute(
+            hot_water_state.dhw_actual_value_top_temperature, "value", "N/A"
+        ),
+        "DHW Pump State": await get_attribute(
+            hot_water_state.state_dhw_pump, "desc", "N/A"
+        ),
+    }
+    print_attributes("Hot Water State (Essential)", attributes)
+
+
+async def print_hot_water_config(hot_water_config: HotWaterConfig) -> None:
+    """Print hot water configuration information.
+
+    Args:
+        hot_water_config (HotWaterConfig): The hot water configuration information
+            from the BSBLan device (checked less frequently).
+
+    """
+    attributes = {
+        "Nominal Setpoint Max": await get_attribute(
+            hot_water_config.nominal_setpoint_max, "value", "N/A"
+        ),
         "Legionella Function": await get_attribute(
-            hot_water_state.legionella_function, "desc", "N/A"
+            hot_water_config.legionella_function, "desc", "N/A"
+        ),
+        "Legionella Setpoint": await get_attribute(
+            hot_water_config.legionella_setpoint, "value", "N/A"
         ),
         "Legionella Periodicity": await get_attribute(
-            hot_water_state.legionella_periodicity, "value", "N/A"
+            hot_water_config.legionella_periodicity, "value", "N/A"
         ),
-        "Legionella Setpoint": await get_attribute(
-            hot_water_state.legionella_setpoint, "value", "N/A"
+        "Circulation Pump Release": await get_attribute(
+            hot_water_config.dhw_circulation_pump_release, "desc", "N/A"
         ),
-        "Current Temperature": await get_attribute(
-            hot_water_state.dhw_actual_value_top_temperature, "value", "N/A"
+        "Circulation Setpoint": await get_attribute(
+            hot_water_config.dhw_circulation_setpoint, "value", "N/A"
         ),
-        "Time Program Monday": await get_attribute(
-            hot_water_state.dhw_time_program_monday, "value", "N/A"
+    }
+    print_attributes("Hot Water Configuration", attributes)
+
+
+async def print_hot_water_schedule(hot_water_schedule: HotWaterSchedule) -> None:
+    """Print hot water schedule information.
+
+    Args:
+        hot_water_schedule (HotWaterSchedule): The hot water schedule information
+            from the BSBLan device (time programs).
+
+    """
+    attributes = {
+        "Monday": await get_attribute(
+            hot_water_schedule.dhw_time_program_monday, "value", "N/A"
+        ),
+        "Tuesday": await get_attribute(
+            hot_water_schedule.dhw_time_program_tuesday, "value", "N/A"
         ),
-        "Time Program Tuesday": await get_attribute(
-            hot_water_state.dhw_time_program_tuesday, "value", "N/A"
+        "Wednesday": await get_attribute(
+            hot_water_schedule.dhw_time_program_wednesday, "value", "N/A"
         ),
-        "Time Program Wednesday": await get_attribute(
-            hot_water_state.dhw_time_program_wednesday, "value", "N/A"
+        "Thursday": await get_attribute(
+            hot_water_schedule.dhw_time_program_thursday, "value", "N/A"
         ),
-        "Time Program Thursday": await get_attribute(
-            hot_water_state.dhw_time_program_thursday, "value", "N/A"
+        "Friday": await get_attribute(
+            hot_water_schedule.dhw_time_program_friday, "value", "N/A"
         ),
-        "Time Program Friday": await get_attribute(
-            hot_water_state.dhw_time_program_friday, "value", "N/A"
+        "Saturday": await get_attribute(
+            hot_water_schedule.dhw_time_program_saturday, "value", "N/A"
         ),
-        "Time Program Saturday": await get_attribute(
-            hot_water_state.dhw_time_program_saturday, "value", "N/A"
+        "Sunday": await get_attribute(
+            hot_water_schedule.dhw_time_program_sunday, "value", "N/A"
         ),
-        "Time Program Sunday": await get_attribute(
-            hot_water_state.dhw_time_program_sunday, "value", "N/A"
+        "Standard Values": await get_attribute(
+            hot_water_schedule.dhw_time_program_standard_values, "value", "N/A"
         ),
     }
-    print_attributes("Hot Water State", attributes)
+    print_attributes("Hot Water Schedule", attributes)
 
 
 async def main() -> None:
@@ -241,10 +292,24 @@ async def main() -> None:
         static_state: StaticState = await bsblan.static_values()
         await print_static_state(static_state)
 
-        # Get hot water state
+        # Get hot water state (essential parameters for frequent polling)
         hot_water_state: HotWaterState = await bsblan.hot_water_state()
         await print_hot_water_state(hot_water_state)
 
+        # Get hot water configuration (checked less frequently)
+        try:
+            hot_water_config: HotWaterConfig = await bsblan.hot_water_config()
+            await print_hot_water_config(hot_water_config)
+        except Exception as e:  # noqa: BLE001
+            print(f"Hot water configuration not available: {e}")
+
+        # Get hot water schedule (time programs)
+        try:
+            hot_water_schedule: HotWaterSchedule = await bsblan.hot_water_schedule()
+            await print_hot_water_schedule(hot_water_schedule)
+        except Exception as e:  # noqa: BLE001
+            print(f"Hot water schedule not available: {e}")
+
         # Example: Set DHW time program for Monday
         print("\nSetting DHW time program for Monday to 13:00-14:00")
 

src/bsblan/__init__.py

@@ -6,6 +6,8 @@
     Device,
     DeviceTime,
     DHWTimeSwitchPrograms,
+    HotWaterConfig,
+    HotWaterSchedule,
     HotWaterState,
     Info,
     Sensor,
@@ -22,6 +24,8 @@
     "DHWTimeSwitchPrograms",
     "Device",
     "DeviceTime",
+    "HotWaterConfig",
+    "HotWaterSchedule",
     "HotWaterState",
     "Info",
     "Sensor",

src/bsblan/bsblan.py

@@ -23,6 +23,9 @@
     API_VERSION_ERROR_MSG,
     API_VERSIONS,
     FIRMWARE_VERSION_ERROR_MSG,
+    HOT_WATER_CONFIG_PARAMS,
+    HOT_WATER_ESSENTIAL_PARAMS,
+    HOT_WATER_SCHEDULE_PARAMS,
     HVAC_MODE_DICT,
     HVAC_MODE_DICT_REVERSE,
     MAX_VALID_YEAR,
@@ -45,6 +48,8 @@
     Device,
     DeviceTime,
     DHWTimeSwitchPrograms,
+    HotWaterConfig,
+    HotWaterSchedule,
     HotWaterState,
     Info,
     Sensor,
@@ -92,6 +97,7 @@ class BSBLAN:
     _initialized: bool = False
     _api_validator: APIValidator = field(init=False)
     _temperature_unit: str = "°C"
+    _hot_water_param_cache: dict[str, str] = field(default_factory=dict)
 
     async def __aenter__(self) -> Self:
         """Enter the context manager.
@@ -189,12 +195,36 @@ async def _validate_api_section(self, section: SectionLiteral) -> None:
             # Update API data with validated configuration
             if self._api_data:
                 self._api_data[section] = api_validator.get_section_params(section)
+
+            # Cache hot water parameters if this is the hot_water section
+            if section == "hot_water":
+                self._populate_hot_water_cache()
         except BSBLANError as err:
             logger.warning("Failed to validate section %s: %s", section, str(err))
             # Reset validation state for this section
             api_validator.reset_validation(section)
             raise
 
+    def _populate_hot_water_cache(self) -> None:
+        """Populate the hot water parameter cache with all available parameters."""
+        if not self._api_validator:
+            return
+
+        # Get all hot water parameters and cache them
+        hotwater_params = self._api_validator.get_section_params("hot_water")
+        self._hot_water_param_cache = hotwater_params.copy()
+        logger.debug("Cached %d hot water parameters", len(self._hot_water_param_cache))
+
+    def set_hot_water_cache(self, params: dict[str, str]) -> None:
+        """Set the hot water parameter cache manually (for testing).
+
+        Args:
+            params: Dictionary of parameter_id -> parameter_name mappings
+
+        """
+        self._hot_water_param_cache = params.copy()
+        logger.debug("Manually set cache with %d hot water parameters", len(params))
+
     async def _fetch_firmware_version(self) -> None:
         """Fetch the firmware version if not already available."""
         if self._firmware_version is None:
@@ -683,18 +713,96 @@ async def _set_thermostat_state(self, state: dict[str, Any]) -> None:
         logger.debug("Response for setting: %s", response)
 
     async def hot_water_state(self) -> HotWaterState:
-        """Get the current hot water state from BSBLAN device.
+        """Get essential hot water state for frequent polling.
+
+        This method returns only the most important hot water parameters
+        that are typically checked frequently for monitoring purposes.
+        This reduces API calls and improves performance for regular polling.
 
         Returns:
-            HotWaterState: The current hot water state.
+            HotWaterState: Essential hot water state information.
 
         """
-        hotwater_params = self._api_validator.get_section_params("hot_water")
-        params = await self._extract_params_summary(hotwater_params)
+        # Use cached parameters or fall back to API validator
+        hotwater_params = (
+            self._hot_water_param_cache
+            or self._api_validator.get_section_params("hot_water")
+        )
+        essential_params = {
+            param_id: param_name
+            for param_id, param_name in hotwater_params.items()
+            if param_id in HOT_WATER_ESSENTIAL_PARAMS
+        }
+
+        if not essential_params:
+            msg = "No essential hot water parameters available"
+            raise BSBLANError(msg)
+
+        params = await self._extract_params_summary(essential_params)
         data = await self._request(params={"Parameter": params["string_par"]})
         data = dict(zip(params["list"], list(data.values()), strict=True))
         return HotWaterState.from_dict(data)
 
+    async def hot_water_config(self) -> HotWaterConfig:
+        """Get hot water configuration and advanced settings.
+
+        This method returns configuration parameters that are typically
+        set once and checked less frequently.
+
+        Returns:
+            HotWaterConfig: Hot water configuration information.
+
+        """
+        # Use cached parameters or fall back to API validator
+        hotwater_params = (
+            self._hot_water_param_cache
+            or self._api_validator.get_section_params("hot_water")
+        )
+        config_params = {
+            param_id: param_name
+            for param_id, param_name in hotwater_params.items()
+            if param_id in HOT_WATER_CONFIG_PARAMS
+        }
+
+        if not config_params:
+            msg = "No hot water configuration parameters available"
+            raise BSBLANError(msg)
+
+        params = await self._extract_params_summary(config_params)
+        data = await self._request(params={"Parameter": params["string_par"]})
+        data = dict(zip(params["list"], list(data.values()), strict=True))
+        return HotWaterConfig.from_dict(data)
+
+    async def hot_water_schedule(self) -> HotWaterSchedule:
+        """Get hot water time program schedules.
+
+        This method returns time program settings that are typically
+        configured once and rarely changed.
+
+        Returns:
+            HotWaterSchedule: Hot water schedule information.
+
+        """
+        # Use cached parameters or fall back to API validator
+        hotwater_params = (
+            self._hot_water_param_cache
+            or self._api_validator.get_section_params("hot_water")
+        )
+        schedule_params = {
+            param_id: param_name
+            for param_id, param_name in hotwater_params.items()
+            if param_id in HOT_WATER_SCHEDULE_PARAMS
+        }
+
+        if not schedule_params:
+            msg = "No hot water schedule parameters available"
+            raise BSBLANError(msg)
+
+        params = await self._extract_params_summary(schedule_params)
+        data = await self._request(params={"Parameter": params["string_par"]})
+        data = dict(zip(params["list"], list(data.values()), strict=True))
+        return HotWaterSchedule.from_dict(data)
+
     async def set_hot_water(  # noqa: PLR0913
         self,
         nominal_setpoint: float | None = None,