From 45e19abf5c5347cfc2e95e18e822f8676eb01124 Mon Sep 17 00:00:00 2001 From: Alexander Herold Date: Sat, 20 Jun 2026 18:39:38 +0200 Subject: [PATCH 1/2] docs: document loadpoint priorityStrategy and priorityHysteresis Co-Authored-By: Claude Opus 4.8 --- .../en/reference/configuration/loadpoints.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/src/content/docs/en/reference/configuration/loadpoints.md b/src/content/docs/en/reference/configuration/loadpoints.md index 57f4fc74a..e0b8448a6 100644 --- a/src/content/docs/en/reference/configuration/loadpoints.md +++ b/src/content/docs/en/reference/configuration/loadpoints.md @@ -358,3 +358,43 @@ priority: 2 ``` --- + +### `priorityStrategy` + +Determines how loadpoints that share the same integer `priority` are sub-ordered when PV surplus is distributed. This only breaks ties between equal-priority loadpoints; it never changes the ordering between loadpoints of different `priority`. + +Possible values: + +- `static`: Rank by `priority` only. This is the current default behaviour and keeps the order between equal-priority loadpoints unchanged. +- `soc`: Among equal-priority loadpoints, prefer the one whose vehicle has the **lower** soc, i.e. charge the emptier car first. Only applies when a positive vehicle soc is known. +- `deficit`: Among equal-priority loadpoints, prefer the one with the **larger** gap between vehicle soc and its limit soc (`limitSoc − soc`), i.e. the one furthest from its target. + +The default is `static`, so existing configurations are unaffected unless this option is set explicitly. + +**Default value:** `static` + +**For example**: + +```yaml +priorityStrategy: soc +``` + +--- + +### `priorityHysteresis` + +A deadband (in soc-%) for the `soc` and `deficit` sub-ordering selected via `priorityStrategy`. A loadpoint only outranks another of the same `priority` when it is ahead by **more** than this many soc-%. This prevents two near-equal loadpoints from leapfrogging each other (swapping priority every time their soc crosses); instead they tie and share the available surplus. + +Valid values range from `0` to `99`. The default `0` disables the deadband. Values around `5`–`10` are a good starting point. + +This option has no effect with `priorityStrategy: static`, and it never affects the ordering between loadpoints of different `priority`. + +**Default value:** `0` + +**For example**: + +```yaml +priorityHysteresis: 5 +``` + +--- From 5e426dd3598a16fc029adb84dc079ea2f9ca96e8 Mon Sep 17 00:00:00 2001 From: Alexander Herold Date: Sun, 21 Jun 2026 06:40:48 +0200 Subject: [PATCH 2/2] docs: document loadpoint priorityBasis (percent/energy) Add a priorityBasis section covering the percent (default) and energy bases for the soc/deficit priority strategies, including the capacity fallback, and note that the priorityHysteresis unit follows the basis (soc-% or kWh). Co-Authored-By: Claude Opus 4.8 --- .../en/reference/configuration/loadpoints.md | 27 ++++++++++++++++++- 1 file changed, 26 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/reference/configuration/loadpoints.md b/src/content/docs/en/reference/configuration/loadpoints.md index e0b8448a6..414fccb78 100644 --- a/src/content/docs/en/reference/configuration/loadpoints.md +++ b/src/content/docs/en/reference/configuration/loadpoints.md @@ -381,9 +381,34 @@ priorityStrategy: soc --- +### `priorityBasis` + +Determines whether the `soc` and `deficit` sub-ordering selected via `priorityStrategy` compares loadpoints by charge level percentage or by absolute energy. This avoids over-prioritizing a smaller battery just because its percentage is lower even though it needs less energy (e.g. a 25 kWh second car at 40 % needs less energy than a 75 kWh car at 50 %). + +Possible values: + +- `percent`: Rank by the soc-% gap (`100 − soc` for `soc`, `limitSoc − soc` for `deficit`). This is the default behaviour. +- `energy`: Scale the soc-% gap by the vehicle [`capacity`](/en/reference/configuration/vehicles#capacity), so loadpoints are ranked by **absolute energy (kWh)** rather than percentage — the loadpoint that needs the most energy is charged first. + +When a vehicle's capacity is unknown, the `energy` basis falls back to the percentage gap for that loadpoint, so a missing `capacity` does not break the ordering. + +This option has no effect with `priorityStrategy: static`. + +**Default value:** `percent` + +**For example**: + +```yaml +priorityBasis: energy +``` + +--- + ### `priorityHysteresis` -A deadband (in soc-%) for the `soc` and `deficit` sub-ordering selected via `priorityStrategy`. A loadpoint only outranks another of the same `priority` when it is ahead by **more** than this many soc-%. This prevents two near-equal loadpoints from leapfrogging each other (swapping priority every time their soc crosses); instead they tie and share the available surplus. +A deadband for the `soc` and `deficit` sub-ordering selected via `priorityStrategy`. A loadpoint only outranks another of the same `priority` when it is ahead by **more** than this amount. This prevents two near-equal loadpoints from leapfrogging each other (swapping priority every time their soc crosses); instead they tie and share the available surplus. + +The unit follows [`priorityBasis`](#prioritybasis): soc-% with the `percent` basis (the default) and kWh with the `energy` basis. Valid values range from `0` to `99`. The default `0` disables the deadband. Values around `5`–`10` are a good starting point.