diff --git a/docs/_generated/configdevices.md b/docs/_generated/configdevices.md index 5a9b4fb5..ce09b543 100644 --- a/docs/_generated/configdevices.md +++ b/docs/_generated/configdevices.md @@ -12,14 +12,14 @@ config path from ``self.device_id`` without needing an external index. | Name | Environment Variable | Type | Read-Only | Default | Description | | ---- | -------------------- | ---- | --------- | ------- | ----------- | -| batteries | `EOS_DEVICES__BATTERIES` | `dict[str, akkudoktoreos.devices.settings.batterysettings.BatteriesCommonSettings] | None` | `rw` | `None` | Stationary battery storage devices, keyed by device_id. | -| electric_vehicles | `EOS_DEVICES__ELECTRIC_VEHICLES` | `dict[str, akkudoktoreos.devices.settings.batterysettings.BatteriesCommonSettings] | None` | `rw` | `None` | Electric vehicle battery packs, keyed by device_id. | +| batteries | `EOS_DEVICES__BATTERIES` | `Optional[dict[str, akkudoktoreos.devices.settings.batterysettings.BatteriesCommonSettings]]` | `rw` | `None` | Stationary battery storage devices, keyed by device_id. | +| electric_vehicles | `EOS_DEVICES__ELECTRIC_VEHICLES` | `Optional[dict[str, akkudoktoreos.devices.settings.batterysettings.BatteriesCommonSettings]]` | `rw` | `None` | Electric vehicle battery packs, keyed by device_id. | | home_appliances | `EOS_DEVICES__HOME_APPLIANCES` | `dict[str, akkudoktoreos.devices.settings.homeappliancesettings.HomeApplianceCommonSettings]` | `rw` | `required` | Shiftable home appliance devices, keyed by device_id. | -| inverters | `EOS_DEVICES__INVERTERS` | `dict[str, akkudoktoreos.devices.settings.invertersettings.InverterCommonSettings] | None` | `rw` | `None` | Inverter devices, keyed by device_id. | -| max_batteries | `EOS_DEVICES__MAX_BATTERIES` | `int | None` | `rw` | `None` | Maximum number of batteries allowed. | -| max_electric_vehicles | `EOS_DEVICES__MAX_ELECTRIC_VEHICLES` | `int | None` | `rw` | `None` | Maximum number of EVs allowed. | -| max_home_appliances | `EOS_DEVICES__MAX_HOME_APPLIANCES` | `int | None` | `rw` | `None` | Maximum number of home appliances allowed. | -| max_inverters | `EOS_DEVICES__MAX_INVERTERS` | `int | None` | `rw` | `None` | Maximum number of inverters allowed. | +| inverters | `EOS_DEVICES__INVERTERS` | `Optional[dict[str, akkudoktoreos.devices.settings.invertersettings.InverterCommonSettings]]` | `rw` | `None` | Inverter devices, keyed by device_id. | +| max_batteries | `EOS_DEVICES__MAX_BATTERIES` | `Optional[int]` | `rw` | `None` | Maximum number of batteries allowed. | +| max_electric_vehicles | `EOS_DEVICES__MAX_ELECTRIC_VEHICLES` | `Optional[int]` | `rw` | `None` | Maximum number of EVs allowed. | +| max_home_appliances | `EOS_DEVICES__MAX_HOME_APPLIANCES` | `Optional[int]` | `rw` | `None` | Maximum number of home appliances allowed. | +| max_inverters | `EOS_DEVICES__MAX_INVERTERS` | `Optional[int]` | `rw` | `None` | Maximum number of inverters allowed. | | measurement_keys | | `list[str]` | `ro` | `N/A` | All measurement keys across all configured devices. | ::: @@ -35,6 +35,8 @@ config path from ``self.device_id`` without needing an external index. "batteries": { "bat0": { "device_id": "bat0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 8000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -55,13 +57,21 @@ config path from ``self.device_id`` without needing an external index. 1.0 ], "min_soc_percentage": 0, - "max_soc_percentage": 100 + "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ] } }, "max_batteries": 1, "electric_vehicles": { "ev0": { "device_id": "ev0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 60000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -82,7 +92,13 @@ config path from ``self.device_id`` without needing an external index. 1.0 ], "min_soc_percentage": 0, - "max_soc_percentage": 100 + "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ] } }, "max_electric_vehicles": 1, @@ -116,6 +132,8 @@ config path from ``self.device_id`` without needing an external index. "batteries": { "bat0": { "device_id": "bat0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 8000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -137,6 +155,12 @@ config path from ``self.device_id`` without needing an external index. ], "min_soc_percentage": 0, "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ], "measurement_key_soc_factor": "bat0-soc-factor", "measurement_key_power_l1_w": "bat0-power-l1-w", "measurement_key_power_l2_w": "bat0-power-l2-w", @@ -155,6 +179,8 @@ config path from ``self.device_id`` without needing an external index. "electric_vehicles": { "ev0": { "device_id": "ev0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 60000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -176,6 +202,12 @@ config path from ``self.device_id`` without needing an external index. ], "min_soc_percentage": 0, "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ], "measurement_key_soc_factor": "ev0-soc-factor", "measurement_key_power_l1_w": "ev0-power-l1-w", "measurement_key_power_l2_w": "ev0-power-l2-w", diff --git a/docs/_generated/configexample.md b/docs/_generated/configexample.md index 02bf87bf..908f3ab1 100644 --- a/docs/_generated/configexample.md +++ b/docs/_generated/configexample.md @@ -39,6 +39,8 @@ "batteries": { "bat0": { "device_id": "bat0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 8000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -59,13 +61,21 @@ 1.0 ], "min_soc_percentage": 0, - "max_soc_percentage": 100 + "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ] } }, "max_batteries": 1, "electric_vehicles": { "ev0": { "device_id": "ev0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 60000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -86,7 +96,13 @@ 1.0 ], "min_soc_percentage": 0, - "max_soc_percentage": 100 + "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ] } }, "max_electric_vehicles": 1, @@ -205,6 +221,9 @@ }, "measurement": { "historic_hours": 17520, + "channels": {}, + "household": null, + "energy_context_seconds": 86400, "load_emr_keys": [ "load0_emr" ], diff --git a/docs/_generated/configmeasurement.md b/docs/_generated/configmeasurement.md index 303e6793..c0d58f09 100644 --- a/docs/_generated/configmeasurement.md +++ b/docs/_generated/configmeasurement.md @@ -7,9 +7,12 @@ | Name | Environment Variable | Type | Read-Only | Default | Description | | ---- | -------------------- | ---- | --------- | ------- | ----------- | +| channels | `EOS_MEASUREMENT__CHANNELS` | `dict[str, akkudoktoreos.measurement.measurement.MeasurementChannelSettings]` | `rw` | `required` | Typed raw measurement channels keyed by measurement key. | +| energy_context_seconds | `EOS_MEASUREMENT__ENERGY_CONTEXT_SECONDS` | `int` | `rw` | `86400` | None | | grid_export_emr_keys | `EOS_MEASUREMENT__GRID_EXPORT_EMR_KEYS` | `Optional[list[str]]` | `rw` | `None` | The keys of the measurements that are energy meter readings of energy export to grid [kWh]. | | grid_import_emr_keys | `EOS_MEASUREMENT__GRID_IMPORT_EMR_KEYS` | `Optional[list[str]]` | `rw` | `None` | The keys of the measurements that are energy meter readings of energy import from grid [kWh]. | | historic_hours | `EOS_MEASUREMENT__HISTORIC_HOURS` | `Optional[int]` | `rw` | `17520` | Number of hours into the past for measurement data | +| household | `EOS_MEASUREMENT__HOUSEHOLD` | `Optional[akkudoktoreos.measurement.household.HouseholdSettings]` | `rw` | `None` | Optional household energy balance definition. | | keys | | `list[str]` | `ro` | `N/A` | The keys of the measurements that can be stored. | | load_emr_keys | `EOS_MEASUREMENT__LOAD_EMR_KEYS` | `Optional[list[str]]` | `rw` | `None` | The keys of the measurements that are energy meter readings of a load [kWh]. | | pv_production_emr_keys | `EOS_MEASUREMENT__PV_PRODUCTION_EMR_KEYS` | `Optional[list[str]]` | `rw` | `None` | The keys of the measurements that are PV production energy meter readings [kWh]. | @@ -25,6 +28,9 @@ { "measurement": { "historic_hours": 17520, + "channels": {}, + "household": null, + "energy_context_seconds": 86400, "load_emr_keys": [ "load0_emr" ], @@ -51,6 +57,9 @@ { "measurement": { "historic_hours": 17520, + "channels": {}, + "household": null, + "energy_context_seconds": 86400, "load_emr_keys": [ "load0_emr" ], diff --git a/docs/_generated/openapi.md b/docs/_generated/openapi.md index 4cb3b71d..32f08da2 100644 --- a/docs/_generated/openapi.md +++ b/docs/_generated/openapi.md @@ -1,6 +1,6 @@ # Akkudoktor-EOS -**Version**: `v0.3.0.dev2609161092365525` +**Version**: `v0.3.0.dev2609161038708598` **Description**: This project provides a comprehensive solution for simulating and optimizing an energy system based on renewable energy sources. With a focus on photovoltaic (PV) systems, battery storage (batteries), load management (consumer requirements), heat pumps, electric vehicles, and consideration of electricity price data, this system enables forecasting and optimization of energy flow and costs over a specified period. @@ -880,6 +880,44 @@ Returns: --- +## POST /v1/measurement/battery-capacity/{battery_id} + + +**Links**: [local](http://localhost:8503/docs#/default/post_battery_capacity_v1_measurement_battery-capacity__battery_id__post), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/post_battery_capacity_v1_measurement_battery-capacity__battery_id__post) + + +Post Battery Capacity + + +```python +""" +Estimate capacity from independent SoC anchors and configured DC power. + +store_estimate writes the separate capacity_estimate config field in memory. +Persistence follows the regular EOS configuration save mechanism. +The active capacity_wh and raw measurements are never changed here. +""" +``` + + +**Parameters**: + +- `battery_id` (path, required): No description provided. + +**Request Body**: + +- `application/json`: { + "$ref": "#/components/schemas/BatteryCapacityRequest" +} + +**Responses**: + +- **200**: Successful Response + +- **422**: Validation Error + +--- + ## PUT /v1/measurement/data @@ -940,6 +978,72 @@ Merge the measurement data given as dataframe into EOS measurements. --- +## GET /v1/measurement/energy + + +**Links**: [local](http://localhost:8503/docs#/default/get_energy_v1_measurement_energy_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/get_energy_v1_measurement_energy_get) + + +Get Energy + + +```python +""" +Energy in Wh, with temporal coverage and quality; no missing-to-zero filling. +""" +``` + + +**Parameters**: + +- `key` (query, required): No description provided. + +- `start` (query, required): No description provided. + +- `end` (query, required): No description provided. + +- `interval_seconds` (query, optional): No description provided. + +**Responses**: + +- **200**: Successful Response + +- **422**: Validation Error + +--- + +## GET /v1/measurement/household + + +**Links**: [local](http://localhost:8503/docs#/default/get_household_v1_measurement_household_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/get_household_v1_measurement_household_get) + + +Get Household + + +```python +""" +Site, household without EV, and base without separately measured devices. +""" +``` + + +**Parameters**: + +- `start` (query, required): No description provided. + +- `end` (query, required): No description provided. + +- `interval_seconds` (query, optional): No description provided. + +**Responses**: + +- **200**: Successful Response + +- **422**: Validation Error + +--- + ## GET /v1/measurement/keys @@ -994,6 +1098,73 @@ Delete measurement values for a key within a datetime range. --- +## GET /v1/measurement/samples + + +**Links**: [local](http://localhost:8503/docs#/default/get_samples_v1_measurement_samples_get), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/get_samples_v1_measurement_samples_get) + + +Get Samples + + +```python +""" +Read raw samples including quality, in a bounded half-open range. +""" +``` + + +**Parameters**: + +- `key` (query, required): No description provided. + +- `start` (query, required): No description provided. + +- `end` (query, required): No description provided. + +**Responses**: + +- **200**: Successful Response + +- **422**: Validation Error + +--- + +## PUT /v1/measurement/samples + + +**Links**: [local](http://localhost:8503/docs#/default/put_samples_v1_measurement_samples_put), [eos](https://petstore3.swagger.io/?url=https://raw.githubusercontent.com/Akkudoktor-EOS/EOS/refs/heads/main/openapi.json#/default/put_samples_v1_measurement_samples_put) + + +Put Samples + + +```python +""" +Upsert raw values and their quality; legacy value/series payloads remain valid. +""" +``` + + +**Request Body**: + +- `application/json`: { + "type": "array", + "items": { + "$ref": "#/components/schemas/MeasurementSample" + }, + "maxItems": 10000, + "title": "Samples" +} + +**Responses**: + +- **200**: Successful Response + +- **422**: Validation Error + +--- + ## GET /v1/measurement/series diff --git a/docs/development/eos-consolidation.md b/docs/development/eos-consolidation.md new file mode 100644 index 00000000..1e663acf --- /dev/null +++ b/docs/development/eos-consolidation.md @@ -0,0 +1,168 @@ +# EOS consolidation — integration record + +Status: in progress, not a completed optimizer port. Updated 2026-09-16. + +## Pinned sources + +- Official main: `afb7bcb8bc84769ec2febd34e2dea1b1ad44ddbe`. +- Feature branch: `d2e2d58237339454dd8bb226f92677c5987f8b27`. +- PR #1256: `6ebd343047b87819b57778359784a616452b5f76`, open, conflicts. +- PR #1305: `6fb84765c4b6d2c032fdf83effcb2ea6597f18f9`, open, main target. +- PR #1224: `0b12a34c11685822d97c3bc9f56c6292774cd930`, open, feature target. +- PR #1304: `4b4b49f29902579a8deb34999d71eb2142c0620d`, open, feature target. +- PR #1190 merged into main: GENETIC0 retained separately. + +Sources: https://github.com/Akkudoktor-EOS/EOS/issues/1192 and linked PRs. +Issue body, all issue comments (none), and PR metadata were retrieved from the GitHub API. +Use `refs/remotes/origin/main`: local `refs/heads/origin/main` is ambiguous. + +## Isolation and recovery + +Original EOS worktree remains on the feature branch. No reset, stash or checkout there. +Integration branch: `integration/eos-consolidation-20260916`, sibling directory +`EOS-integration-20260916`. Unmodified main comparison worktree: `EOS-reference-20260916`. + +Private backup: `%USERPROFILE%/.codex/backups/eos-20260916-120324`. +102 modified/untracked files copied byte-for-byte with SHA256 verification; binary +tracked and index patches, original status/refs, verified `repository.bundle`. +See private `RESTORE.md` and `manifest.json` for recovery into a NEW checkout. +Ignored runtime files stay in the original worktree; this is not an archive of its +virtual environment, caches or ignored production datasets. Backup is private and +may include credentials or real measurements; never stage or publish it. +Only explicitly reviewed source/test/document paths are staged for new commits. + +## Functional matrix + +| Area | Evidence | Integration state | +| --- | --- | --- | +| Providers, SMARD, fee model | #1192 checked; main prediction modules and #1235 | Keep main implementation; provider equivalence not yet established | +| GENETIC0 / legacy API | #1190; `core/ems.py`, `server/eos.py`, `optimization/genetic0` | Preserved; device regressions pass, full endpoint validation pending | +| Device maps / algorithm conversion | #1256; `devices/settings`, `config/configmigrate.py` | Merged with original history; four merge conflicts resolved | +| Runtime updates | #1305; `config/config.py`, `core/pydantic.py` | Merged with original history; configuration tests pass | +| Stable IDs / LCOS migration | New `test_consolidation_config.py` | Four initial regression failures fixed; 55 configuration tests pass | +| 15-minute battery/inverter physics | Feature `devices/genetic`, `prediction/interpolator.py` | Ported in c0796e1; parameter classes retained in device modules, export/slot/efficiency tests pass | +| New GENETIC, adaptive evolution, export states | Feature `optimization/genetic/genetic.py` | Pending; current optimizer is not the complete feature optimizer | +| Warm start alignment | Feature d2e2d58, `test_genetic_warm_start_alignment.py` | Pending | +| Control horizon / forecast tail / terminal value | Feature a2f4ef6, `tailvalue.py`, `terminalvalue.py` | Primitives ported in f70a786; 22 tests pass. Optimizer/horizon/API integration pending | +| EV deadlines / flexible consumers | Feature f24d9ea; #1256 cycle windows | Pending reconciliation: preserve both per-cycle windows and profile/deadline semantics | +| Imported feed-in revenue | #1224 + #1304, 38 feature regression cases | Neither PR targets main; adapt after GENETIC preparation port, keep author credit | +| Local calibrated PV | Feature f976335/6dc58c3/faed0fd | Pending; keep public provider ID PVForecastAkkudoktor per #1192 | +| Algorithm-specific PDF | Main #1205 vs feature utils/visualize.py | Keep on-demand API; feature slot/tail fields pending | +| Measurement channels/energy/quality/capacity/household | Original uncommitted source + five new tests | Ported in 7338baf to async storage and keyed devices; 127 related tests passed | +| Request configuration learning | Original uncommitted `genetic/configrequest.py` | Secured only; pending | +| HA-private core differences | Separate private repo | Not ported; no HA files modified, no deployment | + +## Completed packages and tests + +1. `d3f96c4`: merge #1256 onto pinned main. Conflicts in devices.py and three generated + documents; preserve maps/settings and main evolution. Regenerate OpenAPI from + merged code. Do not adopt PR build version bumps. 244 configuration/time-window + tests + 81 device/simulation tests passed before subsequent packages. +2. `b43c8df`: merge #1305 without conflicts. 275 config/configabc/configmigrate/pydantic + tests passed. +3. `e3987b2`: stable map identities, reject key/ID mismatch, preserve renamed LCOS, + repair legacy EV charge-rate migration. 4 regression cases failed before fix; + 55 related tests passed afterwards. These are integration/PR defects, not claimed + as unchanged-main defects. + +Tests currently use the existing Python 3.11.9 environment read-only; pytest adds +this worktree's src. No mutation of the original venv. Missing pypdf 6.19.0 installed into the private +backup test-packages directory and exposed only through test-process PYTHONPATH. +This is not yet validation against every pinned dependency / CI Python version. +Synthetic pytest fixtures; no real devices, server deployment or production config. + +## HA handoff and acceptance + +Do not relocate active feature development to this integration branch yet. +Device collections are keyed maps, with identical map key and device_id. New settings +live in devices/settings; conversion methods derive algorithm parameters. LCOS +configuration is `levelized_cost_of_storage_amt_kwh`; old files migrate. +Runtime config bulk/granular precedence follows #1305. Both algorithms remain +separate; `/optimize` uses GENETIC0 and cannot demonstrate the new GENETIC port. +Pin a final tested commit for HA only after all remaining packages and end-to-end +API/forecast/output tests. No public push, PR, comment or main update is authorized. + + +4. `c0796e1`: slot-duration-aware battery/inverter simulation, bounded per-slot + discharge/export, probabilistic direct-use energy model and GENETIC converter + support for LCOS/export levels. Original author co-authorship retained. + Fixed monetary goldens from the previous model are intentionally replaced with + independent grid-flow repricing. Original simulation test passed on unchanged + main; the changed result is not labelled a baseline failure. +5. `f70a786`: bounded forecast reader, concave terminal value and deterministic + forecast-tail primitives. 22 direct primitive tests passed. Does NOT activate + the new optimization algorithm, warmstart, horizon handling or diagnostic API. +6. `d9c434f`: keep main's charge-rate ndarray contract and exported constant after + #1256. The first broad collection found this missed overlap. +7. `7338baf`: typed measurement channels, sample quality, energy integration, + household accounting and battery capacity estimation. Adapt all storage calls + and endpoints to main's async API; map battery IDs through device collections. + Capacity estimates survive subsequent runtime config updates and never change + the active capacity_wh. 127 new/existing measurement tests passed, including + JSON/SQLite/LMDB restart, partial coverage and real FastAPI routes with no lifespan. + JSON measurement reload regression reproduced on unchanged afb7bcb (0 records + after reload); applying the previously local singleton fix resolves it. +8. `876756b`: replace stochastic GENETIC output equality with schema, independent + per-slot cost/revenue accounting and physical-range assertions. GENETIC0 goldens + remain unchanged. Short optimizer/PDF runs: 4 GENETIC0 and 4 GENETIC pass; one + 400-generation case for each algorithm skipped by the existing --finalize rule. + New household configuration field has documentation metadata. + +### Remaining integration risks and concrete next package + +The current GENETIC orchestration is still the main-era optimizer with the newly +ported device physics. It must NOT be described as the complete feature optimizer. +Next port `optimization/genetic/genetic.py`, its parameter preparation and solution +model together, carrying feature d2e2d58 warmstart and #1304 revenue fixes. Translate +old top-level optimization settings to `optimization.genetic` and main's `_amt_kwh` +prediction keys with explicit /1000 conversion. Use #1256 `to_genetic_*` converters +instead of reintroducing parallel settings. Reconcile flexible profiles/deadlines +with #1256 per-cycle windows/completed cycles before exposing the combined API. +Both porting sides must retain their regression cases. Follow with local PV and +algorithm-specific on-demand PDF; do not copy feature's synchronous/automatic-PDF +server paths over main. Then adapt local configrequest.py to the current API. + +No feature-provider robustness fixes are claimed ported merely because a provider +with the same name exists on main. HA private-core differences remain unaudited. +No full 2030-test suite run, --finalize optimization run, dependency-pin CI matrix, +or physical installation validation has been completed. + +### Backup verification + +An independent clone of repository.bundle at the original feature HEAD was restored +using the backup files. All 102 restored SHA256 hashes match. The original worktree +HEAD and all 102 file hashes were also rechecked unchanged after the source ports. + + +## Reproducing the focused acceptance run + +Use a disposable environment with the repository dependencies plus pytest, +pytest-asyncio, pytest-xprocess, pytest-cov and pypdf. The private backup contains +`test-environment.json`, `integration-final.xml` and the complete collection log. +Run from the integration worktree (not the original feature worktree): + +```powershell +python -m pytest tests/test_typingmodels.py tests/test_config.py tests/test_configabc.py tests/test_configmigrate.py tests/test_configfile.py tests/test_pydantic.py tests/test_consolidation_config.py tests/test_genetichomeappliance.py tests/test_genetic0battery.py tests/test_genetic0inverterefficiency.py tests/test_genetic0simulation.py tests/test_battery.py tests/test_inverter.py tests/test_inverter_efficiency.py tests/test_geneticsimulation.py tests/test_geneticsimulation2.py tests/test_terminalvalue.py tests/test_tailvalue_physics.py tests/test_interpolator.py tests/test_measurement_channels.py tests/test_measurement_energy.py tests/test_measurement_household.py tests/test_battery_capacity.py tests/test_consolidation_file_restore.py tests/test_measurement.py tests/test_genetic0optimize.py tests/test_geneticoptimize.py tests/test_doc.py -q --tb=short +``` + +Do not inherit EOS_DIR/EOS_CONFIG_DIR from documentation generation when running +pytest: these conflict with fixture-controlled temporary config directories. +Generate OpenAPI after committing source changes; source-dirty version timestamps +otherwise make exact documentation comparisons nondeterministic. + + +## Final verified checkpoint for this work session + +Focused combined run: **633 passed, 2 skipped in 65.46 s**. The skips are the +existing 400-generation --finalize cases. Zero remaining failures in that run. +All 2030 collected tests were collectable after supplying pypdf and resolving the +charge-rate import overlap; collection alone is not a pass of the full suite. +Ruff passed for the ported measurement/device/interpolator/primitive source files; +git diff --check passed. OpenAPI/config documentation generation and the documentation +comparison tests passed. The first combined run caught fixture state leakage in the +new battery test; reset-before/after fixture isolation resolved it on the repeated run. + +This is a tested partial integration checkpoint, NOT completion of the consolidation. +The source packages are locally committed; release, full feature acceptance and +upstream submission remain pending. Do not move active development or HA deployment +here until the remaining optimizer/prognosis/output/request packages are integrated. diff --git a/docs/development/eos-ha-handoff.md b/docs/development/eos-ha-handoff.md new file mode 100644 index 00000000..f5dffb62 --- /dev/null +++ b/docs/development/eos-ha-handoff.md @@ -0,0 +1,36 @@ +# EOS interface handoff to Home Assistant + +2026-09-16 — intermediate integration only; do not deploy or switch HA dependency yet. + +Source branch: `integration/eos-consolidation-20260916` on main `afb7bcb8`. +See eos-consolidation.md for source commits, tests, backup, and remaining work. + +- Configuration collections `devices.batteries`, `electric_vehicles`, `inverters`, + `home_appliances` are maps keyed by stable device ID. A supplied `device_id` must + match its map key; omitted IDs use that key. Old lists migrate. LCOS configuration + uses `levelized_cost_of_storage_amt_kwh`; old files retain their values. +- Algorithm settings are separate under `optimization.genetic` / `genetic0`. + Existing main configuration uses `interval_sec` and `horizon_hours` there. + Do not send feature-branch top-level interval/horizon settings without migration. +- #1305 runtime bulk/granular changes are retained above file/environment sources; + config persistence is still an explicit existing save operation. +- New measurement routes: PUT/GET `/v1/measurement/samples`, GET + `/v1/measurement/energy`, GET `/v1/measurement/household`, POST + `/v1/measurement/battery-capacity/{battery_id}`. OpenAPI describes request schemas. + Sample times require timezone; values remain in declared raw units, derived energy + is Wh and includes coverage/quality. Missing data is not implicitly zero energy. +- Capacity estimates are separate evidence; even store_estimate=true never replaces + devices.batteries[id].capacity_wh. Explicitly stored estimates survive runtime + bulk changes; existing config save controls disk persistence. +- Python measurement storage-facing methods are async and must be awaited. The HTTP + schema remains ordinary JSON; HA does not need to mirror EOS internals. +- Legacy POST `/optimize` remains GENETIC0. The existing algorithm-specific raw result + route is GET `/v1/energy-management/optimization/solution/{algorithm}`. The local + feature ConfigOptimizationRequest and its `/v1/optimize` route are NOT yet ported. +- New GENETIC orchestration/warmstart, imported-tariff #1304 fix, flexible-consumer + reconciliation, calibrated local PV, complete output/PDF and forecast handling + remain pending. Passing GENETIC0 or primitive tests does not cover these. + +No HA repository changes, lab deployment, real device control or production config +were performed. Retire the private HA core only after its differences are audited +and a final EOS commit passes the full feature/API acceptance scenarios. diff --git a/openapi.json b/openapi.json index 705ddbb6..905aaa00 100644 --- a/openapi.json +++ b/openapi.json @@ -8,9 +8,328 @@ "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, - "version": "v0.3.0.dev2609161092365525" + "version": "v0.3.0.dev2609161038708598" }, "paths": { + "/v1/measurement/battery-capacity/{battery_id}": { + "post": { + "tags": [ + "measurement" + ], + "summary": "Post Battery Capacity", + "description": "Estimate capacity from independent SoC anchors and configured DC power.\n\nstore_estimate writes the separate capacity_estimate config field in memory.\nPersistence follows the regular EOS configuration save mechanism.\nThe active capacity_wh and raw measurements are never changed here.", + "operationId": "post_battery_capacity_v1_measurement_battery_capacity__battery_id__post", + "parameters": [ + { + "name": "battery_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Battery Id" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BatteryCapacityRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BatteryCapacityEstimate" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/measurement/samples": { + "put": { + "tags": [ + "measurement" + ], + "summary": "Put Samples", + "description": "Upsert raw values and their quality; legacy value/series payloads remain valid.", + "operationId": "put_samples_v1_measurement_samples_put", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MeasurementSample" + }, + "maxItems": 10000, + "title": "Samples" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": { + "type": "integer" + }, + "title": "Response Put Samples V1 Measurement Samples Put" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "get": { + "tags": [ + "measurement" + ], + "summary": "Get Samples", + "description": "Read raw samples including quality, in a bounded half-open range.", + "operationId": "get_samples_v1_measurement_samples_get", + "parameters": [ + { + "name": "key", + "in": "query", + "required": true, + "schema": { + "type": "string", + "title": "Key" + } + }, + { + "name": "start", + "in": "query", + "required": true, + "schema": { + "type": "string", + "format": "date-time", + "title": "Start" + } + }, + { + "name": "end", + "in": "query", + "required": true, + "schema": { + "type": "string", + "format": "date-time", + "title": "End" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/MeasurementSample" + }, + "title": "Response Get Samples V1 Measurement Samples Get" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/measurement/energy": { + "get": { + "tags": [ + "measurement" + ], + "summary": "Get Energy", + "description": "Energy in Wh, with temporal coverage and quality; no missing-to-zero filling.", + "operationId": "get_energy_v1_measurement_energy_get", + "parameters": [ + { + "name": "key", + "in": "query", + "required": true, + "schema": { + "type": "string", + "title": "Key" + } + }, + { + "name": "start", + "in": "query", + "required": true, + "schema": { + "type": "string", + "format": "date-time", + "title": "Start" + } + }, + { + "name": "end", + "in": "query", + "required": true, + "schema": { + "type": "string", + "format": "date-time", + "title": "End" + } + }, + { + "name": "interval_seconds", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "exclusiveMinimum": 0, + "default": 900, + "title": "Interval Seconds" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EnergyInterval" + }, + "title": "Response Get Energy V1 Measurement Energy Get" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/measurement/household": { + "get": { + "tags": [ + "measurement" + ], + "summary": "Get Household", + "description": "Site, household without EV, and base without separately measured devices.", + "operationId": "get_household_v1_measurement_household_get", + "parameters": [ + { + "name": "start", + "in": "query", + "required": true, + "schema": { + "type": "string", + "format": "date-time", + "title": "Start" + } + }, + { + "name": "end", + "in": "query", + "required": true, + "schema": { + "type": "string", + "format": "date-time", + "title": "End" + } + }, + { + "name": "interval_seconds", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "exclusiveMinimum": 0, + "default": 900, + "title": "Interval Seconds" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EnergyInterval" + } + }, + "title": "Response Get Household V1 Measurement Household Get" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, "/v1/admin/cache/clear": { "post": { "tags": [ @@ -2886,6 +3205,27 @@ "dishwasher" ] }, + "capacity_estimation": { + "anyOf": [ + { + "$ref": "#/components/schemas/BatteryCapacityEstimationSettings" + }, + { + "type": "null" + } + ] + }, + "capacity_estimate": { + "anyOf": [ + { + "$ref": "#/components/schemas/BatteryCapacityEstimate" + }, + { + "type": "null" + } + ], + "description": "Last explicitly stored capacity estimate; does not override capacity_wh." + }, "capacity_wh": { "type": "integer", "exclusiveMinimum": 0.0, @@ -3020,6 +3360,39 @@ "examples": [ 100 ] + }, + "grid_export_rates": { + "anyOf": [ + { + "items": { + "type": "number" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Grid Export Rates", + "description": "Battery-to-grid export rates as factor of maximum discharge power ]0.00 ... 1.00]. Only used with direct marketing (feedintariff.direct_marketing_enabled). Each rate is one additional optimizer state; [1.0] restores all-or-nothing export. None triggers fallback to default export-rates.", + "default": [ + 0.25, + 0.5, + 0.75, + 1.0 + ], + "examples": [ + [ + 0.25, + 0.5, + 0.75, + 1.0 + ], + [ + 1.0 + ], + null + ] } }, "type": "object", @@ -3039,6 +3412,27 @@ "dishwasher" ] }, + "capacity_estimation": { + "anyOf": [ + { + "$ref": "#/components/schemas/BatteryCapacityEstimationSettings" + }, + { + "type": "null" + } + ] + }, + "capacity_estimate": { + "anyOf": [ + { + "$ref": "#/components/schemas/BatteryCapacityEstimate" + }, + { + "type": "null" + } + ], + "description": "Last explicitly stored capacity estimate; does not override capacity_wh." + }, "capacity_wh": { "type": "integer", "exclusiveMinimum": 0.0, @@ -3174,6 +3568,39 @@ 100 ] }, + "grid_export_rates": { + "anyOf": [ + { + "items": { + "type": "number" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Grid Export Rates", + "description": "Battery-to-grid export rates as factor of maximum discharge power ]0.00 ... 1.00]. Only used with direct marketing (feedintariff.direct_marketing_enabled). Each rate is one additional optimizer state; [1.0] restores all-or-nothing export. None triggers fallback to default export-rates.", + "default": [ + 0.25, + 0.5, + 0.75, + 1.0 + ], + "examples": [ + [ + 0.25, + 0.5, + 0.75, + 1.0 + ], + [ + 1.0 + ], + null + ] + }, "measurement_key_soc_factor": { "type": "string", "title": "Measurement Key Soc Factor", @@ -3226,6 +3653,225 @@ "title": "BatteriesCommonSettings", "description": "Battery and electric vehicle device settings.\n\nUsed for both stationary batteries and EV battery packs.\n\nNote: Used for the GENETIC and GENETIC0 algorithm." }, + "BatteryCapacityEstimate": { + "properties": { + "battery_id": { + "type": "string", + "title": "Battery Id" + }, + "start": { + "type": "string", + "format": "date-time", + "title": "Start" + }, + "end": { + "type": "string", + "format": "date-time", + "title": "End" + }, + "soc_reference": { + "type": "string", + "title": "Soc Reference" + }, + "start_soc_percentage": { + "type": "number", + "title": "Start Soc Percentage" + }, + "end_soc_percentage": { + "type": "number", + "title": "End Soc Percentage" + }, + "estimated_capacity_wh": { + "type": "number", + "title": "Estimated Capacity Wh" + }, + "configured_capacity_wh": { + "type": "number", + "title": "Configured Capacity Wh" + }, + "capacity_change_percentage": { + "type": "number", + "title": "Capacity Change Percentage" + }, + "model_end_soc_percentage_unclipped": { + "type": "number", + "title": "Model End Soc Percentage Unclipped" + }, + "model_soc_error_percentage_points": { + "type": "number", + "title": "Model Soc Error Percentage Points" + }, + "charge_energy_wh": { + "type": "number", + "title": "Charge Energy Wh" + }, + "discharge_energy_wh": { + "type": "number", + "title": "Discharge Energy Wh" + }, + "stored_energy_change_wh": { + "type": "number", + "title": "Stored Energy Change Wh" + }, + "charging_efficiency": { + "type": "number", + "title": "Charging Efficiency" + }, + "discharging_efficiency": { + "type": "number", + "title": "Discharging Efficiency" + }, + "power_key": { + "type": "string", + "title": "Power Key" + }, + "positive_power": { + "type": "string", + "title": "Positive Power" + }, + "integration_method": { + "type": "string", + "title": "Integration Method" + }, + "coverage_seconds": { + "type": "number", + "title": "Coverage Seconds" + }, + "samples_used": { + "type": "integer", + "title": "Samples Used" + }, + "warnings": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Warnings" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "battery_id", + "start", + "end", + "soc_reference", + "start_soc_percentage", + "end_soc_percentage", + "estimated_capacity_wh", + "configured_capacity_wh", + "capacity_change_percentage", + "model_end_soc_percentage_unclipped", + "model_soc_error_percentage_points", + "charge_energy_wh", + "discharge_energy_wh", + "stored_energy_change_wh", + "charging_efficiency", + "discharging_efficiency", + "power_key", + "positive_power", + "integration_method", + "coverage_seconds", + "samples_used", + "warnings" + ], + "title": "BatteryCapacityEstimate" + }, + "BatteryCapacityEstimationSettings": { + "properties": { + "power_key": { + "type": "string", + "minLength": 1, + "title": "Power Key" + }, + "positive_power": { + "type": "string", + "enum": [ + "charging", + "discharging" + ], + "title": "Positive Power" + }, + "measurement_boundary": { + "type": "string", + "const": "battery_dc", + "title": "Measurement Boundary", + "default": "battery_dc" + }, + "min_soc_change_percentage": { + "type": "number", + "maximum": 100.0, + "exclusiveMinimum": 0.0, + "title": "Min Soc Change Percentage", + "default": 20 + }, + "max_duration_hours": { + "type": "number", + "maximum": 744.0, + "exclusiveMinimum": 0.0, + "title": "Max Duration Hours", + "default": 168 + } + }, + "type": "object", + "required": [ + "power_key", + "positive_power" + ], + "title": "BatteryCapacityEstimationSettings", + "description": "Only a battery-terminal DC power channel is supported, not inverter AC." + }, + "BatteryCapacityRequest": { + "properties": { + "start": { + "type": "string", + "format": "date-time", + "title": "Start" + }, + "end": { + "type": "string", + "format": "date-time", + "title": "End" + }, + "start_soc_percentage": { + "type": "number", + "maximum": 100.0, + "minimum": 0.0, + "title": "Start Soc Percentage" + }, + "end_soc_percentage": { + "type": "number", + "maximum": 100.0, + "minimum": 0.0, + "title": "End Soc Percentage", + "default": 100 + }, + "soc_reference": { + "type": "string", + "enum": [ + "bms", + "external_calibration", + "voltage_current_anchor" + ], + "title": "Soc Reference" + }, + "store_estimate": { + "type": "boolean", + "title": "Store Estimate", + "default": false + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "start", + "end", + "start_soc_percentage", + "soc_reference" + ], + "title": "BatteryCapacityRequest", + "description": "Caller attests both anchors are independent of the capacity being fitted.\n\nEnd is the first confirmed full point when using the default end SoC.\nVoltage/current anchors must be independently established for the chemistry." + }, "CacheCommonSettings": { "properties": { "subpath": { @@ -4798,6 +5444,67 @@ ], null ] + }, + "grid_export_rates": { + "anyOf": [ + { + "items": { + "type": "number" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Grid Export Rates", + "description": "Battery-to-grid export rates as factor of maximum discharge power ]0.00 ... 1.00]. Only used with direct marketing. None falls back to the configured devices.batteries[0].grid_export_rates.", + "examples": [ + [ + 0.25, + 0.5, + 0.75, + 1.0 + ], + [ + 1.0 + ], + null + ] + }, + "min_soc_deadline_datetime": { + "anyOf": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "null" + } + ], + "title": "Min Soc Deadline Datetime", + "description": "Absolute moment by which 'min_soc_percentage' has to be reached (departure time). A date time without timezone is read as local time. None means end of the optimization horizon.", + "examples": [ + null, + "2026-07-16T07:00:00+02:00" + ] + }, + "min_soc_max_duration_h": { + "anyOf": [ + { + "type": "number", + "exclusiveMinimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Min Soc Max Duration H", + "description": "Maximum time from the start of the optimization until 'min_soc_percentage' has to be reached [h]. Combined with 'min_soc_deadline_datetime' the earlier of the two applies.", + "examples": [ + null, + 6.0 + ] } }, "additionalProperties": false, @@ -4807,7 +5514,7 @@ "capacity_wh" ], "title": "ElectricVehicleParameters", - "description": "Battery Electric Vehicle Device Simulation Configuration." + "description": "Battery Electric Vehicle Device Simulation Configuration.\n\n``min_soc_percentage`` is the charging target. By default it only has to be\nreached by the end of the optimization horizon; a deadline\n(``min_soc_deadline_datetime`` and/or ``min_soc_max_duration_h``) moves that\nrequirement forward, for example to the next departure." }, "ElectricVehicleResult": { "properties": { @@ -4915,6 +5622,103 @@ "title": "EnergyChartsBiddingZones", "description": "Energy Charts Bidding Zones." }, + "EnergyInterval": { + "properties": { + "start": { + "type": "string", + "format": "date-time", + "title": "Start" + }, + "end": { + "type": "string", + "format": "date-time", + "title": "End" + }, + "energy_wh": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Energy Wh" + }, + "observed_energy_wh": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Observed Energy Wh" + }, + "coverage_seconds": { + "type": "number", + "title": "Coverage Seconds" + }, + "coverage_status": { + "type": "string", + "enum": [ + "complete", + "partial", + "missing", + "invalid" + ], + "title": "Coverage Status" + }, + "methods": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Methods" + }, + "flags": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Flags" + }, + "coverage_ranges": { + "items": { + "prefixItems": [ + { + "type": "string", + "format": "date-time" + }, + { + "type": "string", + "format": "date-time" + } + ], + "type": "array", + "maxItems": 2, + "minItems": 2 + }, + "type": "array", + "title": "Coverage Ranges" + } + }, + "type": "object", + "required": [ + "start", + "end", + "energy_wh", + "observed_energy_wh", + "coverage_seconds", + "coverage_status", + "methods", + "flags", + "coverage_ranges" + ], + "title": "EnergyInterval", + "description": "Energy and actual temporal support; missing energy is never zero-filled." + }, "EnergyManagementCommonSettings-Input": { "properties": { "startup_delay": { @@ -9412,6 +10216,79 @@ "title": "HomeAssistantAdapterCommonSettings", "description": "Common settings for the home assistant adapter." }, + "HouseholdInput": { + "properties": { + "key": { + "type": "string", + "title": "Key" + }, + "branch": { + "type": "string", + "minLength": 1, + "title": "Branch" + }, + "role": { + "type": "string", + "enum": [ + "site", + "grid", + "pv", + "battery", + "inverter", + "ev", + "device" + ], + "title": "Role" + }, + "polarity": { + "type": "integer", + "enum": [ + -1, + 1 + ], + "title": "Polarity", + "default": 1 + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "key", + "branch", + "role" + ], + "title": "HouseholdInput", + "description": "A non-overlapping AC branch; polarity normalizes the sensor's sign." + }, + "HouseholdSettings": { + "properties": { + "topology": { + "type": "string", + "enum": [ + "direct", + "separate_ac", + "hybrid_ac" + ], + "title": "Topology" + }, + "inputs": { + "items": { + "$ref": "#/components/schemas/HouseholdInput" + }, + "type": "array", + "minItems": 1, + "title": "Inputs" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "topology", + "inputs" + ], + "title": "HouseholdSettings", + "description": "Fixed topology, never user-supplied executable balance expressions.\n\nGrid import, PV production and battery/inverter discharge are positive.\nEV/device inputs are positive consumption, subtracted only from derived loads." + }, "InverterCommonSettings-Input": { "properties": { "device_id": { @@ -10643,6 +11520,90 @@ "title": "LoggingCommonSettings", "description": "Logging Configuration." }, + "MeasurementChannelSettings": { + "properties": { + "quantity": { + "type": "string", + "enum": [ + "power", + "cumulative_energy", + "interval_energy" + ], + "title": "Quantity" + }, + "unit": { + "type": "string", + "enum": [ + "W", + "kW", + "Wh", + "kWh" + ], + "title": "Unit" + }, + "integration_method": { + "anyOf": [ + { + "type": "string", + "enum": [ + "hold", + "linear" + ] + }, + { + "type": "null" + } + ], + "title": "Integration Method" + }, + "max_gap_seconds": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Max Gap Seconds" + }, + "interval_seconds": { + "anyOf": [ + { + "type": "integer", + "exclusiveMinimum": 0.0 + }, + { + "type": "null" + } + ], + "title": "Interval Seconds" + }, + "timestamp_reference": { + "anyOf": [ + { + "type": "string", + "enum": [ + "start", + "end" + ] + }, + { + "type": "null" + } + ], + "title": "Timestamp Reference" + } + }, + "type": "object", + "required": [ + "quantity", + "unit" + ], + "title": "MeasurementChannelSettings", + "description": "Meaning of a raw measurement channel; no conversion is performed on storage." + }, "MeasurementCommonSettings-Input": { "properties": { "historic_hours": { @@ -10662,6 +11623,35 @@ 17520 ] }, + "channels": { + "additionalProperties": { + "$ref": "#/components/schemas/MeasurementChannelSettings" + }, + "type": "object", + "title": "Channels", + "description": "Typed raw measurement channels keyed by measurement key." + }, + "household": { + "anyOf": [ + { + "$ref": "#/components/schemas/HouseholdSettings" + }, + { + "type": "null" + } + ], + "description": "Optional household energy balance definition.", + "examples": [ + null + ] + }, + "energy_context_seconds": { + "type": "integer", + "maximum": 604800.0, + "exclusiveMinimum": 0.0, + "title": "Energy Context Seconds", + "default": 86400 + }, "load_emr_keys": { "anyOf": [ { @@ -10766,6 +11756,35 @@ 17520 ] }, + "channels": { + "additionalProperties": { + "$ref": "#/components/schemas/MeasurementChannelSettings" + }, + "type": "object", + "title": "Channels", + "description": "Typed raw measurement channels keyed by measurement key." + }, + "household": { + "anyOf": [ + { + "$ref": "#/components/schemas/HouseholdSettings" + }, + { + "type": "null" + } + ], + "description": "Optional household energy balance definition.", + "examples": [ + null + ] + }, + "energy_context_seconds": { + "type": "integer", + "maximum": 604800.0, + "exclusiveMinimum": 0.0, + "title": "Energy Context Seconds", + "default": 86400 + }, "load_emr_keys": { "anyOf": [ { @@ -10863,6 +11882,42 @@ "title": "MeasurementCommonSettings", "description": "Measurement Configuration." }, + "MeasurementSample": { + "properties": { + "date_time": { + "type": "string", + "format": "date-time", + "title": "Date Time" + }, + "key": { + "type": "string", + "title": "Key" + }, + "value": { + "anyOf": [ + { + "type": "number" + }, + { + "type": "null" + } + ], + "title": "Value" + }, + "quality": { + "$ref": "#/components/schemas/SampleQuality" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "date_time", + "key", + "value" + ], + "title": "MeasurementSample", + "description": "Complete replacement of one key/timestamp, including its quality." + }, "NodeREDAdapterCommonSettings": { "properties": { "host": { @@ -12649,6 +13704,42 @@ "title": "PydanticDateTimeSeries", "description": "Pydantic model for validating pandas Series with datetime index in JSON format.\n\nThis model handles Series data serialized with orient='index', where the keys are\ndatetime strings and values are the series values. Provides validation and\nconversion between JSON and pandas Series with datetime index.\n\nAttributes:\n data (Dict[str, Any]): Dictionary mapping datetime strings to values.\n dtype (str): The data type of the series values.\n tz (str | None): Timezone name if the datetime index is timezone-aware." }, + "SampleQuality": { + "properties": { + "status": { + "type": "string", + "enum": [ + "measured", + "estimated", + "invalid", + "unavailable" + ], + "title": "Status", + "default": "measured" + }, + "reset": { + "type": "boolean", + "title": "Reset", + "default": false + }, + "generation": { + "anyOf": [ + { + "type": "string", + "maxLength": 128 + }, + { + "type": "null" + } + ], + "title": "Generation" + } + }, + "additionalProperties": false, + "type": "object", + "title": "SampleQuality", + "description": "Reset marks the first reading after a reset; generation identifies a meter." + }, "SeriesProcessing": { "type": "string", "enum": [ @@ -13094,6 +14185,43 @@ ], null ] + }, + "grid_export_rates": { + "anyOf": [ + { + "items": { + "type": "number" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Grid Export Rates", + "description": "Battery-to-grid export rates as factor of maximum discharge power ]0.00 ... 1.00]. Only used with direct marketing. None falls back to the configured devices.batteries[0].grid_export_rates.", + "examples": [ + [ + 0.25, + 0.5, + 0.75, + 1.0 + ], + [ + 1.0 + ], + null + ] + }, + "levelized_cost_of_storage_kwh": { + "type": "number", + "minimum": 0.0, + "title": "Levelized Cost Of Storage Kwh", + "description": "Levelized cost of storage applied once to each kWh delivered by the battery [EUR/kWh].", + "default": 0.0, + "examples": [ + 0.12 + ] } }, "additionalProperties": false, diff --git a/tests/test_battery_capacity.py b/tests/test_battery_capacity.py index e0ba2666..96ba9f03 100644 --- a/tests/test_battery_capacity.py +++ b/tests/test_battery_capacity.py @@ -161,6 +161,7 @@ async def database_case(config_eos): from akkudoktoreos.core.coreabc import get_measurement from akkudoktoreos.measurement.quality import MeasurementSample + get_measurement()._db_reset_state() config_eos.merge_settings_from_dict( { "devices": { @@ -197,7 +198,10 @@ async def database_case(config_eos): for t in (0, 1800, 3600) ] )) - return config_eos + try: + yield config_eos + finally: + get_measurement()._db_reset_state() def test_http_reads_database_and_stores_only_explicit_estimate(database_case): diff --git a/tests/testdata/docs/_generated/configdevices.md b/tests/testdata/docs/_generated/configdevices.md index 5a9b4fb5..ce09b543 100644 --- a/tests/testdata/docs/_generated/configdevices.md +++ b/tests/testdata/docs/_generated/configdevices.md @@ -12,14 +12,14 @@ config path from ``self.device_id`` without needing an external index. | Name | Environment Variable | Type | Read-Only | Default | Description | | ---- | -------------------- | ---- | --------- | ------- | ----------- | -| batteries | `EOS_DEVICES__BATTERIES` | `dict[str, akkudoktoreos.devices.settings.batterysettings.BatteriesCommonSettings] | None` | `rw` | `None` | Stationary battery storage devices, keyed by device_id. | -| electric_vehicles | `EOS_DEVICES__ELECTRIC_VEHICLES` | `dict[str, akkudoktoreos.devices.settings.batterysettings.BatteriesCommonSettings] | None` | `rw` | `None` | Electric vehicle battery packs, keyed by device_id. | +| batteries | `EOS_DEVICES__BATTERIES` | `Optional[dict[str, akkudoktoreos.devices.settings.batterysettings.BatteriesCommonSettings]]` | `rw` | `None` | Stationary battery storage devices, keyed by device_id. | +| electric_vehicles | `EOS_DEVICES__ELECTRIC_VEHICLES` | `Optional[dict[str, akkudoktoreos.devices.settings.batterysettings.BatteriesCommonSettings]]` | `rw` | `None` | Electric vehicle battery packs, keyed by device_id. | | home_appliances | `EOS_DEVICES__HOME_APPLIANCES` | `dict[str, akkudoktoreos.devices.settings.homeappliancesettings.HomeApplianceCommonSettings]` | `rw` | `required` | Shiftable home appliance devices, keyed by device_id. | -| inverters | `EOS_DEVICES__INVERTERS` | `dict[str, akkudoktoreos.devices.settings.invertersettings.InverterCommonSettings] | None` | `rw` | `None` | Inverter devices, keyed by device_id. | -| max_batteries | `EOS_DEVICES__MAX_BATTERIES` | `int | None` | `rw` | `None` | Maximum number of batteries allowed. | -| max_electric_vehicles | `EOS_DEVICES__MAX_ELECTRIC_VEHICLES` | `int | None` | `rw` | `None` | Maximum number of EVs allowed. | -| max_home_appliances | `EOS_DEVICES__MAX_HOME_APPLIANCES` | `int | None` | `rw` | `None` | Maximum number of home appliances allowed. | -| max_inverters | `EOS_DEVICES__MAX_INVERTERS` | `int | None` | `rw` | `None` | Maximum number of inverters allowed. | +| inverters | `EOS_DEVICES__INVERTERS` | `Optional[dict[str, akkudoktoreos.devices.settings.invertersettings.InverterCommonSettings]]` | `rw` | `None` | Inverter devices, keyed by device_id. | +| max_batteries | `EOS_DEVICES__MAX_BATTERIES` | `Optional[int]` | `rw` | `None` | Maximum number of batteries allowed. | +| max_electric_vehicles | `EOS_DEVICES__MAX_ELECTRIC_VEHICLES` | `Optional[int]` | `rw` | `None` | Maximum number of EVs allowed. | +| max_home_appliances | `EOS_DEVICES__MAX_HOME_APPLIANCES` | `Optional[int]` | `rw` | `None` | Maximum number of home appliances allowed. | +| max_inverters | `EOS_DEVICES__MAX_INVERTERS` | `Optional[int]` | `rw` | `None` | Maximum number of inverters allowed. | | measurement_keys | | `list[str]` | `ro` | `N/A` | All measurement keys across all configured devices. | ::: @@ -35,6 +35,8 @@ config path from ``self.device_id`` without needing an external index. "batteries": { "bat0": { "device_id": "bat0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 8000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -55,13 +57,21 @@ config path from ``self.device_id`` without needing an external index. 1.0 ], "min_soc_percentage": 0, - "max_soc_percentage": 100 + "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ] } }, "max_batteries": 1, "electric_vehicles": { "ev0": { "device_id": "ev0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 60000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -82,7 +92,13 @@ config path from ``self.device_id`` without needing an external index. 1.0 ], "min_soc_percentage": 0, - "max_soc_percentage": 100 + "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ] } }, "max_electric_vehicles": 1, @@ -116,6 +132,8 @@ config path from ``self.device_id`` without needing an external index. "batteries": { "bat0": { "device_id": "bat0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 8000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -137,6 +155,12 @@ config path from ``self.device_id`` without needing an external index. ], "min_soc_percentage": 0, "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ], "measurement_key_soc_factor": "bat0-soc-factor", "measurement_key_power_l1_w": "bat0-power-l1-w", "measurement_key_power_l2_w": "bat0-power-l2-w", @@ -155,6 +179,8 @@ config path from ``self.device_id`` without needing an external index. "electric_vehicles": { "ev0": { "device_id": "ev0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 60000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -176,6 +202,12 @@ config path from ``self.device_id`` without needing an external index. ], "min_soc_percentage": 0, "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ], "measurement_key_soc_factor": "ev0-soc-factor", "measurement_key_power_l1_w": "ev0-power-l1-w", "measurement_key_power_l2_w": "ev0-power-l2-w", diff --git a/tests/testdata/docs/_generated/configexample.md b/tests/testdata/docs/_generated/configexample.md index 02bf87bf..908f3ab1 100644 --- a/tests/testdata/docs/_generated/configexample.md +++ b/tests/testdata/docs/_generated/configexample.md @@ -39,6 +39,8 @@ "batteries": { "bat0": { "device_id": "bat0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 8000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -59,13 +61,21 @@ 1.0 ], "min_soc_percentage": 0, - "max_soc_percentage": 100 + "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ] } }, "max_batteries": 1, "electric_vehicles": { "ev0": { "device_id": "ev0", + "capacity_estimation": null, + "capacity_estimate": null, "capacity_wh": 60000, "charging_efficiency": 0.88, "discharging_efficiency": 0.88, @@ -86,7 +96,13 @@ 1.0 ], "min_soc_percentage": 0, - "max_soc_percentage": 100 + "max_soc_percentage": 100, + "grid_export_rates": [ + 0.25, + 0.5, + 0.75, + 1.0 + ] } }, "max_electric_vehicles": 1, @@ -205,6 +221,9 @@ }, "measurement": { "historic_hours": 17520, + "channels": {}, + "household": null, + "energy_context_seconds": 86400, "load_emr_keys": [ "load0_emr" ], diff --git a/tests/testdata/docs/_generated/configmeasurement.md b/tests/testdata/docs/_generated/configmeasurement.md index f6bc7c66..c0d58f09 100644 --- a/tests/testdata/docs/_generated/configmeasurement.md +++ b/tests/testdata/docs/_generated/configmeasurement.md @@ -7,12 +7,15 @@ | Name | Environment Variable | Type | Read-Only | Default | Description | | ---- | -------------------- | ---- | --------- | ------- | ----------- | -| grid_export_emr_keys | `EOS_MEASUREMENT__GRID_EXPORT_EMR_KEYS` | `list[str] | None` | `rw` | `None` | The keys of the measurements that are energy meter readings of energy export to grid [kWh]. | -| grid_import_emr_keys | `EOS_MEASUREMENT__GRID_IMPORT_EMR_KEYS` | `list[str] | None` | `rw` | `None` | The keys of the measurements that are energy meter readings of energy import from grid [kWh]. | -| historic_hours | `EOS_MEASUREMENT__HISTORIC_HOURS` | `int | None` | `rw` | `17520` | Number of hours into the past for measurement data | +| channels | `EOS_MEASUREMENT__CHANNELS` | `dict[str, akkudoktoreos.measurement.measurement.MeasurementChannelSettings]` | `rw` | `required` | Typed raw measurement channels keyed by measurement key. | +| energy_context_seconds | `EOS_MEASUREMENT__ENERGY_CONTEXT_SECONDS` | `int` | `rw` | `86400` | None | +| grid_export_emr_keys | `EOS_MEASUREMENT__GRID_EXPORT_EMR_KEYS` | `Optional[list[str]]` | `rw` | `None` | The keys of the measurements that are energy meter readings of energy export to grid [kWh]. | +| grid_import_emr_keys | `EOS_MEASUREMENT__GRID_IMPORT_EMR_KEYS` | `Optional[list[str]]` | `rw` | `None` | The keys of the measurements that are energy meter readings of energy import from grid [kWh]. | +| historic_hours | `EOS_MEASUREMENT__HISTORIC_HOURS` | `Optional[int]` | `rw` | `17520` | Number of hours into the past for measurement data | +| household | `EOS_MEASUREMENT__HOUSEHOLD` | `Optional[akkudoktoreos.measurement.household.HouseholdSettings]` | `rw` | `None` | Optional household energy balance definition. | | keys | | `list[str]` | `ro` | `N/A` | The keys of the measurements that can be stored. | -| load_emr_keys | `EOS_MEASUREMENT__LOAD_EMR_KEYS` | `list[str] | None` | `rw` | `None` | The keys of the measurements that are energy meter readings of a load [kWh]. | -| pv_production_emr_keys | `EOS_MEASUREMENT__PV_PRODUCTION_EMR_KEYS` | `list[str] | None` | `rw` | `None` | The keys of the measurements that are PV production energy meter readings [kWh]. | +| load_emr_keys | `EOS_MEASUREMENT__LOAD_EMR_KEYS` | `Optional[list[str]]` | `rw` | `None` | The keys of the measurements that are energy meter readings of a load [kWh]. | +| pv_production_emr_keys | `EOS_MEASUREMENT__PV_PRODUCTION_EMR_KEYS` | `Optional[list[str]]` | `rw` | `None` | The keys of the measurements that are PV production energy meter readings [kWh]. | ::: @@ -25,6 +28,9 @@ { "measurement": { "historic_hours": 17520, + "channels": {}, + "household": null, + "energy_context_seconds": 86400, "load_emr_keys": [ "load0_emr" ], @@ -51,6 +57,9 @@ { "measurement": { "historic_hours": 17520, + "channels": {}, + "household": null, + "energy_context_seconds": 86400, "load_emr_keys": [ "load0_emr" ],