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
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,14 @@

## [Unreleased]

### easee_cloud 1.4.3

Report the current Easee signals below FTW's order. Attribute the limit to
load balancing when the circuit allocation supports it. Require a usable
allocation on all three phases when the active phase of a one-phase car is
unknown. Reject out-of-order REST power observations and keep the coarse
session energy counter declaration.

### easee_cloud 1.4.1

The driver says its session energy is coarse, with `session_wh_coarse`. Easee
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.1 | ftw-core | not_assessed | — | not_recorded | not_assessed |
| easee_cloud | 1.4.1 | 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 |
| 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.1"
version: "1.4.3"
ders: [ev]
control: true
firmware_versions: ""
Expand Down
11 changes: 11 additions & 0 deletions docs/WRITING-A-DRIVER.md
Original file line number Diff line number Diff line change
Expand Up @@ -425,6 +425,17 @@ all modes. They never grant control or replace a safety limit:
from the dynamic offer in `max_a`. `device_limit_age_s` is time since the
successful settings read. Failed reads must not reset its age. Core stops
treating it as a current limit after two minutes.
- `current_limit_a`: the current per phase the charger lets the car take
now, while the car charges and that current is below the host's last
order, which the charger reads back. Set it only from a value that
answers that order: one the charger reported at or after it took the
order, or any once the order has stood long enough for the value to
move. Leave it nil otherwise.
- `current_limited_by`: `"load_balancer"` when the charger's own load
balancing sets `current_limit_a`, shown by an allocation that is below
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 device reading makes a response measured, nothing more. Core calls it
confirmed only when an identified, separate site meter shows a matching
Expand Down
206 changes: 180 additions & 26 deletions 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.1",
version = "1.4.3",
protocols = { "http" },
capabilities = { "ev" },
description = "Easee Home/Charge via Cloud REST API. No local protocol needed.",
Expand Down Expand Up @@ -292,17 +292,19 @@ end

-- Observation IDs (from developer.easee.com/docs/charger-observation-ids)
local OBS_DYN_CURRENT = 48
local OBS_ALLOCATED_L1 = 70 -- circuit total allocated current L1; L2 71, L3 72
local OBS_REASON_NO_CUR = 96
local OBS_CABLE_LOCKED = 103
local OBS_OP_MODE = 109
local OBS_OUTPUT_CURRENT = 114 -- current signalled to the car with the pilot
local OBS_TOTAL_POWER = 120
local OBS_SESSION_ENERGY = 121
local OBS_LIFETIME_ENERGY = 124
local OBS_CURRENT = 183
local OBS_VOLTAGE = 194
local OBS_SESSION_START = 223

local OBS_IDS = "48,96,103,109,120,121,124,183,194,223"
local OBS_IDS = "48,70,71,72,96,103,109,114,120,121,124,183,194,223"
local OBS_WANTED = {}
for id in OBS_IDS:gmatch("%d+") do OBS_WANTED[tonumber(id)] = true end

Expand All @@ -311,14 +313,44 @@ for id in OBS_IDS:gmatch("%d+") do OBS_WANTED[tonumber(id)] = true end
-- stays current until a newer one arrives.
local latest, latest_at, latest_pushed = {}, {}, {}

-- source_time_key makes an RFC 3339 UTC time comparable as a string,
-- whatever its fractional precision: "…:05Z" and "…:05.120+00:00" become
-- "…:05.120000000" and "…:05.120000000". Other offsets give nil.
-- source_time_key makes an RFC 3339 time comparable as a string: seconds
-- since 1970 and nine fractional digits, whatever the offset and precision,
-- so "…03:49:08.1Z" and "…05:49:08.1000000+02:00" give the same key. A time
-- that is not RFC 3339, or names a day that does not exist, gives nil.
-- Written by Segran for srcfl/device-drivers#183.
local function source_time_key(stamp)
if type(stamp) ~= "string" then return nil end
local base, frac, zone = stamp:match("^(%d%d%d%d%-%d%d%-%d%dT%d%d:%d%d:%d%d)(%.?%d*)(.*)$")
if not base or (zone ~= "Z" and zone ~= "+00:00") then return nil end
return base .. "." .. (frac:sub(2) .. "000000000"):sub(1, 9)
local year, month, day, hour, minute, second, suffix = stamp:match(
"^(%d%d%d%d)%-(%d%d)%-(%d%d)T(%d%d):(%d%d):(%d%d)(.*)$")
if not year then return nil end
year, month, day = tonumber(year), tonumber(month), tonumber(day)
hour, minute, second = tonumber(hour), tonumber(minute), tonumber(second)
if year < 1970 or month < 1 or month > 12 or hour > 23 or minute > 59 or second > 59 then return nil end
local leap = year % 4 == 0 and (year % 100 ~= 0 or year % 400 == 0)
local lengths = {31, leap and 29 or 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31}
if day < 1 or day > lengths[month] then return nil end
local fraction = ""
if suffix:sub(1, 1) == "." then
local digits, zone = suffix:match("^%.(%d+)(.*)$")
if not digits or #digits > 9 then return nil end
fraction, suffix = digits, zone
end
local offset = 0
if suffix ~= "Z" then
local sign, oh, om = suffix:match("^([+-])(%d%d):(%d%d)$")
if not sign then return nil end
oh, om = tonumber(oh), tonumber(om)
if oh > 23 or om > 59 then return nil end
offset = (oh * 60 + om) * 60 * (sign == "+" and 1 or -1)
end
local function leaps(y)
return math.floor(y / 4) - math.floor(y / 100) + math.floor(y / 400)
end
local days = 365 * (year - 1970) + leaps(year - 1) - leaps(1969) + day - 1
for m = 1, month - 1 do days = days + lengths[m] end
local seconds = days * 86400 + hour * 3600 + minute * 60 + second - offset
if seconds < 0 then return nil end
return string.format("%012d", seconds) .. "." .. fraction .. string.rep("0", 9 - #fraction)
end

-- note_observation records a sample. SignalR delivers one connection's
Expand Down Expand Up @@ -386,7 +418,57 @@ local function state_problem(obs)
return nil
end

-- get_observations reads REST. The caller checks the reply with state_problem.
-- REST can answer from an older cache after a newer reply: a late reply once
-- turned a measured 10.242 kW into 0 W (srcfl/device-drivers#183). A REST
-- reply is not used when its power time goes back from the last one used,
-- gives another value at the same instant, or, while a car is connected,
-- cannot be read. Such replies one after another for UNORDERED_RESET_MS
-- mean the time itself is wrong, for example a stamp from the future or a
-- format this parser does not know, so the driver uses them rather than go
-- silent: an older time starts the order again, and unreadable ones are
-- used as they come until a readable time arrives. A disconnect starts the
-- order again too. A run of rejected replies ends after a gap of more than
-- UNORDERED_RESET_MS between them, such as an outage.
local UNORDERED_RESET_MS = 30000
local accepted_power_key, accepted_power_value = nil, nil
local unordered_since_ms, unordered_last_ms, unreadable_logged = nil, nil, false
local function power_order_problem(obs, stamps, now)
local value, key = obs[OBS_TOTAL_POWER], source_time_key(stamps[OBS_TOTAL_POWER])
local disconnected = obs[OBS_OP_MODE] == 1
local problem = nil
if not key then
if not disconnected then problem = "missing or invalid power source timestamp" end
elseif accepted_power_key and key < accepted_power_key then
problem = "out-of-order power observation"
elseif key == accepted_power_key and value ~= accepted_power_value then
problem = "conflicting power at one source timestamp"
end
if problem then
if not unordered_since_ms or now - unordered_last_ms > UNORDERED_RESET_MS then
unordered_since_ms = now
end
unordered_last_ms = now
if now - unordered_since_ms < UNORDERED_RESET_MS then return problem end
if not key then
if not unreadable_logged then
host.log("warn", "Easee: power times unreadable for 30 s; using replies as they come")
end
unreadable_logged = true
return nil
end
host.log("warn", "Easee: power times went back for 30 s; using the newest reply")
end
unordered_since_ms, unreadable_logged = nil, false
if disconnected then
accepted_power_key, accepted_power_value = nil, nil
else
accepted_power_key, accepted_power_value = key, value
end
return nil
end

-- get_observations reads REST. The caller checks the reply with state_problem
-- and power_order_problem.
local function get_observations(serial)
local url = "https://api.easee.com/state/" .. serial .. "/observations?ids=" .. OBS_IDS
local resp, err = safe_http_get(url, auth_headers())
Expand Down Expand Up @@ -613,7 +695,7 @@ local function owe(id, key, value, now, why)
end

-- stream_update records a pushed sample. One Core could not read, with a
-- time that is not RFC 3339 UTC, is skipped, and so is a state, power or
-- time that is not RFC 3339, is skipped, and so is a state, power or
-- energy reading that is not a number; the stream then owes that reading.
-- Before the subscription completes the stream replays its current state,
-- which can be older than a REST read just before it; the newer one stays.
Expand Down Expand Up @@ -733,18 +815,18 @@ local REASON_LABELS = {
[3] = "offline fallback circuit current too low",
[4] = "circuit fuse too low",
[5] = "waiting in queue",
[6] = "waiting (other cars fully charged)",
[6] = "waiting in fully charged queue",
[7] = "illegal grid type",
[8] = "no current request from primary",
[9] = "max dynamic charger current too low",
[10] = "phase imbalance",
[11] = "equalizer communication lost",
[25] = "equalizer dynamic limit too low",
[26] = "equalizer static limit too low",
[27] = "offline fallback equalizer too low",
[28] = "fuse limit reached",
[29] = "current limited by equalizer",
[30] = "current limited by offline equalizer",
[8] = "no current request from car",
[9] = "master communication lost",
[10] = "equalizer current too low",
[11] = "phase not connected",
[25] = "current limited by circuit fuse",
[26] = "current limited by circuit max current",
[27] = "current limited by dynamic circuit current",
[28] = "current limited by equalizer",
[29] = "current limited by circuit load balancing",
[30] = "current limited by offline settings",
[50] = "secondary unit not requesting current",
[51] = "max charger current too low",
[52] = "max dynamic charger current too low",
Expand All @@ -755,7 +837,7 @@ local REASON_LABELS = {
[57] = "erratic EV",
[75] = "limited by cable rating",
[76] = "limited by schedule",
[77] = "limited by charger current",
[77] = "limited by charger max current",
[78] = "limited by dynamic charger current",
[79] = "car not drawing current",
[80] = "current ramping",
Expand All @@ -769,6 +851,23 @@ local REASON_LABELS = {
[100] = "EV not accepting current",
}

-- Easee's own load balancing can hold the car below FTW's order. In a field
-- trace (srcfl/ftw#1763, 23 Oct 2026) FTW ordered 15 A and the charger read
-- back 15 A (observation 48), while the circuit's allocated current (70-72)
-- and the current signalled to the car (114) fell to 12, 14 and 13 A; the
-- car took 8.2-8.9 kW instead of 10.4 kW. Easee records a value when it
-- changes, so a value answers the order when it was recorded at or after
-- the order, or when the order has stood ORDER_SETTLE_MS since the driver
-- saw it and the value has not moved.
local ORDER_SETTLE_MS = 30000
local order_seen_a, order_seen_ms = nil, 0
-- When Easee lets the car take the order again, the car needs a few seconds
-- to draw it and the cloud to report that. Until then the reading still
-- shows the old limit's draw, so the old limit is kept for up to
-- LIMIT_RELEASE_HOLD_MS while the car charges below the order.
local LIMIT_RELEASE_HOLD_MS = 20000
local last_limit_a, last_limited_by, last_limit_ms = nil, nil, nil

local email, password, configured_max_a
local device_limit_a, device_limit_read_ms
local settings_poll_ms = 0
Expand Down Expand Up @@ -961,14 +1060,18 @@ function driver_poll()
local values, err, stamps
if rest_due then values, err, stamps = get_observations(charger_serial) end
local now = host.millis()
local rest_read = false
local rest_read, held_back = false, false
if rest_due then
local problem = err or state_problem(values)
rest_next_ms = now + (problem and 10000 or REST_CONFIRM_MS)
local unordered = not problem and power_order_problem(values, stamps, now)
rest_next_ms = now + ((problem or unordered) and 10000 or REST_CONFIRM_MS)
if problem then
host.log("warn", "Easee: observations poll failed: " .. (err and redact_http_err(err) or problem))
-- The cloud answered that it does not hear the charger.
if not err then heard_ms = nil end
elseif unordered then
held_back = true
host.log("warn", "Easee: observations reply not used: " .. unordered)
else
-- Without the stream the reply is the whole state, as before.
if not streaming then latest, latest_at, latest_pushed = {}, {}, {} end
Expand Down Expand Up @@ -996,8 +1099,9 @@ function driver_poll()
end
last_blocked = blocked or nil
if not vouched or blocked then
-- An unreadable charger may have changed cars during the gap.
invalidate_session_proof()
-- An unreadable charger may have changed cars during the gap. A
-- reply held back for its order is not a gap.
if not held_back then invalidate_session_proof() end
return stream_state == "up" and STREAM_POLL_MS or 10000
end
local obs, timestamps = latest, latest_at
Expand Down Expand Up @@ -1093,6 +1197,54 @@ function driver_poll()
request_active = false
end

-- current_limit_a is the current signalled to the car while it is below
-- the order the charger holds and answers it. current_limited_by names
-- the load balancer only when the circuit's allocation is below the order
-- too and no higher than that current, so the allocation explains it.
-- ReasonForNoCurrent is not used here: an older reason is not proof.
if dyn_current ~= order_seen_a then order_seen_a, order_seen_ms = dyn_current, now end
local order_at = source_time_key(timestamps[OBS_DYN_CURRENT])
local order_settled = now - order_seen_ms >= ORDER_SETTLE_MS
local function answering(id)
local value, value_at = obs[id], source_time_key(timestamps[id])
if type(value) ~= "number" then return nil end
if order_settled or (value_at and order_at and value_at >= order_at) then return value end
return nil
end
-- The charger must hold FTW's last order: while it reads back an older
-- one, the pilot may be following the new order. The charger's own
-- static limit is device_limit_a, not its load balancing.
local current_limit_a, current_limited_by = nil, nil
local pilot_a = answering(OBS_OUTPUT_CURRENT)
if charging and type(dyn_current) == "number" and last_amps_set ~= nil and
math.abs(last_amps_set - dyn_current) <= 0.5 and
pilot_a and pilot_a > 0 and pilot_a < dyn_current - 0.5 then
current_limit_a = pilot_a
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
-- A three-phase car gets the lowest share of the phases it uses; a
-- phase with none is not one of them. For a one-phase car the
-- active phase is unknown, so use the highest of all three.
local allocated_a = n == 3 and ((phases == 1) and high or low) or nil
local own_limit = device_limit_a ~= nil and pilot_a >= device_limit_a - 0.5
if allocated_a and allocated_a > 0 and allocated_a < dyn_current - 0.5 and allocated_a <= pilot_a + 0.5 and
not own_limit then
current_limited_by = "load_balancer"
end
end
if current_limit_a then
last_limit_a, last_limited_by, last_limit_ms = current_limit_a, current_limited_by, now
elseif last_limit_ms and now - last_limit_ms < LIMIT_RELEASE_HOLD_MS and charging and
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

local limit_age_s = device_limit_read_ms and (host.millis() - device_limit_read_ms) / 1000
host.emit("ev", {
w = power_w,
Expand Down Expand Up @@ -1127,6 +1279,8 @@ function driver_poll()
cable_locked = cable_locked,
device_limit_a = device_limit_a,
device_limit_age_s = limit_age_s,
current_limit_a = current_limit_a, -- A signalled to the car, below the order
current_limited_by = current_limited_by, -- "load_balancer" or nil
max_a = dyn_current, -- last-set dynamic limit (echoes our write, may lag)
actual_amps_per_phase = actual_amps_per_phase, -- live per-phase A derived from totalPower
phases = phases, -- our committed phase count (1 or 3)
Expand Down
Loading
Loading