mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-07-19 16:28:12 +00:00
feat: add cloud PV forecast providers: pvnode.com, forecast-solar and solcast (#1150)
Some checks failed
Bump Version / Bump Version Workflow (push) Has been cancelled
CodeQL Advanced / Analyze (actions) (push) Has been cancelled
CodeQL Advanced / Analyze (python) (push) Has been cancelled
docker-build / platform-excludes (push) Has been cancelled
docker-build / build (push) Has been cancelled
docker-build / merge (push) Has been cancelled
pre-commit / pre-commit (push) Has been cancelled
Run Pytest on Pull Request / test (push) Has been cancelled
Some checks failed
Bump Version / Bump Version Workflow (push) Has been cancelled
CodeQL Advanced / Analyze (actions) (push) Has been cancelled
CodeQL Advanced / Analyze (python) (push) Has been cancelled
docker-build / platform-excludes (push) Has been cancelled
docker-build / build (push) Has been cancelled
docker-build / merge (push) Has been cancelled
pre-commit / pre-commit (push) Has been cancelled
Run Pytest on Pull Request / test (push) Has been cancelled
This PR adds three native PV power forecast providers, giving operators more
cloud forecast sources to choose from via pvforecast.provider, alongside the
existing PVForecastAkkudoktor, PVForecastVrm and PVForecastImport:
PVForecastPVNode — native 15-minute forecasts from the pvnode.com
V2 API. Saved-site mode (GET /v2/forecast/{site_id}) where the operator enters their API key +
site id, or inline mode (POST /v2/forecast/inline) using the configured planes.
PVForecastForecastSolar — the free Forecast.Solar API (no key
required for the public endpoint). Multi-plane systems issue one request per plane and the
instantaneous powers are summed per timestamp.
PVForecastSolcast — the Solcast rooftop-site API (API key + resource id).
Implementation notes
All three populate the existing pvforecast_ac_power (and mirror pvforecast_dc_power)
prediction keys, so they slot into the optimizer unchanged.
Timezone handling: pvnode and Forecast.Solar return site-local wall-clock timestamps with an
IANA timezone field, which are resolved to absolute instants before resampling; Solcast returns
UTC period_end and is normalised to the period start.
Each provider follows the existing provider pattern (provider_id(), _request_forecast() with
@cache_in_file, _update_data()), is registered in pvforecast.py and prediction.py, and is
upstream-neutral.
Validation
27 unit tests (timezone resolution, null/zero handling, kW→W and period-start conversion,
azimuth conversion, multi-plane summation, request URL/auth, HTTP-error handling).
ruff check (F/D/S/bandit) and ruff format clean.
Each provider was additionally validated against its live API with a real plant, confirming
the response shapes (pvnode: 288 native 15-min slots; Forecast.Solar: instantaneous watts;
Solcast: kW estimates with period_end/PT30M).
Documentation
Provider descriptions and configuration examples added to docs/akkudoktoreos/prediction.md.
CHANGELOG.md entry under Unreleased.
Regenerated docs/_generated/configpvforecast.md and configexample.md.
Notes for reviewers
Forecast.Solar's free endpoint is rate-limited (12 req/hour) and Solcast's free tier limits daily
calls; both providers rely on the standard 1-hour cache_in_file TTL to stay within budget.
Authors:
The code is created by Christin. Only minor adaptions by Bobby.
Signed-off-by: Christin <info@bikinibottom.capital>
Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: Christin <info@bikinibottom.capital>
This commit is contained in:
Bobby Noelte
GitHub
2
.env
2
.env
@@ -11,7 +11,7 @@ DOCKER_COMPOSE_DATA_DIR=${HOME}/.local/share/net.akkudoktor.eos
|
||||
# -----------------------------------------------------------------------------
|
||||
# Image / build
|
||||
# -----------------------------------------------------------------------------
|
||||
VERSION=0.3.0.dev2607161418098328
|
||||
VERSION=0.3.0.dev2607161979035365
|
||||
PYTHON_VERSION=3.13.9
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
10
CHANGELOG.md
10
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.
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
# the root directory (no add-on folder as usual).
|
||||
|
||||
name: "Akkudoktor-EOS"
|
||||
version: "0.3.0.dev2607161418098328"
|
||||
version: "0.3.0.dev2607161979035365"
|
||||
slug: "eos"
|
||||
description: "Akkudoktor-EOS add-on"
|
||||
url: "https://github.com/Akkudoktor-EOS/EOS"
|
||||
|
||||
@@ -187,7 +187,10 @@
|
||||
"provider": "PVForecastAkkudoktor",
|
||||
"provider_settings": {
|
||||
"PVForecastImport": null,
|
||||
"PVForecastVrm": null
|
||||
"PVForecastVrm": null,
|
||||
"PVForecastPVNode": null,
|
||||
"PVForecastForecastSolar": null,
|
||||
"PVForecastSolcast": null
|
||||
},
|
||||
"planes": [
|
||||
{
|
||||
|
||||
@@ -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 @@
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
### Common settings for the Solcast PV forecast provider
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
:::{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. |
|
||||
:::
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
<!-- pyml disable no-emphasis-as-heading -->
|
||||
**Example Input/Output**
|
||||
<!-- pyml enable no-emphasis-as-heading -->
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
```json
|
||||
{
|
||||
"pvforecast": {
|
||||
"provider_settings": {
|
||||
"PVForecastSolcast": {
|
||||
"api_key": "your-solcast-key",
|
||||
"site_id": "abcd-1234-efgh-5678"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
### Common settings for the Forecast.Solar PV forecast provider
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
:::{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). |
|
||||
:::
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
<!-- pyml disable no-emphasis-as-heading -->
|
||||
**Example Input/Output**
|
||||
<!-- pyml enable no-emphasis-as-heading -->
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
```json
|
||||
{
|
||||
"pvforecast": {
|
||||
"provider_settings": {
|
||||
"PVForecastForecastSolar": {
|
||||
"api_key": null
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
### Common settings for the pvnode.com PV forecast provider
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
:::{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. |
|
||||
:::
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
<!-- pyml disable no-emphasis-as-heading -->
|
||||
**Example Input/Output**
|
||||
<!-- pyml enable no-emphasis-as-heading -->
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
```json
|
||||
{
|
||||
"pvforecast": {
|
||||
"provider_settings": {
|
||||
"PVForecastPVNode": {
|
||||
"api_key": "pvn_live_xxxxxxxxxxxxxxxx",
|
||||
"site_id": "abcd-1234",
|
||||
"forecast_days": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
### Common settings for PV forecast VRM API
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
@@ -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 |
|
||||
:::
|
||||
<!-- pyml enable line-length -->
|
||||
@@ -273,7 +384,10 @@
|
||||
"pvforecast": {
|
||||
"provider_settings": {
|
||||
"PVForecastImport": null,
|
||||
"PVForecastVrm": null
|
||||
"PVForecastVrm": null,
|
||||
"PVForecastPVNode": null,
|
||||
"PVForecastForecastSolar": null,
|
||||
"PVForecastSolcast": null
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Akkudoktor-EOS
|
||||
|
||||
**Version**: `v0.3.0.dev2607161418098328`
|
||||
**Version**: `v0.3.0.dev2607161979035365`
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
**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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
134
openapi.json
134
openapi.json
@@ -8,7 +8,7 @@
|
||||
"name": "Apache 2.0",
|
||||
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
|
||||
},
|
||||
"version": "v0.3.0.dev2607161418098328"
|
||||
"version": "v0.3.0.dev2607161979035365"
|
||||
},
|
||||
"paths": {
|
||||
"/v1/admin/cache/clear": {
|
||||
@@ -7494,6 +7494,48 @@
|
||||
"examples": [
|
||||
null
|
||||
]
|
||||
},
|
||||
"PVForecastPVNode": {
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/PVForecastPVNodeCommonSettings"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "PVForecastPVNode settings",
|
||||
"examples": [
|
||||
null
|
||||
]
|
||||
},
|
||||
"PVForecastForecastSolar": {
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/PVForecastForecastSolarCommonSettings"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "PVForecastForecastSolar settings",
|
||||
"examples": [
|
||||
null
|
||||
]
|
||||
},
|
||||
"PVForecastSolcast": {
|
||||
"anyOf": [
|
||||
{
|
||||
"$ref": "#/components/schemas/PVForecastSolcastCommonSettings"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"description": "PVForecastSolcast settings",
|
||||
"examples": [
|
||||
null
|
||||
]
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
@@ -7762,6 +7804,29 @@
|
||||
"title": "PVForecastCommonSettings",
|
||||
"description": "PV Forecast Configuration."
|
||||
},
|
||||
"PVForecastForecastSolarCommonSettings": {
|
||||
"properties": {
|
||||
"api_key": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "Api Key",
|
||||
"description": "Forecast.Solar API key. Optional \u2014 the public endpoint works without a key (lower rate limit).",
|
||||
"examples": [
|
||||
null,
|
||||
"your-forecast-solar-key"
|
||||
]
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"title": "PVForecastForecastSolarCommonSettings",
|
||||
"description": "Common settings for the Forecast.Solar PV forecast provider."
|
||||
},
|
||||
"PVForecastImportCommonSettings": {
|
||||
"properties": {
|
||||
"import_file_path": {
|
||||
@@ -7804,6 +7869,48 @@
|
||||
"title": "PVForecastImportCommonSettings",
|
||||
"description": "Common settings for pvforecast data import from file or JSON string."
|
||||
},
|
||||
"PVForecastPVNodeCommonSettings": {
|
||||
"properties": {
|
||||
"api_key": {
|
||||
"type": "string",
|
||||
"title": "Api Key",
|
||||
"description": "pvnode.com API key (Bearer auth). Required.",
|
||||
"default": "",
|
||||
"examples": [
|
||||
"pvn_live_xxxxxxxxxxxxxxxx"
|
||||
]
|
||||
},
|
||||
"site_id": {
|
||||
"anyOf": [
|
||||
{
|
||||
"type": "string"
|
||||
},
|
||||
{
|
||||
"type": "null"
|
||||
}
|
||||
],
|
||||
"title": "Site Id",
|
||||
"description": "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.",
|
||||
"examples": [
|
||||
"abcd-1234"
|
||||
]
|
||||
},
|
||||
"forecast_days": {
|
||||
"type": "integer",
|
||||
"maximum": 7.0,
|
||||
"minimum": 1.0,
|
||||
"title": "Forecast Days",
|
||||
"description": "Forecast horizon in days (1-7, capped by the pvnode plan).",
|
||||
"default": 2,
|
||||
"examples": [
|
||||
2
|
||||
]
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"title": "PVForecastPVNodeCommonSettings",
|
||||
"description": "Common settings for the pvnode.com PV forecast provider."
|
||||
},
|
||||
"PVForecastPlaneSetting": {
|
||||
"properties": {
|
||||
"surface_tilt": {
|
||||
@@ -8076,6 +8183,31 @@
|
||||
"title": "PVForecastPlaneSetting",
|
||||
"description": "PV Forecast Plane Configuration."
|
||||
},
|
||||
"PVForecastSolcastCommonSettings": {
|
||||
"properties": {
|
||||
"api_key": {
|
||||
"type": "string",
|
||||
"title": "Api Key",
|
||||
"description": "Solcast API key (Bearer auth). Required.",
|
||||
"default": "",
|
||||
"examples": [
|
||||
"your-solcast-key"
|
||||
]
|
||||
},
|
||||
"site_id": {
|
||||
"type": "string",
|
||||
"title": "Site Id",
|
||||
"description": "Solcast rooftop site (resource) id. Required.",
|
||||
"default": "",
|
||||
"examples": [
|
||||
"abcd-1234-efgh-5678"
|
||||
]
|
||||
}
|
||||
},
|
||||
"type": "object",
|
||||
"title": "PVForecastSolcastCommonSettings",
|
||||
"description": "Common settings for the Solcast PV forecast provider."
|
||||
},
|
||||
"PVForecastVrmCommonSettings": {
|
||||
"properties": {
|
||||
"pvforecast_vrm_token": {
|
||||
|
||||
@@ -45,7 +45,10 @@ from akkudoktoreos.prediction.loadimport import LoadImport
|
||||
from akkudoktoreos.prediction.loadvrm import LoadVrm
|
||||
from akkudoktoreos.prediction.predictionabc import PredictionContainer
|
||||
from akkudoktoreos.prediction.pvforecastakkudoktor import PVForecastAkkudoktor
|
||||
from akkudoktoreos.prediction.pvforecastforecastsolar import PVForecastForecastSolar
|
||||
from akkudoktoreos.prediction.pvforecastimport import PVForecastImport
|
||||
from akkudoktoreos.prediction.pvforecastpvnode import PVForecastPVNode
|
||||
from akkudoktoreos.prediction.pvforecastsolcast import PVForecastSolcast
|
||||
from akkudoktoreos.prediction.pvforecastvrm import PVForecastVrm
|
||||
from akkudoktoreos.prediction.weatherbrightsky import WeatherBrightSky
|
||||
from akkudoktoreos.prediction.weatherclearoutside import WeatherClearOutside
|
||||
@@ -84,6 +87,9 @@ loadforecast_vrm = LoadVrm()
|
||||
loadforecast_import = LoadImport()
|
||||
pvforecast_akkudoktor = PVForecastAkkudoktor()
|
||||
pvforecast_vrm = PVForecastVrm()
|
||||
pvforecast_pvnode = PVForecastPVNode()
|
||||
pvforecast_forecastsolar = PVForecastForecastSolar()
|
||||
pvforecast_solcast = PVForecastSolcast()
|
||||
pvforecast_import = PVForecastImport()
|
||||
weather_brightsky = WeatherBrightSky()
|
||||
weather_clearoutside = WeatherClearOutside()
|
||||
@@ -105,6 +111,9 @@ def prediction_providers() -> list[
|
||||
LoadImport,
|
||||
PVForecastAkkudoktor,
|
||||
PVForecastVrm,
|
||||
PVForecastPVNode,
|
||||
PVForecastForecastSolar,
|
||||
PVForecastSolcast,
|
||||
PVForecastImport,
|
||||
WeatherBrightSky,
|
||||
WeatherClearOutside,
|
||||
@@ -129,6 +138,9 @@ def prediction_providers() -> list[
|
||||
loadforecast_import, \
|
||||
pvforecast_akkudoktor, \
|
||||
pvforecast_vrm, \
|
||||
pvforecast_pvnode, \
|
||||
pvforecast_forecastsolar, \
|
||||
pvforecast_solcast, \
|
||||
pvforecast_import, \
|
||||
weather_brightsky, \
|
||||
weather_clearoutside, \
|
||||
@@ -149,6 +161,9 @@ def prediction_providers() -> list[
|
||||
loadforecast_import,
|
||||
pvforecast_akkudoktor,
|
||||
pvforecast_vrm,
|
||||
pvforecast_pvnode,
|
||||
pvforecast_forecastsolar,
|
||||
pvforecast_solcast,
|
||||
pvforecast_import,
|
||||
weather_brightsky,
|
||||
weather_clearoutside,
|
||||
@@ -174,6 +189,9 @@ class Prediction(PredictionContainer):
|
||||
LoadImport,
|
||||
PVForecastAkkudoktor,
|
||||
PVForecastVrm,
|
||||
PVForecastPVNode,
|
||||
PVForecastForecastSolar,
|
||||
PVForecastSolcast,
|
||||
PVForecastImport,
|
||||
WeatherBrightSky,
|
||||
WeatherClearOutside,
|
||||
|
||||
@@ -7,7 +7,12 @@ from pydantic import Field, computed_field, field_validator, model_validator
|
||||
from akkudoktoreos.config.configabc import SettingsBaseModel
|
||||
from akkudoktoreos.core.coreabc import get_prediction
|
||||
from akkudoktoreos.prediction.pvforecastabc import PVForecastProvider
|
||||
from akkudoktoreos.prediction.pvforecastforecastsolar import (
|
||||
PVForecastForecastSolarCommonSettings,
|
||||
)
|
||||
from akkudoktoreos.prediction.pvforecastimport import PVForecastImportCommonSettings
|
||||
from akkudoktoreos.prediction.pvforecastpvnode import PVForecastPVNodeCommonSettings
|
||||
from akkudoktoreos.prediction.pvforecastsolcast import PVForecastSolcastCommonSettings
|
||||
from akkudoktoreos.prediction.pvforecastvrm import PVForecastVrmCommonSettings
|
||||
|
||||
|
||||
@@ -18,7 +23,14 @@ def pvforecast_provider_ids() -> list[str]:
|
||||
except:
|
||||
# Prediction may not be initialized
|
||||
# Return at least provider used in example
|
||||
return ["PVForecastAkkudoktor", "PVForecastImport", "PVForecastVrm"]
|
||||
return [
|
||||
"PVForecastAkkudoktor",
|
||||
"PVForecastImport",
|
||||
"PVForecastVrm",
|
||||
"PVForecastPVNode",
|
||||
"PVForecastForecastSolar",
|
||||
"PVForecastSolcast",
|
||||
]
|
||||
|
||||
return [
|
||||
provider.provider_id()
|
||||
@@ -179,6 +191,18 @@ class PVForecastCommonProviderSettings(SettingsBaseModel):
|
||||
default=None,
|
||||
json_schema_extra={"description": "PVForecastVrm settings", "examples": [None]},
|
||||
)
|
||||
PVForecastPVNode: Optional[PVForecastPVNodeCommonSettings] = Field(
|
||||
default=None,
|
||||
json_schema_extra={"description": "PVForecastPVNode settings", "examples": [None]},
|
||||
)
|
||||
PVForecastForecastSolar: Optional[PVForecastForecastSolarCommonSettings] = Field(
|
||||
default=None,
|
||||
json_schema_extra={"description": "PVForecastForecastSolar settings", "examples": [None]},
|
||||
)
|
||||
PVForecastSolcast: Optional[PVForecastSolcastCommonSettings] = Field(
|
||||
default=None,
|
||||
json_schema_extra={"description": "PVForecastSolcast settings", "examples": [None]},
|
||||
)
|
||||
|
||||
|
||||
class PVForecastCommonSettings(SettingsBaseModel):
|
||||
|
||||
163
src/akkudoktoreos/prediction/pvforecastforecastsolar.py
Normal file
163
src/akkudoktoreos/prediction/pvforecastforecastsolar.py
Normal file
@@ -0,0 +1,163 @@
|
||||
"""Retrieves PV forecast data from the Forecast.Solar API.
|
||||
|
||||
Forecast.Solar (https://forecast.solar) is a free public PV forecast service
|
||||
(no API key required; an optional key raises the rate/feature limits). Each
|
||||
request covers a single plane:
|
||||
|
||||
GET https://api.forecast.solar[/{api_key}]/estimate/{lat}/{lon}/{dec}/{az}/{kwp}
|
||||
|
||||
``result.watts`` is the instantaneous AC power per timestamp — exactly what the
|
||||
optimizer consumes as ``pvforecast_ac_power``. EOS plants with several roof
|
||||
planes issue one request per plane and the instantaneous powers are summed per
|
||||
timestamp.
|
||||
|
||||
Note on conventions:
|
||||
- Forecast.Solar azimuth is -180=N, -90=E, 0=S, 90=W, whereas EOS
|
||||
``surface_azimuth`` is north=0, east=90, south=180, west=270. The provider
|
||||
converts via ``az = surface_azimuth - 180``.
|
||||
- Response timestamps are local wall-clock; ``message.info.timezone`` is used
|
||||
to resolve them to absolute instants before EOS resamples them.
|
||||
"""
|
||||
|
||||
import re
|
||||
from typing import Any, Optional
|
||||
|
||||
import pendulum
|
||||
import requests
|
||||
from loguru import logger
|
||||
from pydantic import Field
|
||||
|
||||
from akkudoktoreos.config.configabc import SettingsBaseModel
|
||||
from akkudoktoreos.core.cache import cache_in_file
|
||||
from akkudoktoreos.prediction.pvforecastabc import PVForecastProvider
|
||||
from akkudoktoreos.utils.datetimeutil import to_datetime
|
||||
|
||||
FORECAST_SOLAR_BASE = "https://api.forecast.solar"
|
||||
|
||||
_TZ_SUFFIX = re.compile(r"([zZ]|[+-]\d\d:?\d\d)$")
|
||||
|
||||
|
||||
class PVForecastForecastSolarCommonSettings(SettingsBaseModel):
|
||||
"""Common settings for the Forecast.Solar PV forecast provider."""
|
||||
|
||||
api_key: Optional[str] = Field(
|
||||
default=None,
|
||||
json_schema_extra={
|
||||
"description": (
|
||||
"Forecast.Solar API key. Optional — the public endpoint works "
|
||||
"without a key (lower rate limit)."
|
||||
),
|
||||
"examples": [None, "your-forecast-solar-key"],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
class PVForecastForecastSolar(PVForecastProvider):
|
||||
"""Fetch and process PV forecast data from the Forecast.Solar API."""
|
||||
|
||||
@classmethod
|
||||
def provider_id(cls) -> str:
|
||||
"""Return the unique identifier for the PV-Forecast-Provider."""
|
||||
return "PVForecastForecastSolar"
|
||||
|
||||
@property
|
||||
def _api_key(self) -> Optional[str]:
|
||||
settings = self.config.pvforecast.provider_settings.PVForecastForecastSolar
|
||||
return settings.api_key if settings is not None else None
|
||||
|
||||
def _to_utc_datetime(self, local_ts: Any, iana_tz: Optional[str]) -> Any:
|
||||
"""Resolve a Forecast.Solar wall-clock timestamp to a timezone-aware datetime."""
|
||||
s = str(local_ts).strip()
|
||||
if _TZ_SUFFIX.search(s):
|
||||
return to_datetime(s)
|
||||
tz = iana_tz or str(self.config.general.timezone)
|
||||
dt = pendulum.parse(s, tz=tz)
|
||||
return to_datetime(dt.isoformat())
|
||||
|
||||
def _plane_url(self, plane: Any) -> str:
|
||||
"""Build the single-plane estimate URL for the given plane configuration."""
|
||||
latitude = self.config.general.latitude
|
||||
longitude = self.config.general.longitude
|
||||
if latitude is None or longitude is None:
|
||||
raise ValueError("PVForecastForecastSolar needs general.latitude/longitude")
|
||||
tilt = getattr(plane, "surface_tilt", None)
|
||||
azimuth = getattr(plane, "surface_azimuth", None)
|
||||
peakpower = getattr(plane, "peakpower", None)
|
||||
if tilt is None or azimuth is None or peakpower is None:
|
||||
raise ValueError(
|
||||
"PVForecastForecastSolar needs surface_tilt, surface_azimuth and "
|
||||
"peakpower on each pvforecast.planes entry"
|
||||
)
|
||||
# EOS azimuth (north=0..south=180) -> Forecast.Solar (north=-180..south=0).
|
||||
fs_az = float(azimuth) - 180.0
|
||||
base = FORECAST_SOLAR_BASE
|
||||
api_key = self._api_key
|
||||
if api_key:
|
||||
base = f"{base}/{api_key}"
|
||||
return f"{base}/estimate/{latitude}/{longitude}/{float(tilt)}/{fs_az}/{float(peakpower)}"
|
||||
|
||||
@cache_in_file(with_ttl="1 hour")
|
||||
def _request_forecast(self) -> dict:
|
||||
"""Fetch and aggregate the Forecast.Solar estimate across all configured planes."""
|
||||
planes = self.config.pvforecast.planes or []
|
||||
if not planes:
|
||||
raise ValueError("PVForecastForecastSolar needs at least one pvforecast.planes entry")
|
||||
|
||||
summed: dict[str, float] = {}
|
||||
timezone: Optional[str] = None
|
||||
for plane in planes:
|
||||
url = self._plane_url(plane)
|
||||
logger.debug(f"Requesting Forecast.Solar estimate: {url}")
|
||||
try:
|
||||
response = requests.get(url, headers={"Accept": "application/json"}, timeout=30)
|
||||
response.raise_for_status()
|
||||
except requests.RequestException as e:
|
||||
logger.error(f"Failed to fetch pvforecast from Forecast.Solar: {e}")
|
||||
raise RuntimeError("Failed to fetch pvforecast from Forecast.Solar API") from e
|
||||
data = response.json()
|
||||
if timezone is None:
|
||||
timezone = (data.get("message", {}).get("info", {}) or {}).get("timezone")
|
||||
watts = (data.get("result", {}) or {}).get("watts", {}) or {}
|
||||
for ts, power in watts.items():
|
||||
try:
|
||||
summed[ts] = summed.get(ts, 0.0) + float(power)
|
||||
except (TypeError, ValueError):
|
||||
continue
|
||||
|
||||
self.update_datetime = to_datetime(in_timezone=self.config.general.timezone)
|
||||
return {"timezone": timezone, "watts": summed}
|
||||
|
||||
async def _update_data(self, force_update: Optional[bool] = False) -> None:
|
||||
"""Update forecast data in the PVForecastDataRecord format."""
|
||||
if not self.enabled():
|
||||
logger.info("PVForecastForecastSolar is disabled, skipping update.")
|
||||
return
|
||||
|
||||
body = self._request_forecast(force_update=force_update) # type: ignore[call-arg]
|
||||
timezone = body.get("timezone")
|
||||
watts = body.get("watts", {})
|
||||
|
||||
count = 0
|
||||
for ts, power_w in sorted(watts.items()):
|
||||
try:
|
||||
date = self._to_utc_datetime(ts, timezone)
|
||||
except Exception as e: # noqa: BLE001 - skip unparseable rows
|
||||
logger.warning(f"Forecast.Solar: skipping unparseable timestamp {ts!r}: {e}")
|
||||
continue
|
||||
value = round(float(power_w), 1)
|
||||
await self.update_value(
|
||||
date,
|
||||
{"pvforecast_ac_power": value, "pvforecast_dc_power": value},
|
||||
)
|
||||
count += 1
|
||||
|
||||
logger.debug(f"Updated pvforecast from Forecast.Solar with {count} entries.")
|
||||
self.update_datetime = to_datetime(in_timezone=self.config.general.timezone)
|
||||
|
||||
|
||||
# Example usage
|
||||
if __name__ == "__main__":
|
||||
import asyncio
|
||||
|
||||
pv = PVForecastForecastSolar()
|
||||
asyncio.run(pv._update_data())
|
||||
244
src/akkudoktoreos/prediction/pvforecastpvnode.py
Normal file
244
src/akkudoktoreos/prediction/pvforecastpvnode.py
Normal file
@@ -0,0 +1,244 @@
|
||||
"""Retrieves PV forecast data from the pvnode.com V2 API.
|
||||
|
||||
pvnode.com delivers native 15-minute PV power forecasts. Two request modes,
|
||||
decided by configuration:
|
||||
|
||||
* ``site_id`` set -> ``GET /v2/forecast/{site_id}`` — a saved (and possibly
|
||||
calibrated) site managed in the pvnode web app. This is the operator's primary
|
||||
path: register the plant once on pvnode.com, then enter the site id + API key.
|
||||
* ``site_id`` empty -> ``POST /v2/forecast/inline`` — geometry is sent inline from
|
||||
the configured ``pvforecast.planes`` (works without any web-app setup).
|
||||
|
||||
V2 response timestamps are SITE-LOCAL wall-clock (no offset) accompanied by an
|
||||
IANA ``timezone`` field. We resolve them to absolute instants here so the rest of
|
||||
EOS keeps working in its own timezone. ``pv_power`` is nullable (e.g. at night) —
|
||||
null is treated as 0 W so the optimizer's linear resampling does not interpolate
|
||||
phantom production across the night.
|
||||
|
||||
Notes:
|
||||
- Requires ``pvforecast.provider_settings.PVForecastPVNode.api_key`` (Bearer auth).
|
||||
- API: https://api.pvnode.com/v2 (15-minute resolution).
|
||||
"""
|
||||
|
||||
import re
|
||||
import urllib.parse
|
||||
from typing import Any, Optional
|
||||
|
||||
import pendulum
|
||||
import requests
|
||||
from loguru import logger
|
||||
from pydantic import Field
|
||||
|
||||
from akkudoktoreos.config.configabc import SettingsBaseModel
|
||||
from akkudoktoreos.core.cache import cache_in_file
|
||||
from akkudoktoreos.prediction.pvforecastabc import PVForecastProvider
|
||||
from akkudoktoreos.utils.datetimeutil import to_datetime
|
||||
|
||||
PVNODE_BASE = "https://api.pvnode.com/v2"
|
||||
|
||||
_TZ_SUFFIX = re.compile(r"([zZ]|[+-]\d\d:?\d\d)$")
|
||||
|
||||
|
||||
class PVForecastPVNodeCommonSettings(SettingsBaseModel):
|
||||
"""Common settings for the pvnode.com PV forecast provider."""
|
||||
|
||||
api_key: str = Field(
|
||||
default="",
|
||||
json_schema_extra={
|
||||
"description": "pvnode.com API key (Bearer auth). Required.",
|
||||
"examples": ["pvn_live_xxxxxxxxxxxxxxxx"],
|
||||
},
|
||||
)
|
||||
site_id: Optional[str] = Field(
|
||||
default=None,
|
||||
json_schema_extra={
|
||||
"description": (
|
||||
"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."
|
||||
),
|
||||
"examples": ["abcd-1234"],
|
||||
},
|
||||
)
|
||||
forecast_days: int = Field(
|
||||
default=2,
|
||||
ge=1,
|
||||
le=7,
|
||||
json_schema_extra={
|
||||
"description": "Forecast horizon in days (1-7, capped by the pvnode plan).",
|
||||
"examples": [2],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
class PVForecastPVNode(PVForecastProvider):
|
||||
"""Fetch and process PV forecast data from the pvnode.com V2 API."""
|
||||
|
||||
@classmethod
|
||||
def provider_id(cls) -> str:
|
||||
"""Return the unique identifier for the PV-Forecast-Provider."""
|
||||
return "PVForecastPVNode"
|
||||
|
||||
@property
|
||||
def _settings(self) -> PVForecastPVNodeCommonSettings:
|
||||
settings = self.config.pvforecast.provider_settings.PVForecastPVNode
|
||||
if settings is None:
|
||||
settings = PVForecastPVNodeCommonSettings()
|
||||
return settings
|
||||
|
||||
def _to_utc_datetime(self, local_ts: Any, iana_tz: Optional[str]) -> Any:
|
||||
"""Resolve a pvnode V2 wall-clock timestamp to a timezone-aware datetime.
|
||||
|
||||
V2 timestamps are local wall-clock without offset (e.g. "2026-06-22T14:00:00")
|
||||
plus a response-level IANA ``timezone``. If the string already carries an
|
||||
explicit offset or 'Z' it is trusted as-is.
|
||||
"""
|
||||
s = str(local_ts).strip()
|
||||
if _TZ_SUFFIX.search(s):
|
||||
# Already absolute (offset or Z present) — parse as-is.
|
||||
return to_datetime(s)
|
||||
tz = iana_tz or str(self.config.general.timezone)
|
||||
# Interpret the naive wall-clock string AS local time in tz, then resolve.
|
||||
dt = pendulum.parse(s, tz=tz)
|
||||
return to_datetime(dt.isoformat())
|
||||
|
||||
def _extract_values(self, body: Any) -> list[tuple[Any, float]]:
|
||||
"""Extract (datetime, power_w) rows from a pvnode V2 response body.
|
||||
|
||||
Canonical shape: ``{"timezone": ..., "values": [{"timestamp", "pv_power"}, ...]}``.
|
||||
Tolerant of edge/legacy shapes (mirrors the production DVhub client).
|
||||
"""
|
||||
tz: Optional[str] = None
|
||||
arr: Any = None
|
||||
if isinstance(body, list):
|
||||
arr = body
|
||||
elif isinstance(body, dict):
|
||||
tz = body.get("timezone") if isinstance(body.get("timezone"), str) else None
|
||||
for key in ("values", "forecasts", "data", "forecast"):
|
||||
if isinstance(body.get(key), list):
|
||||
arr = body[key]
|
||||
break
|
||||
if not isinstance(arr, list):
|
||||
return []
|
||||
|
||||
rows: list[tuple[Any, float]] = []
|
||||
for entry in arr:
|
||||
if not isinstance(entry, dict):
|
||||
continue
|
||||
ts = (
|
||||
entry.get("timestamp")
|
||||
or entry.get("time")
|
||||
or entry.get("ts")
|
||||
or entry.get("ts_utc")
|
||||
or entry.get("datetime")
|
||||
)
|
||||
if ts is None:
|
||||
continue
|
||||
# pv_power is nullable (night) -> treat missing as 0 W, not a gap, so the
|
||||
# optimizer's linear resampling does not interpolate across the night.
|
||||
raw_power = entry.get("pv_power")
|
||||
if raw_power is None:
|
||||
raw_power = entry.get("power_w")
|
||||
if raw_power is None:
|
||||
raw_power = entry.get("power")
|
||||
if raw_power is None:
|
||||
raw_power = entry.get("watts")
|
||||
power = 0.0 if raw_power is None else float(raw_power)
|
||||
try:
|
||||
date = self._to_utc_datetime(ts, tz)
|
||||
except Exception as e: # noqa: BLE001 - skip unparseable rows
|
||||
logger.warning(f"pvnode: skipping unparseable timestamp {ts!r}: {e}")
|
||||
continue
|
||||
rows.append((date, round(power, 1)))
|
||||
return rows
|
||||
|
||||
@cache_in_file(with_ttl="1 hour")
|
||||
def _request_forecast(self) -> Any:
|
||||
"""Fetch the PV forecast from pvnode.com (saved site or inline planes)."""
|
||||
settings = self._settings
|
||||
api_key = settings.api_key
|
||||
if not api_key:
|
||||
raise ValueError("PVForecastPVNode requires pvforecast...PVForecastPVNode.api_key")
|
||||
|
||||
headers = {"Authorization": f"Bearer {api_key}", "Accept": "application/json"}
|
||||
params = {"forecast_days": str(settings.forecast_days)}
|
||||
site_id = (settings.site_id or "").strip()
|
||||
|
||||
try:
|
||||
if site_id:
|
||||
url = f"{PVNODE_BASE}/forecast/{urllib.parse.quote(site_id, safe='')}"
|
||||
response = requests.get(url, headers=headers, params=params, timeout=30)
|
||||
else:
|
||||
body = self._inline_body()
|
||||
url = f"{PVNODE_BASE}/forecast/inline"
|
||||
headers["Content-Type"] = "application/json"
|
||||
response = requests.post(url, headers=headers, params=params, json=body, timeout=30)
|
||||
logger.debug(f"Requesting pvnode forecast: {url}")
|
||||
response.raise_for_status()
|
||||
except requests.RequestException as e:
|
||||
logger.error(f"Failed to fetch pvforecast from pvnode: {e}")
|
||||
raise RuntimeError("Failed to fetch pvforecast from pvnode API") from e
|
||||
|
||||
self.update_datetime = to_datetime(in_timezone=self.config.general.timezone)
|
||||
return response.json()
|
||||
|
||||
def _inline_body(self) -> dict:
|
||||
"""Build the inline-mode request body from latitude/longitude + planes."""
|
||||
latitude = self.config.general.latitude
|
||||
longitude = self.config.general.longitude
|
||||
if latitude is None or longitude is None:
|
||||
raise ValueError(
|
||||
"PVForecastPVNode inline mode needs general.latitude/longitude "
|
||||
"(or set pvforecast...PVForecastPVNode.site_id)"
|
||||
)
|
||||
planes = self.config.pvforecast.planes or []
|
||||
strings = []
|
||||
for plane in planes:
|
||||
tilt = getattr(plane, "surface_tilt", None)
|
||||
azimuth = getattr(plane, "surface_azimuth", None)
|
||||
peakpower = getattr(plane, "peakpower", None)
|
||||
if peakpower is None or tilt is None or azimuth is None:
|
||||
continue
|
||||
strings.append(
|
||||
{
|
||||
"slope": float(tilt),
|
||||
# pvnode V2 azimuth convention (0=N, 90=E, 180=S, 270=W) matches
|
||||
# EOS surface_azimuth, so it is forwarded unchanged.
|
||||
"orientation": float(azimuth),
|
||||
"power_kw": float(peakpower),
|
||||
}
|
||||
)
|
||||
if not strings:
|
||||
raise ValueError(
|
||||
"PVForecastPVNode inline mode needs at least one pvforecast.planes "
|
||||
"entry with peakpower, surface_tilt and surface_azimuth"
|
||||
)
|
||||
return {"latitude": float(latitude), "longitude": float(longitude), "strings": strings}
|
||||
|
||||
async def _update_data(self, force_update: Optional[bool] = False) -> None:
|
||||
"""Update forecast data in the PVForecastDataRecord format."""
|
||||
if not self.enabled():
|
||||
logger.info("PVForecastPVNode is disabled, skipping update.")
|
||||
return
|
||||
|
||||
body = self._request_forecast(force_update=force_update) # type: ignore[call-arg]
|
||||
rows = self._extract_values(body)
|
||||
|
||||
for date, power_w in rows:
|
||||
# pvnode returns the plant's expected output power; feed it as AC power
|
||||
# (the key the optimizer reads) and mirror it to DC for reporting.
|
||||
await self.update_value(
|
||||
date,
|
||||
{"pvforecast_ac_power": power_w, "pvforecast_dc_power": power_w},
|
||||
)
|
||||
|
||||
logger.debug(f"Updated pvforecast from pvnode with {len(rows)} entries.")
|
||||
self.update_datetime = to_datetime(in_timezone=self.config.general.timezone)
|
||||
|
||||
|
||||
# Example usage
|
||||
if __name__ == "__main__":
|
||||
import asyncio
|
||||
|
||||
pv = PVForecastPVNode()
|
||||
asyncio.run(pv._update_data())
|
||||
144
src/akkudoktoreos/prediction/pvforecastsolcast.py
Normal file
144
src/akkudoktoreos/prediction/pvforecastsolcast.py
Normal file
@@ -0,0 +1,144 @@
|
||||
"""Retrieves PV forecast data from the Solcast API.
|
||||
|
||||
Solcast (https://solcast.com) provides high-accuracy PV forecasts for a rooftop
|
||||
site that the operator registers in the Solcast web app. The operator enters the
|
||||
API key + the rooftop resource id (site id):
|
||||
|
||||
GET https://api.solcast.com.au/rooftop_sites/{site_id}/forecasts?format=json&hours=72
|
||||
|
||||
Each forecast row carries ``pv_estimate`` (in kW) and ``period_end`` (UTC) plus
|
||||
an ISO-8601 ``period`` duration. The estimate is converted to watts and the
|
||||
timestamp is normalised to the period START (``period_end - period``) so it sits
|
||||
on the same axis EOS resamples onto.
|
||||
|
||||
Notes:
|
||||
- Solcast's free tier limits the number of calls per day; the response is
|
||||
cached (1 hour TTL) to stay within budget.
|
||||
"""
|
||||
|
||||
import re
|
||||
import urllib.parse
|
||||
from typing import Any, Optional
|
||||
|
||||
import requests
|
||||
from loguru import logger
|
||||
from pydantic import Field
|
||||
|
||||
from akkudoktoreos.config.configabc import SettingsBaseModel
|
||||
from akkudoktoreos.core.cache import cache_in_file
|
||||
from akkudoktoreos.prediction.pvforecastabc import PVForecastProvider
|
||||
from akkudoktoreos.utils.datetimeutil import to_datetime
|
||||
|
||||
SOLCAST_BASE = "https://api.solcast.com.au/rooftop_sites"
|
||||
|
||||
_PERIOD_RE = re.compile(r"^PT(?:(\d+)H)?(?:(\d+)M)?$")
|
||||
|
||||
|
||||
class PVForecastSolcastCommonSettings(SettingsBaseModel):
|
||||
"""Common settings for the Solcast PV forecast provider."""
|
||||
|
||||
api_key: str = Field(
|
||||
default="",
|
||||
json_schema_extra={
|
||||
"description": "Solcast API key (Bearer auth). Required.",
|
||||
"examples": ["your-solcast-key"],
|
||||
},
|
||||
)
|
||||
site_id: str = Field(
|
||||
default="",
|
||||
json_schema_extra={
|
||||
"description": "Solcast rooftop site (resource) id. Required.",
|
||||
"examples": ["abcd-1234-efgh-5678"],
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
class PVForecastSolcast(PVForecastProvider):
|
||||
"""Fetch and process PV forecast data from the Solcast API."""
|
||||
|
||||
@classmethod
|
||||
def provider_id(cls) -> str:
|
||||
"""Return the unique identifier for the PV-Forecast-Provider."""
|
||||
return "PVForecastSolcast"
|
||||
|
||||
@property
|
||||
def _settings(self) -> PVForecastSolcastCommonSettings:
|
||||
settings = self.config.pvforecast.provider_settings.PVForecastSolcast
|
||||
if settings is None:
|
||||
settings = PVForecastSolcastCommonSettings()
|
||||
return settings
|
||||
|
||||
@staticmethod
|
||||
def _period_minutes(period: Optional[str]) -> int:
|
||||
"""Parse an ISO-8601 period like 'PT30M' or 'PT1H' into minutes (0 if unknown)."""
|
||||
match = _PERIOD_RE.match(str(period or ""))
|
||||
if not match:
|
||||
return 0
|
||||
hours = int(match.group(1) or 0)
|
||||
minutes = int(match.group(2) or 0)
|
||||
return hours * 60 + minutes
|
||||
|
||||
@cache_in_file(with_ttl="1 hour")
|
||||
def _request_forecast(self) -> Any:
|
||||
"""Fetch the rooftop-site forecast from Solcast."""
|
||||
settings = self._settings
|
||||
if not settings.api_key or not settings.site_id:
|
||||
raise ValueError("PVForecastSolcast requires api_key and site_id")
|
||||
|
||||
url = f"{SOLCAST_BASE}/{urllib.parse.quote(settings.site_id, safe='')}/forecasts"
|
||||
params = {"format": "json", "hours": "72"}
|
||||
headers = {"Authorization": f"Bearer {settings.api_key}", "Accept": "application/json"}
|
||||
logger.debug(f"Requesting Solcast forecast: {url}")
|
||||
try:
|
||||
response = requests.get(url, headers=headers, params=params, timeout=30)
|
||||
response.raise_for_status()
|
||||
except requests.RequestException as e:
|
||||
logger.error(f"Failed to fetch pvforecast from Solcast: {e}")
|
||||
raise RuntimeError("Failed to fetch pvforecast from Solcast API") from e
|
||||
|
||||
self.update_datetime = to_datetime(in_timezone=self.config.general.timezone)
|
||||
return response.json()
|
||||
|
||||
async def _update_data(self, force_update: Optional[bool] = False) -> None:
|
||||
"""Update forecast data in the PVForecastDataRecord format."""
|
||||
if not self.enabled():
|
||||
logger.info("PVForecastSolcast is disabled, skipping update.")
|
||||
return
|
||||
|
||||
body = self._request_forecast(force_update=force_update) # type: ignore[call-arg]
|
||||
forecasts = body.get("forecasts", []) if isinstance(body, dict) else []
|
||||
|
||||
count = 0
|
||||
for entry in forecasts:
|
||||
if not isinstance(entry, dict):
|
||||
continue
|
||||
estimate_kw = entry.get("pv_estimate")
|
||||
if estimate_kw is None:
|
||||
estimate_kw = entry.get("pv_estimate_period")
|
||||
period_end = entry.get("period_end")
|
||||
if estimate_kw is None or period_end is None:
|
||||
continue
|
||||
try:
|
||||
end = to_datetime(period_end)
|
||||
except Exception as e: # noqa: BLE001 - skip unparseable rows
|
||||
logger.warning(f"Solcast: skipping unparseable period_end {period_end!r}: {e}")
|
||||
continue
|
||||
minutes = self._period_minutes(entry.get("period"))
|
||||
date = end.subtract(minutes=minutes) if minutes else end
|
||||
power_w = round(float(estimate_kw) * 1000.0, 1)
|
||||
await self.update_value(
|
||||
date,
|
||||
{"pvforecast_ac_power": power_w, "pvforecast_dc_power": power_w},
|
||||
)
|
||||
count += 1
|
||||
|
||||
logger.debug(f"Updated pvforecast from Solcast with {count} entries.")
|
||||
self.update_datetime = to_datetime(in_timezone=self.config.general.timezone)
|
||||
|
||||
|
||||
# Example usage
|
||||
if __name__ == "__main__":
|
||||
import asyncio
|
||||
|
||||
pv = PVForecastSolcast()
|
||||
asyncio.run(pv._update_data())
|
||||
@@ -19,7 +19,10 @@ from akkudoktoreos.prediction.prediction import (
|
||||
PredictionCommonSettings,
|
||||
)
|
||||
from akkudoktoreos.prediction.pvforecastakkudoktor import PVForecastAkkudoktor
|
||||
from akkudoktoreos.prediction.pvforecastforecastsolar import PVForecastForecastSolar
|
||||
from akkudoktoreos.prediction.pvforecastimport import PVForecastImport
|
||||
from akkudoktoreos.prediction.pvforecastpvnode import PVForecastPVNode
|
||||
from akkudoktoreos.prediction.pvforecastsolcast import PVForecastSolcast
|
||||
from akkudoktoreos.prediction.pvforecastvrm import PVForecastVrm
|
||||
from akkudoktoreos.prediction.weatherbrightsky import WeatherBrightSky
|
||||
from akkudoktoreos.prediction.weatherclearoutside import WeatherClearOutside
|
||||
@@ -49,6 +52,9 @@ def forecast_providers():
|
||||
LoadImport(),
|
||||
PVForecastAkkudoktor(),
|
||||
PVForecastVrm(),
|
||||
PVForecastPVNode(),
|
||||
PVForecastForecastSolar(),
|
||||
PVForecastSolcast(),
|
||||
PVForecastImport(),
|
||||
WeatherBrightSky(),
|
||||
WeatherClearOutside(),
|
||||
@@ -98,11 +104,14 @@ def test_provider_sequence(prediction):
|
||||
assert isinstance(prediction.providers[9], LoadImport)
|
||||
assert isinstance(prediction.providers[10], PVForecastAkkudoktor)
|
||||
assert isinstance(prediction.providers[11], PVForecastVrm)
|
||||
assert isinstance(prediction.providers[12], PVForecastImport)
|
||||
assert isinstance(prediction.providers[13], WeatherBrightSky)
|
||||
assert isinstance(prediction.providers[14], WeatherClearOutside)
|
||||
assert isinstance(prediction.providers[15], WeatherOpenMeteo)
|
||||
assert isinstance(prediction.providers[16], WeatherImport)
|
||||
assert isinstance(prediction.providers[12], PVForecastPVNode)
|
||||
assert isinstance(prediction.providers[13], PVForecastForecastSolar)
|
||||
assert isinstance(prediction.providers[14], PVForecastSolcast)
|
||||
assert isinstance(prediction.providers[15], PVForecastImport)
|
||||
assert isinstance(prediction.providers[16], WeatherBrightSky)
|
||||
assert isinstance(prediction.providers[17], WeatherClearOutside)
|
||||
assert isinstance(prediction.providers[18], WeatherOpenMeteo)
|
||||
assert isinstance(prediction.providers[19], WeatherImport)
|
||||
|
||||
|
||||
def test_provider_by_id(prediction, forecast_providers):
|
||||
|
||||
130
tests/test_pvforecastforecastsolar.py
Normal file
130
tests/test_pvforecastforecastsolar.py
Normal file
@@ -0,0 +1,130 @@
|
||||
from unittest.mock import call, patch
|
||||
|
||||
import pendulum
|
||||
import pytest
|
||||
import requests
|
||||
|
||||
from akkudoktoreos.prediction.pvforecastforecastsolar import PVForecastForecastSolar
|
||||
|
||||
|
||||
def _config(config_eos, planes=None, api_key=None):
|
||||
settings = {
|
||||
"general": {"latitude": 52.5, "longitude": 13.4},
|
||||
"pvforecast": {
|
||||
"provider": "PVForecastForecastSolar",
|
||||
"planes": planes
|
||||
if planes is not None
|
||||
else [{"surface_tilt": 30.0, "surface_azimuth": 180.0, "peakpower": 5.0}],
|
||||
"provider_settings": {"PVForecastForecastSolar": {"api_key": api_key}},
|
||||
},
|
||||
}
|
||||
config_eos.merge_settings_from_dict(settings)
|
||||
return config_eos
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def pvforecast_instance(config_eos):
|
||||
_config(config_eos)
|
||||
start_dt = pendulum.datetime(2025, 1, 1, tz="Europe/Berlin")
|
||||
return PVForecastForecastSolar(config=config_eos.load, start_datetime=start_dt)
|
||||
|
||||
|
||||
def _http(watts, timezone="Europe/Berlin"):
|
||||
return type(
|
||||
"R",
|
||||
(),
|
||||
{
|
||||
"raise_for_status": lambda self: None,
|
||||
"json": lambda self: {
|
||||
"result": {"watts": watts},
|
||||
"message": {"info": {"timezone": timezone}},
|
||||
},
|
||||
},
|
||||
)()
|
||||
|
||||
|
||||
def test_provider_id(pvforecast_instance):
|
||||
assert PVForecastForecastSolar.provider_id() == "PVForecastForecastSolar"
|
||||
assert pvforecast_instance.enabled() is True
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_update_data_resolves_tz_and_sets_power(pvforecast_instance):
|
||||
body = {
|
||||
"timezone": "Europe/Berlin",
|
||||
"watts": {"2025-01-01 12:00:00": 1200.0, "2025-01-01 13:00:00": 1500.0},
|
||||
}
|
||||
with patch.object(pvforecast_instance, "_request_forecast", return_value=body), \
|
||||
patch.object(PVForecastForecastSolar, "update_value") as mock_update:
|
||||
await pvforecast_instance._update_data()
|
||||
|
||||
assert mock_update.call_count == 2
|
||||
expected = [
|
||||
call(
|
||||
pendulum.datetime(2025, 1, 1, 12, 0, tz="Europe/Berlin"),
|
||||
{"pvforecast_ac_power": 1200.0, "pvforecast_dc_power": 1200.0},
|
||||
),
|
||||
call(
|
||||
pendulum.datetime(2025, 1, 1, 13, 0, tz="Europe/Berlin"),
|
||||
{"pvforecast_ac_power": 1500.0, "pvforecast_dc_power": 1500.0},
|
||||
),
|
||||
]
|
||||
mock_update.assert_has_calls(expected, any_order=False)
|
||||
# 12:00 Europe/Berlin (CET) is 11:00 UTC.
|
||||
assert mock_update.call_args_list[0][0][0].in_timezone("UTC").hour == 11
|
||||
|
||||
|
||||
def test_plane_url_converts_azimuth(config_eos):
|
||||
"""EOS azimuth 270 (west) -> Forecast.Solar 90; the key + plane geometry land in the URL."""
|
||||
_config(
|
||||
config_eos,
|
||||
planes=[{"surface_tilt": 25.0, "surface_azimuth": 270.0, "peakpower": 7.5}],
|
||||
api_key="secret",
|
||||
)
|
||||
pv = PVForecastForecastSolar(
|
||||
config=config_eos.load, start_datetime=pendulum.datetime(2025, 1, 1, tz="UTC")
|
||||
)
|
||||
with patch("requests.get", return_value=_http({})) as mock_get:
|
||||
# force_update is consumed by the cache_in_file decorator at runtime
|
||||
# (same call convention as pvforecastakkudoktor.py).
|
||||
pv._request_forecast(force_update=True) # type: ignore
|
||||
url = mock_get.call_args[0][0]
|
||||
assert url == "https://api.forecast.solar/secret/estimate/52.5/13.4/25.0/90.0/7.5"
|
||||
|
||||
|
||||
def test_request_forecast_sums_planes(config_eos):
|
||||
"""Two planes -> two requests; instantaneous powers are summed per timestamp."""
|
||||
_config(
|
||||
config_eos,
|
||||
planes=[
|
||||
{"surface_tilt": 30.0, "surface_azimuth": 90.0, "peakpower": 3.0},
|
||||
{"surface_tilt": 30.0, "surface_azimuth": 270.0, "peakpower": 3.0},
|
||||
],
|
||||
)
|
||||
pv = PVForecastForecastSolar(
|
||||
config=config_eos.load, start_datetime=pendulum.datetime(2025, 1, 1, tz="UTC")
|
||||
)
|
||||
responses = [
|
||||
_http({"2025-01-01 12:00:00": 1000.0}),
|
||||
_http({"2025-01-01 12:00:00": 800.0}),
|
||||
]
|
||||
with patch("requests.get", side_effect=responses) as mock_get:
|
||||
body = pv._request_forecast(force_update=True) # type: ignore
|
||||
assert mock_get.call_count == 2
|
||||
assert body["watts"]["2025-01-01 12:00:00"] == 1800.0
|
||||
|
||||
|
||||
def test_update_data_skips_when_disabled(pvforecast_instance, config_eos):
|
||||
config_eos.merge_settings_from_dict({"pvforecast": {"provider": "PVForecastAkkudoktor"}})
|
||||
with patch.object(pvforecast_instance, "_request_forecast") as mock_req, \
|
||||
patch.object(PVForecastForecastSolar, "update_value") as mock_update:
|
||||
pvforecast_instance._update_data()
|
||||
mock_req.assert_not_called()
|
||||
mock_update.assert_not_called()
|
||||
|
||||
|
||||
def test_request_forecast_raises_on_http_error(pvforecast_instance):
|
||||
with patch("requests.get", side_effect=requests.Timeout("timed out")):
|
||||
with pytest.raises(RuntimeError) as exc_info:
|
||||
pvforecast_instance._request_forecast(force_update=True)
|
||||
assert "Failed to fetch pvforecast from Forecast.Solar" in str(exc_info.value)
|
||||
146
tests/test_pvforecastpvnode.py
Normal file
146
tests/test_pvforecastpvnode.py
Normal file
@@ -0,0 +1,146 @@
|
||||
from unittest.mock import call, patch
|
||||
|
||||
import pendulum
|
||||
import pytest
|
||||
import requests
|
||||
|
||||
from akkudoktoreos.prediction.pvforecastpvnode import PVForecastPVNode
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def pvforecast_instance(config_eos):
|
||||
settings = {
|
||||
"general": {"latitude": 52.5, "longitude": 13.4},
|
||||
"pvforecast": {
|
||||
"provider": "PVForecastPVNode",
|
||||
"provider_settings": {
|
||||
"PVForecastPVNode": {
|
||||
"api_key": "dummy-key",
|
||||
"site_id": "test-site-123",
|
||||
"forecast_days": 2,
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
config_eos.merge_settings_from_dict(settings)
|
||||
start_dt = pendulum.datetime(2025, 1, 1, tz="Europe/Berlin")
|
||||
return PVForecastPVNode(config=config_eos.load, start_datetime=start_dt)
|
||||
|
||||
|
||||
def mock_v2_body():
|
||||
"""A canonical pvnode V2 response: site-local wall-clock + IANA timezone.
|
||||
|
||||
The second slot carries a null ``pv_power`` (night) which must become 0 W.
|
||||
"""
|
||||
return {
|
||||
"timezone": "Europe/Berlin",
|
||||
"values": [
|
||||
{"timestamp": "2025-01-01T12:00:00", "pv_power": 1200.0},
|
||||
{"timestamp": "2025-01-01T12:15:00", "pv_power": None},
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def test_provider_id(pvforecast_instance):
|
||||
assert PVForecastPVNode.provider_id() == "PVForecastPVNode"
|
||||
assert pvforecast_instance.enabled() is True
|
||||
|
||||
|
||||
def test_extract_values_resolves_local_wall_clock_to_instant(pvforecast_instance):
|
||||
"""V2 timestamps are local wall-clock; 12:00 Europe/Berlin (CET) == 11:00 UTC."""
|
||||
rows = pvforecast_instance._extract_values(mock_v2_body())
|
||||
|
||||
assert len(rows) == 2
|
||||
# Same instant, regardless of representation.
|
||||
assert rows[0][0] == pendulum.datetime(2025, 1, 1, 12, 0, tz="Europe/Berlin")
|
||||
assert rows[0][0].in_timezone("UTC").hour == 11
|
||||
assert rows[0][1] == 1200.0
|
||||
# Null pv_power -> 0 W (not a gap, to avoid phantom night interpolation).
|
||||
assert rows[1][1] == 0.0
|
||||
|
||||
|
||||
def test_extract_values_trusts_explicit_offset(pvforecast_instance):
|
||||
"""A timestamp already carrying an offset is trusted as-is (no double shift)."""
|
||||
body = {
|
||||
"timezone": "Europe/Berlin",
|
||||
"values": [{"timestamp": "2025-01-01T12:00:00+00:00", "pv_power": 500.0}],
|
||||
}
|
||||
rows = pvforecast_instance._extract_values(body)
|
||||
assert rows[0][0].in_timezone("UTC").hour == 12
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_update_data_sets_ac_and_dc_power(pvforecast_instance):
|
||||
with patch.object(pvforecast_instance, "_request_forecast", return_value=mock_v2_body()), \
|
||||
patch.object(PVForecastPVNode, "update_value") as mock_update:
|
||||
await pvforecast_instance._update_data()
|
||||
|
||||
assert mock_update.call_count == 2
|
||||
expected = [
|
||||
call(
|
||||
pendulum.datetime(2025, 1, 1, 12, 0, tz="Europe/Berlin"),
|
||||
{"pvforecast_ac_power": 1200.0, "pvforecast_dc_power": 1200.0},
|
||||
),
|
||||
call(
|
||||
pendulum.datetime(2025, 1, 1, 12, 15, tz="Europe/Berlin"),
|
||||
{"pvforecast_ac_power": 0.0, "pvforecast_dc_power": 0.0},
|
||||
),
|
||||
]
|
||||
mock_update.assert_has_calls(expected, any_order=False)
|
||||
|
||||
|
||||
def test_update_data_skips_when_disabled(pvforecast_instance, config_eos):
|
||||
config_eos.merge_settings_from_dict({"pvforecast": {"provider": "PVForecastAkkudoktor"}})
|
||||
with patch.object(pvforecast_instance, "_request_forecast") as mock_req, \
|
||||
patch.object(PVForecastPVNode, "update_value") as mock_update:
|
||||
pvforecast_instance._update_data()
|
||||
mock_req.assert_not_called()
|
||||
mock_update.assert_not_called()
|
||||
|
||||
|
||||
def test_update_data_skips_on_empty_forecast(pvforecast_instance):
|
||||
with patch.object(pvforecast_instance, "_request_forecast", return_value={"values": []}), \
|
||||
patch.object(PVForecastPVNode, "update_value") as mock_update:
|
||||
pvforecast_instance._update_data()
|
||||
mock_update.assert_not_called()
|
||||
|
||||
|
||||
def test_request_forecast_uses_saved_site_get(pvforecast_instance):
|
||||
"""site_id set -> GET /v2/forecast/{site_id} with Bearer auth."""
|
||||
fake = type("R", (), {"raise_for_status": lambda self: None, "json": lambda self: {"values": []}})()
|
||||
with patch("requests.get", return_value=fake) as mock_get:
|
||||
pvforecast_instance._request_forecast(force_update=True)
|
||||
url = mock_get.call_args[0][0]
|
||||
assert url.endswith("/v2/forecast/test-site-123")
|
||||
assert mock_get.call_args.kwargs["headers"]["Authorization"] == "Bearer dummy-key"
|
||||
|
||||
|
||||
def test_request_forecast_inline_post_when_no_site(config_eos):
|
||||
"""No site_id -> POST /v2/forecast/inline with planes geometry."""
|
||||
config_eos.merge_settings_from_dict(
|
||||
{
|
||||
"general": {"latitude": 52.5, "longitude": 13.4},
|
||||
"pvforecast": {
|
||||
"provider": "PVForecastPVNode",
|
||||
"planes": [{"surface_tilt": 30.0, "surface_azimuth": 180.0, "peakpower": 5.0}],
|
||||
"provider_settings": {"PVForecastPVNode": {"api_key": "k", "site_id": None}},
|
||||
},
|
||||
}
|
||||
)
|
||||
pv = PVForecastPVNode(config=config_eos.load, start_datetime=pendulum.datetime(2025, 1, 1, tz="UTC"))
|
||||
fake = type("R", (), {"raise_for_status": lambda self: None, "json": lambda self: {"values": []}})()
|
||||
with patch("requests.post", return_value=fake) as mock_post:
|
||||
# force_update is consumed by the cache_in_file decorator at runtime
|
||||
# (same call convention as pvforecastakkudoktor.py).
|
||||
pv._request_forecast(force_update=True) # type: ignore
|
||||
url = mock_post.call_args[0][0]
|
||||
assert url.endswith("/v2/forecast/inline")
|
||||
body = mock_post.call_args.kwargs["json"]
|
||||
assert body["strings"][0] == {"slope": 30.0, "orientation": 180.0, "power_kw": 5.0}
|
||||
|
||||
|
||||
def test_request_forecast_raises_on_http_error(pvforecast_instance):
|
||||
with patch("requests.get", side_effect=requests.Timeout("timed out")):
|
||||
with pytest.raises(RuntimeError) as exc_info:
|
||||
pvforecast_instance._request_forecast(force_update=True)
|
||||
assert "Failed to fetch pvforecast from pvnode" in str(exc_info.value)
|
||||
98
tests/test_pvforecastsolcast.py
Normal file
98
tests/test_pvforecastsolcast.py
Normal file
@@ -0,0 +1,98 @@
|
||||
from unittest.mock import call, patch
|
||||
|
||||
import pendulum
|
||||
import pytest
|
||||
import requests
|
||||
|
||||
from akkudoktoreos.prediction.pvforecastsolcast import PVForecastSolcast
|
||||
|
||||
|
||||
@pytest.fixture
|
||||
def pvforecast_instance(config_eos):
|
||||
settings = {
|
||||
"pvforecast": {
|
||||
"provider": "PVForecastSolcast",
|
||||
"provider_settings": {
|
||||
"PVForecastSolcast": {"api_key": "dummy-key", "site_id": "site-abc"},
|
||||
},
|
||||
},
|
||||
}
|
||||
config_eos.merge_settings_from_dict(settings)
|
||||
start_dt = pendulum.datetime(2025, 1, 1, tz="Europe/Berlin")
|
||||
return PVForecastSolcast(config=config_eos.load, start_datetime=start_dt)
|
||||
|
||||
|
||||
def _http(forecasts):
|
||||
return type(
|
||||
"R",
|
||||
(),
|
||||
{
|
||||
"raise_for_status": lambda self: None,
|
||||
"json": lambda self: {"forecasts": forecasts},
|
||||
},
|
||||
)()
|
||||
|
||||
|
||||
def test_provider_id(pvforecast_instance):
|
||||
assert PVForecastSolcast.provider_id() == "PVForecastSolcast"
|
||||
assert pvforecast_instance.enabled() is True
|
||||
|
||||
|
||||
@pytest.mark.parametrize(
|
||||
"period,minutes",
|
||||
[("PT30M", 30), ("PT15M", 15), ("PT5M", 5), ("PT1H", 60), ("PT1H30M", 90), ("", 0), (None, 0)],
|
||||
)
|
||||
def test_period_minutes(period, minutes):
|
||||
assert PVForecastSolcast._period_minutes(period) == minutes
|
||||
|
||||
|
||||
@pytest.mark.asyncio
|
||||
async def test_update_data_normalises_to_period_start_and_converts_kw(pvforecast_instance):
|
||||
"""pv_estimate (kW) -> W; timestamp = period_end - period; period_end is UTC."""
|
||||
body = {
|
||||
"forecasts": [
|
||||
{"pv_estimate": 1.2, "period_end": "2025-01-01T12:30:00.0000000Z", "period": "PT30M"},
|
||||
{"pv_estimate": 0.0, "period_end": "2025-01-01T13:00:00.0000000Z", "period": "PT30M"},
|
||||
]
|
||||
}
|
||||
with patch.object(pvforecast_instance, "_request_forecast", return_value=body), \
|
||||
patch.object(PVForecastSolcast, "update_value") as mock_update:
|
||||
await pvforecast_instance._update_data()
|
||||
|
||||
assert mock_update.call_count == 2
|
||||
expected = [
|
||||
call(
|
||||
pendulum.datetime(2025, 1, 1, 12, 0, tz="UTC"),
|
||||
{"pvforecast_ac_power": 1200.0, "pvforecast_dc_power": 1200.0},
|
||||
),
|
||||
call(
|
||||
pendulum.datetime(2025, 1, 1, 12, 30, tz="UTC"),
|
||||
{"pvforecast_ac_power": 0.0, "pvforecast_dc_power": 0.0},
|
||||
),
|
||||
]
|
||||
mock_update.assert_has_calls(expected, any_order=False)
|
||||
|
||||
|
||||
def test_request_forecast_uses_site_and_bearer(pvforecast_instance):
|
||||
with patch("requests.get", return_value=_http([])) as mock_get:
|
||||
pvforecast_instance._request_forecast(force_update=True)
|
||||
url = mock_get.call_args[0][0]
|
||||
assert url.endswith("/rooftop_sites/site-abc/forecasts")
|
||||
assert mock_get.call_args.kwargs["headers"]["Authorization"] == "Bearer dummy-key"
|
||||
assert mock_get.call_args.kwargs["params"]["format"] == "json"
|
||||
|
||||
|
||||
def test_update_data_skips_when_disabled(pvforecast_instance, config_eos):
|
||||
config_eos.merge_settings_from_dict({"pvforecast": {"provider": "PVForecastAkkudoktor"}})
|
||||
with patch.object(pvforecast_instance, "_request_forecast") as mock_req, \
|
||||
patch.object(PVForecastSolcast, "update_value") as mock_update:
|
||||
pvforecast_instance._update_data()
|
||||
mock_req.assert_not_called()
|
||||
mock_update.assert_not_called()
|
||||
|
||||
|
||||
def test_request_forecast_raises_on_http_error(pvforecast_instance):
|
||||
with patch("requests.get", side_effect=requests.Timeout("timed out")):
|
||||
with pytest.raises(RuntimeError) as exc_info:
|
||||
pvforecast_instance._request_forecast(force_update=True)
|
||||
assert "Failed to fetch pvforecast from Solcast" in str(exc_info.value)
|
||||
@@ -187,7 +187,10 @@
|
||||
"provider": "PVForecastAkkudoktor",
|
||||
"provider_settings": {
|
||||
"PVForecastImport": null,
|
||||
"PVForecastVrm": null
|
||||
"PVForecastVrm": null,
|
||||
"PVForecastPVNode": null,
|
||||
"PVForecastForecastSolar": null,
|
||||
"PVForecastSolcast": null
|
||||
},
|
||||
"planes": [
|
||||
{
|
||||
|
||||
120
tests/testdata/docs/_generated/configpvforecast.md
vendored
120
tests/testdata/docs/_generated/configpvforecast.md
vendored
@@ -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 @@
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
### Common settings for the Solcast PV forecast provider
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
:::{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. |
|
||||
:::
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
<!-- pyml disable no-emphasis-as-heading -->
|
||||
**Example Input/Output**
|
||||
<!-- pyml enable no-emphasis-as-heading -->
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
```json
|
||||
{
|
||||
"pvforecast": {
|
||||
"provider_settings": {
|
||||
"PVForecastSolcast": {
|
||||
"api_key": "your-solcast-key",
|
||||
"site_id": "abcd-1234-efgh-5678"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
### Common settings for the Forecast.Solar PV forecast provider
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
:::{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). |
|
||||
:::
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
<!-- pyml disable no-emphasis-as-heading -->
|
||||
**Example Input/Output**
|
||||
<!-- pyml enable no-emphasis-as-heading -->
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
```json
|
||||
{
|
||||
"pvforecast": {
|
||||
"provider_settings": {
|
||||
"PVForecastForecastSolar": {
|
||||
"api_key": null
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
### Common settings for the pvnode.com PV forecast provider
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
:::{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. |
|
||||
:::
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
<!-- pyml disable no-emphasis-as-heading -->
|
||||
**Example Input/Output**
|
||||
<!-- pyml enable no-emphasis-as-heading -->
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
```json
|
||||
{
|
||||
"pvforecast": {
|
||||
"provider_settings": {
|
||||
"PVForecastPVNode": {
|
||||
"api_key": "pvn_live_xxxxxxxxxxxxxxxx",
|
||||
"site_id": "abcd-1234",
|
||||
"forecast_days": 2
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
<!-- pyml enable line-length -->
|
||||
|
||||
### Common settings for PV forecast VRM API
|
||||
|
||||
<!-- pyml disable line-length -->
|
||||
@@ -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 |
|
||||
:::
|
||||
<!-- pyml enable line-length -->
|
||||
@@ -273,7 +384,10 @@
|
||||
"pvforecast": {
|
||||
"provider_settings": {
|
||||
"PVForecastImport": null,
|
||||
"PVForecastVrm": null
|
||||
"PVForecastVrm": null,
|
||||
"PVForecastPVNode": null,
|
||||
"PVForecastForecastSolar": null,
|
||||
"PVForecastSolcast": null
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user