Current Taper - Compliance with YamBMS core 1.8.0

See Changelog_Auto_CCL_Current_Taper_1.1.2.md
This commit is contained in:
Sleeper85 committed 2026-11-08 23:08:32 +01:00
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)
[![Badge License: GPLv3](https://img.shields.io/badge/License-GPLv3-brightgreen.svg)](https://www.gnu.org/licenses/gpl-3.0)
[![Badge Version](https://img.shields.io/github/v/release/Sleeper85/esphome-yambms?include_prereleases&color=yellow&logo=DocuSign&logoColor=white)](https://github.com/Sleeper85/esphome-yambms/releases/latest)
![GitHub stars](https://img.shields.io/github/stars/Sleeper85/esphome-yambms)
![GitHub forks](https://img.shields.io/github/forks/Sleeper85/esphome-yambms)
![GitHub watchers](https://img.shields.io/github/watchers/Sleeper85/esphome-yambms)
`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