From fd4ee6e9033f96efa4c12a6733e037ce80dfd90a Mon Sep 17 00:00:00 2001 From: Sleeper85 Date: Tue, 11 Aug 2026 00:47:10 +0200 Subject: [PATCH] Current Taper - Compliance with YamBMS core 1.8.0 See Changelog_Auto_CCL_Current_Taper_1.1.2.md --- .../Changelog_Auto_CCL_Current_Taper_1.1.2.md | 121 ++++++++++++++++++ .../yambms/yambms_auto_ccl_current_taper.yaml | 75 +++++++---- 2 files changed, 173 insertions(+), 23 deletions(-) create mode 100644 documents/README/changelog/Changelog_Auto_CCL_Current_Taper_1.1.2.md diff --git a/documents/README/changelog/Changelog_Auto_CCL_Current_Taper_1.1.2.md b/documents/README/changelog/Changelog_Auto_CCL_Current_Taper_1.1.2.md new file mode 100644 index 0000000..4765852 --- /dev/null +++ b/documents/README/changelog/Changelog_Auto_CCL_Current_Taper_1.1.2.md @@ -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. diff --git a/packages/yambms/yambms_auto_ccl_current_taper.yaml b/packages/yambms/yambms_auto_ccl_current_taper.yaml index cc961f6..2965676 100644 --- a/packages/yambms/yambms_auto_ccl_current_taper.yaml +++ b/packages/yambms/yambms_auto_ccl_current_taper.yaml @@ -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