From 7fc55192c8daa36f67df757b7a1bf896e75d430b Mon Sep 17 00:00:00 2001 From: Sleeper85 Date: Fri, 28 Aug 2026 00:35:06 +0200 Subject: [PATCH] Updated Auto CVL changelog 1.8.0 --- documents/README/YamBMS_functions.md | 3 + .../Changelog_YamBMS_1.8.0_Auto_CVL.md | 173 ++++++++---------- 2 files changed, 78 insertions(+), 98 deletions(-) diff --git a/documents/README/YamBMS_functions.md b/documents/README/YamBMS_functions.md index 5bcc9b9..8d758fa 100644 --- a/documents/README/YamBMS_functions.md +++ b/documents/README/YamBMS_functions.md @@ -241,6 +241,9 @@ default allows 0.5C from -20°C up to 55°C, with a cut-off below -30°C and abo > [!IMPORTANT] > In Bulk, the `Auto CVL` function uses the `Balance Trig. Volt.` value of your BMS. `e.g. for LFP` : BTG=0.010V +> [!NOTE] +> `Auto CVL` was reworked in `YamBMS 1.8.0` by [@Sleeper85](https://github.com/Sleeper85), see [release note](changelog/Changelog_YamBMS_1.8.0_Auto_CVL.md). + When enabled, the `Automatic Charge Voltage Limit` function automatically reduces the `Requested Charge Voltage (CVL)` sent to the inverter when a cell starts to exceed the `Bulk Voltage` target. The runner cell is maintained at or near that target, the balancer can start diff --git a/documents/README/changelog/Changelog_YamBMS_1.8.0_Auto_CVL.md b/documents/README/changelog/Changelog_YamBMS_1.8.0_Auto_CVL.md index b5c42ee..211a79b 100644 --- a/documents/README/changelog/Changelog_YamBMS_1.8.0_Auto_CVL.md +++ b/documents/README/changelog/Changelog_YamBMS_1.8.0_Auto_CVL.md @@ -20,31 +20,42 @@ Float : float_voltage + charger_offset + var_auto_float Stop : rebulk_voltage + charger_offset ``` -The controller itself matched that scope: its reference (`CVL`, `CVL_orig`) and deadband +Two problems with that shape: + +- **The formula was hardcoded per phase.** Each new correction had to be wired into the right + branch by hand, and a phase that had never needed one had no slot to receive it. +- **`Stop` requested `Rebulk V.` itself**, which left the pack sitting on the very threshold that + decides when to rebulk. + +The controller itself matched that Bulk-only scope: its reference (`CVL`, `CVL_orig`) and deadband reference (`cell_bulk_v`) were anchored to `bulk_voltage`, its ceiling to `bulk_voltage + boost`, its floor to `float_voltage`. -The gap: **`Float` and `Stop` had no correction at all.** Some inverters hold their output -voltage a bit above (~0.1–0.3 V) the requested `CVL`, and they do so in every phase, not just -Bulk. Once charging is meant to taper or stop, an uncompensated overshoot keeps pushing current -into a pack that is already full — exactly when it is least wanted. `Auto CVL` therefore needed -to become a general "help the pack respect whatever `requested_charge_voltage` currently is" -function, regardless of which phase produced that target. - -Extending it was not a matter of removing a phase check. Every reference the controller used was -a Bulk constant, and the metric that makes sense in Bulk (`max_cell_v`, protecting against a -single runner cell) is not the one that makes sense once the pack is full. - ## Design decisions Each was validated against one hard invariant: **Bulk's observable behavior must not change** unless explicitly stated otherwise. -1. **Phase source of truth**: read the existing `yambms${id}_charging_instruction` text sensor +1. **The core formula becomes a base plus offsets.** `yambms_core.yaml` now picks a per-phase base + target and adds a common set of offsets to it, instead of carrying a separate formula per + branch. Every phase now has a slot for every correction; an offset is simply `0` when its + function is idle or disabled. + +2. **`Stop` is anchored to nominal voltage** (`cell_count × var_cell_nominal_v`) instead of + `Rebulk V.`, giving it a target that is independent of the rebulk decision instead of one that + sits exactly on it. + +3. **`Auto CVL` is rewritten from a per-second template sensor into an interval lambda.** The + 1.7.0 version was a `lambda:` returning a value inside a single `internal: true` sensor, so the + correction and the published value were necessarily the same thing. Separating them is what + allows the two user-visible diagnostic sensors below, and gives the file room for the per-phase + branching. + +4. **Phase source of truth**: read the existing `yambms${id}_charging_instruction` text sensor (already published by `yambms_core.yaml`, values `"Bulk"` / `"Float"` / `"Stop"`) instead of duplicating the `charge_status` → phase classification logic in this file. -2. **Bulk** (kept close to identical): still tracks `max_cell_v` against `bulk_voltage`, still +5. **Bulk** (kept close to identical): still tracks `max_cell_v` against `bulk_voltage`, still uses the BMS `Balance Trig. Volt.` as deadband. One deliberate change: the floor moved from `float_voltage` (a user-configurable entity, not guaranteed to sit below `bulk_voltage`) to `cell_count × var_cell_min_charge_v` (the chemistry's fixed cv_min — "fully charged at rest" @@ -52,79 +63,57 @@ unless explicitly stated otherwise. `max_cell_v` drops back under `cell_bulk_v`, well before hitting either floor), so the observable difference is confined to edge cases where the correction saturates. -3. **Float / Stop use a different metric**: `average_cell_v = total_voltage / cell_count` - instead of `max_cell_v`. Rationale: the goal here is compensating a roughly constant inverter - overshoot, not protecting against a single runner cell, and the average is naturally smoother - than a single-cell reading — so no deadband is needed; the correction reacts as soon as - `average_cell_v` exceeds the target. - -4. **Float / Stop are unidirectional**: the correction only ever pulls `CVL` down, never above - target. Implemented by setting `max_CVL = target_v`, and by clamping the integral term at `0` - so it can never wind up positive — an upward correction is blocked by the ceiling anyway, and - a lingering positive integral would only delay the reaction to the next real overshoot. - -5. **Float's target tracks the live `Auto Float` glide, not the final `Float Voltage`**: - `target_v = float_voltage + var_auto_float`. `yambms_auto_float.yaml` already ramps the - effective CVL down from `bulk_voltage` to `float_voltage` over time on entering Float. If - `Auto CVL` targeted the final `float_voltage` directly, it would see the pack still near bulk - level during the ramp and start pulling `CVL` down aggressively — fighting the (deliberately - paced) Auto Float ramp. Tracking the live glide value means `Auto CVL` only reacts to a real - overshoot *beyond* whatever Auto Float currently requests. - -6. **Float's floor is derived from `Rebulk V.`, not from a fixed voltage**: - `min_CVL = Rebulk V. + ${auto_cvl_rebulk_margin_v}` (default margin 0.5 V). - This is the single most important safety property of the Float branch. Any fixed floor — - including `cell_count × var_cell_nominal_v`, which is exactly the lower bound of the - `Rebulk V.` range — can sit *at or below* the rebulk threshold, depending on the user's - settings. `Auto CVL` would then be able to pull the pack down far enough to satisfy - `max_cell_v ≤ Rebulk V. / cell_count`, triggering a rebulk it caused itself and looping - Float → Bulk → Float indefinitely. Deriving the floor from the actual `Rebulk V.` entity - keeps that margin correct whatever the configuration. If `Rebulk V.` is unavailable, the - floor falls back to `cell_count × var_cell_nominal_v`; if the Float target is already at or - below the floor, the floor is clamped to the target so `Auto CVL` stays neutral rather than - pushing the voltage back up. - -7. **Stop's target moves from `Rebulk V.` to `cell_count × var_cell_nominal_v`**, and its floor - becomes `cell_count × var_cell_max_discharge_v` — a chemistry constant that existed in - `yambms_core.yaml` but was previously unused (commented `// Not used`). - In 1.7.0, `Stop` requested `Rebulk V.` itself, which left the pack sitting on the very - threshold that decides when to rebulk. Anchoring `Stop` to nominal voltage instead gives it a - target that is independent of the rebulk decision, and a real correction range below it, - comfortably above actual discharge cut-off — so a poorly-behaved inverter can't keep - trickling current in after charging has stopped. - -8. **Bounded anti-windup on the Float/Stop integral**: the integral is capped at - `-(target_v - min_CVL) / ki`, i.e. at the correction the floor can actually deliver. Without - this bound, a pack that stays above target while the CVL has no effect — an inverter - substituting its own voltage target, for instance a Deye in ToU mode — winds the integral - down without limit, and the CVL stays pinned to the floor long after the cause is gone. - -9. **PI state is reset when crossing the Bulk ↔ Float/Stop boundary**. Bulk uses - `integral_bulk`; Float and Stop share `integral_avg` (they track the same metric — - `average_cell_v` — so carrying state between them is meaningful). Carrying state across the - Bulk boundary is not: the measured quantity itself changes nature (`max_cell_v` vs - `average_cell_v`) at that transition, so an accumulated integral from one phase does not +6. **PI state is reset when crossing the Bulk ↔ Float/Stop boundary.** Bulk uses `integral_bulk`; + a second state, `integral_avg`, is reserved for the Float/Stop correction and is currently only + ever zeroed. Carrying state across the Bulk boundary is not meaningful: the measured quantity + itself changes nature at that transition, so an accumulated integral from one phase does not represent a valid correction for the other. Without the reset, a stale integral from before a Float cycle would be re-injected on the next rebulk. Turning the `Automatic Charge Voltage` switch off also clears both PI states entirely. -10. **NaN / availability guards are branch-specific**: only `cell_count`, `bulk_voltage` and the - `charging_instruction` state are required upfront (common to all phases). `balance_delta` and - `max_cell_v` are only required to enter the Bulk branch; `float_voltage` and `total_voltage` - only to enter the Float/Stop branch. This avoids a sensor hiccup on one branch's inputs (e.g. - `total_voltage`, an aggregated BMS value more likely to be transiently unavailable than a - restored config entity) silently disabling the other phase's correction — which would have - broken the Bulk invariant in that edge case. +7. **NaN / availability guards are branch-specific**: only `cell_count`, `bulk_voltage` and the + `charging_instruction` state are required upfront (common to all phases). `balance_delta` and + `max_cell_v` are only required to enter the Bulk branch. This keeps a sensor hiccup on one + branch's inputs from silently disabling another phase's correction — which would have broken + the Bulk invariant in that edge case. + +## Auto CVL outside Bulk : implemented, then suspended + +Some inverters hold their output voltage a bit above (~0.1–0.3 V) the requested `CVL`, and they do +so in every phase, not just Bulk. That was the case for extending `Auto CVL` to `Float` and +`Stop`, and a full PI branch for them was written and tested. **It is suspended in the shipped +version**, and the reason is worth recording, because the failure is not obvious from the idea. + +Outside Bulk, a real inverter overshoot, a pack relaxing after charge, and a pack discharging into +house load all present the **same signature**: pack average above target at near-zero current. No +function of pack current tells them apart — a fixed overshoot settles at ~0 A just like a resting +pack does. Left active, the PI integrates against an error it has no authority over and pins `CVL` +to its floor, burning the safety margin above `Rebulk V.` for no benefit. + +`Stop` is a separate case: it means "let the pack discharge down to rebulk", which the low base +target now set by `yambms_core.yaml` (decision 2 above) achieves on its own. A PI loop has nothing +to add there, and `Stop` is not expected to come back even if `Float` does. + +`Bulk` — the `OVP` protection path, and the reason `Auto CVL` exists — is untouched by this. The +`Float`/`Stop` slot of the new core formula stays free for a future implementation, and the +`integral_avg` PI state and the `auto_cvl_rebulk_margin_v` substitution are kept in place for it. + +> [!NOTE] +> `auto_cvl_rebulk_margin_v` (default `0.5`) is declared but **has no effect** in the current +> version. It was the Float branch's safety margin above `Rebulk V.`: any fixed floor can sit at +> or below the rebulk threshold depending on the user's settings, which would let `Auto CVL` +> trigger a rebulk it caused itself and loop `Float → Bulk → Float`. Deriving the floor from the +> live `Rebulk V.` entity is what keeps that margin correct whatever the configuration. ## Result -| Phase | Metric | Target (`target_v`) | Floor | Ceiling | Deadband | -|---|---|---|---|---|---| -| Bulk | `max_cell_v` | `bulk_voltage` | `cell_count × var_cell_min_charge_v` | `bulk_voltage + boost` | `balance_trigger_voltage` | -| Float | `average_cell_v` | `float_voltage + var_auto_float` | `Rebulk V. + rebulk margin` | `target_v` | none | -| Stop | `average_cell_v` | `cell_count × var_cell_nominal_v` | `cell_count × var_cell_max_discharge_v` | `target_v` | none | +| Phase | Base target (`yambms_core.yaml`) | Auto CVL correction | +|---|---|---| +| Bulk | `bulk_voltage` | `max_cell_v` vs `bulk_voltage`, deadband `balance_trigger_voltage`, floor `cell_count × var_cell_min_charge_v`, ceiling `bulk_voltage + boost` | +| Float | `float_voltage` | none (`var_auto_cvl` = `0`) | +| Stop | `cell_count × var_cell_nominal_v` | none (`var_auto_cvl` = `0`) | -`yambms_core.yaml` now builds the requested voltage from a per-phase base plus a common set of +`yambms_core.yaml` builds the requested voltage from that per-phase base plus a common set of offsets, instead of a separate formula per branch: ``` @@ -132,8 +121,7 @@ base : Bulk -> bulk_voltage | Float -> float_voltage | Stop -> cell_count × n result : base + charger_offset + var_auto_cvl + var_auto_float + var_auto_custom_cvl ``` -Each offset is `0` when its function is idle or disabled, so the phases that used to receive no -correction now receive one only when it is actually enabled. +Each offset is `0` when its function is idle or disabled. ### New entities @@ -141,29 +129,18 @@ Two diagnostic sensors expose the two halves of the charge voltage setpoint, so correction can be read directly from the dashboard instead of being inferred: - **`Auto CVL Delta`** — the correction `Auto CVL` is currently applying. Negative when it is - reducing the charge voltage, `0` when idle. + reducing the charge voltage, `0` when idle — which includes the whole of `Float` and `Stop`. - **`Auto Float Voltage Delta`** — the remaining offset of the `Auto Float` glide above the target float voltage. Reaches `0` once the ramp is complete. -Together they reconstruct the setpoint published by `yambms_core.yaml`: +Alongside them, `Auto CVL` and `Auto Float Voltage` publish the absolute value each function is +requesting. Outside `Bulk`, `Auto CVL` sits at `Bulk Voltage` with a delta of `0`. + +Together the two deltas reconstruct the setpoint published by `yambms_core.yaml`: ``` -Requested Charge Voltage = base target + Auto Float Delta + Auto CVL Delta +Requested Charge Voltage = base target + Charger Offset V. + Auto Float Delta + Auto CVL Delta ``` -### New substitution - -`auto_cvl_rebulk_margin_v` (default `0.5`) — safety margin kept above `Rebulk V.` by the Float -floor. It must exceed the spread between pack average and highest cell, otherwise `max_cell_v` -can reach the rebulk threshold while the average is still above the floor. Increase it on a -poorly balanced pack. - -## Known limitations - -- On entering `Float`, `Auto CVL` runs every second while `Auto Float` runs every 60 s. During - that window `var_auto_float` is still `0`, so `Auto CVL` briefly targets `float_voltage` - instead of the start of the glide. The requested voltage can dip for up to a minute before the - glide takes over. To be addressed in `yambms_auto_float.yaml`. - Documentation updated in the same change: `documents/README/YamBMS_functions.md`, `Auto CVL` section.