Updated Auto CVL changelog 1.8.0
This commit is contained in:
1 parent
6973cee171
commit
7fc55192c8
2 files changed
+78
-98
No files matched your search
@@ -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
|
||||
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user