Fixed Auto CVL Float lockup at Rebulk threshold

Rewrote Auto CVL from template sensor lambdas to interval
lambdas, splitting each into a value sensor and a delta sensor.

Fixed a bug confirmed in production: Auto CVL's Float floor coincided
exactly with the Rebulk V. threshold, letting it trigger its own rebulk.
The floor is now capped relative to the live target instead of a fixed
chemistry constant, the Float/Stop integral term can no longer get stuck
once clamped, and PI state now resets when crossing the Bulk <-> Float/Stop
boundary.
This commit is contained in:
Sleeper85 committed 2026-11-08 23:08:32 +01:00
1 parent 5226455f76
commit 2cdc61e8b4
2 files changed
+347 -184

No files matched your search

@@ -9,35 +9,39 @@
## Problem
`Auto CVL` is a PI controller that reduces the `Requested Charge Voltage (CVL)` sent to the
inverter when a cell voltage rises above target, to avoid tripping the BMS `OVP` alarm. Its
computation was hardcoded around `Bulk Voltage`:
inverter when cell voltage rises above target, to avoid tripping the BMS `OVP` alarm.
- the PI's starting point / reference (`CVL`, `CVL_orig`) was always `bulk_voltage`;
- the deadband reference (`cell_bulk_v`) was always `bulk_voltage / cell_count`;
- the lower clamp (`min_CVL`) was always `float_voltage`;
- the upper clamp (`max_CVL`) was always `bulk_voltage + boost`.
In 1.7.0 it was strictly a Bulk-phase function. `yambms_core.yaml` built the requested voltage
one branch per phase, and only the Bulk branch added the correction:
However, `yambms_core.yaml` already adds the resulting offset (`var_auto_cvl`) to
`requested_charge_voltage` **unconditionally**, regardless of the charging phase (`Bulk`,
`Float`, or `Stop`). So the function was never actually gated to Bulk — it just computed a
Bulk-anchored correction that got silently applied during Float/Stop too, where the reference
values no longer made sense. Concretely: in `Stop` (target = nominal voltage, the lowest value
on the whole voltage scale), the old `min_CVL = float_voltage` floor sat *above* the actual
target, so any correction would have pulled the requested voltage *up* toward float voltage
instead of down — silently defeating the purpose of `Stop`.
```
Bulk : bulk_voltage + charger_offset + var_auto_cvl
Float : float_voltage + charger_offset + var_auto_float
Stop : rebulk_voltage + charger_offset
```
Real-world motivation for fixing this: some inverters hold their output voltage a bit above
(~0.1–0.3 V) the requested `CVL`, in every phase, not just Bulk. `Auto CVL` needed to become a
general "help the pack respect whatever `requested_charge_voltage` currently is" function,
regardless of which phase produced that target.
The controller itself matched that 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
Reached iteratively, each validated against one hard invariant: **Bulk's observable behavior
must not change** unless explicitly agreed otherwise.
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
(already published by `yambms_core.yaml`, values `"Bulk"`/`"Float"`/`"Stop"`) instead of
(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
@@ -49,15 +53,15 @@ must not change** unless explicitly agreed otherwise.
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.
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` — combined with the existing
clamp-and-freeze anti-windup pattern (only commit the integral when not clamped), this
naturally prevents any upward correction without needing a separate code path.
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
@@ -67,36 +71,99 @@ must not change** unless explicitly agreed otherwise.
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. **Per-phase floors, chained down the voltage ladder**:
- Float floor = `cell_count × var_cell_nominal_v` (Stop's own target — never pull Float below
what Stop would ask for anyway).
- Stop floor = `cell_count × var_cell_max_discharge_v` — a chemistry constant that existed in
`yambms_core.yaml` but was previously unused (commented `// Not used`). This gives `Stop` a
real correction range below nominal voltage, comfortably above actual discharge cut-off, so
a poorly-behaved inverter can't keep trickling current in even after charging has stopped.
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. **Two independent PI loops, not one shared state**: Bulk uses `integral_bulk` /
`prev_integral_bulk`; Float and Stop share `integral_avg` / `prev_integral_avg` (they track
the same metric — `average_cell_v` — so carrying state between them is meaningful). Carrying
state from Bulk into Float/Stop would not be: the measured quantity itself changes nature
(`max_cell_v` vs `average_cell_v`) at that transition, so an accumulated integral from one
would not represent a valid correction for the other.
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. **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` /
`max_cell_v` are only required to enter the Bulk branch; `float_voltage` / `total_voltage`
are only required 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.
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
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.
## 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` | `cell_count × var_cell_nominal_v` | `target_v` | none |
| 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 |
`yambms_core.yaml` now builds the requested voltage from a per-phase base plus a common set of
offsets, instead of a separate formula per branch:
```
base : Bulk -> bulk_voltage | Float -> float_voltage | Stop -> cell_count × nominal_v
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.
### New entities
Two diagnostic sensors expose the two halves of the charge voltage setpoint, so a misbehaving
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.
- **`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`:
```
Requested Charge Voltage = base target + 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.