bsblan-parameters

liudger's avatarfrom liudger

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.

⭐4stars🔀2forks📁View on GitHub🕐Updated Jan 10, 2026⬇️2downloads

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.
namebsblan-parameters
descriptionAdd 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_case for 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.