python-bsblan 6.1.4__py3-none-any.whl → 6.1.6__py3-none-any.whl

bsblan/_hot_water.py

@@ -0,0 +1,249 @@
+"""Hot water domain logic for BSB-LAN."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from .constants import ErrorMsg, HotWaterParams
+from .exceptions import BSBLANError
+from .models import (
+    HotWaterConfig,
+    HotWaterSchedule,
+    HotWaterState,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from .models import SetHotWaterParam
+
+# TypeVar for hot water data models
+HotWaterDataT = TypeVar(
+    "HotWaterDataT", HotWaterState, HotWaterConfig, HotWaterSchedule
+)
+
+
+class HotWaterManager:
+    """Read and write hot water state, configuration, and schedules."""
+
+    def __init__(  # noqa: PLR0913  # pylint: disable=too-many-arguments
+        self,
+        *,
+        ensure_group_validated: Callable[
+            [str, set[str], list[str] | None], Awaitable[None]
+        ],
+        get_param_cache: Callable[[], dict[str, str]],
+        apply_include_filter: Callable[
+            [dict[str, str], list[str] | None], dict[str, str]
+        ],
+        request_named_params: Callable[[dict[str, str]], Awaitable[dict[str, Any]]],
+        validate_single_parameter: Callable[..., None],
+        set_payload: Callable[[str, str], dict[str, Any]],
+        set_device_state: Callable[[dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        """Initialize the hot water manager.
+
+        Args:
+            ensure_group_validated: Validates a hot water param group lazily.
+            get_param_cache: Returns the validated hot water param cache.
+            apply_include_filter: Filters params by requested names.
+            request_named_params: Requests params and maps them to names.
+            validate_single_parameter: Ensures only one parameter is set.
+            set_payload: Builds a set-parameter payload.
+            set_device_state: Sends a set-parameter request to the device.
+
+        """
+        self._ensure_group_validated = ensure_group_validated
+        self._get_param_cache = get_param_cache
+        self._apply_include_filter = apply_include_filter
+        self._request_named_params = request_named_params
+        self._validate_single_parameter = validate_single_parameter
+        self._set_payload = set_payload
+        self._set_device_state = set_device_state
+
+    async def fetch_data(
+        self,
+        param_filter: set[str],
+        model_class: type[HotWaterDataT],
+        error_msg: str,
+        group_name: str,
+        include: list[str] | None = None,
+    ) -> HotWaterDataT:
+        """Fetch hot water data for a specific parameter set.
+
+        This is a generic helper method that fetches hot water parameters
+        based on the provided filter and returns the appropriate model.
+        It uses granular lazy loading to validate only the specific param group.
+
+        Args:
+            param_filter: Set of parameter IDs to fetch.
+            model_class: The dataclass type to deserialize the response into.
+            error_msg: Error message if no parameters are available.
+            group_name: Name of the param group for lazy validation tracking.
+            include: Optional list of parameter names to fetch. If None,
+                fetches all parameters in the group.
+
+        Returns:
+            The populated model instance.
+
+        Raises:
+            BSBLANError: If no parameters are available for the filter.
+
+        """
+        # Granular lazy load: validate only this param group on first access
+        # Pass include filter so we only validate requested params
+        await self._ensure_group_validated(group_name, param_filter, include)
+
+        # Use cached validated params
+        filtered_params = {
+            param_id: param_name
+            for param_id, param_name in self._get_param_cache().items()
+            if param_id in param_filter
+        }
+
+        # Apply include filter if specified
+        filtered_params = self._apply_include_filter(filtered_params, include)
+
+        if not filtered_params:
+            raise BSBLANError(error_msg)
+
+        data = await self._request_named_params(filtered_params)
+        return model_class.model_validate(data)
+
+    async def state(self, include: list[str] | None = None) -> HotWaterState:
+        """Get essential hot water state for frequent polling.
+
+        Args:
+            include: Optional list of parameter names to fetch.
+
+        Returns:
+            HotWaterState: Essential hot water state information.
+
+        """
+        return await self.fetch_data(
+            param_filter=HotWaterParams.ESSENTIAL,
+            model_class=HotWaterState,
+            error_msg="No essential hot water parameters available",
+            group_name="essential",
+            include=include,
+        )
+
+    async def config(self, include: list[str] | None = None) -> HotWaterConfig:
+        """Get hot water configuration and advanced settings.
+
+        Args:
+            include: Optional list of parameter names to fetch.
+
+        Returns:
+            HotWaterConfig: Hot water configuration information.
+
+        """
+        return await self.fetch_data(
+            param_filter=HotWaterParams.CONFIG,
+            model_class=HotWaterConfig,
+            error_msg="No hot water configuration parameters available",
+            group_name="config",
+            include=include,
+        )
+
+    async def schedule(self, include: list[str] | None = None) -> HotWaterSchedule:
+        """Get hot water time program schedules.
+
+        Args:
+            include: Optional list of parameter names to fetch.
+
+        Returns:
+            HotWaterSchedule: Hot water schedule information.
+
+        """
+        return await self.fetch_data(
+            param_filter=HotWaterParams.SCHEDULE,
+            model_class=HotWaterSchedule,
+            error_msg="No hot water schedule parameters available",
+            group_name="schedule",
+            include=include,
+        )
+
+    async def set_hot_water(self, params: SetHotWaterParam) -> None:
+        """Change the state of the hot water system through BSB-Lan.
+
+        Only one parameter should be set at a time (BSB-LAN API limitation).
+
+        Args:
+            params: SetHotWaterParam object containing the parameter to set.
+
+        Raises:
+            BSBLANError: If multiple parameters are set or no parameter is set.
+
+        """
+        # Validate only one parameter is being set
+        time_program_params: list[str] = []
+        if params.dhw_time_programs:
+            programs = params.dhw_time_programs
+            time_program_params.extend(
+                prog
+                for prog in [
+                    programs.monday,
+                    programs.tuesday,
+                    programs.wednesday,
+                    programs.thursday,
+                    programs.friday,
+                    programs.saturday,
+                    programs.sunday,
+                    programs.standard_values,
+                ]
+                if prog
+            )
+
+        self._validate_single_parameter(
+            params.nominal_setpoint,
+            params.reduced_setpoint,
+            params.nominal_setpoint_max,
+            params.operating_mode,
+            params.eco_mode_selection,
+            params.dhw_charging_priority,
+            params.legionella_function_setpoint,
+            params.legionella_function_periodicity,
+            params.legionella_function_day,
+            params.legionella_function_time,
+            params.legionella_function_dwelling_time,
+            params.operating_mode_changeover,
+            *time_program_params,
+            error_msg=ErrorMsg.MULTI_PARAMETER,
+        )
+
+        state = self.prepare_state(params)
+        await self._set_device_state(state)
+
+    def prepare_state(self, params: SetHotWaterParam) -> dict[str, Any]:
+        """Prepare the hot water state for setting.
+
+        Args:
+            params: SetHotWaterParam object containing the parameter to set.
+
+        Returns:
+            dict[str, Any]: The prepared state for the hot water.
+
+        Raises:
+            BSBLANError: If no state is provided.
+
+        """
+        state: dict[str, Any] = {}
+
+        # Process all mapped parameters using constants
+        for param_id, attr_name in HotWaterParams.SETTABLE.items():
+            value = getattr(params, attr_name)
+            if value is not None:
+                state.update(self._set_payload(param_id, str(value)))
+
+        # Process time programs if provided using constants
+        if params.dhw_time_programs:
+            for param_id, attr_name in HotWaterParams.TIME_PROGRAMS.items():
+                value = getattr(params.dhw_time_programs, attr_name)
+                if value is not None:
+                    state.update(self._set_payload(param_id, value))
+
+        if not state:
+            raise BSBLANError(ErrorMsg.NO_STATE)
+
+        return state

bsblan/_parameters.py

@@ -0,0 +1,155 @@
+"""Low-level parameter lookup and read helpers for BSB-LAN."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from .constants import ErrorMsg
+from .exceptions import BSBLANError
+from .models import EntityInfo
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from .constants import APIConfig
+
+
+class ParameterReader:
+    """Resolve and read BSB-LAN parameters by ID or name."""
+
+    def __init__(
+        self,
+        *,
+        request: Callable[..., Awaitable[dict[str, Any]]],
+        get_api_data: Callable[[], APIConfig | None],
+    ) -> None:
+        """Initialize the parameter reader.
+
+        Args:
+            request: Callable performing a client request.
+            get_api_data: Callable returning the current API config data.
+
+        """
+        self._request = request
+        self._get_api_data = get_api_data
+
+    async def read_parameters(
+        self,
+        parameter_ids: list[str],
+    ) -> dict[str, EntityInfo]:
+        """Read specific parameters by their BSB-LAN parameter IDs.
+
+        Args:
+            parameter_ids: List of BSB-LAN parameter IDs to fetch.
+
+        Returns:
+            dict[str, EntityInfo]: Dictionary mapping parameter IDs to
+                EntityInfo objects.
+
+        Raises:
+            BSBLANError: If no parameter IDs are provided or request fails.
+
+        """
+        if not parameter_ids:
+            raise BSBLANError(ErrorMsg.NO_PARAMETER_IDS)
+
+        # Request the parameters from the device
+        params_string = ",".join(parameter_ids)
+        response_data = await self._request(params={"Parameter": params_string})
+
+        # Convert response to EntityInfo objects
+        result: dict[str, EntityInfo] = {}
+        for param_id in parameter_ids:
+            if param_id in response_data:
+                param_data = response_data[param_id]
+                if param_data and isinstance(param_data, dict):
+                    result[param_id] = EntityInfo.model_validate(param_data)
+
+        return result
+
+    def get_parameter_id(self, parameter_name: str) -> str | None:
+        """Look up the parameter ID for a given parameter name.
+
+        Args:
+            parameter_name: The parameter name (e.g., "current_temperature").
+
+        Returns:
+            str | None: The parameter ID if found, None otherwise.
+
+        """
+        api_data = self._get_api_data()
+        if not api_data:
+            return None
+
+        # Search through all sections for the parameter name
+        for section_params in api_data.values():
+            section_dict = cast("dict[str, str]", section_params)
+            for param_id, param_name in section_dict.items():
+                if param_name == parameter_name:
+                    return param_id
+
+        return None
+
+    def get_parameter_ids(self, parameter_names: list[str]) -> dict[str, str]:
+        """Look up parameter IDs for multiple parameter names.
+
+        Args:
+            parameter_names: List of parameter names to look up.
+
+        Returns:
+            dict[str, str]: Dictionary mapping parameter names to their IDs.
+                Only includes parameters that were found.
+
+        """
+        result: dict[str, str] = {}
+        for name in parameter_names:
+            param_id = self.get_parameter_id(name)
+            if param_id is not None:
+                result[name] = param_id
+        return result
+
+    async def read_parameters_by_name(
+        self,
+        parameter_names: list[str],
+    ) -> dict[str, EntityInfo]:
+        """Read specific parameters by their names.
+
+        Args:
+            parameter_names: List of parameter names to fetch.
+
+        Returns:
+            dict[str, EntityInfo]: Dictionary mapping parameter names to
+                EntityInfo objects. Only includes parameters that were found
+                and had valid data.
+
+        Raises:
+            BSBLANError: If no parameter names are provided, no IDs could be
+                resolved, or the client is not initialized.
+
+        """
+        if not parameter_names:
+            raise BSBLANError(ErrorMsg.NO_PARAMETER_NAMES)
+
+        if not self._get_api_data():
+            raise BSBLANError(ErrorMsg.API_DATA_NOT_INITIALIZED)
+
+        # Resolve names to IDs
+        name_to_id = self.get_parameter_ids(parameter_names)
+
+        if not name_to_id:
+            unknown_params = ", ".join(parameter_names)
+            msg = f"{ErrorMsg.PARAMETER_NAMES_NOT_RESOLVED}: {unknown_params}"
+            raise BSBLANError(msg)
+
+        # Fetch parameters by ID
+        param_ids = list(name_to_id.values())
+        id_results = await self.read_parameters(param_ids)
+
+        # Convert back to name-keyed dictionary
+        # id_to_name maps param_id -> param_name for requested params only
+        id_to_name = {v: k for k, v in name_to_id.items()}
+        return {
+            id_to_name[param_id]: entity_info
+            for param_id, entity_info in id_results.items()
+            if param_id in id_to_name
+        }

bsblan/_schedules.py

@@ -0,0 +1,148 @@
+"""Heating and hot water schedule domain logic for BSB-LAN."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .constants import ErrorMsg, HeatingScheduleParams, HotWaterParams
+from .exceptions import BSBLANError
+from .models import HeatingTimeSwitchPrograms
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from .models import DaySchedule, DHWSchedule, HeatingSchedule
+
+
+class ScheduleManager:
+    """Read and write heating and hot water time switch programs."""
+
+    def __init__(  # noqa: PLR0913  # pylint: disable=too-many-arguments
+        self,
+        *,
+        request: Callable[..., Awaitable[dict[str, Any]]],
+        extract_params_summary: Callable[[dict[Any, Any]], dict[Any, Any]],
+        apply_include_filter: Callable[
+            [dict[str, str], list[str] | None], dict[str, str]
+        ],
+        validate_circuit: Callable[[int], None],
+        set_payload: Callable[[str, str], dict[str, Any]],
+        set_device_state: Callable[[dict[str, Any]], Awaitable[None]],
+    ) -> None:
+        """Initialize the schedule manager.
+
+        Args:
+            request: Callable performing a client request.
+            extract_params_summary: Builds the request parameter summary.
+            apply_include_filter: Filters params by requested names.
+            validate_circuit: Validates a heating circuit number.
+            set_payload: Builds a set-parameter payload.
+            set_device_state: Sends a set-parameter request to the device.
+
+        """
+        self._request = request
+        self._extract_params_summary = extract_params_summary
+        self._apply_include_filter = apply_include_filter
+        self._validate_circuit = validate_circuit
+        self._set_payload = set_payload
+        self._set_device_state = set_device_state
+
+    async def heating_schedule(
+        self,
+        include: list[str] | None = None,
+        circuit: int = 1,
+    ) -> HeatingTimeSwitchPrograms:
+        """Get heating time switch programs for a specific circuit.
+
+        Args:
+            include: Optional list of day names to fetch.
+            circuit: The heating circuit number (1 or 2). Defaults to 1.
+
+        Returns:
+            HeatingTimeSwitchPrograms: Heating schedule information.
+
+        Raises:
+            BSBLANError: If no schedule parameters are available.
+
+        """
+        self._validate_circuit(circuit)
+        time_program_params = HeatingScheduleParams.TIME_PROGRAMS[circuit]
+
+        filtered_params = self._apply_include_filter(time_program_params, include)
+
+        params = self._extract_params_summary(filtered_params)
+        data = await self._request(params={"Parameter": params["string_par"]})
+        mapped_data = {
+            name: data[param_id]
+            for param_id, name in filtered_params.items()
+            if param_id in data
+        }
+
+        if not mapped_data:
+            raise BSBLANError(ErrorMsg.NO_HEATING_SCHEDULE_PARAMS)
+
+        return HeatingTimeSwitchPrograms.model_validate(mapped_data)
+
+    async def set_heating_schedule(
+        self,
+        schedule: HeatingSchedule,
+        circuit: int = 1,
+    ) -> None:
+        """Set heating time switch programs for a specific circuit.
+
+        Args:
+            schedule: HeatingSchedule object containing the weekly schedule.
+            circuit: The heating circuit number (1 or 2). Defaults to 1.
+
+        Raises:
+            BSBLANError: If no schedule is provided.
+
+        """
+        self._validate_circuit(circuit)
+        await self._write_day_schedules(
+            schedule,
+            HeatingScheduleParams.TIME_PROGRAMS[circuit],
+        )
+
+    async def set_hot_water_schedule(self, schedule: DHWSchedule) -> None:
+        """Set hot water time program schedules.
+
+        Args:
+            schedule: DHWSchedule object containing the weekly schedule.
+
+        Raises:
+            BSBLANError: If no schedule is provided.
+
+        """
+        await self._write_day_schedules(schedule, HotWaterParams.TIME_PROGRAMS)
+
+    async def _write_day_schedules(
+        self,
+        schedule: HeatingSchedule | DHWSchedule,
+        time_programs: dict[str, str],
+    ) -> None:
+        """Write populated day schedules using one request per day.
+
+        Args:
+            schedule: Weekly schedule object with per-day DaySchedule attrs.
+            time_programs: Mapping of parameter IDs to day names.
+
+        Raises:
+            BSBLANError: If no schedule is provided.
+
+        """
+        if not schedule.has_any_schedule():
+            raise BSBLANError(ErrorMsg.NO_SCHEDULE)
+
+        # Invert the param mapping to get day_name -> param_id
+        # Exclude standard_values as it's not a day of the week
+        day_param_map = {
+            v: k for k, v in time_programs.items() if v != "standard_values"
+        }
+
+        for day_name, param_id in day_param_map.items():
+            day_schedule: DaySchedule | None = getattr(schedule, day_name)
+            if day_schedule is not None:
+                await self._set_device_state(
+                    self._set_payload(param_id, day_schedule.to_bsblan_format()),
+                )

bsblan/_thermostat.py

@@ -0,0 +1,137 @@
+"""Thermostat write preparation for BSB-LAN."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .constants import CircuitConfig, Validation
+from .exceptions import BSBLANInvalidParameterError
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from ._temperature import TemperatureManager
+
+
+class ThermostatWriter:
+    """Prepare and validate thermostat write payloads."""
+
+    def __init__(
+        self,
+        *,
+        uses_pps_bus: Callable[[], bool],
+        temperature: TemperatureManager,
+        set_payload: Callable[[str, str], dict[str, Any]],
+    ) -> None:
+        """Initialize the thermostat writer.
+
+        Args:
+            uses_pps_bus: Returns whether the device uses the PPS bus.
+            temperature: Temperature manager for setpoint validation.
+            set_payload: Builds a set-parameter payload.
+
+        """
+        self._uses_pps_bus = uses_pps_bus
+        self._temperature = temperature
+        self._set_payload = set_payload
+
+    async def prepare_state(  # pylint: disable=too-many-arguments
+        self,
+        target_temperature: str | None,
+        hvac_mode: int | None,
+        circuit: int = 1,
+        target_temperature_high: str | float | None = None,
+        *,
+        cooling_operating_mode: int | None = None,
+    ) -> dict[str, Any]:
+        """Prepare the thermostat state for setting.
+
+        Args:
+            target_temperature (str | None): The target temperature to set.
+            hvac_mode (int | None): The HVAC mode to set as raw integer.
+            circuit: The heating circuit number (1 or 2).
+            target_temperature_high: The cooling comfort setpoint to set.
+            cooling_operating_mode: The cooling circuit operating mode to set
+                as raw integer.
+
+        Returns:
+            dict[str, Any]: The prepared state for the thermostat.
+
+        """
+        param_ids = self.thermostat_params(circuit)
+        state: dict[str, Any] = {}
+        if target_temperature is not None:
+            await self._temperature.validate_target_temperature(
+                target_temperature,
+                circuit,
+            )
+            state.update(
+                self._set_payload(param_ids["target_temperature"], target_temperature),
+            )
+        if target_temperature_high is not None:
+            param_id = param_ids.get("target_temperature_high")
+            if param_id is None:
+                parameter_name = "target_temperature_high"
+                raise BSBLANInvalidParameterError(parameter_name)
+            await self._temperature.validate_target_temperature_high(
+                target_temperature_high,
+                circuit,
+            )
+            state.update(
+                self._set_payload(param_id, str(target_temperature_high)),
+            )
+        if hvac_mode is not None:
+            self.validate_hvac_mode(hvac_mode)
+            hvac_value = str(hvac_mode)
+            if self._uses_pps_bus():
+                hvac_value = Validation.PPS_HVAC_MODE_TO_BSBLAN[hvac_mode]
+            state.update(
+                self._set_payload(param_ids["hvac_mode"], hvac_value),
+            )
+        if cooling_operating_mode is not None:
+            param_id = param_ids.get("cooling_operating_mode")
+            if param_id is None:
+                parameter_name = "cooling_operating_mode"
+                raise BSBLANInvalidParameterError(parameter_name)
+            self.validate_cooling_operating_mode(cooling_operating_mode)
+            state.update(
+                self._set_payload(param_id, str(cooling_operating_mode)),
+            )
+        return state
+
+    def thermostat_params(self, circuit: int) -> dict[str, str]:
+        """Return thermostat write parameters for the active bus type."""
+        if self._uses_pps_bus():
+            return {"target_temperature": "15004", "hvac_mode": "15000"}
+        return CircuitConfig.THERMOSTAT_PARAMS[circuit]
+
+    def validate_hvac_mode(self, hvac_mode: int) -> None:
+        """Validate the HVAC mode.
+
+        Args:
+            hvac_mode (int): The HVAC mode to validate. BSB/LPB accepts 0-3;
+                PPS accepts 0, 1, and 3.
+
+        Raises:
+            BSBLANInvalidParameterError: If the HVAC mode is invalid.
+
+        """
+        valid_modes = (
+            Validation.PPS_HVAC_MODES if self._uses_pps_bus() else Validation.HVAC_MODES
+        )
+        if hvac_mode not in valid_modes:
+            raise BSBLANInvalidParameterError(str(hvac_mode))
+
+    def validate_cooling_operating_mode(self, cooling_operating_mode: int) -> None:
+        """Validate the cooling circuit operating mode.
+
+        Args:
+            cooling_operating_mode (int): The mode to validate. Valid values
+                are 0=Protection, 1=Automatic, 2=Reduced, 3=Comfort.
+
+        Raises:
+            BSBLANInvalidParameterError: If the mode is invalid.
+
+        """
+        if cooling_operating_mode not in Validation.COOLING_OPERATING_MODES:
+            raise BSBLANInvalidParameterError(str(cooling_operating_mode))