Feature: Lazy loading

[liudger]

🚀 Performance Comparison: Lazy Loading

Before (Eager Loading)

• Initialize(): ~24 seconds
• All sections validated upfront (heating, sensor, staticValues, device, hot_water)
• Hot water section alone: ~7.9 seconds (67% of total init time)

After (Lazy Loading)

• Initialize(): ~0.02 seconds (~1200x faster)
• Only fetches firmware version on init
• Sections validated on-demand when first accessed

Granular Hot Water Loading

Hot water parameters split into 3 groups for more efficient loading:

Group	Params	Method	Use Case
Essential	5	hot_water_state()	Frequent polling
Config	16	hot_water_config()	Advanced settings
Schedule	8	hot_water_schedule()	Time programs

Race Condition Prevention

Added asyncio locks (double-checked locking pattern) to prevent duplicate network requests when concurrent calls access the same section before validation completes.

Home Assistant Impact

• ⚡ Integration loads almost instantly
• 📉 Reduced startup blocking time from ~24s to ~0.02s
• 🔄 Data fetched on-demand, spreading network load over time

Summary

This pull request introduces significant improvements to developer documentation, parameter management, and device discovery for the python-bsblan library. The main highlights include new developer skills and prompt templates, enhanced documentation on parameter grouping and lazy loading, and the addition of mDNS-based device discovery (via Zeroconf) for easier setup and testing. The example control script is updated to use these new discovery features, and dependency management is updated accordingly.

Documentation and Developer Guidance:

• Added new skill guides for parameter management (.github/skills/bsblan-parameters/SKILL.md) and testing (.github/skills/bsblan-testing/SKILL.md), covering naming conventions, step-by-step instructions, test patterns, coverage requirements, and validation commands. [1] [2]
• Introduced prompt templates for adding parameters and code reviews, standardizing the process and requirements for contributions (.github/prompts/add-parameter.prompt.md, .github/prompts/code-review.prompt.md). [1] [2]

Parameter Grouping and Lazy Loading:

• Updated documentation to explain new hot water parameter groups (essential, config, schedule) and their mapping to lazy-loaded API methods, improving clarity for contributors (.github/copilot-instructions.md). [1] [2]
• Added internal tracking (_validated_hot_water_groups) to the BSBLAN class for managing which hot water parameter groups have been validated, supporting the new lazy loading architecture (src/bsblan/bsblan.py).

Device Discovery and Example Improvements:

• Added a new examples/discovery.py utility that uses mDNS/Zeroconf to discover BSB-LAN devices on the local network, and provides helpers for retrieving device host/port from the environment or discovery.
• Updated the example control script to use the new discovery utility and environment-based configuration instead of hardcoded values, improving ease of use and portability (examples/control.py). [1] [2] [3]

Dependency Management:

• Added zeroconf as a development dependency to support mDNS-based device discovery (pyproject.toml).

[Copilot]

Pull request overview

This pull request introduces lazy loading for improved initialization performance and adds mDNS device discovery via Zeroconf. The main objective is to defer section validation until data is actually needed, significantly reducing startup time for the python-bsblan library (important for Home Assistant integration).

Changes:

• Implemented lazy loading architecture: minimal initialization (firmware only) with on-demand section validation
• Added granular hot water parameter validation (validates only essential/config/schedule groups as needed, not all 29 params)
• Added mDNS/Zeroconf device discovery utility and updated examples to use environment-based configuration
• Enhanced developer documentation with skill guides, prompt templates, and lazy loading architecture details

Reviewed changes

Copilot reviewed 16 out of 17 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/bsblan/bsblan.py	Core lazy loading implementation: _setup_api_validator(), _ensure_section_validated(), and _ensure_hot_water_group_validated() methods for on-demand validation; _validate_target_temperature() now async with lazy temperature range initialization
tests/test_temperature_validation.py	Updated temperature validation tests to async with lazy loading support
tests/test_state.py	Changed validated section from "state" to "heating" (correct for lazy loading)
tests/test_initialization.py	Updated to test new _setup_api_validator() instead of multiple initialization methods
tests/test_hotwater_state.py	Added test setup to mark hot water groups as validated
tests/test_hot_water_additional.py	Added granular validation tests and updated existing tests to mark groups as validated
examples/discovery.py	New mDNS discovery utility using Zeroconf for finding BSB-LAN devices
examples/control.py	Updated to use discovery utility and environment variables instead of hardcoded values
examples/profile_init.py	New profiling utility to measure lazy loading performance improvements
pyproject.toml	Added zeroconf>=0.148.0 as development dependency
uv.lock	Lock file updated with zeroconf and ifaddr dependencies
.github/copilot-instructions.md	Added hot water parameter groups table and lazy loading architecture documentation
.github/skills/bsblan-parameters/SKILL.md	New skill guide for adding parameters with hot water group mappings
.github/skills/bsblan-testing/SKILL.md	New skill guide for testing patterns and lazy loading test setup
.github/prompts/add-parameter.prompt.md	New prompt template for adding parameters
.github/prompts/code-review.prompt.md	New prompt template for code reviews

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.87%. Comparing base (c2d32ba) to head (ecf599b).
⚠️ Report is 14 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1307      +/-   ##
==========================================
+ Coverage   99.60%   99.87%   +0.27%     
==========================================
  Files           6        6              
  Lines         767      827      +60     
  Branches       83      102      +19     
==========================================
+ Hits          764      826      +62     
+ Partials        3        1       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[sonarqubecloud]

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud