EOS/docs/_generated/configpvforecast.md at 1abdd345c47b3db5b59b7989491ee1f43fd0fa49

Mirrors/EOS

Fork 0

mirror of https://github.com/Akkudoktor-EOS/EOS.git synced 2026-09-11 10:26:38 +00:00

Files

T

1abdd345c4 fix: unify mypy environments for local checks and CI (#1291 )

The isolated pre-commit mypy hook previously omitted runtime type information that
make mypy used, hiding errors involving dependencies such as Pydantic and Pendulum.
Makefile, pre-commit and CI now run the same full-project typing policy in the
development environment defined by uv.lock.

- Use uv run --locked --exact --extra dev and the same mypy arguments for Makefile
and the local hook. Check all of src and tests, including on configuration-only
changes.
- Pin Python 3.13 for local development and the pre-commit CI job, and install the
locked pre-commit version in CI.
- Disable incremental analysis because existing Pendulum cache state changes mypy 2.3.1
diagnostics. Document the policy, the performance tradeoff and the existing typing debt.
- Add a regression test that exercises Makefile, the hook and the CI command in a
temporary project, accepting valid dependency types and detecting deliberate
Pydantic/Pendulum assignment errors.

Resolve the newly detected mypy diagnostics.

- Enable the numpydantic and Pydantic mypy plugins, retaining strict Pydantic
constructor typing with init_typed = true. Validate raw/coercible payloads through model_validate.
- Propagate concrete record, provider and time-window types through generic collections,
factories and lookup methods. Preserve runtime field inspection and generated time-window
documentation.
- Align Pendulum annotations with actual factory/arithmetic results while retaining Pydantic
validation adapters at runtime. Correct optional values, array boundaries, REST handlers
and plotting interfaces.
- Add pinned scipy-stubs and types-psutil, update uv.lock, and supply the plugins' dependencies.
- Add runtime regression coverage for validated path defaults, normalized time-series metadata,
generic field inspection, invalid timestamps and unsupported provider imports.

Runtime and compatibility details:

- Validate path defaults as Path objects while retaining raw string defaults needed by
migration serialization with exclude_defaults.
- Normalize feed-in tariff lists and default charge rates to NumPy arrays; reject missing
timestamps/uninitialized values explicitly. Importing into a provider without import support
returns HTTP 400.
- Public JSON schemas and OpenAPI structure match main (excluding the generated version).

Signed-off-by: dr-dimitry

Signed-off-by: dr-dimitry
Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>
Co-authored-by: dr-dimitri <87113560+dr-dimitri@users.noreply.github.com>
Co-authored-by: Normann <github@koldrack.com>

2026-09-10 23:20:35 +02:00

19 KiB

Raw Blame History

PV Forecast Configuration

:::{table} pvforecast :widths: 10 20 10 5 5 30 :align: left

Name	Environment Variable	Type	Read-Only	Default	Description
forecastsolar	`EOS_PVFORECAST__FORECASTSOLAR`	`PVForecastForecastSolarCommonSettings`	`rw`	`required`	ForecastSolar provider settings
homeassistant	`EOS_PVFORECAST__HOMEASSISTANT`	`PVForecastHomeAssistantCommonSettings`	`rw`	`required`	Home Assistant provider settings
max_planes	`EOS_PVFORECAST__MAX_PLANES`	`Optional[int]`	`rw`	`0`	Maximum number of planes that can be set
planes	`EOS_PVFORECAST__PLANES`	`Optional[list[akkudoktoreos.prediction.pvforecast.PVForecastPlaneSetting]]`	`rw`	`None`	Plane configuration.
planes_azimuth		`List[float]`	`ro`	`N/A`	Compute a list of the azimuths per active planes.
planes_inverter_paco		`Any`	`ro`	`N/A`	Compute a list of the maximum power rating of the inverter per active planes.
planes_peakpower		`List[float]`	`ro`	`N/A`	Compute a list of the peak power per active planes.
planes_tilt		`List[float]`	`ro`	`N/A`	Compute a list of the tilts per active planes.
planes_userhorizon		`Any`	`ro`	`N/A`	Compute a list of the user horizon per active planes.
provider	`EOS_PVFORECAST__PROVIDER`	`Optional[str]`	`rw`	`None`	PVForecast provider id of provider to be used.
providers		`list[str]`	`ro`	`N/A`	Available PVForecast provider ids.
pvforecastimport	`EOS_PVFORECAST__PVFORECASTIMPORT`	`PVForecastImportCommonSettings`	`rw`	`required`	PV forecast import provider settings
pvlib	`EOS_PVFORECAST__PVLIB`	`PVForecastPVLibCommonSettings`	`rw`	`required`	PVLib provider settings
pvnode	`EOS_PVFORECAST__PVNODE`	`PVForecastPVNodeCommonSettings`	`rw`	`required`	PVNode provider settings
solcast	`EOS_PVFORECAST__SOLCAST`	`PVForecastSolcastCommonSettings`	`rw`	`required`	Solcast provider settings
vrm	`EOS_PVFORECAST__VRM`	`PVForecastVrmCommonSettings`	`rw`	`required`	Victron Remote Management (VRM) provider settings
:::

Example Input

   {
       "pvforecast": {
           "provider": "PVForecastAkkudoktor",
           "pvforecastimport": {
               "import_file_path": null,
               "import_json": null
           },
           "vrm": {
               "token": "your-token",
               "site_id": 12345
           },
           "homeassistant": {
               "entity_id": "sensor.pv_forecast",
               "attribute": "forecast",
               "datetime_key": "datetime",
               "value_key": "watts",
               "value_unit": "W",
               "base_url": null,
               "token": null
           },
           "pvlib": {},
           "pvnode": {
               "api_key": "",
               "site_id": null,
               "forecast_days": 2
           },
           "forecastsolar": {
               "api_key": null
           },
           "solcast": {
               "api_key": "",
               "site_id": ""
           },
           "planes": [
               {
                   "surface_tilt": 10.0,
                   "surface_azimuth": 180.0,
                   "userhorizon": [
                       10.0,
                       20.0,
                       30.0
                   ],
                   "peakpower": 5.0,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "free",
                   "loss": 14.0,
                   "trackingtype": 0,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 6000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               },
               {
                   "surface_tilt": 20.0,
                   "surface_azimuth": 90.0,
                   "userhorizon": [
                       5.0,
                       15.0,
                       25.0
                   ],
                   "peakpower": 3.5,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "free",
                   "loss": 14.0,
                   "trackingtype": 1,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 4000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               }
           ],
           "max_planes": 1
       }
   }

Example Output

   {
       "pvforecast": {
           "provider": "PVForecastAkkudoktor",
           "pvforecastimport": {
               "import_file_path": null,
               "import_json": null
           },
           "vrm": {
               "token": "your-token",
               "site_id": 12345
           },
           "homeassistant": {
               "entity_id": "sensor.pv_forecast",
               "attribute": "forecast",
               "datetime_key": "datetime",
               "value_key": "watts",
               "value_unit": "W",
               "base_url": null,
               "token": null
           },
           "pvlib": {},
           "pvnode": {
               "api_key": "",
               "site_id": null,
               "forecast_days": 2
           },
           "forecastsolar": {
               "api_key": null
           },
           "solcast": {
               "api_key": "",
               "site_id": ""
           },
           "planes": [
               {
                   "surface_tilt": 10.0,
                   "surface_azimuth": 180.0,
                   "userhorizon": [
                       10.0,
                       20.0,
                       30.0
                   ],
                   "peakpower": 5.0,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "free",
                   "loss": 14.0,
                   "trackingtype": 0,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 6000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               },
               {
                   "surface_tilt": 20.0,
                   "surface_azimuth": 90.0,
                   "userhorizon": [
                       5.0,
                       15.0,
                       25.0
                   ],
                   "peakpower": 3.5,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "free",
                   "loss": 14.0,
                   "trackingtype": 1,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 4000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               }
           ],
           "max_planes": 1,
           "providers": [
               "PVForecastAkkudoktor",
               "PVForecastForecastSolar",
               "PVForecastHomeAssistant",
               "PVForecastImport",
               "PVForecastPVLib",
               "PVForecastPVNode",
               "PVForecastSolcast",
               "PVForecastVrm"
           ],
           "planes_peakpower": [
               5.0,
               3.5
           ],
           "planes_azimuth": [
               180.0,
               90.0
           ],
           "planes_tilt": [
               10.0,
               20.0
           ],
           "planes_userhorizon": [
               [
                   10.0,
                   20.0,
                   30.0
               ],
               [
                   5.0,
                   15.0,
                   25.0
               ]
           ],
           "planes_inverter_paco": [
               6000.0,
               4000.0
           ]
       }
   }

Common settings for PV forecast VRM API

:::{table} pvforecast::vrm :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
site_id	`int`	`rw`	`12345`	VRM-Installation-ID
token	`str`	`rw`	`your-token`	Access token for connecting to the Victron Remote Management (VRM) API
:::

Example Input/Output

   {
       "pvforecast": {
           "vrm": {
               "token": "your-token",
               "site_id": 12345
           }
       }
   }

Common settings for the Solcast PV forecast provider

:::{table} pvforecast::solcast :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

   {
       "pvforecast": {
           "solcast": {
               "api_key": "your-solcast-key",
               "site_id": "abcd-1234-efgh-5678"
           }
       }
   }

Common settings for the pvnode.com PV forecast provider

:::{table} pvforecast::pvnode :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

   {
       "pvforecast": {
           "pvnode": {
               "api_key": "pvn_live_xxxxxxxxxxxxxxxx",
               "site_id": "abcd-1234",
               "forecast_days": 2
           }
       }
   }

Common settings for pvforecast data calculation with PVLib

:::{table} pvforecast::pvlib :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
:::

Example Input/Output

   {
       "pvforecast": {
           "pvlib": {}
       }
   }

Common settings for pvforecast data import from file or JSON string

:::{table} pvforecast::pvforecastimport :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
import_file_path	`Union[str, pathlib.Path, NoneType]`	`rw`	`None`	Path to the file to import PV forecast data from.
import_json	`Optional[str]`	`rw`	`None`	JSON string, dictionary of PV forecast value lists.
:::

Example Input/Output

   {
       "pvforecast": {
           "pvforecastimport": {
               "import_file_path": null,
               "import_json": "{\"pvforecast_ac_power\": [0, 8.05, 352.91]}"
           }
       }
   }

PV Forecast Plane Configuration

:::{table} pvforecast::planes::list :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
albedo	`Optional[float]`	`rw`	`0.2`	Proportion of the light hitting the ground that it reflects back.
inverter_model	`Optional[str]`	`rw`	`None`	Model of the inverter of this plane.
inverter_paco	`Optional[int]`	`rw`	`None`	AC power rating of the inverter [W].
loss	`Optional[float]`	`rw`	`14.0`	Sum of PV system losses in percent
module_model	`Optional[str]`	`rw`	`None`	Model of the PV modules of this plane.
modules_per_string	`Optional[int]`	`rw`	`None`	Number of the PV modules of the strings of this plane.
mountingplace	`Optional[str]`	`rw`	`building`	Type of mounting for PV system. Options are 'free' for free-standing and 'building' for building-integrated.
optimal_surface_tilt	`Optional[bool]`	`rw`	`False`	Calculate the optimum tilt angle. Ignored for two-axis tracking.
optimalangles	`Optional[bool]`	`rw`	`False`	Calculate the optimum tilt and azimuth angles. Ignored for two-axis tracking.
peakpower	`Optional[float]`	`rw`	`None`	Nominal power of PV system in kW.
pvtechchoice	`Optional[str]`	`rw`	`crystSi`	PV technology. One of 'crystSi', 'CIS', 'CdTe', 'Unknown'.
strings_per_inverter	`Optional[int]`	`rw`	`None`	Number of the strings of the inverter of this plane.
surface_azimuth	`Optional[float]`	`rw`	`180.0`	Orientation (azimuth angle) of the (fixed) plane. Clockwise from north (north=0, east=90, south=180, west=270).
surface_tilt	`Optional[float]`	`rw`	`30.0`	Tilt angle from horizontal plane. Ignored for two-axis tracking.
trackingtype	`Optional[int]`	`rw`	`None`	Type of suntracking. 0=fixed, 1=single horizontal axis aligned north-south, 2=two-axis tracking, 3=vertical axis tracking, 4=single horizontal axis aligned east-west, 5=single inclined axis aligned north-south.
userhorizon	`Optional[List[float]]`	`rw`	`None`	Elevation of horizon in degrees, at equally spaced azimuth clockwise from north.
:::

Example Input/Output

   {
       "pvforecast": {
           "planes": [
               {
                   "surface_tilt": 10.0,
                   "surface_azimuth": 180.0,
                   "userhorizon": [
                       10.0,
                       20.0,
                       30.0
                   ],
                   "peakpower": 5.0,
                   "pvtechchoice": "crystSi",
                   "mountingplace": "building",
                   "loss": 14.0,
                   "trackingtype": 0,
                   "optimal_surface_tilt": false,
                   "optimalangles": false,
                   "albedo": null,
                   "module_model": null,
                   "inverter_model": null,
                   "inverter_paco": 6000,
                   "modules_per_string": 20,
                   "strings_per_inverter": 2
               }
           ]
       }
   }

Common settings for pvforecast data from a Home Assistant entity

:::{table} pvforecast::homeassistant :widths: 10 10 5 5 30 :align: left

Name	Type	Read-Only	Default	Description
attribute	`str`	`rw`	`forecast`	Entity attribute holding the forecast list.
base_url	`Optional[str]`	`rw`	`None`	Base URL of the Home Assistant instance. Only required when EOS is not running as a Home Assistant add-on (no SUPERVISOR_TOKEN available).
datetime_key	`str`	`rw`	`datetime`	Key for the timestamp in each forecast entry.
entity_id	`str`	`rw`	`sensor.pv_forecast`	Home Assistant entity providing the PV forecast.
token	`Optional[str]`	`rw`	`None`	Long-lived access token for the Home Assistant instance. Only required when EOS is not running as a Home Assistant add-on.
value_key	`str`	`rw`	`watts`	Key for the AC power value in each forecast entry.
value_unit	`Literal['W', 'kW']`	`rw`	`W`	Unit of the forecast value. Converted to W internally.
:::

Example Input/Output

   {
       "pvforecast": {
           "homeassistant": {
               "entity_id": "sensor.pv1_power_now",
               "attribute": "forecast",
               "datetime_key": "datetime",
               "value_key": "watts",
               "value_unit": "W",
               "base_url": "http://homeassistant.local:8123",
               "token": null
           }
       }
   }

Common settings for the Forecast.Solar PV forecast provider

:::{table} pvforecast::forecastsolar :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

   {
       "pvforecast": {
           "forecastsolar": {
               "api_key": null
           }
       }
   }

19 KiB Raw Blame History

PV Forecast Configuration

Common settings for PV forecast VRM API

Common settings for the Solcast PV forecast provider

Common settings for the pvnode.com PV forecast provider

Common settings for pvforecast data calculation with PVLib

Common settings for pvforecast data import from file or JSON string

PV Forecast Plane Configuration

Common settings for pvforecast data from a Home Assistant entity

Common settings for the Forecast.Solar PV forecast provider

19 KiB

Raw Blame History