The inferred balancing flag stops the Cut-Off timer while the cell spread stays above bms_balance_trigger_voltage. A pack that does not actually balance (no balancer, balancing disabled, or a balancer too weak for the pack) never closes its spread, so the charge stayed in Cut-Off until the EOC timer ended it, or indefinitely with the EOC timer switch off. bms_fake_equalizing_enabled now defaults to 'false' for every BMS that includes the package (EG4 LL V2, Seplos V1/V2, Seplos V3, JK RS485 DISPLAY, Fake/Demo BMS): the flag reports the constant false these packages used to hardcode. Set it to 'true' per BMS to enable it. Charging_logic.md and Changelog_Fake_Equalizing.md describe the new default and the warning.
9.7 KiB
YamBMS charging logic
Note
Please read the documentation regarding the charging settings.
Note
Please read the YamBMS 1.7.1 Cut-Off charging logic release note.
Charging Logic Diagram
The charging voltage and current correspond to the default values in the YAML script and can be modified.
BMS dropout
While no BMS is combined (boot, reboot, OTA update, RS485 or BLE dropout), the charging logic is suspended:
- the
Charging Statuskeeps its value: a battery inFloatorEOCstays there and is not sent back toBulkwhen the BMS returns; - the cut-off timer and the EOC timer are stopped: a dropout during the
Cut-Offphase cannot declare an EOC with no BMS to confirm it; - the
Charging InstructionisStop, theDischarging Instructionis off, and the requested values (CVL, DVL, CCL, DCL) are unknown; - nothing is sent to the inverter until YamBMS is initialized again.
When a BMS is combined again, the logic resumes from the kept status, and the usual rebulk rules apply: if the battery was discharged during the dropout, Rebulk voltage, Rebulk SoC or Rebulk days start a new Bulk.
Charging blocked (Wait)
While at least one BMS is combined, the Charging Status goes to Wait when charging is not allowed:
- without
bms_options_charging_logic.yaml: when theChargingswitch is off, or when no combined BMS allows charging (protection, charge switch off); - with
bms_options_charging_logic.yaml: only when theChargingswitch is off. In that mode YamBMS turns the BMS charge switch off itself at Cut-Off, and that block must not change the status.
In Wait the Charging Instruction is Stop, and the cut-off timer and the EOC timer are stopped: an EOC is only declared while charging is allowed.
When charging is allowed again:
- a battery that was in
FloatorEOCgoes back there, unless a rebulk rule applies (Rebulk voltage,Rebulk SoC,Rebulk days,Force BulkorRequest Force Charge), in which case a newBulkstarts; - any other status (
Init,Bulk,Cut-Off,Balancing) goes toBulk.
Bulk to Float with Auto Float
With Automatic Float Voltage enabled and a bulk voltage above the float voltage, the Requested Charge Voltage (CVL) does not drop when Float starts: the first Float CVL is the bulk voltage, and it is then lowered step by step down to the float voltage. See Auto Float Voltage.
If the bulk or float voltage is changed less than a minute before Float starts, the first Float CVL can still use the previous values until the next Auto Float update, at most 60 s later.
Cut-Off Charging Logic Equation
Source: Charging Marine Lithium Battery Banks
Special thanks to @shvmm for deriving the equations.
Note: The equations below can be adopted for other chemistries like Li-ion and LTO with specific CVmin and CVmax values.
The physical anchor of the equation is CVmin, the resting voltage of a fully charged cell (~3.37 V for LFP): a cell above cv_min at zero current is full, and a cell cannot become full while staying below cv_min + R·I under current. The current taper therefore inevitably crosses the criterion when the battery is genuinely full, even if the requested charge voltage is never reached (e.g. low PV production days).
Cut-Off Cell Voltage source
The Cut-Off Cell Voltage select defines which cell voltage feeds the whole Cut-Off logic below (cell_v in this document):
Max Cell Voltage(default):cell_v = max_cell_v. Conservative, the end of charge depends on the highest cell.Average Cell Voltage:cell_v = battery_voltage / cell_count. The end of charge reflects the state of the whole pack, giving a consistent charge termination voltage from one day to the next. Recommended for packs built from unmatched cells (different internal resistances), packs with a runner cell, or a BMS that does not report its equalizing status.
Warning
With
Average Cell Voltage, the highest cell no longer stops the charge. Cell-level protection must be ensured byAuto CVLand/orAuto CCL, the BMSOVPremaining the last resort. If your inverter does not respect the requested charge voltage, only theAuto CCLis effective.
Cut-Off Charging Logic Diagram (what's happening in the yellow diamond)
Note
The diagram below is valid for other chemistries like Li-ion and LTO but with other CVmin and CVmax values.
Warning
This diagram no longer reflects reality and needs to be updated.
The logic evaluates the battery current first, in three zones:
1. Current deadband (current < 0.005C, ≈1.4 A on a 280 Ah pack) — the current is within sensor noise or PV starvation, the compensated equation is not meaningful. Three outcomes:
cell_v ≥ cv_minandSoC ≥ 95 %→ Cut-Off conditions valid. This is the fully charged at rest signature:cv_minis by definition the resting voltage of a full cell, so a battery that stops accepting current withcell_vabove it has completed its charge — without ever needing to reach the bulk voltage.cell_v < cv_min→ Bulk conditions valid: the battery cannot be full, any running timer is stopped.- otherwise → grey zone: no conclusion is drawn, the charge status is left unchanged.
2. Charging (current > deadband) — the Cut-Off conditions are valid when both:
cutoff_voltage ≥ cv_minwherecutoff_voltage = cell_v − cutoff_resistance × current(the compensated criterion, see the equation above);SoC ≥ 95 %(yambms_eoc_min_soc, configurable, max 98 %) — a safety net against premature Cut-Off caused by a runner cell or a transient voltage reading.
Otherwise the Bulk conditions are valid.
3. Discharging — the Bulk conditions are valid when cell_v < cell_bulk_v − cell_hysteresis_v (20 mV/cell by default). Otherwise nothing changes (grey zone).
The Bulk or Cut-Off conditions must hold continuously for 10s before the corresponding phase is entered. Transient states (cloud passages, load spikes) that flip the conditions back and forth never change the phase.
Once the Cut-Off phase is entered:
- if the cells are reported — or inferred — as equalizing, the cut-off timer is stopped: the charge is held so the balancer can work;
- otherwise the cut-off timer starts (
180sdefault): if the Cut-Off conditions still hold when it expires, the EOC (End Of Charge) is declared; - in parallel, if the
EOC timerswitch is enabled, the EOC timer (30mindefault) guarantees that the Cut-Off phase ends at the latest when it expires, even if cells are still equalizing.
Returning to the Bulk phase, going to Wait or a BMS dropout stops both timers.
Some BMS balance their cells but never expose a balancing flag. YamBMS infers it for
them, from the max cell reaching the bulk setpoint together with a cell spread that has
reached bms_balance_trigger_voltage, the threshold at which that pack's own balancer
engages, so the cut-off timer is held exactly as it would be with a
BMS that reports the flag. A real external balancer, when one is online, always takes
priority over the inference. It is available, but disabled by default, for Seplos V3,
Seplos V1/V2, EG4 LL v2 and JK RS485 DISPLAY: enable it per BMS with
bms_fake_equalizing_enabled: 'true'. A pack that does not actually balance (no balancer,
balancing disabled, or a balancer too weak for the pack) never closes its cell spread, so
the charge can stay in Cut-Off until the EOC timer ends it, or indefinitely if the
EOC Timer enabled switch is off. See
Changelog_Fake_Equalizing.md for the references
it uses and how to tune it.
LFP Cut-Off Values
- Nominal : 3.20 V
- CV min : 3.37 V
- CV max : 3.65 V
To enter the Cut-Off phase while charging, cutoff_voltage ≥ cv_min and SoC ≥ 95 % must hold for 10s.
Reading example at 5A: the Cut-Off conditions become valid when cell_v reaches 3.47 V (the row where Cut-Off A. equals the instantaneous current). The Cut-Off V. column shows the compensated voltage for each cell_v, which must exceed cv_min.
Li-ion Cut-Off Values
- Nominal : 3.60 V
- CV min : 3.90 V
- CV max : 4.20 V
To enter the Cut-Off phase while charging, cutoff_voltage ≥ cv_min and SoC ≥ 95 % must hold for 10s.
LTO Cut-Off Values
- Nominal : 2.40 V
- CV min : 2.55 V
- CV max : 2.85 V
To enter the Cut-Off phase while charging, cutoff_voltage ≥ cv_min and SoC ≥ 95 % must hold for 10s.






