Drop v1 API support and add heat/cool setpoint parameters

- Require BSB-LAN API v3 (firmware >= 3.0.0); remove v1 config and
  version branching, raising BSBLANVersionError for unsupported firmware
- Add cooling setpoint bounds to StaticState (heating_protective_setpoint,
  cooling_comfort_setpoint_min, cooling_reduced_setpoint) and map params
  for HC1 (905/903) and HC2 (1205/1203)
- Validate target_temperature_high against cooling bounds and fail fast
  on buses without a cooling setpoint parameter
- Track available circuits to skip temperature-range fetches for
  unavailable circuits
- Update fixtures, tests, and docs for the v3-only parameter set

Author: liudger

docs/getting-started.md

@@ -63,11 +63,25 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+## Temperature bounds
+
+For heating comfort setpoint writes (`target_temperature`), `min_temp` maps to
+the reduced setpoint (`712` for circuit 1, `1012` for circuit 2). The protective
+setpoints (`714` and `1014`) are exposed separately and are not used as the
+comfort setpoint lower bound. The upper heating bound is `716` for circuit 1 and
+`1016` for circuit 2 when the device exposes those parameters.
+
 ## Cooling setpoint support
 
-Some BSB/LPB controllers expose a cooling comfort setpoint for heating circuit
-1. The client maps BSB-LAN parameter `902` to `target_temperature_high`; the
-duplicate decimal parameters `902.1` and `902.2` are not used.
+Some BSB/LPB controllers expose a cooling comfort setpoint for each heating
+circuit. The client maps BSB-LAN parameter `902` for circuit 1 and `1202` for
+circuit 2 to `target_temperature_high`; the duplicate decimal parameters
+`902.1` and `902.2` are not used.
+
+When available, cooling setpoint validation uses `905`/`1205` (comfort setpoint
+minimum) as the lower bound and `903`/`1203` (room temperature reduced setpoint)
+as the upper bound. Parameters `908` and `1208` are flow setpoints and are not
+used for room setpoint validation.
 
 Cooling support is optional. During section validation, unsupported parameters
 are removed from the active API map, so integrations can detect support by

docs/index.md

@@ -9,7 +9,7 @@ Asynchronous Python client for [BSB-LAN](https://github.com/fredlcore/bsb_lan) d
 - Control thermostat settings and hot water parameters
 - Detect optional cooling setpoints for heat/cool range controls
 - Fully typed with PEP 561 support
-- Automatic API version detection (v1/v3)
+- API v3 parameter support
 - Lazy loading with per-section validation
 
 ## Quick example

src/bsblan/bsblan.py

@@ -18,9 +18,10 @@
 from yarl import URL
 
 from .constants import (
-    API_VERSIONS,
+    API_V3,
     PPS_HEATING_PARAMS,
     PPS_STATIC_VALUES_PARAMS,
+    SUPPORTED_API_VERSION,
     APIConfig,
     CircuitConfig,
     ErrorMsg,
@@ -100,7 +101,7 @@ class BSBLAN:
     session: ClientSession | None = None
     _close_session: bool = False
     _firmware_version: str | None = None
-    _api_version: str | None = None
+    _api_version: str | None = SUPPORTED_API_VERSION
     _api_data: APIConfig | None = None
     _device: Device | None = None
     _initialized: bool = False
@@ -111,6 +112,7 @@ class BSBLAN:
         default_factory=dict,
     )
     _circuit_temp_initialized: set[int] = field(default_factory=set)
+    _available_circuits: set[int] | None = None
     _hot_water_param_cache: dict[str, str] = field(default_factory=dict)
     # Track which hot water param groups have been validated
     _validated_hot_water_groups: set[str] = field(default_factory=set)
@@ -199,6 +201,7 @@ async def get_available_circuits(self) -> list[int]:
                 continue
 
             available.append(circuit)
+        self._available_circuits = set(available)
         return sorted(available)
 
     async def _get_available_pps_circuits(self) -> list[int]:
@@ -208,11 +211,14 @@ async def _get_available_pps_circuits(self) -> list[int]:
             response = await self._request(params={"Parameter": param_id})
         except BSBLANError:
             logger.debug("PPS climate circuit not available")
+            self._available_circuits = set()
             return []
 
         if not response.get(param_id):
             logger.debug("PPS climate circuit has no operating mode data")
+            self._available_circuits = set()
             return []
+        self._available_circuits = {1}
         return [1]
 
     async def _setup_api_validator(self) -> None:
@@ -575,16 +581,10 @@ def _set_api_version(self) -> None:
         if not self._firmware_version:
             raise BSBLANError(ErrorMsg.FIRMWARE_VERSION)
 
-        version = pkg_version.parse(self._firmware_version)
-        if version < pkg_version.parse("1.2.0"):
-            self._api_version = "v1"
-        elif version >= pkg_version.parse("5.0.0"):
-            # BSB-LAN 5.0+ has breaking changes but uses v3-compatible API
-            self._api_version = "v3"
-        elif version >= pkg_version.parse("3.0.0"):
-            self._api_version = "v3"
-        else:
+        firmware_version = pkg_version.parse(self._firmware_version)
+        if firmware_version < pkg_version.parse("3.0.0"):
             raise BSBLANVersionError(ErrorMsg.VERSION)
+        self._api_version = SUPPORTED_API_VERSION
 
     async def _fetch_temperature_range(
         self,
@@ -596,10 +596,26 @@ async def _fetch_temperature_range(
             circuit: The heating circuit number (1 or 2).
 
         Returns:
-            dict with 'min' and 'max' keys (values may be None if unavailable).
+            dict with heating and cooling min/max keys. Values may be None if
+            unavailable.
 
         """
-        temp_range: dict[str, float | None] = {"min": None, "max": None}
+        temp_range: dict[str, float | None] = {
+            "min": None,
+            "max": None,
+            "cooling_min": None,
+            "cooling_max": None,
+        }
+        if (
+            self._available_circuits is not None
+            and circuit not in self._available_circuits
+        ):
+            logger.debug(
+                "Skipping temperature range fetch for unavailable circuit %d",
+                circuit,
+            )
+            return temp_range
+
         try:
             static_values = await self.static_values(circuit=circuit)
         except BSBLANError as err:
@@ -627,6 +643,22 @@ async def _fetch_temperature_range(
                 temp_range["max"],
             )
 
+        if static_values.cooling_comfort_setpoint_min is not None:
+            temp_range["cooling_min"] = static_values.cooling_comfort_setpoint_min.value
+            logger.debug(
+                "Circuit %d cooling min temp initialized: %s",
+                circuit,
+                temp_range["cooling_min"],
+            )
+
+        if static_values.cooling_reduced_setpoint is not None:
+            temp_range["cooling_max"] = static_values.cooling_reduced_setpoint.value
+            logger.debug(
+                "Circuit %d cooling max temp initialized: %s",
+                circuit,
+                temp_range["cooling_max"],
+            )
+
         return temp_range
 
     async def _initialize_temperature_range(
@@ -703,7 +735,9 @@ def _copy_api_config(self) -> APIConfig:
         """
         if self._api_version is None:
             raise BSBLANError(ErrorMsg.API_VERSION)
-        source_config: APIConfig = API_VERSIONS[self._api_version]
+        if self._api_version != SUPPORTED_API_VERSION:
+            raise BSBLANVersionError(ErrorMsg.VERSION)
+        source_config: APIConfig = API_V3
         return cast(
             "APIConfig",
             {
@@ -1215,11 +1249,14 @@ async def _prepare_thermostat_state(
                 },
             )
         if target_temperature_high is not None:
-            self._validate_target_temperature_high(target_temperature_high)
             param_id = param_ids.get("target_temperature_high")
             if param_id is None:
                 parameter_name = "target_temperature_high"
                 raise BSBLANInvalidParameterError(parameter_name)
+            await self._validate_target_temperature_high(
+                target_temperature_high,
+                circuit,
+            )
             state.update(
                 {
                     "Parameter": param_id,
@@ -1247,16 +1284,30 @@ def _thermostat_params(self, circuit: int) -> dict[str, str]:
             return {"target_temperature": "15004", "hvac_mode": "15000"}
         return CircuitConfig.THERMOSTAT_PARAMS[circuit]
 
-    def _validate_target_temperature_high(
+    async def _validate_target_temperature_high(
         self,
         target_temperature_high: str | float,
+        circuit: int = 1,
     ) -> None:
         """Validate the cooling target temperature value."""
         try:
-            float(target_temperature_high)
+            temp = float(target_temperature_high)
         except ValueError as err:
             raise BSBLANInvalidParameterError(str(target_temperature_high)) from err
 
+        if circuit not in self._circuit_temp_initialized:
+            await self._initialize_temperature_range(circuit)
+
+        temp_range = self._circuit_temp_ranges.get(circuit, {})
+        min_temp = temp_range.get("cooling_min")
+        max_temp = temp_range.get("cooling_max")
+
+        if min_temp is None or max_temp is None:
+            return
+
+        if not (min_temp <= temp <= max_temp):
+            raise BSBLANInvalidParameterError(str(target_temperature_high))
+
     async def _validate_target_temperature(
         self,
         target_temperature: str,

src/bsblan/constants.py

@@ -10,7 +10,10 @@
 MAX_CIRCUIT: Final[int] = 2
 
 
-# API Versions
+# API version
+SUPPORTED_API_VERSION: Final[str] = "v3"
+
+
 class APIConfig(TypedDict):
     """Type for API configuration."""
 
@@ -24,7 +27,7 @@ class APIConfig(TypedDict):
     staticValues_circuit2: dict[str, str]
 
 
-# Base parameters that exist in all API versions
+# Supported BSB-LAN v3 API parameters
 BASE_HEATING_PARAMS: Final[dict[str, str]] = {
     "700": "hvac_mode",
     "710": "target_temperature",
@@ -33,10 +36,15 @@ class APIConfig(TypedDict):
     # -------
     "8000": "hvac_action",
     "8740": "current_temperature",
+    "770": "room1_temp_setpoint_boost",
 }
 
 BASE_STATIC_VALUES_PARAMS: Final[dict[str, str]] = {
-    "714": "min_temp",
+    "712": "min_temp",
+    "714": "heating_protective_setpoint",
+    "716": "max_temp",
+    "905": "cooling_comfort_setpoint_min",
+    "903": "cooling_reduced_setpoint",
 }
 
 BASE_DEVICE_PARAMS: Final[dict[str, str]] = {
@@ -85,34 +93,25 @@ class APIConfig(TypedDict):
     "576": "dhw_time_program_standard_values",
 }
 
-# V1-specific parameters
-V1_STATIC_VALUES_EXTENSIONS: Final[dict[str, str]] = {
-    "730": "max_temp",  # V1 uses 730 for max_temp
-}
-
-# V3-specific additional parameters
-V3_HEATING_EXTENSIONS: Final[dict[str, str]] = {
-    "770": "room1_temp_setpoint_boost",
-    # Future V3 extensions like 701, 701.1, 701.2 can be added here
-}
-
-V3_STATIC_VALUES_EXTENSIONS: Final[dict[str, str]] = {
-    "716": "max_temp",  # V3 uses 716 for max_temp
-}
-
 # --- Heating Circuit 2 parameters (1000-series) ---
 # These mirror HC1 (700-series) with an offset of +300
 BASE_HEATING_CIRCUIT2_PARAMS: Final[dict[str, str]] = {
     "1000": "hvac_mode",
     "1010": "target_temperature",
     "1200": "hvac_mode_changeover",
+    "1202": "target_temperature_high",
     # -------
     "8001": "hvac_action",
     "8770": "current_temperature",
+    "1070": "room1_temp_setpoint_boost",
 }
 
 BASE_STATIC_VALUES_CIRCUIT2_PARAMS: Final[dict[str, str]] = {
-    "1014": "min_temp",
+    "1012": "min_temp",
+    "1014": "heating_protective_setpoint",
+    "1016": "max_temp",
+    "1205": "cooling_comfort_setpoint_min",
+    "1203": "cooling_reduced_setpoint",
 }
 
 # PPS bus supports one room-unit style climate circuit. These parameters are
@@ -128,18 +127,6 @@ class APIConfig(TypedDict):
     "15007": "max_temp",
 }
 
-V1_STATIC_VALUES_CIRCUIT2_EXTENSIONS: Final[dict[str, str]] = {
-    "1030": "max_temp",
-}
-
-V3_HEATING_CIRCUIT2_EXTENSIONS: Final[dict[str, str]] = {
-    "1070": "room1_temp_setpoint_boost",
-}
-
-V3_STATIC_VALUES_CIRCUIT2_EXTENSIONS: Final[dict[str, str]] = {
-    "1016": "max_temp",
-}
-
 
 # Circuit configuration
 class CircuitConfig:
@@ -160,7 +147,11 @@ class CircuitConfig:
             "target_temperature_high": "902",
             "hvac_mode": "700",
         },
-        2: {"target_temperature": "1010", "hvac_mode": "1000"},
+        2: {
+            "target_temperature": "1010",
+            "target_temperature_high": "1202",
+            "hvac_mode": "1000",
+        },
     }
     PROBE_PARAMS: Final[dict[int, str]] = {
         1: "700",
@@ -173,16 +164,23 @@ class CircuitConfig:
     INACTIVE_MARKER: Final[str] = "---"
 
 
-def build_api_config(version: str) -> APIConfig:
-    """Build API configuration dynamically based on version.
+def build_api_config(version: str = SUPPORTED_API_VERSION) -> APIConfig:
+    """Build the supported v3 API configuration.
 
     Args:
-        version: The API version ("v1" or "v3")
+        version: The API version to build. Only ``"v3"`` is supported.
 
     Returns:
-        APIConfig: The complete API configuration for the specified version
+        APIConfig: The complete API configuration.
+
+    Raises:
+        ValueError: If a version other than ``"v3"`` is requested.
 
     """
+    if version != SUPPORTED_API_VERSION:
+        msg = f"Only API version {SUPPORTED_API_VERSION} is supported"
+        raise ValueError(msg)
+
     config: APIConfig = {
         "heating": BASE_HEATING_PARAMS.copy(),
         "staticValues": BASE_STATIC_VALUES_PARAMS.copy(),
@@ -193,31 +191,11 @@ def build_api_config(version: str) -> APIConfig:
         "heating_circuit2": BASE_HEATING_CIRCUIT2_PARAMS.copy(),
         "staticValues_circuit2": BASE_STATIC_VALUES_CIRCUIT2_PARAMS.copy(),
     }
-
-    if version == "v1":
-        config["staticValues"].update(V1_STATIC_VALUES_EXTENSIONS)
-        config["staticValues_circuit2"].update(
-            V1_STATIC_VALUES_CIRCUIT2_EXTENSIONS,
-        )
-    elif version == "v3":
-        config["heating"].update(V3_HEATING_EXTENSIONS)
-        config["staticValues"].update(V3_STATIC_VALUES_EXTENSIONS)
-        config["heating_circuit2"].update(V3_HEATING_CIRCUIT2_EXTENSIONS)
-        config["staticValues_circuit2"].update(
-            V3_STATIC_VALUES_CIRCUIT2_EXTENSIONS,
-        )
-
     return config
 
 
-# Pre-built API configurations
-API_V1: Final[APIConfig] = build_api_config("v1")
-API_V3: Final[APIConfig] = build_api_config("v3")
-
-API_VERSIONS: Final[dict[str, APIConfig]] = {
-    "v1": API_V1,
-    "v3": API_V3,
-}
+# Pre-built API configuration
+API_V3: Final[APIConfig] = build_api_config()
 
 
 # Validation constants