feat: PV curtail support (SolarEdge) + operator manual hold

[erikarenhill]

Summary

PR started as "add curtail support to SolarEdge inverters when prices are negative" and grew into a broader PV-curtail + EV-priority cleanup once real hardware exposed adjacent issues. Verified end-to-end on live hardware: 25/50/75 % manual hold sweep on an 8 kW HD-Wave inverter, EV / battery surplus split before/after the priority fix, 30-min stability monitor after the Tesla cadence change.

PV curtail — SolarEdge (HD-Wave / StorEdge / K-series)

• curtail / curtail_disable action handlers in drivers/solaredge.lua, drivers/solaredge_pv.lua, and drivers/solaredge_legacy.lua writing the SolarEdge proprietary Advanced Power Control registers (F000 enable + F001 percent 0-100).
• Single atomic FC 0x10 multi-register write across F000+F001 — inverter never sees enable=1 paired with a stale F001 from the previous tick.
• Release path writes BOTH F001=100 AND F000=0 — verified on hardware that disabling F000 alone leaves the cap stuck at the last F001 value on some firmware revisions.
• All three drivers advertise the new pv-curtail capability. Operator opt-in via supports_pv_curtail: true + config.nominal_w: <rated W> per driver. SetApp setting "Limit Control Mode = Export Control / Production" required on the inverter for writes to take effect.

PV curtail — control surface

• New control.State.ManualPVHold + POST/GET/DELETE /api/pv/manual_hold mirroring the battery manual-hold UX. Body accepts limit_w or limit_pct; both site-aggregate and driver-scoped holds. limit_pct resolves against each driver's nominal_w (rated inverter output) so "100 %" means the inverter nameplate, not the current cloudy production.
• ComputePVCurtail now treats the planner's PVLimitW as the gating decision and recomputes the actual cap live from telemetry every tick: live_cap = live_load + battery_absorption_headroom + EV_PV_reserve. Self-consumption preserved when load rises mid-slot; absorption sinks (battery SoC headroom < 99 %, EV in surplus_only mode) lift the cap so PV stays uncapped while there's somewhere to put the energy.
• Manual hold bypasses live calc — operator override is unconditional.

EV + battery priority

• loadpoint.SurplusPotentialW — parallel reserve for the curtail decision (counts plugged-but-stopped EVs with SoC headroom, contributes MaxChargeW). The dispatch reserve still excludes them. Surfaced as control.State.EVCurtailHeadroomW.
• loadpoint.SurplusReserveW now reserves MinChargeW for plugged + surplus_only EVs whose SoC is known and below the charge limit. Stays at 0 when SoC is unknown (preserves the strict pre-existing rule — a missing vehicle driver can't permanently block the home battery) or when the vehicle is at its limit (no point holding back for a Tesla taper-to-stop at 59/60). Verified live: Pixii dropped from 5+ kW to <500 W within seconds, EV ramped from 4 W to 1840 W (8 A 1ϕ min step).

EV stability — Tesla driver

• tesla-vehicle polls every 30 s while charging_state == "Charging", 60 s otherwise. The default 60 s cadence + HTTP RTT landed every poll just past the 60 s site watchdog → driver flapped offline/online every cycle, which cascaded into wake-kick + wallbox-cycle spam (28 wake-kicks per 30 min observed before).
• New telemetry.DriverHealth.WatchdogTimeoutOverride + Store.SetDriverWatchdogTimeout + lua binding host.set_watchdog_timeout_s(seconds). Tesla driver registers 5 min at init for headroom on legitimate BLE wake delays.
• Stale-while-charging force-wake at 2.5 min — if last.charging_state == "Charging" and 2.5 min have passed without fresh telemetry, the next poll attaches wakeup=true to recover from "proxy cached one Charging reading then car went BLE-silent." Gated to Charging so a parked car doesn't get its 12 V drained by speculative wakes.
• 30-min stability verification: stale flips 0, wake-kicks 0, wallbox-cycle 0, EV-stopped MPC replans 0 across all six 5-min windows.

UI

• New <ftw-pv-control> modal — Watts / Percent toggle, duration chips, driver scope picker. Opens from the solar planet click in ftw-energy-flow; d.id from an expanded per-driver bubble pre-selects that driver. Reads the picker list from /api/config so only drivers with supports_pv_curtail: true appear.
• Percent label reads "% of inverter max" — matches the backend behavior.

Files changed

• drivers/solaredge.lua, drivers/solaredge_pv.lua, drivers/solaredge_legacy.lua — curtail action handlers + atomic FC 0x10 writes.
• drivers/tesla_vehicle.lua — 30 s Charging cadence + 5 min watchdog + 2.5 min force-wake.
• go/internal/control/dispatch.go — PVManualHold, EVCurtailHeadroomW, liveCurtailLimitW.
• go/internal/api/api_pv_manual.go (new) + routes — /api/pv/manual_hold endpoints.
• go/internal/loadpoint/surplus_reserve.go — SurplusPotentialW + headroom-aware SurplusReserveW.
• go/internal/telemetry/store.go — per-driver watchdog override.
• go/internal/drivers/lua.go — host.set_watchdog_timeout_s binding.
• go/cmd/forty-two-watts/main.go — wires EVCurtailHeadroomW.
• web/components/ftw-pv-control.js + next-app.js + index.html — modal + planet-click routing.
• Tests: control/pv_curtail_test.go, api/api_pv_manual_test.go, drivers/solaredge_curtail_test.go, loadpoint/surplus_reserve_test.go, telemetry/telemetry_test.go.

Design doc: docs/superpowers/specs/2026-05-23-solaredge-curtail-and-pv-manual-hold-design.md.

Operator setup

# config.yaml — example wiring for the HD-Wave variant
- name: solaredge
  lua: drivers/solaredge_pv.lua
  supports_pv_curtail: true
  config:
    nominal_w: 8000          # inverter rated AC output
  capabilities:
    modbus:
      host: 192.168.1.15
      port: 502
      unit_id: 1

Plus enable "Limit Control Mode = Export Control / Production" in the SolarEdge SetApp (or MySolarEdge), otherwise the F000/F001 writes are accepted at the Modbus layer but ignored by the inverter.

Deployment note

The production Pi (192.168.1.139) is currently in dev-binary mode for verification. Switch back to the official image after merge: mv docker-compose.override.yml docker-compose.override.yml.bak-... && docker compose pull && docker compose up -d.

Caveats

• verification_status = experimental on all three SolarEdge drivers. HD-Wave 8 kW verified live in this branch; K-series and StorEdge curtail paths are documented to work but await live-hardware verification.
• F000/F001 do NOT auto-revert on SolarEdge. Cleanup paths write {0, 100} on curtail_disable / deinit / driver_cleanup. A daemon crash mid-curtail will leave the cap applied until SetApp manually releases it (acceptable — operators always have SetApp).

🤖 Generated with Claude Code