Current Taper - Compliance with YamBMS core 1.8.0
See Changelog_Auto_CCL_Current_Taper_1.1.2.md
This commit is contained in:
1 parent
ab3633b0d9
commit
fd4ee6e903
2 files changed
+173
-23
No files matched your search
@@ -0,0 +1,121 @@
|
||||
# YamBMS - Changelog about new Auto CCL Current Taper (1.1.1 → 1.1.2)
|
||||
|
||||
[](https://www.gnu.org/licenses/gpl-3.0)
|
||||
[](https://github.com/Sleeper85/esphome-yambms/releases/latest)
|
||||

|
||||

|
||||

|
||||
|
||||
`packages/yambms/yambms_auto_ccl_current_taper.yaml`
|
||||
|
||||
Changes applied after the code audit. None of them alter the taper curve itself or the
|
||||
Cut-Off logic in `yambms_core.yaml`; they address pipeline contract, portability,
|
||||
numerical robustness and configuration traps.
|
||||
|
||||
---
|
||||
|
||||
## 1. Pipeline contract — reset moved to the core
|
||||
|
||||
**Change:** the package no longer clears the pipeline variable in its early-exit branches.
|
||||
`Gate #1` ("not our pipeline turn") is now a bare `return;` instead of a conditional
|
||||
cleanup block.
|
||||
|
||||
**Why:** `yambms_core.yaml` now resets `var_auto_ccl_current_taper` at the start of every
|
||||
Auto CCL cycle (before restarting the pipeline at step 1). Ownership of the variable
|
||||
belongs to the core, which counts the functions, consumes the values and drives the step
|
||||
counter. A contributor function has no reliable way to know whether it is the only writer
|
||||
or whether the pipeline stalled — it can only clean up its own case.
|
||||
|
||||
**Resulting contract**, now documented in the file header: *a contributor function writes
|
||||
its value on its own turn; staying silent (disabled, gated out, not its turn) is
|
||||
equivalent to writing 0.* New contributed functions inherit the correct behavior without
|
||||
defensive code.
|
||||
|
||||
> Note: the audit recommended the opposite — adding the variable write to Gates #2/#3.
|
||||
> That was rejected in favour of the core-side reset.
|
||||
|
||||
**Core-side counterpart (`yambms_core.yaml`, block "Requested Charge Current (CCL)").** The
|
||||
reset is placed after the sensor is published and before `var_charge_current_step = 1`, so
|
||||
each cycle starts from a clean slate. All six variables of the `std::min` are reset
|
||||
(`var_auto_temperature_ccl`, `var_auto_ccl`, `var_auto_ccl_current_taper`,
|
||||
`var_auto_soc_limit`, `var_auto_eoc`, `var_auto_custom_ccl`): none of them is written by an
|
||||
always-executed internal core block — the only write sites in the core are the reset lines
|
||||
themselves, so they all originate from optional external packages. The globals are `float`,
|
||||
`restore_value: no`, `initial_value: 0.0`, which is consistent with the reset at startup.
|
||||
|
||||
## 2. NaN guard on the inputs
|
||||
|
||||
**Change:** added before `Gate #3`:
|
||||
|
||||
```cpp
|
||||
if (isnan(V_knee) || isnan(V_bulk) || isnan(V_pack)) { … }
|
||||
```
|
||||
|
||||
**Why:** any comparison against NaN evaluates to false, so `Gate #3`
|
||||
(`V_knee >= V_bulk - V_hyst`) does **not** block when `bulk_voltage` is still NaN — the
|
||||
transient window before the `number` is restored at boot. Execution continued into the
|
||||
`p = (V_pack - V_knee) / (V_bulk - V_knee)` division, and the only safety net was the
|
||||
IEEE-754 behaviour of `fminf(0.0f, NaN)` returning `0.0f`. That is a fortunate C semantic,
|
||||
not an explicit protection.
|
||||
|
||||
**Implementation note:** the guard does *not* simply `return` — it resets the session
|
||||
latches, publishes a zero delta and **advances the pipeline step**. A bare `return` here
|
||||
would have stalled the Auto CCL baton for the whole system on a transient NaN. This is a
|
||||
deliberate improvement over the audit's proposed one-liner.
|
||||
|
||||
## 3. One-shot warning on a flat taper curve
|
||||
|
||||
**Change:** added a `flat_curve_warned` static flag, reset on each new session, guarding an
|
||||
`ESP_LOGW` when `I_end >= I_anchor`.
|
||||
|
||||
**Why:** when `Bulk C-Rate >= Knee C-Rate` (or `>=` the effective CCL used as the left
|
||||
anchor), the protective clamp `I_end = fminf(I_bulk, I_anchor)` makes the whole curve flat:
|
||||
the function becomes a silent no-op — no error, no log, no visible effect. The clamp is
|
||||
correct as a safety measure, but the configuration is a trap. The flag prevents the warning
|
||||
from being emitted on every interval.
|
||||
|
||||
## 4. Release hysteresis scaled per cell
|
||||
|
||||
**Change:**
|
||||
|
||||
```diff
|
||||
-constexpr float V_hyst = 0.2f;
|
||||
+const float V_hyst = 0.0125f * ${yambms_cell_count}; // 0.2 V @ 16S
|
||||
```
|
||||
|
||||
**Why:** `V_hyst` is a *pack* hysteresis. At 0.2 V it represents ~5 % of pack voltage on a
|
||||
4S LTO pack (very wide release band) and ~0.26 % on a 24S LFP pack (very narrow, noise
|
||||
sensitive despite the SMA). The per-cell form is portable and preserves the current
|
||||
behaviour exactly on 16S — it is a reformulation of the existing constant, not a new
|
||||
empirical value.
|
||||
|
||||
> `yambms_cell_hysteresis_v` from the core was deliberately **not** reused: it serves the
|
||||
> discharge hysteresis of the Cut-Off logic and has a different purpose.
|
||||
|
||||
## 5. Balance Current bounds scaled with capacity
|
||||
|
||||
**Change:** the `Auto CCL CT Balance Current` maximum is now derived from the battery
|
||||
capacity (0.1C ceiling, same order as `Bulk C-Rate`'s max) instead of a flat 0–50 A, with a
|
||||
clamp of the stored value if it falls outside the window.
|
||||
|
||||
**Why:** unlike `knee_c_rate` / `bulk_c_rate`, this number was an absolute value. On a small
|
||||
pack (e.g. 20 Ah) the UI allowed a 50 A "balance" current — 2.5C — physically meaningless
|
||||
and not signalled to the user.
|
||||
|
||||
## 6. Balance Current vs the Cut-Off current deadband
|
||||
|
||||
**Change:** documentation comment added to the number.
|
||||
|
||||
**Why:** the Cut-Off logic in `yambms_core.yaml` ignores currents below
|
||||
`yambms_current_deadband_crate × capacity` (0.005C, ≈1.4 A on a 280 Ah pack). Below that
|
||||
threshold the compensated voltage criterion is no longer evaluated and charge termination
|
||||
relies solely on the *fully charged at rest* signature. The default Balance Current of 2 A
|
||||
is close to that limit on large packs.
|
||||
|
||||
This is the one real interaction between the taper and the Cut-Off logic, and it is a
|
||||
configuration concern rather than a code defect.
|
||||
|
||||
## 7. Header contract updated
|
||||
|
||||
The `Contract with yambms_core.yaml` section now describes the actual behaviour: the
|
||||
variable is written on the function's own turn only, and the core clears it every cycle.
|
||||
@@ -1,5 +1,5 @@
|
||||
# Updated : 2026.07.20
|
||||
# Version : 1.1.1
|
||||
# Updated : 2026.08.11
|
||||
# Version : 1.1.2
|
||||
# GitHub : https://github.com/Sleeper85/esphome-yambms
|
||||
|
||||
# YamBMS ( Yet another multi-BMS Merging Solution )
|
||||
@@ -26,7 +26,10 @@
|
||||
#
|
||||
# Contract with yambms_core.yaml (upstream/dev):
|
||||
# - Participates in Auto CCL STEP pipeline
|
||||
# - Writes: id(yambms${yambms_id}_var_auto_custom_ccl) (<= 0 when tapering; 0 when inactive)
|
||||
# - Writes: id(yambms${yambms_id}_var_auto_ccl_current_taper) (<= 0 when tapering)
|
||||
# on its own turn only. The core resets this var to 0 every cycle before
|
||||
# restarting the pipeline at step 1, so staying silent (feature disabled,
|
||||
# gated out, or not our turn yet) is equivalent to writing 0.
|
||||
# - Advances pipeline via: id(yambms${yambms_id}_var_charge_current_step)++
|
||||
#--------------------------------------------------------------------------------------------
|
||||
|
||||
@@ -57,7 +60,7 @@ esphome:
|
||||
id(yambms${yambms_id}_number_auto_ccl_ct_knee_v).traits.set_max_value(v_max);
|
||||
|
||||
// Initialize/clamp the value inside the pack window
|
||||
// (the static initial_value is 16S LFP), default = cell_min_charge × cells
|
||||
// (the static initial_value is 16S LFP), default = cell_min_charge * cells
|
||||
const float knee_v = id(yambms${yambms_id}_number_auto_ccl_ct_knee_v).state;
|
||||
if (isnan(knee_v) || (knee_v < v_min) || (knee_v > v_max))
|
||||
id(yambms${yambms_id}_number_auto_ccl_ct_knee_v).publish_state(round(cell_count * id(yambms${yambms_id}_var_cell_min_charge_v) * 10) / 10);
|
||||
@@ -123,6 +126,13 @@ number:
|
||||
icon: mdi:current-dc
|
||||
|
||||
# Balance current (A) while latched at bulk / after EOC
|
||||
# Min/max are updated at runtime from battery capacity (see the interval below);
|
||||
# 0-50 are placeholders until the first capacity reading is available.
|
||||
# Keep this above the Cut-Off Logic's current deadband (yambms_current_deadband_crate
|
||||
# x capacity, e.g. 1.4 A @ 280 Ah/0.005C) — below it, the compensated voltage
|
||||
# criterion in yambms_core.yaml is skipped and charge termination relies solely on
|
||||
# the "fully charged at rest" signature. The default (2 A) is close to that limit
|
||||
# on large packs: lower it with capacity in mind.
|
||||
- platform: template
|
||||
id: yambms${yambms_id}_number_auto_ccl_ct_balance_a
|
||||
device_id: yambms_yambms${yambms_id}
|
||||
@@ -130,7 +140,7 @@ number:
|
||||
unit_of_measurement: A
|
||||
device_class: current
|
||||
min_value: 0
|
||||
max_value: 50
|
||||
max_value: 50 # placeholder; overwritten at runtime once capacity is known
|
||||
step: 1
|
||||
mode: ${yambms_input_number_mode}
|
||||
restore_value: true
|
||||
@@ -204,33 +214,24 @@ interval:
|
||||
//--------------------------------------------------------------------
|
||||
// Internal state
|
||||
//--------------------------------------------------------------------
|
||||
static bool active = false; // At/above knee this session
|
||||
static bool bulk_latched = false; // Pack has touched bulk this session
|
||||
static float I_anchor = NAN; // CCL at knee (left end of curve)
|
||||
static bool active = false; // At/above knee this session
|
||||
static bool bulk_latched = false; // Pack has touched bulk this session
|
||||
static float I_anchor = NAN; // CCL at knee (left end of curve)
|
||||
static bool flat_curve_warned = false; // One-shot log guard for a flat (no-op) taper curve
|
||||
|
||||
//--------------------------------------------------------------------
|
||||
// Gate #1: Correct Auto CCL step
|
||||
//--------------------------------------------------------------------
|
||||
const int cc_step = id(yambms${yambms_id}_var_charge_current_step);
|
||||
const int n_funcs = id(yambms${yambms_id}_var_auto_ccl_functions_count);
|
||||
if (cc_step < 1 || cc_step > n_funcs) {
|
||||
// Not our pipeline turn — clear sticky custom_ccl when inactive/off
|
||||
if (!id(yambms${yambms_id}_switch_auto_ccl_current_taper).state || !active) {
|
||||
active = false;
|
||||
bulk_latched = false;
|
||||
id(yambms${yambms_id}_var_auto_custom_ccl) = 0.0f;
|
||||
id(yambms${yambms_id}_auto_ccl_ct_delta).publish_state(0.0f);
|
||||
}
|
||||
return;
|
||||
}
|
||||
if (cc_step < 1 || cc_step > n_funcs) return; // Not our pipeline turn — core resets the pipeline var
|
||||
|
||||
//--------------------------------------------------------------------
|
||||
// Gate #2: Feature enabled?
|
||||
// Gate #2: Feature enabled ?
|
||||
//--------------------------------------------------------------------
|
||||
if (!id(yambms${yambms_id}_switch_auto_ccl_current_taper).state) {
|
||||
active = false;
|
||||
bulk_latched = false;
|
||||
id(yambms${yambms_id}_var_auto_custom_ccl) = 0.0f;
|
||||
id(yambms${yambms_id}_auto_ccl_ct_delta).publish_state(0.0f);
|
||||
id(yambms${yambms_id}_var_charge_current_step)++;
|
||||
return;
|
||||
@@ -245,6 +246,17 @@ interval:
|
||||
const float bulk_c = id(yambms${yambms_id}_number_auto_ccl_ct_bulk_c_rate).state; // bulk C-rate
|
||||
const float I_knee = cap_ah * knee_c; // knee current
|
||||
const float I_bulk = cap_ah * bulk_c; // bulk current
|
||||
|
||||
// Balance Current bounds scale with capacity (0.1C ceiling,
|
||||
// same order as Bulk C-Rate's max) instead of a flat 50 A.
|
||||
if (cap_ah > 0.0f) {
|
||||
const float balance_max = cap_ah * 0.1f;
|
||||
id(yambms${yambms_id}_number_auto_ccl_ct_balance_a).traits.set_max_value(balance_max);
|
||||
const float balance_v = id(yambms${yambms_id}_number_auto_ccl_ct_balance_a).state;
|
||||
if (isnan(balance_v) || (balance_v > balance_max))
|
||||
id(yambms${yambms_id}_number_auto_ccl_ct_balance_a).publish_state(fminf(balance_v, balance_max));
|
||||
}
|
||||
|
||||
const float I_balance = id(yambms${yambms_id}_number_auto_ccl_ct_balance_a).state; // CCL while latched at bulk / EOC
|
||||
const float V_knee = id(yambms${yambms_id}_number_auto_ccl_ct_knee_v).state; // knee voltage
|
||||
const float V_bulk = id(yambms${yambms_id}_bulk_voltage).state; // bulk voltage
|
||||
@@ -253,11 +265,24 @@ interval:
|
||||
? id(yambms${yambms_id}_auto_ccl_ct_voltage).state
|
||||
: id(yambms${yambms_id}_total_voltage).state;
|
||||
const bool eoc_done = id(yambms${yambms_id}_var_eoc); // EOC reached
|
||||
constexpr float V_hyst = 0.2f; // release hysteresis below knee
|
||||
const float V_hyst = 0.0125f * ${yambms_cell_count}; // release hysteresis below knee (0.2 V @ 16S)
|
||||
|
||||
float I_target = I_max;
|
||||
float delta = 0.0f;
|
||||
|
||||
//--------------------------------------------------------------------
|
||||
// Guard: numbers/sensors not ready yet (NaN before first restore/measurement).
|
||||
// Advance the pipeline turn regardless so a transient NaN can't stall the
|
||||
// whole Auto CCL baton.
|
||||
//--------------------------------------------------------------------
|
||||
if (isnan(V_knee) || isnan(V_bulk) || isnan(V_pack)) {
|
||||
active = false;
|
||||
bulk_latched = false;
|
||||
id(yambms${yambms_id}_auto_ccl_ct_delta).publish_state(0.0f);
|
||||
id(yambms${yambms_id}_var_charge_current_step)++;
|
||||
return;
|
||||
}
|
||||
|
||||
//--------------------------------------------------------------------
|
||||
// Gate #3: Knee must sit below bulk (with hysteresis margin).
|
||||
// bulk_voltage is runtime-adjustable, so boot traits alone can't enforce this.
|
||||
@@ -265,7 +290,6 @@ interval:
|
||||
if (V_knee >= (V_bulk - V_hyst)) {
|
||||
active = false;
|
||||
bulk_latched = false;
|
||||
id(yambms${yambms_id}_var_auto_custom_ccl) = 0.0f;
|
||||
id(yambms${yambms_id}_auto_ccl_ct_delta).publish_state(0.0f);
|
||||
id(yambms${yambms_id}_var_charge_current_step)++;
|
||||
return;
|
||||
@@ -277,6 +301,7 @@ interval:
|
||||
if (!active && V_pack >= V_knee) {
|
||||
active = true;
|
||||
bulk_latched = false; // new session
|
||||
flat_curve_warned = false; // new session
|
||||
// Left end: min(knee amps, current CCL) — never start above Auto EOC (etc.)
|
||||
const float I_ccl = id(yambms${yambms_id}_requested_charge_current).has_state()
|
||||
? id(yambms${yambms_id}_requested_charge_current).state
|
||||
@@ -303,6 +328,10 @@ interval:
|
||||
// Never let the curve end above the left end (I_anchor may be
|
||||
// min(knee amps, current CCL); bulk C-rate must not invert the taper).
|
||||
const float I_end = fminf(I_bulk, I_anchor);
|
||||
if ((I_end >= I_anchor) && !flat_curve_warned) {
|
||||
ESP_LOGW("yambms_debug", "Auto CCL CT: Bulk C-Rate >= effective Knee C-Rate/CCL — taper curve is flat this session (no-op)");
|
||||
flat_curve_warned = true;
|
||||
}
|
||||
I_target = I_end + (I_anchor - I_end) * curve; // I_anchor → I_end
|
||||
}
|
||||
delta = fminf(0.0f, I_target - I_max);
|
||||
@@ -312,7 +341,7 @@ interval:
|
||||
}
|
||||
|
||||
// Write custom_ccl every baton turn (0 when inactive so a prior taper cannot stick)
|
||||
id(yambms${yambms_id}_var_auto_custom_ccl) = delta;
|
||||
id(yambms${yambms_id}_var_auto_ccl_current_taper) = delta;
|
||||
id(yambms${yambms_id}_auto_ccl_ct_delta).publish_state(delta);
|
||||
|
||||
// Pass the baton
|
||||
|
||||
Reference in new issue
Block a user