feat(appproto): ops to set the car's charge level and PV-only

.changeset/ops-soc-surplus.md

@@ -0,0 +1,5 @@
+---
+"ftw": patch
+---
+
+The app can now correct the car's charge level and turn PV-only charging on or off over the session. Two new command operations, `loadpoint.soc.set` and `loadpoint.surplus_only.set`, do what the box's own page does through the same code path, and the matching HTTP routes name them when the passthrough refuses them.

contract/registry.yaml

@@ -117,6 +117,8 @@ ops:
   - { name: battery.hold, scope: ftw.dispatch.write, desc: Hold the battery at a fixed setpoint }
   - { name: loadpoint.hold, scope: ftw.dispatch.write, desc: Charge the car now at a fixed current }
   - { name: loadpoint.boost, scope: ftw.dispatch.write, desc: Boost the car from the house battery }
+  - { name: loadpoint.soc.set, scope: ftw.dispatch.write, desc: Correct the car's current charge level }
+  - { name: loadpoint.surplus_only.set, scope: ftw.dispatch.write, desc: Charge the car from surplus PV only }
 
 # ---------------------------------------------------------------------------
 # Dispatch modes.

go/cmd/ftw/app_link.go

@@ -406,6 +406,50 @@ func (a *appLoadpoints) ObservedBoost(id string, now time.Time) loadpoint.Batter
 	return status
 }
 
+func (a *appLoadpoints) SetSoC(id string, soc float64) bool {
+	if !a.mgr.SetCurrentSoC(id, soc) {
+		return false
+	}
+	if a.mpc != nil {
+		// Before returning, on a fresh context, for the reason the HTTP
+		// route gives: the plan pushed after the result must be drawn from
+		// the corrected level, not from the estimate it replaced.
+		a.mpc.ReplanWithReason(context.Background(), "loadpoint_soc_corrected")
+	}
+	return true
+}
+
+func (a *appLoadpoints) ObservedSoC(id string) (float64, bool) {
+	st, ok := a.mgr.State(id)
+	return st.CurrentSoC, ok
+}
+
+func (a *appLoadpoints) SetSurplusOnly(id string, v bool) (bool, bool) {
+	prev, ok := a.mgr.SetSurplusOnly(id, v)
+	if !ok {
+		return false, false
+	}
+	if a.mpc != nil {
+		if prev && !v {
+			// Turning PV-only off is a regime change: the car may now
+			// import from the grid. The same synchronous, tagged replan the
+			// HTTP target route forces, so the plan pushed after the result
+			// already says so.
+			slog.Info("loadpoint surplus_only disabled — forcing replan", "lp", id)
+			a.mpc.ReplanWithReason(context.Background(), "surplus_only_disabled")
+		} else {
+			// Any other edit gets the HTTP route's background nudge.
+			go a.mpc.ReplanWithReason(context.Background(), "loadpoint_target_changed")
+		}
+	}
+	return prev, true
+}
+
+func (a *appLoadpoints) ObservedSurplusOnly(id string) (bool, bool) {
+	st, ok := a.mgr.State(id)
+	return st.SurplusOnly, ok
+}
+
 // appPlans hands over the planner's current output.
 type appPlans struct {
 	planner *mpc.Service

go/cmd/ftw/app_link_test.go

@@ -1,11 +1,13 @@
 package main
 
 import (
+	"math"
 	"sync"
 	"testing"
 	"time"
 
 	"github.com/srcfl/ftw/go/internal/control"
+	"github.com/srcfl/ftw/go/internal/loadpoint"
 	"github.com/srcfl/ftw/go/internal/telemetry"
 )
 
@@ -240,3 +242,61 @@ func TestAppSetModeRefusesAModeTheBoxDoesNotHave(t *testing.T) {
 		t.Fatalf("a refused mode still changed the state to %q", ctrl.Mode)
 	}
 }
+
+// The port's charge-level path is the HTTP route's: SetCurrentSoC on the
+// manager, refused while no car is plugged in, and read back from the
+// manager's own state — within the half-permille the handler allows, because
+// the manager re-anchors through the session's delivered energy.
+func TestAppLoadpointsCorrectTheChargeLevelThroughTheManager(t *testing.T) {
+	mgr := loadpoint.NewManager()
+	mgr.Load([]loadpoint.Config{{
+		ID: "garage", DriverName: "easee-cloud",
+		VehicleCapacityWh: 60000, PluginSoC: 0.4,
+	}})
+	lp := &appLoadpoints{mgr: mgr}
+
+	if lp.SetSoC("garage", 0.62) {
+		t.Fatal("an unplugged car's level was set")
+	}
+
+	mgr.Observe("garage", true, 7400, 1200, true) // 1.2 kWh into the session
+	if !lp.SetSoC("garage", 0.62) {
+		t.Fatal("a plugged-in car's level was refused")
+	}
+	got, ok := lp.ObservedSoC("garage")
+	if !ok || math.Abs(got-0.62) > 0.0005 {
+		t.Fatalf("read back %v (known %v), want 0.62", got, ok)
+	}
+	if _, ok := lp.ObservedSoC("street"); ok {
+		t.Fatal("a loadpoint the box does not have read back a level")
+	}
+}
+
+// The port's PV-only path is the HTTP target route's SetSurplusOnly: the
+// previous value comes back so the caller knows the direction, and the
+// read-back is the manager's own flag.
+func TestAppLoadpointsFlipSurplusOnlyThroughTheManager(t *testing.T) {
+	mgr := loadpoint.NewManager()
+	mgr.Load([]loadpoint.Config{{ID: "garage", DriverName: "easee-cloud", SurplusOnly: true}})
+	lp := &appLoadpoints{mgr: mgr}
+
+	prev, ok := lp.SetSurplusOnly("garage", false)
+	if !ok || !prev {
+		t.Fatalf("SetSurplusOnly = (%v, %v), want the previous true", prev, ok)
+	}
+	if v, ok := lp.ObservedSurplusOnly("garage"); !ok || v {
+		t.Fatalf("read back %v (known %v), want off", v, ok)
+	}
+
+	prev, ok = lp.SetSurplusOnly("garage", true)
+	if !ok || prev {
+		t.Fatalf("SetSurplusOnly = (%v, %v), want the previous false", prev, ok)
+	}
+	if v, ok := lp.ObservedSurplusOnly("garage"); !ok || !v {
+		t.Fatalf("read back %v (known %v), want on", v, ok)
+	}
+
+	if _, ok := lp.SetSurplusOnly("street", true); ok {
+		t.Fatal("a loadpoint the box does not have took a flag")
+	}
+}

go/internal/api/api.go

@@ -517,14 +517,17 @@ func (s *Server) routes() {
 	s.handle("POST /api/ev/chargers", Configure, s.handleEVChargers)
 	s.handle("GET  /api/ev/providers", Read, s.handleEVProviders)
 	s.handle("GET  /api/loadpoints", Read, s.handleLoadpoints)
-	s.handle("POST /api/loadpoints/{id}/target", Actuate, s.handleLoadpointTarget)
+	// Via names the one field of this body the session can set. The target
+	// level and its deadline still have no command; the passthrough refuses
+	// the whole route either way.
+	s.handle("POST /api/loadpoints/{id}/target", Actuate, s.handleLoadpointTarget, Via(appproto.OpLoadpointSurplusOnlySet))
 	// The schedule is configuration where its sibling target is
 	// actuation: a schedule saved late is the same instruction, only
 	// later, while target/soc/force_start move energy now. The split is
 	// what lets a phone save one through the passthrough.
 	s.handle("PUT    /api/loadpoints/{id}/schedule", Configure, s.handleLoadpointSchedulePut)
 	s.handle("DELETE /api/loadpoints/{id}/schedule", Configure, s.handleLoadpointScheduleClear)
-	s.handle("POST /api/loadpoints/{id}/soc", Actuate, s.handleLoadpointSoC)
+	s.handle("POST /api/loadpoints/{id}/soc", Actuate, s.handleLoadpointSoC, Via(appproto.OpLoadpointSoCSet))
 	s.handle("POST /api/loadpoints/{id}/force_start", Actuate, s.handleLoadpointForceStart)
 	s.handle("POST /api/loadpoints/{id}/manual_hold", Actuate, s.handleLoadpointManualHold)
 	s.handle("DELETE /api/loadpoints/{id}/manual_hold", Actuate, s.handleLoadpointManualHoldClear)

go/internal/api/api_passthrough_test.go

@@ -353,6 +353,22 @@ func TestActuationThroughThePassthroughIsRefused(t *testing.T) {
 				Body: []byte(`{}`), StepUp: true,
 			},
 		},
+		{
+			name: "correcting the car's charge level, which has a command",
+			req: appproto.APIReq{
+				Method: appproto.APIPost, Path: "/api/loadpoints/1/soc",
+				Body: []byte(`{"soc":0.6}`), StepUp: true,
+			},
+			wantOp: appproto.OpLoadpointSoCSet,
+		},
+		{
+			name: "the loadpoint target, whose PV-only flag has a command",
+			req: appproto.APIReq{
+				Method: appproto.APIPost, Path: "/api/loadpoints/1/target",
+				Body: []byte(`{"surplus_only":false}`), StepUp: true,
+			},
+			wantOp: appproto.OpLoadpointSurplusOnlySet,
+		},
 		{
 			name: "holding the battery",
 			req: appproto.APIReq{

go/internal/appproto/command.go

@@ -44,6 +44,15 @@ func defaultOps() map[string]opSpec {
 		// same routes give.
 		OpLoadpointHold:  {scope: ScopeDispatchWrite, dispatchWrite: true},
 		OpLoadpointBoost: {scope: ScopeDispatchWrite, dispatchWrite: true},
+		// The two loadpoint settings carry the same scope — their HTTP
+		// routes are priced Actuate, and a viewer must not change what the
+		// car may draw — but not the dispatch gate, for the mode's reason:
+		// each is state the box holds, and the planner output it reshapes
+		// still meets the gate before anything moves. Refusing a corrected
+		// charge level or a PV-only toggle while a meter is sick would keep
+		// the plan wrong for exactly as long as the box cannot act on it.
+		OpLoadpointSoCSet:         {scope: ScopeDispatchWrite, dispatchWrite: false},
+		OpLoadpointSurplusOnlySet: {scope: ScopeDispatchWrite, dispatchWrite: false},
 	}
 }
 

go/internal/appproto/ev.go

@@ -311,3 +311,135 @@ func (h *Handler) cancelBoost(lp Loadpoints, id string, cmd Cmd, uptimeMs int64)
 	}
 	return h.settleAndReport(cmd.CmdID, res)
 }
+
+// socTolerance is how far a read-back may sit from the level asked for and
+// still be that level: half a permille, the finest unit the telemetry wire
+// carries a state of charge in. The manager re-anchors by subtracting and
+// re-adding the session's delivered energy, which is float arithmetic, and a
+// result that called that "superseded" would be reporting rounding as a
+// rival writer.
+const socTolerance = 0.0005
+
+// loadpointSoCSet is the operator's correction of the car's charge level
+// through the door: the same re-anchor POST /api/loadpoints/{id}/soc does,
+// refused the same way when no car is plugged in. `soc` is a fraction in
+// [0,1] — the rule the rest of the box keeps; permille is a telemetry wire
+// unit, not an argument shape — and the read-back is the same fraction.
+func (h *Handler) loadpointSoCSet(cmd Cmd, uptimeMs int64) error {
+	lp, id, ok, err := h.loadpointFor(cmd)
+	if !ok {
+		return err
+	}
+
+	soc, ok := argNum(cmd.Args, "soc")
+	if !ok || soc < 0 || soc > 1 {
+		return h.rejectArg(cmd, "soc", cmd.Args["soc"])
+	}
+
+	if _, err := h.acceptCmd(cmd, uptimeMs); err != nil {
+		return err
+	}
+
+	if !lp.SetSoC(id, soc) {
+		// No session to correct — the HTTP route's 409. Reported after the
+		// ack, the way control refusing a boost is, and named so the app can
+		// say "plug the car in" rather than "the box is down".
+		return h.settleAndReport(cmd.CmdID, CmdResult{
+			CmdID: cmd.CmdID,
+			State: CmdRejected,
+			Error: &ErrorBody{
+				Code:      ErrUnavailable,
+				Retryable: ErrorRetryable[ErrUnavailable],
+				Args:      map[string]any{"op": cmd.Op, "reason": "unplugged"},
+			},
+		})
+	}
+
+	// Read back the level the box now holds, never the echo of the request.
+	observed, known := lp.ObservedSoC(id)
+	readAtMs := h.cfg.Clock.UptimeMs()
+	var res CmdResult
+	switch {
+	case !known:
+		res = CmdResult{CmdID: cmd.CmdID, State: CmdUnconfirmed}
+	case math.Abs(observed-soc) > socTolerance:
+		// Something else re-anchored the level between the write and the
+		// read — a vehicle reading, another operator.
+		res = CmdResult{
+			CmdID:    cmd.CmdID,
+			State:    CmdSuperseded,
+			Observed: &Observed{Value: observed, Src: ObservedSrcCore, UptimeMs: readAtMs},
+		}
+	default:
+		res = CmdResult{
+			CmdID:    cmd.CmdID,
+			State:    CmdApplied,
+			Observed: &Observed{Value: observed, Src: ObservedSrcCore, UptimeMs: readAtMs},
+		}
+	}
+	return h.settleAndReport(cmd.CmdID, res)
+}
+
+// loadpointSurplusOnlySet turns PV-only charging on or off: the surplus_only
+// field of POST /api/loadpoints/{id}/target, and only that field. The port
+// carries the replan the HTTP route forces when the flag turns off, so the
+// plan pushed after the result already allows the grid. The read-back is 1
+// for on and 0 for off, the boost's convention for a flag.
+func (h *Handler) loadpointSurplusOnlySet(cmd Cmd, uptimeMs int64) error {
+	lp, id, ok, err := h.loadpointFor(cmd)
+	if !ok {
+		return err
+	}
+
+	want, ok := cmd.Args["surplus_only"].(bool)
+	if !ok {
+		return h.rejectArg(cmd, "surplus_only", cmd.Args["surplus_only"])
+	}
+
+	if _, err := h.acceptCmd(cmd, uptimeMs); err != nil {
+		return err
+	}
+
+	if _, ok := lp.SetSurplusOnly(id, want); !ok {
+		// The loadpoint went away between the existence check and the
+		// write — a configuration reload mid-command.
+		return h.settleAndReport(cmd.CmdID, CmdResult{
+			CmdID: cmd.CmdID,
+			State: CmdRejected,
+			Error: &ErrorBody{
+				Code:      ErrUnavailable,
+				Retryable: ErrorRetryable[ErrUnavailable],
+				Args:      map[string]any{"op": cmd.Op},
+			},
+		})
+	}
+
+	observed, known := lp.ObservedSurplusOnly(id)
+	readAtMs := h.cfg.Clock.UptimeMs()
+	var res CmdResult
+	switch {
+	case !known:
+		res = CmdResult{CmdID: cmd.CmdID, State: CmdUnconfirmed}
+	case observed != want:
+		res = CmdResult{
+			CmdID:    cmd.CmdID,
+			State:    CmdSuperseded,
+			Observed: &Observed{Value: flagValue(observed), Src: ObservedSrcCore, UptimeMs: readAtMs},
+		}
+	default:
+		res = CmdResult{
+			CmdID:    cmd.CmdID,
+			State:    CmdApplied,
+			Observed: &Observed{Value: flagValue(observed), Src: ObservedSrcCore, UptimeMs: readAtMs},
+		}
+	}
+	return h.settleAndReport(cmd.CmdID, res)
+}
+
+// flagValue is a flag as an observed value: 1 on, 0 off.
+func flagValue(v bool) float64 {
+	if v {
+		return 1
+	}
+	return 0
+}