Skip to content
Open
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
12 changes: 12 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,18 @@

## [Unreleased]

### easee_cloud 1.4.4

Report when Easee's load balancing holds a start. While the car draws nothing
and the charger holds an order a car can start on, the driver reports
`current_limit_a` as the allocated current and `current_limited_by =
"load_balancer"` when that current is below 6 A. Evidence is the circuit
allocation on all three phases, or else a ReasonForNoCurrent that names the
Equalizer (10 or 28) in the charger's current state. Reason 78 is not
evidence: FTW writes that setting too. Easee support says the Equalizer
raises the current again up to 15 minutes after household use falls
(srcfl/ftw#1948); FTW Core waits that long before it reports a failed start.

### easee_cloud 1.4.3

Report the current Easee signals below FTW's order. Attribute the limit to
Expand Down
4 changes: 2 additions & 2 deletions SUPPORT_STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,8 @@ Catalog source is not proof that a target can install or run a driver.
| deye | 2.1.1 | blixt-l1 | not_assessed | — | not_recorded | not_assessed |
| easee | 1.0.4 | ftw-core | not_assessed | — | not_recorded | not_assessed |
| easee | 1.0.4 | blixt-l1 | not_assessed | — | not_recorded | not_assessed |
| easee_cloud | 1.4.3 | ftw-core | not_assessed | — | not_recorded | not_assessed |
| easee_cloud | 1.4.3 | blixt-l1 | not_assessed | — | not_recorded | not_assessed |
| easee_cloud | 1.4.4 | ftw-core | not_assessed | — | not_recorded | not_assessed |
| easee_cloud | 1.4.4 | blixt-l1 | not_assessed | — | not_recorded | not_assessed |
| esphome_dsmr | 1.0.7 | ftw-core | not_assessed | — | not_recorded | not_assessed |
| esphome_dsmr | 1.0.7 | blixt-l1 | not_assessed | — | not_recorded | not_assessed |
| etrel | 1.0.3 | ftw-core | not_assessed | — | not_recorded | not_assessed |
Expand Down
2 changes: 1 addition & 1 deletion devices.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -338,7 +338,7 @@ manufacturers:
protocols:
- protocol: http
driver: "easee_cloud"
version: "1.4.3"
version: "1.4.4"
ders: [ev]
control: true
firmware_versions: ""
Expand Down
6 changes: 6 additions & 0 deletions docs/WRITING-A-DRIVER.md
Original file line number Diff line number Diff line change
Expand Up @@ -436,6 +436,12 @@ all modes. They never grant control or replace a safety limit:
the order and explains the limit. Leave it nil when the cause is not
shown. An older vendor reason code is not proof of a cause. Core says
the car is limited only when its measured power also falls short.
- A start held by load balancing: while the car draws nothing and the
charger reads back an order of at least 6 A, set `current_limit_a` to the
current the load balancing allows and `current_limited_by` to
`"load_balancer"` when that current is below 6 A, the least a car charges
on. Use the same evidence rule. Core then shows a wait of up to 15 minutes
instead of a failed start, and reports a start still missing after that.

A device reading makes a response measured, nothing more. Core calls it
confirmed only when an identified, separate site meter shows a matching
Expand Down
57 changes: 56 additions & 1 deletion drivers/lua/easee_cloud.lua
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ DRIVER = {
id = "easee_cloud",
name = "Easee Cloud",
manufacturer = "Easee",
version = "1.4.3",
version = "1.4.4",
protocols = { "http" },
capabilities = { "ev" },
description = "Easee Home/Charge via Cloud REST API. No local protocol needed.",
Expand Down Expand Up @@ -868,6 +868,50 @@ local order_seen_a, order_seen_ms = nil, 0
local LIMIT_RELEASE_HOLD_MS = 20000
local last_limit_a, last_limited_by, last_limit_ms = nil, nil, nil

-- A car cannot charge on less than 6 A per phase (IEC 61851-1).
local START_A = 6
-- ReasonForNoCurrent codes in which Easee names its Equalizer: 10 "no
-- current, Equalizer current too low" and 28 "current limited by Equalizer"
-- (developer.easee.com/docs/enumerations).
local EQUALIZER_REASONS = { [10] = true, [28] = true }

-- start_held_a returns the current Easee's load balancing lets the car take
-- when that is too little to start, while the car draws nothing and the
-- charger holds FTW's order, which a car could start on. Evidence is the
-- circuit allocation on all three phases (as below: a three-phase car gets
-- the lowest share of the phases in use, a one-phase car the highest; no
-- allocation on any phase is 0 A), or failing that a reason in which Easee
-- names its Equalizer, recorded no earlier than the charger's state. Both
-- must answer the order. A reason that names FTW's own setting (78) is not
-- evidence: FTW writes that setting too.
local function start_held_a(obs, timestamps, answering, dyn_current, power_w, op_mode, request_active)
if not (op_mode == 2 or op_mode == 3 or op_mode == 6) or not request_active or power_w >= 100 then return nil end
if type(dyn_current) ~= "number" or last_amps_set == nil or math.abs(last_amps_set - dyn_current) > 0.5 or
dyn_current < START_A then
return nil
end
local low, high, n = nil, nil, 0
for id = OBS_ALLOCATED_L1, OBS_ALLOCATED_L1 + 2 do
local a = answering(id)
if a then
n, high = n + 1, math.max(high or a, a)
if a > 0 then low = math.min(low or a, a) end
end
end
if n == 3 then
local allocated_a = (phases == 1) and high or (low or 0)
if allocated_a < START_A and allocated_a < dyn_current - 0.5 then return allocated_a end
return nil
end
local reason = answering(OBS_REASON_NO_CUR)
local reason_at = source_time_key(timestamps[OBS_REASON_NO_CUR])
local state_at = source_time_key(timestamps[OBS_OP_MODE])
if reason and EQUALIZER_REASONS[reason] and not (reason_at and state_at and reason_at < state_at) then
return 0
Comment on lines +909 to +910

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Require comparable timestamps before accepting an Equalizer reason

When either the reason timestamp or charger-state timestamp is missing or invalid, this condition accepts the Equalizer reason without proving that it belongs to the current state. After the order settles for 30 seconds, answering() also accepts an old or untimestamped reason. In the Lua harness, removing the state timestamp lets the explicitly rejected old reason 10 produce current_limit_a = 0 and current_limited_by = "load_balancer". This can misclassify a failed start as a load-balancing hold and prolong the failure timeout. Require both timestamps to be comparable and the reason to be no older than the state before using this fallback, consistent with the stale-telemetry rule in AGENTS.md.

AGENTS.md reference: AGENTS.md:L75-L75

Useful? React with 👍 / 👎.

end
return nil
end

local email, password, configured_max_a
local device_limit_a, device_limit_read_ms
local settings_poll_ms = 0
Expand Down Expand Up @@ -1244,6 +1288,17 @@ function driver_poll()
type(dyn_current) == "number" and actual_amps_per_phase and actual_amps_per_phase < dyn_current - 1 then
current_limit_a, current_limited_by = last_limit_a, last_limited_by
end
-- Easee's load balancing can also hold the start: the car draws nothing
-- while the charger holds an order a car starts on. Easee support
-- (srcfl/ftw#1948, 18 Nov 2026): the Equalizer lowers the current at
-- once, raises it again up to 15 minutes after household use falls, and
-- three-phase charging needs START_A on each phase. In a field trace
-- (srcfl/ftw#1948, 12 Nov 2026) FTW ordered 12 A, the charger read back
-- 12 A, and the allocation was 0 A on all three phases for minutes.
if current_limit_a == nil then
local held_a = start_held_a(obs, timestamps, answering, dyn_current, power_w, op_mode, request_active)
if held_a then current_limit_a, current_limited_by = held_a, "load_balancer" end
end

local limit_age_s = device_limit_read_ms and (host.millis() - device_limit_read_ms) / 1000
host.emit("ev", {
Expand Down
66 changes: 63 additions & 3 deletions drivers/tests/lua_harness/test_easee_cloud_allocated_limit.lua
Original file line number Diff line number Diff line change
Expand Up @@ -130,13 +130,14 @@ expect(poll({pilot=12, alloc={10, false, false}}), 12, nil, "one phase, allocati
expect(poll({pilot=12, alloc={12, 16, 16}}), 12, nil, "one phase, the charger's phase unknown")
expect(poll({pilot=12, alloc={0, 0, 0}}), 12, nil, "one phase, no allocation")

-- 4. At or near the order, not charging, or no positive pilot: no limit.
-- 4. At or near the order, or the car finished: no limit. A car that draws
-- nothing under an allocation too small to start on is held (section 8).
boot()
order(15)
expect(poll({pilot=15, alloc={15, 15, 15}}), nil, nil, "at the order")
expect(poll({pilot=14.6, alloc={14, 14, 14}, order=15}), nil, nil, "within half an amp")
expect(poll({mode=2, kw=0, pilot=0, alloc={0, 0, 0}, power_at="23:55:00"}), nil, nil, "waiting to start")
expect(poll({mode=3, kw=0, pilot=0, alloc={0, 0, 0}, power_at="23:55:00"}), nil, nil, "zero pilot")
expect(poll({mode=2, kw=0, pilot=0, alloc={0, 0, 0}, power_at="23:55:00"}), 0, "load_balancer", "waiting to start")
expect(poll({mode=3, kw=0, pilot=0, alloc={0, 0, 0}, power_at="23:55:00"}), 0, "load_balancer", "zero pilot")
expect(poll({mode=4, kw=0, pilot=12, alloc={12, 12, 12}, power_at="23:55:00"}), nil, nil, "car finished")
expect(poll({order=false, power_at="23:55:00", kw=0}), nil, nil, "no readback of the order")

Expand Down Expand Up @@ -196,4 +197,63 @@ later(2000); driver_poll()
local rows = host._emitted.ev
expect(rows[#rows], 12, "load_balancer", "pushed allocation and pilot")

-- 8. Easee's load balancing holds the start. Field trace (srcfl/ftw#1948,
-- 12 Nov 2026): FTW ordered 12 A, the charger read back 12 A, the pilot was
-- 0 A, the allocation 0 A on all three phases, the reason 78 (FTW's own
-- setting), and the car drew nothing for minutes.
local function idle(o)
o.mode, o.kw, o.pilot, o.power_at = o.mode or 6, 0, o.pilot or 0, "23:55:00"
o.order = o.order or 12
return poll(o)
end
boot()
order(12)
expect(idle({alloc={0, 0, 0}, reason=78, reason_at="23:54:22"}), 0, "load_balancer", "no allocation, reason 78")
expect(idle({alloc={4, 4, 4}}), 4, "load_balancer", "4 A on each phase")
expect(idle({alloc={12, 4, 12}}), 4, "load_balancer", "one phase short of 6 A")
expect(idle({alloc={12, 12, 12}}), nil, nil, "allocation back; the car has not started yet")
expect(idle({alloc={12, 0, 0}}), nil, nil, "one-phase wiring with 12 A")
expect(idle({alloc={0, 0, 0}, mode=2}), 0, "load_balancer", "awaiting start")
-- Without an allocation, only a reason that names the Equalizer, recorded
-- in the charger's current state, is evidence.
expect(idle({alloc=false}), nil, nil, "no allocation, no reason")
expect(idle({alloc=false, reason=78, reason_at="23:54:22"}), nil, nil, "FTW's own setting")
expect(idle({alloc=false, reason=27, reason_at="23:54:22"}), nil, nil, "dynamic circuit current")
expect(idle({alloc=false, reason=10, reason_at="23:54:22"}), 0, "load_balancer", "Equalizer current too low")
expect(idle({alloc=false, reason=28, reason_at="23:54:22"}), 0, "load_balancer", "limited by Equalizer")
expect(idle({alloc=false, reason=10, reason_at="23:40:00"}), nil, nil, "Equalizer reason older than the state")
expect(idle({alloc={0, 0, false}, reason=10, reason_at="23:54:22"}), 0, "load_balancer", "two phases and the reason")
expect(idle({alloc={12, 12, 12}, reason=10, reason_at="23:54:22"}), nil, nil, "the allocation outweighs the reason")
-- Not a hold: FTW's own low order or pause, a charger holding another
-- order, a car that stopped asking, a finished or faulted charger, or a car
-- that draws.
expect(idle({alloc={0, 0, 0}, mode=4}), nil, nil, "car finished")
expect(idle({alloc={0, 0, 0}, mode=5}), nil, nil, "charger fault")
expect(idle({alloc={0, 0, 0}, mode=6, reason=50, reason_at="23:54:22"}), nil, nil, "car not asking")
expect(poll({mode=3, kw=0.2, pilot=0, alloc={0, 0, 0}, order=12, power_at="23:55:00"}), nil, nil, "the car draws")
expect(idle({alloc={0, 0, 0}, order=32}), nil, nil, "charger holds another order")
order(5)
expect(idle({alloc={0, 0, 0}, order=5}), nil, nil, "FTW's own order below 6 A")
order(0)
expect(idle({alloc={0, 0, 0}, order=0}), nil, nil, "FTW's pause")
-- An allocation older than a new order answers it only once the order
-- has stood 30 s.
boot()
order(12)
expect(idle({alloc={0, 0, 0}, order_at="23:56:00", alloc_at="23:54:22"}), nil, nil, "allocation older than the order")
later(30000)
expect(idle({alloc={0, 0, 0}, order_at="23:56:00", alloc_at="23:54:22"}), 0, "load_balancer", "order stood 30 s")
-- A one-phase car takes the highest phase's share.
boot({phases=1})
order(12, "1p")
expect(idle({alloc={0, 0, 0}}), 0, "load_balancer", "one phase, no allocation")
expect(idle({alloc={4, 0, 0}}), 4, "load_balancer", "one phase, 4 A")
expect(idle({alloc={8, 0, 0}}), nil, nil, "one phase, 8 A")
-- The hold does not linger as a charging limit once the car draws.
boot()
order(12)
expect(idle({alloc={0, 0, 0}}), 0, "load_balancer", "held")
expect(poll({mode=3, kw=8.28, pilot=12, alloc={12, 12, 12}, order=12, power_at="23:56:00", pilot_at="23:55:50"}),
nil, nil, "started at the order")

print("easee_cloud allocated limit: ok")
6 changes: 3 additions & 3 deletions index.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -193,15 +193,15 @@ drivers:
size_bytes: 4054
sha256: "4a2cd1efb4a5583468ce897ebd88a000e348917295c40210e86ecf834c0ba543"
- name: "easee_cloud"
version: "1.4.3"
version: "1.4.4"
tier: core
protocol: http
connectivity: cloud
setup: [vendor_portal]
ders: [ev]
control: true
size_bytes: 72912
sha256: "ff920be2a7ce042f8708e9191511b4a757b5d702ef954b00fee4ee8aa21bab11"
size_bytes: 75856
sha256: "b8b4cc765fe7a5948d00d79978c5aa07e92ac64fc0e0c06c7107f99920bf4d78"
- name: "esphome_dsmr"
version: "1.0.7"
tier: core
Expand Down
6 changes: 3 additions & 3 deletions manifests/easee_cloud.yaml
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
name: "easee_cloud"
version: "1.4.3"
version: "1.4.4"
tier: core
author: "Sourceful Labs AB"
protocol: http
Expand All @@ -16,9 +16,9 @@ tested_devices:
notes: "Easee Home/Charge via Cloud REST API. No local protocol needed."
min_driver_version: "1.0.1"
min_host_version: "2.0.0"
size_bytes: 72912
size_bytes: 75856
dkb_id: "easee_cloud"
sha256: "ff920be2a7ce042f8708e9191511b4a757b5d702ef954b00fee4ee8aa21bab11"
sha256: "b8b4cc765fe7a5948d00d79978c5aa07e92ac64fc0e0c06c7107f99920bf4d78"
signature: ""

bytecode_sha256: ""
Expand Down
2 changes: 1 addition & 1 deletion support-status.json
Original file line number Diff line number Diff line change
Expand Up @@ -443,7 +443,7 @@
},
{
"catalog_source": true,
"catalog_version": "1.4.3",
"catalog_version": "1.4.4",
"driver_id": "easee_cloud",
"targets": {
"blixt-l1": {
Expand Down
Loading