bsblan-parameters
Add new BSB-LAN parameters to the python-bsblan library. Use this skill when adding parameter IDs, updating models, or extending the API to support new heating controller parameters.
When & Why to Use This Skill
This Claude skill streamlines the process of extending the python-bsblan library by providing a structured workflow for adding new BSB-LAN parameters. It automates the modification of constants, data models, and API methods, ensuring that new heating controller features are integrated with consistent naming conventions, proper concurrency safety, and comprehensive test coverage.
Use Cases
- Adding support for new heating system parameters such as Legionella functions or Domestic Hot Water (DHW) settings to the python-bsblan library.
- Extending the library's API to support new hardware models or firmware updates for BSB-LAN controllers.
- Automating the generation of boilerplate code for parameter mapping, dataclass models, and asynchronous API methods.
- Ensuring code quality and consistency by generating unit tests and validation logic for newly added parameters.
| name | bsblan-parameters |
|---|---|
| description | Add new BSB-LAN parameters to the python-bsblan library. Use this skill when adding parameter IDs, updating models, or extending the API to support new heating controller parameters. |
Adding BSB-LAN Parameters
This skill guides you through adding new parameters to the python-bsblan library.
Parameter Naming Conventions
- Use
snake_casefor all parameter names - Group related parameters with common prefixes
- Legionella-related parameters use
legionella_function_*prefix - DHW (Domestic Hot Water) parameters use
dhw_*prefix
Steps to Add a New Parameter
1. Add to constants.py
Add the parameter ID mapping:
BASE_HOT_WATER_PARAMS: Final[dict[str, str]] = {
"1645": "legionella_function_setpoint", # Parameter ID: name
}
2. Add to Model in models.py
Add the field to the appropriate dataclass:
@dataclass
class HotWaterConfig(DataClassORJSONMixin):
legionella_function_setpoint: ParameterValue | None = None
3. Update Method in bsblan.py (if settable)
Add parameter to the method signature:
async def set_hot_water(
self,
legionella_function_setpoint: float | None = None,
) -> None:
4. Add Tests
Create tests in tests/test_*.py:
@pytest.mark.asyncio
async def test_set_hot_water(mock_bsblan: BSBLAN) -> None:
"""Test setting BSBLAN hot water state."""
await mock_bsblan.set_hot_water(nominal_setpoint=60.0)
mock_bsblan._request.assert_awaited_with(
base_path="/JS",
data={"Parameter": "1610", "Value": "60.0", "Type": "1"},
)
Polling Categories
Parameters are organized by update frequency:
- Fast Poll (State): Current temperatures, HVAC action/state, pump states
- Slow Poll (Config): Operating modes, setpoints, legionella settings, time programs
- Static: Device identification, min/max temperature limits
Hot Water Parameter Groups
Hot water parameters use granular lazy loading. When adding a new hot water param, add it to the appropriate group in constants.py:
| Group | Constant | Method |
|---|---|---|
| Essential (5 params) | HOT_WATER_ESSENTIAL_PARAMS |
hot_water_state() |
| Config (16 params) | HOT_WATER_CONFIG_PARAMS |
hot_water_config() |
| Schedule (8 params) | HOT_WATER_SCHEDULE_PARAMS |
hot_water_schedule() |
# In constants.py - add to appropriate group set:
HOT_WATER_ESSENTIAL_PARAMS: Final[set[str]] = {"1600", "1610", ...}
HOT_WATER_CONFIG_PARAMS: Final[set[str]] = {"1601", "1614", ...}
Concurrency Safety
The library uses asyncio locks to prevent race conditions:
_section_locks: Per-section locks for lazy loading_hot_water_group_locks: Per-group locks for hot water validation
When adding new sections or groups, the lock is created automatically on first access.
Validation
Always run after changes:
uv run pre-commit run --all-files
uv run pytest --cov=src/bsblan --cov-report=term-missing
Coverage requirements: 95%+ total, 100% patch coverage.