python-bsblan 5.0.0__tar.gz → 5.1.0__tar.gz

{python_bsblan-5.0.0 → python_bsblan-5.1.0}/.github/copilot-instructions.md

@@ -211,8 +211,26 @@ Test fixtures (JSON responses) are in `tests/fixtures/`
 
 ## Common Tasks
 
+### Fetching Parameters from a Real Device
+
+Use `examples/fetch_param.py` to query raw parameter data from a real BSB-LAN device before adding new parameters:
+
+```bash
+# Set your device connection details
+# Leave BSBLAN_HOST unset to use auto-discovery, or set it explicitly:
+export BSBLAN_HOST="192.168.1.100"
+export BSBLAN_PASSKEY=your_passkey  # if needed
+
+# Fetch one or more parameters
+cd examples && python fetch_param.py 1645
+cd examples && python fetch_param.py 1645 1641 1642 1644 1646
+```
+
+The output shows the raw JSON response including value, unit, description, and data type — use this to determine the correct model field type and naming.
+
 ### Adding a New Settable Parameter
 
+0. Fetch the parameter from a real device using `examples/fetch_param.py` to inspect the raw response
 1. Add parameter ID mapping in `constants.py`
 2. Add field to appropriate model in `models.py`
 3. Add parameter to method signature in `bsblan.py`

{python_bsblan-5.0.0 → python_bsblan-5.1.0}/.github/skills/bsblan-parameters/SKILL.md

@@ -14,6 +14,57 @@ This skill guides you through adding new parameters to the python-bsblan library
 - Legionella-related parameters use `legionella_function_*` prefix
 - DHW (Domestic Hot Water) parameters use `dhw_*` prefix
 
+## Discovering Parameters from a Real System
+
+Before adding a new parameter, use `examples/fetch_param.py` to retrieve the raw API response from a real BSB-LAN device. This shows the exact structure, data types, units, and descriptions returned by the device.
+
+### Setup
+
+```bash
+# Set environment variables for your device
+export BSBLAN_HOST=<ip-or-host>     # Your BSB-LAN IP address; leave unset to use autodiscovery
+export BSBLAN_PASSKEY=your_passkey  # Optional: if your device requires a passkey
+export BSBLAN_USER=username         # Optional: if authentication is enabled
+export BSBLAN_PASS=password         # Optional: if authentication is enabled
+export BSBLAN_PORT=80               # Optional: defaults to 80
+```
+
+### Fetching Parameters
+
+```bash
+# Fetch a single parameter
+cd examples && python fetch_param.py 1645
+
+# Fetch multiple parameters at once
+cd examples && python fetch_param.py 1645 1641 1642 1644 1646
+```
+
+### Example Output
+
+The raw API response shows the exact structure you need to model:
+
+```json
+{
+  "1645": {
+    "name": "Legionella function setpoint",
+    "value": "70.0",
+    "unit": "°C",
+    "desc": "",
+    "dataType": 0
+  }
+}
+```
+
+Use this output to determine:
+- **Field type**: `float`, `int`, or `str` based on the `value` format
+- **Unit**: The `unit` field (e.g., `°C`, `%`, `-`)
+- **Description**: The `name` field for docstrings
+- **Data type**: The `dataType` field for `EntityInfo` typing
+
+### Device Discovery
+
+`fetch_param.py` uses mDNS/Zeroconf discovery (via `examples/discovery.py`) to find your BSB-LAN device automatically when `BSBLAN_HOST` is not set. If mDNS is unavailable, set the `BSBLAN_HOST` environment variable directly.
+
 ## Steps to Add a New Parameter
 
 ### 1. Add to `constants.py`

{python_bsblan-5.0.0 → python_bsblan-5.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-bsblan
-Version: 5.0.0
+Version: 5.1.0
 Summary: Asynchronous Python client for BSBLAN API
 Project-URL: Homepage, https://github.com/liudger/python-bsblan
 Project-URL: Repository, https://github.com/liudger/python-bsblan

{python_bsblan-5.0.0 → python_bsblan-5.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-bsblan"
-version = "5.0.0"
+version = "5.1.0"
 description = "Asynchronous Python client for BSBLAN API"
 authors = [
     {name = "Willem-Jan van Rootselaar", email = "liudgervr@gmail.com"}
@@ -187,7 +187,7 @@ dev = [
     "flake8-simplify==0.30.0",
     # hatch is required to support type hinting and proper packaging of the py.typed file.
     "hatch>=1.14.1",
-    "isort==7.0.0",
+    "isort==8.0.0",
     "ty==0.0.18",
     "prek>=0.3.3",
     "pre-commit-hooks==6.0.0",

{python_bsblan-5.0.0 → python_bsblan-5.1.0}/src/bsblan/bsblan.py

@@ -22,13 +22,20 @@ from .constants import (
     API_VALIDATOR_NOT_INITIALIZED_ERROR_MSG,
     API_VERSION_ERROR_MSG,
     API_VERSIONS,
+    CIRCUIT_HEATING_SECTIONS,
+    CIRCUIT_PROBE_PARAMS,
+    CIRCUIT_STATIC_SECTIONS,
+    CIRCUIT_THERMOSTAT_PARAMS,
     DHW_TIME_PROGRAM_PARAMS,
     EMPTY_INCLUDE_LIST_ERROR_MSG,
+    EMPTY_SECTION_PARAMS_ERROR_MSG,
     FIRMWARE_VERSION_ERROR_MSG,
     HOT_WATER_CONFIG_PARAMS,
     HOT_WATER_ESSENTIAL_PARAMS,
     HOT_WATER_SCHEDULE_PARAMS,
+    INVALID_CIRCUIT_ERROR_MSG,
     INVALID_INCLUDE_PARAMS_ERROR_MSG,
+    INVALID_RESPONSE_ERROR_MSG,
     MAX_VALID_YEAR,
     MIN_VALID_YEAR,
     MULTI_PARAMETER_ERROR_MSG,
@@ -37,9 +44,11 @@ from .constants import (
     NO_SCHEDULE_ERROR_MSG,
     NO_STATE_ERROR_MSG,
     PARAMETER_NAMES_NOT_RESOLVED_ERROR_MSG,
+    SECTION_NOT_FOUND_ERROR_MSG,
     SESSION_NOT_INITIALIZED_ERROR_MSG,
     SETTABLE_HOT_WATER_PARAMS,
     TEMPERATURE_RANGE_ERROR_MSG,
+    VALID_CIRCUITS,
     VALID_HVAC_MODES,
     VERSION_ERROR_MSG,
     APIConfig,
@@ -73,7 +82,17 @@ if TYPE_CHECKING:
 
     from aiohttp.client import ClientSession
 
-SectionLiteral = Literal["heating", "staticValues", "device", "sensor", "hot_water"]
+SectionLiteral = Literal[
+    "heating",
+    "staticValues",
+    "device",
+    "sensor",
+    "hot_water",
+    "heating_circuit2",
+    "heating_circuit3",
+    "staticValues_circuit2",
+    "staticValues_circuit3",
+]
 
 # TypeVar for hot water data models
 HotWaterDataT = TypeVar(
@@ -114,6 +133,11 @@ class BSBLAN:
     _initialized: bool = False
     _api_validator: APIValidator = field(init=False)
     _temperature_unit: str = "°C"
+    # Per-circuit temperature ranges: circuit_number -> (min, max, initialized)
+    _circuit_temp_ranges: dict[int, dict[str, float | None]] = field(
+        default_factory=dict,
+    )
+    _circuit_temp_initialized: set[int] = field(default_factory=set)
     _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)
@@ -155,6 +179,40 @@ class BSBLAN:
             await self._setup_api_validator()
             self._initialized = True
 
+    async def get_available_circuits(self) -> list[int]:
+        """Detect which heating circuits are available on the device.
+
+        Probes the operating mode parameter for each circuit (1, 2, 3).
+        A circuit is considered available if the device returns a non-empty
+        response with a valid value (not empty ``{}``).
+
+        This is useful for integration setup flows (e.g., Home Assistant
+        config flow) to discover how many circuits the user's controller
+        supports.
+
+        Returns:
+            list[int]: Sorted list of available circuit numbers (e.g., [1, 2]).
+
+        Example:
+            async with BSBLAN(config) as client:
+                circuits = await client.get_available_circuits()
+                # circuits == [1, 2] for a dual-circuit controller
+
+        """
+        available: list[int] = []
+        for circuit, param_id in CIRCUIT_PROBE_PARAMS.items():
+            try:
+                response = await self._request(
+                    params={"Parameter": param_id},
+                )
+                # A circuit exists if the response contains the param_id key
+                # with actual data (not an empty dict)
+                if response.get(param_id):
+                    available.append(circuit)
+            except BSBLANError:
+                logger.debug("Circuit %d not available (request failed)", circuit)
+        return sorted(available)
+
     async def _setup_api_validator(self) -> None:
         """Set up the API validator without validating sections.
 
@@ -387,8 +445,8 @@ class BSBLAN:
         try:
             section_data = self._api_data[section]
         except KeyError as err:
-            error_msg = f"Section '{section}' not found in API data"
-            raise BSBLANError(error_msg) from err
+            msg = SECTION_NOT_FOUND_ERROR_MSG.format(section)
+            raise BSBLANError(msg) from err
 
         # Filter to only included params if specified
         if include is not None:
@@ -509,44 +567,96 @@ class BSBLAN:
         else:
             raise BSBLANVersionError(VERSION_ERROR_MSG)
 
-    async def _initialize_temperature_range(self) -> None:
+    async def _fetch_temperature_range(
+        self,
+        circuit: int,
+    ) -> dict[str, float | None]:
+        """Fetch min/max temperature range for a circuit from the device.
+
+        Args:
+            circuit: The heating circuit number (1, 2, or 3).
+
+        Returns:
+            dict with 'min' and 'max' keys (values may be None if unavailable).
+
+        """
+        temp_range: dict[str, float | None] = {"min": None, "max": None}
+        try:
+            static_values = await self.static_values(circuit=circuit)
+        except BSBLANError as err:
+            logger.warning(
+                "Failed to get static values for circuit %d: %s. "
+                "Temperature range will be None",
+                circuit,
+                str(err),
+            )
+            return temp_range
+
+        if static_values.min_temp is not None:
+            temp_range["min"] = static_values.min_temp.value
+            logger.debug(
+                "Circuit %d min temp initialized: %s",
+                circuit,
+                temp_range["min"],
+            )
+
+        if static_values.max_temp is not None:
+            temp_range["max"] = static_values.max_temp.value
+            logger.debug(
+                "Circuit %d max temp initialized: %s",
+                circuit,
+                temp_range["max"],
+            )
+
+        return temp_range
+
+    async def _initialize_temperature_range(
+        self,
+        circuit: int = 1,
+    ) -> None:
         """Initialize the temperature range from static values (lazy loaded).
 
         This method is called on-demand when temperature range is needed.
         It uses lazy loading through static_values() which will validate
         the staticValues section if not already done.
 
+        Args:
+            circuit: The heating circuit number (1, 2, or 3).
+
         Note: Temperature unit is extracted during heating section validation
         from the response (parameter 710), so no extra API call is needed here.
+
         """
-        if not self._temperature_range_initialized:
-            # Try to get temperature range from static values (lazy loaded)
-            try:
-                static_values = await self.static_values()
-                if static_values.min_temp is not None:
-                    self._min_temp = static_values.min_temp.value
-                    logger.debug("Min temperature initialized: %s", self._min_temp)
-                else:
-                    logger.warning(
-                        "min_temp not available from device, "
-                        "temperature range will be None"
-                    )
+        if circuit == 1 and self._temperature_range_initialized:
+            return
+        if circuit != 1 and circuit in self._circuit_temp_initialized:
+            return
 
-                if static_values.max_temp is not None:
-                    self._max_temp = static_values.max_temp.value
-                    logger.debug("Max temperature initialized: %s", self._max_temp)
-                else:
-                    logger.warning(
-                        "max_temp not available from device, "
-                        "temperature range will be None"
-                    )
-            except BSBLANError as err:
-                logger.warning(
-                    "Failed to get static values: %s. Temperature range will be None",
-                    str(err),
-                )
+        temp_range = await self._fetch_temperature_range(circuit)
 
+        if circuit == 1:
+            # HC1 uses legacy fields for backwards compatibility
+            self._min_temp = temp_range["min"]
+            self._max_temp = temp_range["max"]
             self._temperature_range_initialized = True
+        else:
+            # HC2/HC3 use per-circuit storage
+            self._circuit_temp_ranges[circuit] = temp_range
+            self._circuit_temp_initialized.add(circuit)
+
+    def _validate_circuit(self, circuit: int) -> None:
+        """Validate the circuit number.
+
+        Args:
+            circuit: The heating circuit number to validate.
+
+        Raises:
+            BSBLANInvalidParameterError: If the circuit number is invalid.
+
+        """
+        if circuit not in VALID_CIRCUITS:
+            msg = INVALID_CIRCUIT_ERROR_MSG.format(circuit)
+            raise BSBLANInvalidParameterError(msg)
 
     @property
     def get_temperature_unit(self) -> str:
@@ -690,8 +800,8 @@ class BSBLAN:
             raise
         except (ValueError, UnicodeDecodeError) as e:
             # Handle JSON decode errors and other parsing issues
-            error_msg = f"Invalid response format from BSB-LAN device: {e!s}"
-            raise BSBLANError(error_msg) from e
+            msg = INVALID_RESPONSE_ERROR_MSG.format(e)
+            raise BSBLANError(msg) from e
 
     def _process_response(
         self, response_data: dict[str, Any], base_path: str
@@ -826,6 +936,11 @@ class BSBLAN:
 
         section_params = self._api_validator.get_section_params(section)
 
+        # Guard: if validation removed all params, the section is not available
+        if not section_params:
+            msg = EMPTY_SECTION_PARAMS_ERROR_MSG.format(section)
+            raise BSBLANError(msg)
+
         # Filter parameters if include list is specified
         if include is not None:
             if not include:
@@ -843,7 +958,11 @@ class BSBLAN:
         data = dict(zip(params["list"], list(data.values()), strict=True))
         return model_class.model_validate(data)
 
-    async def state(self, include: list[str] | None = None) -> State:
+    async def state(
+        self,
+        include: list[str] | None = None,
+        circuit: int = 1,
+    ) -> State:
         """Get the current state from BSBLAN device.
 
         Args:
@@ -852,6 +971,9 @@ class BSBLAN:
                 hvac_mode, target_temperature, hvac_action,
                 hvac_mode_changeover, current_temperature,
                 room1_thermostat_mode, room1_temp_setpoint_boost.
+            circuit: The heating circuit number (1, 2, or 3). Defaults to 1.
+                Circuit 2 and 3 use separate parameter IDs but return the
+                same State model with the same field names.
 
         Returns:
             State: The current state of the BSBLAN device.
@@ -864,8 +986,15 @@ class BSBLAN:
             # Fetch only hvac_mode and current_temperature
             state = await client.state(include=["hvac_mode", "current_temperature"])
 
+            # Fetch state for heating circuit 2
+            state_hc2 = await client.state(circuit=2)
+
         """
-        return await self._fetch_section_data("heating", State, include)
+        self._validate_circuit(circuit)
+        section: SectionLiteral = cast(
+            "SectionLiteral", CIRCUIT_HEATING_SECTIONS[circuit]
+        )
+        return await self._fetch_section_data(section, State, include)
 
     async def sensor(self, include: list[str] | None = None) -> Sensor:
         """Get the sensor information from BSBLAN device.
@@ -885,13 +1014,18 @@ class BSBLAN:
         """
         return await self._fetch_section_data("sensor", Sensor, include)
 
-    async def static_values(self, include: list[str] | None = None) -> StaticState:
+    async def static_values(
+        self,
+        include: list[str] | None = None,
+        circuit: int = 1,
+    ) -> StaticState:
         """Get the static information from BSBLAN device.
 
         Args:
             include: Optional list of parameter names to fetch. If None,
                 fetches all static parameters. Valid names include:
                 min_temp, max_temp.
+            circuit: The heating circuit number (1, 2, or 3). Defaults to 1.
 
         Returns:
             StaticState: The static information from the BSBLAN device.
@@ -900,8 +1034,15 @@ class BSBLAN:
             # Fetch only min_temp
             static = await client.static_values(include=["min_temp"])
 
+            # Fetch static values for heating circuit 2
+            static_hc2 = await client.static_values(circuit=2)
+
         """
-        return await self._fetch_section_data("staticValues", StaticState, include)
+        self._validate_circuit(circuit)
+        section: SectionLiteral = cast(
+            "SectionLiteral", CIRCUIT_STATIC_SECTIONS[circuit]
+        )
+        return await self._fetch_section_data(section, StaticState, include)
 
     async def device(self) -> Device:
         """Get BSBLAN device info.
@@ -968,6 +1109,7 @@ class BSBLAN:
         self,
         target_temperature: str | None = None,
         hvac_mode: int | None = None,
+        circuit: int = 1,
     ) -> None:
         """Change the state of the thermostat through BSB-Lan.
 
@@ -975,9 +1117,18 @@ class BSBLAN:
             target_temperature (str | None): The target temperature to set.
             hvac_mode (int | None): The HVAC mode to set as raw integer value.
                 Valid values: 0=off, 1=auto, 2=eco, 3=heat.
+            circuit: The heating circuit number (1, 2, or 3). Defaults to 1.
+
+        Example:
+            # Set HC1 temperature
+            await client.thermostat(target_temperature="21.0")
+
+            # Set HC2 mode
+            await client.thermostat(hvac_mode=1, circuit=2)
 
         """
-        await self._initialize_temperature_range()
+        self._validate_circuit(circuit)
+        await self._initialize_temperature_range(circuit)
 
         self._validate_single_parameter(
             target_temperature,
@@ -985,65 +1136,98 @@ class BSBLAN:
             error_msg=MULTI_PARAMETER_ERROR_MSG,
         )
 
-        state = await self._prepare_thermostat_state(target_temperature, hvac_mode)
+        state = await self._prepare_thermostat_state(
+            target_temperature,
+            hvac_mode,
+            circuit,
+        )
         await self._set_device_state(state)
 
     async def _prepare_thermostat_state(
         self,
         target_temperature: str | None,
         hvac_mode: int | None,
+        circuit: int = 1,
     ) -> 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, 2, or 3).
 
         Returns:
             dict[str, Any]: The prepared state for the thermostat.
 
         """
+        param_ids = CIRCUIT_THERMOSTAT_PARAMS[circuit]
         state: dict[str, Any] = {}
         if target_temperature is not None:
-            await self._validate_target_temperature(target_temperature)
+            await self._validate_target_temperature(
+                target_temperature,
+                circuit,
+            )
             state.update(
-                {"Parameter": "710", "Value": target_temperature, "Type": "1"},
+                {
+                    "Parameter": param_ids["target_temperature"],
+                    "Value": target_temperature,
+                    "Type": "1",
+                },
             )
         if hvac_mode is not None:
             self._validate_hvac_mode(hvac_mode)
             state.update(
                 {
-                    "Parameter": "700",
+                    "Parameter": param_ids["hvac_mode"],
                     "Value": str(hvac_mode),
                     "Type": "1",
                 },
             )
         return state
 
-    async def _validate_target_temperature(self, target_temperature: str) -> None:
+    async def _validate_target_temperature(
+        self,
+        target_temperature: str,
+        circuit: int = 1,
+    ) -> None:
         """Validate the target temperature.
 
         This method lazy-loads the temperature range if not already initialized.
 
         Args:
             target_temperature (str): The target temperature to validate.
+            circuit: The heating circuit number (1, 2, or 3).
 
         Raises:
             BSBLANError: If the temperature range cannot be initialized.
             BSBLANInvalidParameterError: If the target temperature is invalid.
 
         """
-        # Lazy load temperature range if needed
-        if self._min_temp is None or self._max_temp is None:
-            await self._initialize_temperature_range()
+        if circuit == 1:
+            # HC1 uses legacy fields for backwards compatibility
+            if self._min_temp is None or self._max_temp is None:
+                await self._initialize_temperature_range(circuit)
+
+            if self._min_temp is None or self._max_temp is None:
+                raise BSBLANError(TEMPERATURE_RANGE_ERROR_MSG)
+
+            min_temp = self._min_temp
+            max_temp = self._max_temp
+        else:
+            # HC2/HC3 use per-circuit storage
+            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("min")
+            max_temp = temp_range.get("max")
 
-        # After initialization attempt, check if we have the range
-        if self._min_temp is None or self._max_temp is None:
-            raise BSBLANError(TEMPERATURE_RANGE_ERROR_MSG)
+            if min_temp is None or max_temp is None:
+                raise BSBLANError(TEMPERATURE_RANGE_ERROR_MSG)
 
         try:
             temp = float(target_temperature)
-            if not (self._min_temp <= temp <= self._max_temp):
+            if not (min_temp <= temp <= max_temp):
                 raise BSBLANInvalidParameterError(target_temperature)
         except ValueError as err:
             raise BSBLANInvalidParameterError(target_temperature) from err