diff --git a/CHANGELOG.md b/CHANGELOG.md index 03db594..d812d1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,16 @@ All notable changes to the akkudoktoreos project will be documented in this file The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). +## Unreleased + +### Added + +- New PV forecast providers giving operators more cloud forecast sources to choose from in + addition to Akkudoktor, VRM and Import: + - `PVForecastPVNode` — native 15-minute forecasts from the pvnode.com API. + - `PVForecastForecastSolar` — forecasts from the free Forecast.Solar API. + - `PVForecastSolcast` — forecasts from the Solcast rooftop-site API. + ## 0.3.0 (2026-03-17) Akkudoktor-EOS can now be run as Home Assistant add-on and standalone. diff --git a/docs/_generated/configexample.md b/docs/_generated/configexample.md index dbc8187..aaad1b7 100644 --- a/docs/_generated/configexample.md +++ b/docs/_generated/configexample.md @@ -187,7 +187,10 @@ "provider": "PVForecastAkkudoktor", "provider_settings": { "PVForecastImport": null, - "PVForecastVrm": null + "PVForecastVrm": null, + "PVForecastPVNode": null, + "PVForecastForecastSolar": null, + "PVForecastSolcast": null }, "planes": [ { diff --git a/docs/_generated/configpvforecast.md b/docs/_generated/configpvforecast.md index ea78dbd..a5776e0 100644 --- a/docs/_generated/configpvforecast.md +++ b/docs/_generated/configpvforecast.md @@ -31,7 +31,10 @@ "provider": "PVForecastAkkudoktor", "provider_settings": { "PVForecastImport": null, - "PVForecastVrm": null + "PVForecastVrm": null, + "PVForecastPVNode": null, + "PVForecastForecastSolar": null, + "PVForecastSolcast": null }, "planes": [ { @@ -96,7 +99,10 @@ "provider": "PVForecastAkkudoktor", "provider_settings": { "PVForecastImport": null, - "PVForecastVrm": null + "PVForecastVrm": null, + "PVForecastPVNode": null, + "PVForecastForecastSolar": null, + "PVForecastSolcast": null }, "planes": [ { @@ -148,6 +154,9 @@ "providers": [ "PVForecastAkkudoktor", "PVForecastVrm", + "PVForecastPVNode", + "PVForecastForecastSolar", + "PVForecastSolcast", "PVForecastImport" ], "planes_peakpower": [ @@ -183,6 +192,105 @@ ``` +### Common settings for the Solcast PV forecast provider + + +:::{table} pvforecast::provider_settings::PVForecastSolcast +:widths: 10 10 5 5 30 +:align: left + +| Name | Type | Read-Only | Default | Description | +| ---- | ---- | --------- | ------- | ----------- | +| api_key | `str` | `rw` | `` | Solcast API key (Bearer auth). Required. | +| site_id | `str` | `rw` | `` | Solcast rooftop site (resource) id. Required. | +::: + + + +**Example Input/Output** + + + +```json + { + "pvforecast": { + "provider_settings": { + "PVForecastSolcast": { + "api_key": "your-solcast-key", + "site_id": "abcd-1234-efgh-5678" + } + } + } + } +``` + + +### Common settings for the Forecast.Solar PV forecast provider + + +:::{table} pvforecast::provider_settings::PVForecastForecastSolar +:widths: 10 10 5 5 30 +:align: left + +| Name | Type | Read-Only | Default | Description | +| ---- | ---- | --------- | ------- | ----------- | +| api_key | `Optional[str]` | `rw` | `None` | Forecast.Solar API key. Optional — the public endpoint works without a key (lower rate limit). | +::: + + + +**Example Input/Output** + + + +```json + { + "pvforecast": { + "provider_settings": { + "PVForecastForecastSolar": { + "api_key": null + } + } + } + } +``` + + +### Common settings for the pvnode.com PV forecast provider + + +:::{table} pvforecast::provider_settings::PVForecastPVNode +:widths: 10 10 5 5 30 +:align: left + +| Name | Type | Read-Only | Default | Description | +| ---- | ---- | --------- | ------- | ----------- | +| api_key | `str` | `rw` | `` | pvnode.com API key (Bearer auth). Required. | +| forecast_days | `int` | `rw` | `2` | Forecast horizon in days (1-7, capped by the pvnode plan). | +| site_id | `Optional[str]` | `rw` | `None` | pvnode.com site id of the saved plant ('Anlagen-ID'). When set, the saved (possibly calibrated) site is used. Leave empty to send the configured pvforecast.planes inline instead. | +::: + + + +**Example Input/Output** + + + +```json + { + "pvforecast": { + "provider_settings": { + "PVForecastPVNode": { + "api_key": "pvn_live_xxxxxxxxxxxxxxxx", + "site_id": "abcd-1234", + "forecast_days": 2 + } + } + } + } +``` + + ### Common settings for PV forecast VRM API @@ -258,7 +366,10 @@ | Name | Type | Read-Only | Default | Description | | ---- | ---- | --------- | ------- | ----------- | +| PVForecastForecastSolar | `Optional[akkudoktoreos.prediction.pvforecastforecastsolar.PVForecastForecastSolarCommonSettings]` | `rw` | `None` | PVForecastForecastSolar settings | | PVForecastImport | `Optional[akkudoktoreos.prediction.pvforecastimport.PVForecastImportCommonSettings]` | `rw` | `None` | PVForecastImport settings | +| PVForecastPVNode | `Optional[akkudoktoreos.prediction.pvforecastpvnode.PVForecastPVNodeCommonSettings]` | `rw` | `None` | PVForecastPVNode settings | +| PVForecastSolcast | `Optional[akkudoktoreos.prediction.pvforecastsolcast.PVForecastSolcastCommonSettings]` | `rw` | `None` | PVForecastSolcast settings | | PVForecastVrm | `Optional[akkudoktoreos.prediction.pvforecastvrm.PVForecastVrmCommonSettings]` | `rw` | `None` | PVForecastVrm settings | ::: @@ -273,7 +384,10 @@ "pvforecast": { "provider_settings": { "PVForecastImport": null, - "PVForecastVrm": null + "PVForecastVrm": null, + "PVForecastPVNode": null, + "PVForecastForecastSolar": null, + "PVForecastSolcast": null } } } diff --git a/docs/akkudoktoreos/prediction.md b/docs/akkudoktoreos/prediction.md index c53c93d..d1a0e7c 100644 --- a/docs/akkudoktoreos/prediction.md +++ b/docs/akkudoktoreos/prediction.md @@ -373,6 +373,9 @@ Configuration options: - `PVForecastAkkudoktor`: Retrieves from Akkudoktor.net. - `PVForecastVrm`: Retrieves data from the VRM API by Victron Energy. + - `PVForecastPVNode`: Retrieves native 15-minute forecasts from the pvnode.com API. + - `PVForecastForecastSolar`: Retrieves forecasts from the free Forecast.Solar API. + - `PVForecastSolcast`: Retrieves forecasts from the Solcast rooftop-site API. - `PVForecastImport`: Imports from a file or JSON string or by endpoint data provision. - `planes[].surface_tilt`: Tilt angle from horizontal plane. Ignored for two-axis tracking. @@ -401,6 +404,12 @@ Configuration options: - `planes[].strings_per_inverter`: Number of the strings of the inverter of this plane. - `provider_settings.import_file_path`: Path to the file to import PV forecast data from. - `provider_settings.import_json`: JSON string, dictionary of PV forecast value lists. + - `provider_settings.PVForecastPVNode.api_key`: pvnode.com API key. + - `provider_settings.PVForecastPVNode.site_id`: pvnode.com saved-site id. Leave empty for inline mode. + - `provider_settings.PVForecastPVNode.forecast_days`: Forecast horizon in days (1-7). + - `provider_settings.PVForecastForecastSolar.api_key`: Forecast.Solar API key (optional). + - `provider_settings.PVForecastSolcast.api_key`: Solcast API key. + - `provider_settings.PVForecastSolcast.site_id`: Solcast rooftop resource (site) id. --- @@ -604,6 +613,84 @@ The PV forecast data must be provided in one of the formats described in The data may additionally or solely be provided by the **PUT** `/v1/prediction/import/PVForecastImport` endpoint. +### PVForecastPVNode Provider + +The `PVForecastPVNode` provider retrieves native 15-minute PV power forecasts from the +[pvnode.com](https://pvnode.com) V2 API. Register a site in the pvnode web app and store the API +key together with the site id in the EOS configuration (saved-site mode). Alternatively, leave the +site id empty to send the configured `planes` geometry inline. + +```python + { + "pvforecast": { + "provider": "PVForecastPVNode", + "provider_settings": { + "PVForecastPVNode": { + "api_key": "your-pvnode-key", + "site_id": "your-site-id", + "forecast_days": 2 + } + } + } + } +``` + +The prediction keys for the PV forecast data are: + +- `pvforecast_ac_power`: Total AC power (W). +- `pvforecast_dc_power`: Total DC power (W). + +### PVForecastForecastSolar Provider + +The `PVForecastForecastSolar` provider retrieves PV power forecasts from the free +[Forecast.Solar](https://forecast.solar) API. No API key is required for the public endpoint; an +optional key raises the rate limit. The location is taken from `general.latitude`/`longitude` and +the system geometry from the configured `planes` (one request per plane, summed per timestamp). + +```python + { + "pvforecast": { + "provider": "PVForecastForecastSolar", + "provider_settings": { + "PVForecastForecastSolar": { + "api_key": null + } + } + } + } +``` + +The prediction keys for the PV forecast data are: + +- `pvforecast_ac_power`: Total AC power (W). +- `pvforecast_dc_power`: Total DC power (W). + +### PVForecastSolcast Provider + +The `PVForecastSolcast` provider retrieves PV power forecasts from the +[Solcast](https://solcast.com) rooftop-site API. Register a rooftop site in the Solcast web app and +store the API key together with the resource (site) id in the EOS configuration. Note that the free +tier limits the number of API calls per day. + +```python + { + "pvforecast": { + "provider": "PVForecastSolcast", + "provider_settings": { + "PVForecastSolcast": { + "api_key": "your-solcast-key", + "site_id": "your-resource-id" + } + } + } + } +``` + +The prediction keys for the PV forecast data are: + +- `pvforecast_ac_power`: Total AC power (W). +- `pvforecast_dc_power`: Total DC power (W). + ## Weather Prediction Prediction keys: