feat(battery): forced discharge to grid mode (feed-in arbitrage)

[webalexeu]

Refs #31971

Implements the forced discharge battery mode that @andig flagged as the missing prerequisite ("we'd require a forced discharge battery mode which is not available"). It adds that mode plus the symmetric feed-in counterpart to the existing batteryGridChargeLimit, so grid arbitrage works in both directions.

Opt-in and region-dependent by construction: inactive unless batteryGridDischargeLimit is set. When set, the battery discharges to grid while the feed-in rate is at or above the limit — after house/EV priority, and only down to the battery's min-soc reserve.

• new api.BatteryDischarge mode, appended to the enum so existing persisted mode values are unchanged
• batteryGridDischargeLimit setting mirroring batteryGridChargeLimit (site API, HTTP, MQTT, persistence)
• requiredBatteryMode: discharge when the feed-in rate ≥ limit; grid-charge and the EV discharge-control hold both take precedence
• min-soc reserve guard in applyBatteryMode (falls back to hold before draining the reserve)
• unit tests for the new mode transitions, incl. grid-charge winning when both are active

On device support (@andig's "verify how common devices would support this", and @Thomvh's note that NL batteries commonly have a "sell" mode): the new mode reuses the existing battery-mode plumbing. A custom meter's batteryMode setter receives it as an int/string (5 / discharge) and maps it to the device's sell command; SoC-limit-only batteries return ErrNotAvailable and are unaffected.

TODO

• UI setting for the discharge limit
• optimizer (MIP) integration to plan export windows from price spreads — deliberately out of scope; this PR is the mode + site-logic foundation

[sourcery-ai]

Hey - I've found 2 issues, and left some high level feedback:

• In applyBatteryMode, the min-SoC reserve enforcement mirrors the existing max-SoC handling but duplicates the pattern; consider extracting a shared helper for these mode-to-hold transitions to keep the charge/discharge guard logic centralized and less error-prone to change.
• batteryMinSocReached returns a hard error when a BatterySocLimiter-capable device lacks Battery capability; if such mixed capability devices are possible, you may want to treat this as ErrNotAvailable (and skip the reserve check) instead of failing the whole battery mode update.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In applyBatteryMode, the min-SoC reserve enforcement mirrors the existing max-SoC handling but duplicates the pattern; consider extracting a shared helper for these mode-to-hold transitions to keep the charge/discharge guard logic centralized and less error-prone to change.
- batteryMinSocReached returns a hard error when a BatterySocLimiter-capable device lacks Battery capability; if such mixed capability devices are possible, you may want to treat this as ErrNotAvailable (and skip the reserve check) instead of failing the whole battery mode update.

## Individual Comments

### Comment 1
<location path="core/site_battery.go" line_range="149-158" />
<code_context>

+// batteryMinSocReached checks if the battery has reached its min soc reserve.
+// Used to stop forced grid discharge before draining the reserve.
+func (site *Site) batteryMinSocReached(dev config.Device[api.Meter]) (bool, error) {
+	meter := dev.Instance()
+
+	batLimiter, ok := api.Cap[api.BatterySocLimiter](meter)
+	if !ok {
+		return false, nil
+	}
+
+	batSoc, ok := api.Cap[api.Battery](meter)
+	if !ok {
+		return false, errors.New("battery with soc limits must have soc")
+	}
+
+	soc, err := batSoc.Soc()
+	if err != nil {
+		return false, err
+	}
+
+	if min, _ := batLimiter.GetSocLimits(); min > 0 && soc <= min {
+		site.log.DEBUG.Printf("battery %s: reserve soc reached (%.0f <= %.0f)", deviceTitleOrName(dev), soc, min)
+		return true, nil
</code_context>
<issue_to_address>
**question:** Min-SoC logic silently ignores a configured limit of 0%, which might be an unintended edge case.

In `batteryMinSocReached`, `min > 0 && soc <= min` means a configured min-SoC of 0% is treated as “no limit”. If 0% should be a valid setting (e.g. “allow full discharge, but still enforce/track a limit”), this condition will never trigger. If the intended meaning is “0 disables the limit”, consider making that explicit (e.g. with a `min == 0` branch or by documenting this behavior where the limit is configured).
</issue_to_address>

### Comment 2
<location path="core/site_battery.go" line_range="183-186" />
<code_context>
 //	In case max soc is reached, hold mode is applied.
 func (site *Site) applyBatteryMode(mode api.BatteryMode) error {
 	fromToCharge := mode == api.BatteryCharge || mode == api.BatteryUnknown && site.batteryMode == api.BatteryCharge
+	fromToDischarge := mode == api.BatteryDischarge || mode == api.BatteryUnknown && site.batteryMode == api.BatteryDischarge

 	for _, dev := range site.batteryMeters {
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Mutating `mode` inside the device loop affects all subsequent batteries, which might be broader than intended.

In `applyBatteryMode`, `mode` is reused for all devices. If `fromToDischarge` is true and any battery reaches reserve (`batteryMinSocReached`), `mode` is switched to `BatteryHold`, causing all later batteries to be held even if they haven’t reached min-SoC. If Hold is meant to be global, this is correct; otherwise, consider using a per-device `deviceMode` derived from `mode` so you can change it locally without affecting the rest of the loop.

Suggested implementation:

```golang
func (site *Site) applyBatteryMode(mode api.BatteryMode) error {
	fromToCharge := mode == api.BatteryCharge || mode == api.BatteryUnknown && site.batteryMode == api.BatteryCharge
	fromToDischarge := mode == api.BatteryDischarge || mode == api.BatteryUnknown && site.batteryMode == api.BatteryDischarge

	for _, dev := range site.batteryMeters {
		deviceMode := mode

		meter := dev.Instance()
			}
		}

		// validate min soc reserve when discharging to grid
		if fromToDischarge && deviceMode != api.BatteryHold {
			ok, err := site.batteryMinSocReached(dev)

```

To fully implement per-device mode handling and avoid unintended global mode mutation:

1. Inside the `for _, dev := range site.batteryMeters` loop, any place where `mode` is:
   - mutated (e.g. `mode = api.BatteryHold`), or
   - read to decide behavior for that specific battery (e.g. `if mode == api.BatteryDischarge { ... }`, `switch mode { ... }`),
   should be switched to use `deviceMode` instead, e.g. `deviceMode = api.BatteryHold`, `if deviceMode == ...`, `switch deviceMode { ... }`.

2. If `site.batteryMode` is intended to reflect the *global* mode, ensure it is updated explicitly outside or after the per-device loop as needed, rather than indirectly via mutations inside the loop.

You’ll need to apply these replacements to the rest of the `applyBatteryMode` function where the snippet did not show all uses of `mode`.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[andig]

Now you're pushing me ;)

[andig]

I really like the PR. The optimizer already has discharge_to_grid: bool. The follow-up problem ist now that we're not enabling this:

• optimizer doesn't use it
• optimizer discharge suggestion not surfaced
• missing legal framework to drive it

I've added #32086 to control this.

[andig]

@copilot resolve the merge conflicts in this pull request

[webalexeu]

@copilot resolve the merge conflicts in this pull request

I've resolved the conflicts. I'm on holidays for the next two weeks so I will probably be less responsive

[FrankvdAa]

@webalexeu please also add discharge option to flagBatteryModeDescription in cmd/flags.go. ;-)

[webalexeu]

@webalexeu please also add discharge option to flagBatteryModeDescription in cmd/flags.go. ;-)

Good catch. PR updated accordingly

[webalexeu]

@andig @premultiply Can you please review it ?

[andig]

@webalexeu can we keep the devices separate? Would also help to not force-push, it makes incremental review impossible.

[andig]

@webalexeu sorry for the confusion — that remark was about device support, not a request. I've pushed four commits to this branch that work through my review above, so you don't have to:

• plugin: switch returns ErrNotAvailable for unmatched value — the ~30 templates using batterymode: source: switch have no default: case, so setting the new mode returned a plain error and aborted the whole battery loop on every tick. Unmatched now wraps api.ErrNotAvailable and the device is skipped. (blocker 1)
• battery: address review findings on grid discharge — hold when HEMS curtails production (blocker 2, with a test), restore the hard error for a soc-limited battery without soc reading (blocker 3), move the conflict WARN into the charge case so it only fires on entry (6), unshadow the min/max builtins (nit).
• site: log missing feed-in rate, reuse BatteryDischarge for the suggestion action — actionDischarge is now api.BatteryDischarge.String(), so the discharge advisory gets the same actionable check as the other three (7); missing feed-in rate is logged like the consumption one (nit).
• api: document battery discharge mode and grid discharge limit endpoints — BATTERY_MODE.DISCHARGE in evcc.ts with regenerated state schema and mcp/openapi.json, BatteryModeResult up to 5, and the /batterygriddischargelimit POST/DELETE documented like their grid charge twins (5).

gofmt clean, go test ./core/... ./plugin/... ./server/... green, vue-tsc --noEmit clean.

Left open, and I'd like your input:

• Overlap with smartFeedInPriorityLimit (8) — we now have two independent feed-in thresholds. That's a config trap and I'd rather decide this before merging than after.
• "after house/EV priority" only holds conditionally (9) — dischargeControlActive returns false unless batteryDischargeControl is enabled, so by default grid discharge outranks an actively fast-charging EV. Either the description gets reworded or the mode gets gated.
• Per-device hold (4) still ships inside the feature commit. Fine by me, just noting it.
• UI for the discharge limit is still the open TODO in your description.

[andig]

Two follow-ups on top of those four: battery: extract fromTo mode helper (the entering/holding/leaving check was spelled out four times) and api: regenerate mcp tool docs for grid discharge limit — the new endpoints made make porcelain drift on server/mcp/openapi.md. All checks are green on cde7fdd.

[webalexeu]

Pushed one more commit on top: 729c390f5 battery: hold grid discharge for fast-charging EV regardless of discharge control.

Finding 9: dischargeControlActive is opt-in and off by default, so the "after house/EV priority" claim in the description didn't hold unless batteryDischargeControl was explicitly enabled. Added evFastChargingActive() as an unconditional check scoped only to the discharge branch of requiredBatteryMode — the existing charge/hold toggle behavior (smartCostActive, the toggle itself) is untouched. Covered by TestBatteryGridDischargeEvFastCharging.

Finding 8: agreed it's a real config trap. Since there's no UI for batteryGridDischargeLimit yet (still the open TODO), I'd rather fold a same-value nudge (pre-filling smartFeedInPriorityLimit when the discharge limit is set) into that UI work as a fast-follow than block this PR on it. Open to stronger coupling later if it still looks needed once the UI exists.

[andig]

@webalexeu @naltatis we've seen that discharging to grid is regulated in some geographies (Germany...). It seems that:

• batteryGridDischargeLimit should be gated behind experimental batteryGridDischarge
• batteryGridDischargeLimit should be marked experimental itself

[andig]

Commit coming up. Except for that- are we good to merge?

[webalexeu]

Commit coming up. Except for that- are we good to merge?

Ok for me

[andig]

@naltatis @webalexeu tried adding the UI setting too to make sure it contains the gating logic. Could you kindly check?

[webalexeu]

Checked the gating logic per your ask. Found one gap: gridDischargeVisible hides the discharge-limit card whenever the experimental toggle is off, even if a limit is already set — the opposite of what the comment right above it says ("a limit that is already set stays reachable so it can be removed"). The new e2e test only covers toggle-off+no-limit and toggle-on, so it didn't catch this. Suggested fix inline. Everything else — the backend gate in batteryGridDischargeActive, the isLoadpoint/apply-all guard, and the toggle switch in BatteryConfigCard.vue — looks correct.

[webalexeu]

This hides the card whenever batteryGridDischarge is off, even when a limit is already set — contradicting the comment above it. Compare gridChargeVisible just above (no such gate, correctly keeps a stale limit reachable/removable).

Suggested change

	gridDischargeVisible(): boolean {
	return (
	!!this.state.batteryGridDischarge &&
	(this.gridDischargePossible || this.gridDischargeLimit !== null)
	);
	},
	gridDischargeVisible(): boolean {
	return (
	this.gridDischargeLimit !== null ||
	(!!this.state.batteryGridDischarge && this.gridDischargePossible)
	);
	},

[webalexeu]

@andig tested locally and seems to be good on the UI side
Do you still need something before merging ?

[naltatis]

I'll give this a closer look and will provide feedback soon.