Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/easee-load-balancer-limit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"ftw": patch
---

When an Easee charger's own load balancing holds the car below FTW's order, the EV sheet now says "Easee limits the charger to 12 A (its load balancing). FTW asked for 15 A; the car takes 8.3 kW." instead of "Not following". It needs easee_cloud 1.4.1, which reports the current Easee lets the car take while it is below the order, and names its load balancing when Easee's allocation shows it. Without a named cause the sheet reads "The charger lets the car take 12 A, below the 15 A FTW asked for." A car taking far less or more than the limit allows is still judged as before, and an old charger reason is never shown as the cause.
5 changes: 5 additions & 0 deletions .changeset/pilot-evidence.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"ftw": patch
---

Expose fresh effective EV pilot current separately from the dynamic current setting. A confirmed lower pilot that explains measured delivery is an informational charger limitation even when its internal cause is unknown. Stale or future pilot evidence cannot explain an EV shortfall. A pilot that is only past its 90 s window reads as unknown, and the driver's reported limit, such as Easee's load balancing, still stands.
156 changes: 124 additions & 32 deletions go/internal/api/api_control_feedback.go
Original file line number Diff line number Diff line change
Expand Up @@ -35,28 +35,38 @@ type ControlFeedback struct {
SiteEvidence *ControlComparison `json:"site_evidence,omitempty"`
ToleranceW *float64 `json:"tolerance_w"`
// Internal steps of the verdict; the API exposes their result above.
State string `json:"-"`
VerificationTier *int `json:"-"`
VerificationLost bool `json:"-"`
Escalated bool `json:"-"` // not following long enough to be an alarm
Response string `json:"-"`
SiteBeforeW *float64 `json:"-"`
SiteAfterW *float64 `json:"-"`
SiteBeforeAtMs int64 `json:"-"`
SiteAfterAtMs int64 `json:"-"`
SiteDeltaW *float64 `json:"-"`
DeviceDeltaW *float64 `json:"-"`
VerifiedAtMs int64 `json:"-"`
RequestedW *float64 `json:"requested_w"`
SentW *float64 `json:"sent_w"`
ReadbackW *float64 `json:"readback_w"`
ActualW *float64 `json:"actual_w"`
BatterySoC *float64 `json:"battery_soc,omitempty"`
ChargeResumeSoC *float64 `json:"charge_resume_soc,omitempty"`
RequestedA *float64 `json:"requested_a"`
OfferedA *float64 `json:"offered_a"`
DeviceLimitA *float64 `json:"device_limit_a"`
DeviceReason string `json:"device_reason,omitempty"`
State string `json:"-"`
VerificationTier *int `json:"-"`
VerificationLost bool `json:"-"`
Escalated bool `json:"-"` // not following long enough to be an alarm
Response string `json:"-"`
SiteBeforeW *float64 `json:"-"`
SiteAfterW *float64 `json:"-"`
SiteBeforeAtMs int64 `json:"-"`
SiteAfterAtMs int64 `json:"-"`
SiteDeltaW *float64 `json:"-"`
DeviceDeltaW *float64 `json:"-"`
VerifiedAtMs int64 `json:"-"`
RequestedW *float64 `json:"requested_w"`
SentW *float64 `json:"sent_w"`
ReadbackW *float64 `json:"readback_w"`
ActualW *float64 `json:"actual_w"`
BatterySoC *float64 `json:"battery_soc,omitempty"`
ChargeResumeSoC *float64 `json:"charge_resume_soc,omitempty"`
RequestedA *float64 `json:"requested_a"`
OfferedA *float64 `json:"offered_a"`
DeviceLimitA *float64 `json:"device_limit_a"`
PilotA *float64 `json:"pilot_a"`
PilotObservedAt string `json:"pilot_observed_at,omitempty"`
PilotConfirmedAtMs int64 `json:"pilot_confirmed_at_ms,omitempty"`
DynamicLimitA *float64 `json:"dynamic_limit_a"`
// LimitA is the current a charger lets the car take now, when its driver
// reports it below the order; LimitedBy names the cause when the driver
// shows it, and Make the charger for the sentence.
LimitA *float64 `json:"limit_a,omitempty"`
LimitedBy string `json:"limited_by,omitempty"`
Make string `json:"make,omitempty"`
DeviceReason string `json:"device_reason,omitempty"`
// ChargingPhase names the one phase (L1-L3) a one-phase car charges on
// under a three-phase order, and ChargingPhaseMaxW the most it takes.
ChargingPhase string `json:"charging_phase,omitempty"`
Expand All @@ -67,13 +77,19 @@ type ControlFeedback struct {
}

type feedbackReading struct {
SetpointW *float64 `json:"setpoint_w"`
MaxA *float64 `json:"max_a"`
DeviceLimitA *float64 `json:"device_limit_a"`
DeviceLimitAgeS *float64 `json:"device_limit_age_s"`
Reason string `json:"reason_no_current_label"`
Connected *bool `json:"connected"`
Online *bool `json:"is_online"`
SetpointW *float64 `json:"setpoint_w"`
MaxA *float64 `json:"max_a"`
PilotA *float64 `json:"pilot_a"`
PilotObservedAt string `json:"pilot_observed_at"`
PilotConfirmedAtMs *int64 `json:"pilot_confirmed_at_ms"`
DynamicLimitA *float64 `json:"dynamic_limit_a"`
DeviceLimitA *float64 `json:"device_limit_a"`
DeviceLimitAgeS *float64 `json:"device_limit_age_s"`
Reason string `json:"reason_no_current_label"`
LimitA *float64 `json:"current_limit_a"`
LimitedBy string `json:"current_limited_by"`
Connected *bool `json:"connected"`
Online *bool `json:"is_online"`
}

func watts(v float64) *float64 {
Expand Down Expand Up @@ -150,6 +166,30 @@ func (s *Server) controlFeedback(now time.Time) []ControlFeedback {
var d feedbackReading
_ = json.Unmarshal(rd.Data, &d)
f.ReadbackW, f.OfferedA, f.DeviceReason = d.SetpointW, d.MaxA, d.Reason
f.DynamicLimitA = d.DynamicLimitA
pilotAge, pilotValid := pilotReadingAge(d, now)
pilotFresh := pilotValid && pilotAge <= pilotFreshFor
if pilotFresh {
f.PilotA, f.PilotObservedAt, f.PilotConfirmedAtMs = d.PilotA, d.PilotObservedAt, *d.PilotConfirmedAtMs
}
// New pilot-aware drivers must provide usable evidence. Older
// drivers keep their existing normalized-limit contract, and so
// does a valid pilot that is only too old: easee_cloud re-reads it
// once a minute, a late read can pass 90 s, and Core keeps the
// last reading for a minute after the driver stops sending. The
// driver checked its limit against the pilot when it was fresh,
// so only the pilot becomes unknown.
if d.PilotConfirmedAtMs != nil && (!pilotValid || (pilotFresh && *d.PilotA == 0)) {
d.LimitA, d.LimitedBy = nil, ""
}
if d.LimitA != nil {
f.LimitA, f.LimitedBy = d.LimitA, d.LimitedBy
if s.deps.Registry != nil {
if env := s.deps.Registry.Env(rd.Driver); env != nil {
f.Make, _ = env.Identity()
}
}
}
if d.DeviceLimitAgeS != nil && *d.DeviceLimitAgeS >= 0 && *d.DeviceLimitAgeS <= 120 {
f.DeviceLimitA = d.DeviceLimitA
}
Expand Down Expand Up @@ -359,7 +399,7 @@ func setControlStatus(f *ControlFeedback) {
"vehicle_complete", "vehicle_limit_completion", "vehicle_not_requesting":
status = "following"
case "battery_full", "battery_nearly_full", "battery_nearly_empty", "core_limit",
"fuse_limit", "fuse_cooldown", "charger_limit", "one_phase":
"fuse_limit", "fuse_cooldown", "charger_limit", "load_balancer_limit", "charger_pilot_limit", "one_phase":
status = "limited"
case "import_limit":
status = "limited"
Expand Down Expand Up @@ -427,7 +467,9 @@ const (
func classifyControlFeedback(f *ControlFeedback, cmd telemetry.CommandEvidence, commanded, fresh bool, coreReason string, connected *bool, now time.Time) {
set := func(state, reason, severity string) { f.State, f.Reason, f.Severity = state, reason, severity }
if !fresh {
f.ActualW, f.ReadbackW, f.OfferedA, f.DeviceLimitA = nil, nil, nil, nil
f.ActualW, f.ReadbackW, f.OfferedA, f.DeviceLimitA, f.LimitA, f.LimitedBy, f.Make = nil, nil, nil, nil, nil, "", ""
f.PilotA, f.DynamicLimitA = nil, nil
f.PilotObservedAt, f.PilotConfirmedAtMs = "", 0
set("unknown", "telemetry_stale", "warning")
return
}
Expand Down Expand Up @@ -462,7 +504,10 @@ func classifyControlFeedback(f *ControlFeedback, cmd telemetry.CommandEvidence,
set("warning", "no_power_response", "warning")
return
}
if f.RequestedA != nil && f.DeviceLimitA != nil && *f.RequestedA > *f.DeviceLimitA+0.5 {
// With a fresh pilot and the current the charger lets the car take, the
// draw is judged against them below, so the charger's own limit cannot
// hide a car taking less.
if !(f.PilotA != nil && f.LimitA != nil) && f.RequestedA != nil && f.DeviceLimitA != nil && *f.RequestedA > *f.DeviceLimitA+0.5 {
set("limited", "device_limit", "warning")
return
}
Expand Down Expand Up @@ -493,6 +538,34 @@ func classifyControlFeedback(f *ControlFeedback, cmd telemetry.CommandEvidence,
set("limited", "offered_current_lower", "warning")
return
}
// The charger holds the order but its driver reports that it lets the car
// take less, and names its load balancing when the charger's allocation
// shows it (easee_cloud 1.4.1). That explains a car taking about that
// much, never more: within 10 %, or as the car follows a step, within
// 2 A but at most 15 % of the limit. A car taking far less, nothing, or
// more keeps its verdict. A fresh pilot names the charger as the cause
// only when it is below the order and is that current. A lower current
// whose cause the driver does not show still asks for a look.
if f.Kind == "ev" && commanded && cmd.Result == "accepted" && f.SentW != nil && f.RequestedW != nil && f.RequestedA != nil && f.LimitA != nil && f.ActualW != nil &&
*f.SentW > 100 && *f.RequestedA > 0 && *f.LimitA > 0 && *f.LimitA+0.5 < *f.RequestedA && settled {
perA := *f.RequestedW / *f.RequestedA
limitW := *f.LimitA * perA
tolerance := telemetry.ControlToleranceW(limitW)
if *f.ActualW >= limitW-math.Max(tolerance, math.Min(2*perA, 0.15*limitW)) && *f.ActualW <= limitW+tolerance && *f.ActualW < *f.SentW {
if f.LimitedBy == "load_balancer" {
set("limited", "load_balancer_limit", "info")
} else if f.PilotA != nil && *f.PilotA+0.5 < *f.RequestedA && math.Abs(*f.PilotA-*f.LimitA) <= 0.5 {
if f.DeviceLimitA != nil && math.Abs(*f.LimitA-*f.DeviceLimitA) <= 0.5 {
set("limited", "device_limit", "info")
} else {
set("limited", "charger_pilot_limit", "info")
}
} else {
set("limited", "offered_current_lower", "warning")
}
return
}
}
// This is a known Core stop, not a BMS diagnosis or new measurement proof.
// Continued power, changed setpoints, stale readings and faults keep their
// own verdicts. A full battery is still allowed to discharge.
Expand Down Expand Up @@ -626,3 +699,22 @@ func (s *Server) loadpointsWithFeedback(states []loadpoint.State) []loadpointFee
}
return out
}

// pilotFreshFor is how long a pilot's confirmation can explain a draw; it
// matches the 90 s for which easee_cloud vouches for a cloud read.
const pilotFreshFor = 90 * time.Second

// pilotReadingAge is how long ago a pilot-aware driver confirmed its pilot.
// ok is false when the pilot is not a current, or its confirmation is
// missing or lies after now, or its source time after the confirmation.
func pilotReadingAge(d feedbackReading, now time.Time) (age time.Duration, ok bool) {
if d.PilotA == nil || d.PilotConfirmedAtMs == nil || *d.PilotConfirmedAtMs <= 0 || math.IsNaN(*d.PilotA) || math.IsInf(*d.PilotA, 0) || *d.PilotA < 0 {
return 0, false
}
confirmed := time.UnixMilli(*d.PilotConfirmedAtMs)
source, err := time.Parse(time.RFC3339Nano, d.PilotObservedAt)
if err != nil || confirmed.After(now) || source.After(confirmed) {
return 0, false
}
return now.Sub(confirmed), true
}
1 change: 1 addition & 0 deletions go/internal/api/api_control_scenarios_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -272,6 +272,7 @@ func TestControlStatusAnswersEveryReason(t *testing.T) {
"battery_full": {"limited", "info"},
"battery_nearly_full": {"limited", "info"},
"fuse_limit": {"limited", "info"},
"load_balancer_limit": {"limited", "info"},
"device_limit": {"limited", "warning"},
"power_below_target": {"not_following", "warning"},
"setpoint_changed": {"not_following", "warning"},
Expand Down
150 changes: 150 additions & 0 deletions go/internal/api/api_ev_load_balancer_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
package api

import (
"context"
"math"
"os"
"path/filepath"
"testing"
"testing/synctest"
"time"

"github.com/srcfl/ftw/go/internal/config"
"github.com/srcfl/ftw/go/internal/drivers"
"github.com/srcfl/ftw/go/internal/telemetry"
)

// Field trace, 23 Oct 2026 (srcfl/ftw#1763), Easee Cloud: FTW ordered 15 A
// (10.35 kW) throughout and the charger read back 15 A, while Easee's own
// load balancing signalled 13 A to the car, which took 8.85 kW. FTW said
// "Not following". The driver now reports the limit and, when its
// allocation shows it, names the load balancing.
func TestEaseeLoadBalancingReadsAsLimited(t *testing.T) {
// The driver always reads back the order it holds (max_a, observation 48).
const held = `,"max_a":15`
const named = held + `,"current_limit_a":13,"current_limited_by":"load_balancer"`
for _, tc := range []struct {
name, extra string
drawW float64
status, reason, severity string
}{
{"named", named, 8850, "limited", "load_balancer_limit", "info"},
{"cause not shown", held + `,"current_limit_a":13`, 8850, "limited", "offered_current_lower", "warning"},
{"no limit reported", held, 8850, "not_following", "power_below_target", "warning"},
{"a 13 A limit does not explain zero", named, 0, "not_following", "no_power_response", "warning"},
{"nor a car taking far less", named, 4000, "not_following", "power_below_target", "warning"},
{"nor a car 2 A under it", named, 7500, "not_following", "power_below_target", "warning"},
{"nor a car 1.5 A under a 7 A limit", held + `,"current_limit_a":7,"current_limited_by":"load_balancer"`, 3800, "not_following", "power_below_target", "warning"},
{"nor a car at the order", named, 10300, "following", "power_observed", "info"},
{"limit at the order", held + `,"current_limit_a":15,"current_limited_by":"load_balancer"`, 8850, "not_following", "power_below_target", "warning"},
{"a zero limit", held + `,"current_limit_a":0,"current_limited_by":"load_balancer"`, 0, "not_following", "no_power_response", "warning"},
{"a zero limit, no readback", `,"current_limit_a":0,"current_limited_by":"load_balancer"`, 0, "not_following", "no_power_response", "warning"},
// A charger that holds a lower order than FTW sent says so first.
{"charger holds 12 A", `,"max_a":12,"current_limit_a":10,"current_limited_by":"load_balancer"`, 6900, "limited", "offered_current_lower", "warning"},
} {
t.Run(tc.name, func(t *testing.T) {
synctest.Test(t, func(t *testing.T) {
e := newEVTrace(10370)
e.extra = held
for range 5 * 60 / 5 {
e.tick(10350, "plan")
}
if f := e.verdict(t); f.Status != "following" {
t.Fatalf("before the cut: %s/%s", f.Status, f.Reason)
}
e.drawW, e.changedAt, e.extra = tc.drawW, time.Now(), tc.extra
cut := time.Now()
var f ControlFeedback
for range 6 * 60 / 5 {
e.tick(10350, "plan")
f = e.verdict(t)
if tc.status == "limited" && f.Status == "not_following" {
t.Fatalf("at %v: not following (%s)", time.Since(cut), f.Reason)
}
}
if f.Status != tc.status || f.Reason != tc.reason || f.Severity != tc.severity {
t.Fatalf("got %s/%s/%s, want %s/%s/%s", f.Status, f.Reason, f.Severity, tc.status, tc.reason, tc.severity)
}
if tc.reason != "load_balancer_limit" {
return
}
// Requested, allocated and delivered stay apart.
if f.RequestedA == nil || math.Abs(*f.RequestedA-15) > 0.01 || f.OfferedA == nil || *f.OfferedA != 15 ||
f.LimitA == nil || *f.LimitA != 13 || f.LimitedBy != "load_balancer" || f.ActualW == nil || *f.ActualW != 8850 {
t.Fatalf("numbers: requested %v, offer %v, limit %v by %q, actual %v", f.RequestedA, f.OfferedA, f.LimitA, f.LimitedBy, f.ActualW)
}
})
})
}
}

// The trace's balancer stepped between 12, 14 and 13 A. When it lets the
// car take more, the cloud reports the car's old draw for a while; that is
// the balancer's limit, not a charger that stopped following.
func TestEaseeLoadBalancingStepsUp(t *testing.T) {
synctest.Test(t, func(t *testing.T) {
e := newEVTrace(8280)
e.extra = `,"max_a":15,"current_limit_a":12,"current_limited_by":"load_balancer"`
for range 5 * 60 / 5 {
e.tick(10350, "plan")
}
if f := e.verdict(t); f.Reason != "load_balancer_limit" {
t.Fatalf("at 12 A: %s/%s", f.Status, f.Reason)
}
e.extra = `,"max_a":15,"current_limit_a":14,"current_limited_by":"load_balancer"`
for range 4 {
e.tick(10350, "plan")
if f := e.verdict(t); f.Reason != "load_balancer_limit" {
t.Fatalf("after the step to 14 A, car still at 8,280 W: %s/%s", f.Status, f.Reason)
}
}
e.drawW, e.changedAt = 9660, time.Now()
e.tick(10350, "plan")
if f := e.verdict(t); f.Reason != "load_balancer_limit" || *f.LimitA != 14 {
t.Fatalf("at 14 A: %s/%s", f.Status, f.Reason)
}
})
}

// The sentence names the charger's make with its limit, from the identity
// its driver reported. Rows without a limit do not carry it.
func TestChargerLimitCarriesTheMake(t *testing.T) {
dir := t.TempDir()
lua := filepath.Join(dir, "easee_like.lua")
src := `
function driver_init(config) host.set_make("Easee") end
function driver_poll() return 60000 end
function driver_command(action, power_w, cmd) return true end
function driver_default_mode() end
`
if err := os.WriteFile(lua, []byte(src), 0o644); err != nil {
t.Fatal(err)
}
tel := telemetry.NewStore()
reg := drivers.NewRegistry(tel)
t.Cleanup(reg.ShutdownAll)
if err := reg.Add(context.Background(), config.Driver{Name: "easee", Lua: lua}); err != nil {
t.Fatal(err)
}
srv := New(&Deps{Tel: tel, Registry: reg})
for _, tc := range []struct {
extra, make string
}{
{`,"current_limit_a":13,"current_limited_by":"load_balancer"`, "Easee"},
{``, ""},
} {
c := tel.BeginCommand("easee", []byte(`{"action":"ev_set_current","power_w":10350}`), time.Now())
tel.CompleteCommand(c, "accepted")
tel.Update("easee", telemetry.DerEV, 8850, nil, []byte(`{"connected":true`+tc.extra+`}`))
rows := srv.controlFeedback(time.Now())
if len(rows) != 1 || rows[0].Make != tc.make {
t.Fatalf("extra %q: rows %+v, want make %q", tc.extra, rows, tc.make)
}
}
// Stale readings drop the limit, its cause and the make together.
tel.Update("easee", telemetry.DerEV, 8850, nil, []byte(`{"connected":true,"current_limit_a":13,"current_limited_by":"load_balancer"}`))
rows := srv.controlFeedback(time.Now().Add(2 * time.Minute))
if len(rows) != 1 || rows[0].Reason != "telemetry_stale" || rows[0].LimitA != nil || rows[0].LimitedBy != "" || rows[0].Make != "" {
t.Fatalf("stale row keeps its limit: %+v", rows)
}
}
5 changes: 3 additions & 2 deletions go/internal/api/api_ev_not_following_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ type evTrace struct {
srv *Server
changedAt time.Time
drawW float64
extra string // more reading fields, each with a leading comma
}

func newEVTrace(drawW float64) *evTrace {
Expand All @@ -35,8 +36,8 @@ func (e *evTrace) tick(w float64, reason string) {
e.tel.CompleteCommand(c, "accepted")
e.mgr.SetCommanded("garage", w, reason)
e.tel.Update("easee", telemetry.DerEV, e.drawW, nil, []byte(fmt.Sprintf(
`{"connected":true,"control_power_observed_at":%q,"control_power_confirmed":true,"power_max_age_s":180}`,
e.changedAt.Format(time.RFC3339Nano))))
`{"connected":true,"control_power_observed_at":%q,"control_power_confirmed":true,"power_max_age_s":180%s}`,
e.changedAt.Format(time.RFC3339Nano), e.extra)))
e.mgr.Observe("garage", true, e.drawW, 0, true)
time.Sleep(5 * time.Second)
}
Expand Down
Loading
Loading