Add comprehensive documentation and refactor forecast metrics#379
Closed
MaStr wants to merge 5 commits into
Closed
Add comprehensive documentation and refactor forecast metrics#379MaStr wants to merge 5 commits into
MaStr wants to merge 5 commits into
Conversation
Replace all references to muexx/batcontrol with mastr950/batcontrol in README.md. https://claude.ai/code/session_01QxmdmZEMbLQHjpgro1yURH Co-authored-by: Claude <noreply@anthropic.com>
Bumps [codecov/codecov-action](https://github.com/codecov/codecov-action) from 6 to 7. - [Release notes](https://github.com/codecov/codecov-action/releases) - [Changelog](https://github.com/codecov/codecov-action/blob/main/CHANGELOG.md) - [Commits](codecov/codecov-action@v6...v7) --- updated-dependencies: - dependency-name: codecov/codecov-action dependency-version: '7' dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <support@github.com>
* Migrate GitHub wiki into MkDocs documentation site Move all 13 wiki pages into a structured docs/ tree (getting-started, configuration, features, integrations, development) so the repository becomes the single source of truth for documentation. - Add mkdocs.yml with Material theme and navigation - Add docs deploy workflow publishing to GitHub Pages on push to main - Add 'docs' optional dependency group (mkdocs-material) - Vendor externally hosted images into docs/assets - Rewrite wiki-style and stale fork-wiki links to relative doc paths - Fix 'Price-difference-calcualtion' filename typo - Replace docs/WIKI_peak_shaving.md with the newer wiki version - Point README and config template links to the new docs site Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Scope ASCII-only rule to source code, update docs contribution guideline The ASCII-only rule applies to source code and log messages, not to documentation in docs/. Replace the obsolete WIKI_ prefix workflow with the MkDocs-based docs/ workflow. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
) * Fix documentation inaccuracies found by verifying against the code Corrections (code is the source of truth): - enable_resilient_wrapper default is false, not true - MQTT inverter SoC defaults in README are 5/100, not 10/95 - max_charging_from_grid_limit default is 80%, not 89% - Config key is min_price_difference_rel, not min_price_difference_relative - history_weights uses semicolons ("1;1;1"); comma example would crash parsing - evcc solar forecast endpoint is /api/tariff/solar, not /api/tariff/grid - SOC topic publishes a two-decimal float, not a 3-digit integer - discharge_blocked publishes lowercase true/false - peak_shaving mode and price_limit ARE runtime-settable via MQTT /set - combined mode without price_limit falls back to time-only with a warning, it is not silently disabled - battery_halt_topic has no default; feature is disabled when unset - MQTT inverter default topic structure uses 'inverters/' (plural) Additions: - Document mode 8 (limit battery charge rate) in the MQTT API - Document previously missing MQTT topics: min_grid_charge_soc(_percent), limit_battery_charge_rate, production_offset, api_override_active, control_source, solar_surplus_wh, solar_active, night_surplus_wh, peak_shaving/*, and the matching /set input topics - Document dynamic network fees (para. 14a EnWG, dynamic_network_fees) - Document evcc loadpoint mode/connected subscriptions and their peak-shaving interaction - Mark MQTT/evcc TLS support as non-functional (contradictory config handling in code) instead of merely untested - Mention all available providers in the architecture overview Plus minor typo and broken-link fixes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Address review feedback: use the real mqtt.topic config key The MQTT base topic is configured via 'topic' in the mqtt section (mqtt_api.py reads config['topic']), not 'base_topic'; the username key is 'username', not 'user'. Fix the placeholder and the connection example accordingly. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
…ttery_wh Extract the forecast-derived battery metrics from core.py into a new stateless ForecastMetrics class (src/batcontrol/forecast_metrics.py) and replace the single night_surplus_wh metric with two clearer indicators: - pv_start_battery_wh: battery level (Wh above MIN_SOC) at the next net-charging crossover, simulated slot-by-slot with floor/ceiling clamping. Direct successor of night_surplus_wh. - forecast_min_battery_wh: minimum battery level over the entire forecast horizon; 0 signals an expected shortage. MQTT API changes: - Publish the two new topics and HA discovery entries; remove the night_surplus_wh entry and clean up its retained discovery config via an empty retained payload (tombstone, remove in 0.9.1). - Fix stale net_consumption by recomputing it after the slot-0 elapsed-time factorization. Documentation: - New MkDocs page docs/features/forecast-metrics.md describing all metrics, their semantics, a decision matrix and concrete use cases (heat pump on PV surplus, EV charging, overnight flexible loads, multi-day shortage guard). - Update the MQTT API topic list and mkdocs.yml navigation. Tests: rename test_night_surplus.py to test_pv_battery_metrics.py and cover both new metrics; adapt test_solar_surplus.py and test_mqtt_api.py to the ForecastMetrics extraction. https://claude.ai/code/session_0151Lxg9ZSesbGBUA9odRA64
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a new ForecastMetrics helper to compute forecast-derived battery metrics in a stateless/testable way, updates core.py and MQTT publishing to use the new metrics, and adds a MkDocs-based documentation site with GitHub Pages deployment.
Changes:
- Refactor forecast metric calculations into
src/batcontrol/forecast_metrics.pyand wire them intocore.py+ MQTT. - Update/expand pytest coverage for the new metrics and remove the legacy night-surplus tests.
- Add MkDocs documentation site + deployment workflow and migrate user docs into
docs/.
Reviewed changes
Copilot reviewed 30 out of 34 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
src/batcontrol/forecast_metrics.py |
New stateless forecast metrics helpers |
src/batcontrol/core.py |
Use ForecastMetrics + publish new metrics |
src/batcontrol/mqtt_api.py |
New MQTT publishers + HA discovery updates |
tests/batcontrol/test_solar_surplus.py |
Test solar_active_and_surplus() directly |
tests/batcontrol/test_pv_battery_metrics.py |
New tests for PV-start + min-battery |
tests/batcontrol/test_night_surplus.py |
Removed legacy night surplus tests |
tests/batcontrol/test_mqtt_api.py |
Adjust discovery stubs for new usage |
README.md |
Point to new docs site + update examples |
pyproject.toml |
Add docs dependency group |
mkdocs.yml |
MkDocs Material configuration + nav |
docs/index.md |
New docs landing page |
docs/getting-started/how-batcontrol-works.md |
New getting-started explanation |
docs/configuration/batcontrol-configuration.md |
New config reference page |
docs/configuration/inverter-configuration.md |
New inverter configuration page |
docs/configuration/dynamic-tariff-provider.md |
New tariff provider config page |
docs/configuration/solar-forecast.md |
New solar forecast config page |
docs/configuration/consumption-forecast.md |
New consumption forecast config page |
docs/features/forecast-metrics.md |
Document new forecast metrics + migration |
docs/features/peak-shaving.md |
Peak shaving documentation (new location) |
docs/features/price-difference-calculation.md |
Price-diff documentation page |
docs/features/battery-control-expert.md |
Expert tuning documentation page |
docs/integrations/mqtt-api.md |
MQTT API documentation page |
docs/integrations/mqtt-inverter.md |
MQTT inverter integration documentation |
docs/integrations/evcc-connection.md |
EVCC integration documentation page |
docs/WIKI_peak_shaving.md |
Removed old wiki-prefixed peak shaving doc |
.github/workflows/docs.yml |
New GitHub Pages docs deployment workflow |
.github/workflows/pytest.yml |
Update Codecov action version |
.gitignore |
Ignore MkDocs site/ output |
config/batcontrol_config_dummy.yaml |
Update links to new docs site |
.github/copilot-instructions.md |
Update contribution/docs guidance |
CLAUDE.md |
Align guidelines + pitfalls with new docs |
.github/workflows/pytest.yml |
Codecov action bump to v7 |
Comments suppressed due to low confidence (1)
src/batcontrol/mqtt_api.py:36
- The module docstring says the /FCST/* forecast arrays are published in W, but the forecast providers and core logic operate on energy per interval (Wh per slot), especially important in 15-minute mode. This docstring should describe the published unit as Wh per interval to avoid downstream consumers misinterpreting values by up to 4x.
- /forecast_min_battery_wh: minimum battery level in Wh (above MIN_SOC) over the entire forecast horizon (0 = shortage expected)
The following statistical arrays are published as JSON arrays:
- /FCST/production: forecasted production in W
- /FCST/consumption: forecasted consumption in W
Comment on lines
+129
to
+133
| ### Forecasts (JSON Arrays) | ||
| - `house/batcontrol/FCST/production` - Forecasted solar production in W | ||
| - `house/batcontrol/FCST/consumption` - Forecasted consumption in W | ||
| - `house/batcontrol/FCST/prices` - Forecasted electricity prices in EUR | ||
| - `house/batcontrol/FCST/net_consumption` - Forecasted net consumption in W |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR adds comprehensive user-facing documentation for batcontrol and refactors forecast metric calculations into a dedicated
ForecastMetricsclass for better maintainability and testability.Key Changes
Documentation (New)
docs.yml) for automatic documentation deployment on push to mainCode Refactoring
New
ForecastMetricsclass (src/batcontrol/forecast_metrics.py)solar_active_and_surplus()— solar production flag and expected PV overflowpv_start_battery()— battery level at next net-charging pointforecast_min_battery()— minimum battery level over forecast horizoncore.pyUpdated
core.pyForecastMetricsmethods instead of internal_compute_*methods_compute_solar_active_and_surplus()and_compute_night_surplus()methodsnet_consumptioncalculation for claritypv_start_battery_wh,forecast_min_battery_wh)Updated
mqtt_api.pynight_surplus_whtopv_start_battery_whandforecast_min_battery_whTesting
New test file
tests/batcontrol/test_pv_battery_metrics.pypv_start_battery()andforecast_min_battery()metricsRefactored test file
tests/batcontrol/test_solar_surplus.pyForecastMetrics.solar_active_and_surplus()directlyBatcontrolstub mockingRemoved test file
tests/batcontrol/test_night_surplus.pytest_pv_battery_metrics.pywith improved metric semanticsConfiguration & Build
mkdocs-materialdependency for documentation buildssite/directory for MkDocs build outputImplementation Details
The
ForecastMetricsclass uses pure functions with no shared state, making metrics computation transparent and testable. All methods accept forecast arrays and battery state as parameters and return computed values, enabling external automations (Home Assistant, evcc, Node-RED) to make smarter decisions about flexible loads without re-implementing forecast simulation.The refactoring maintains backward compatibility in MQTT topic structure while improving semantic clarity of the published metrics.
https://claude.ai/code/session_0151Lxg9ZSesbGBUA9odRA64