Diagnostic Test 03 — Cell Balancing Test
| Mode number | 3 |
| Registered handler | cell_balancing_test → _run_test_03_cell_balancing in ems_diagnostic_handlers.py |
| Model actions | read_soc (measurement), change_power (charge/discharge) |
| Parameters | diagnostic_test_mode.cell_balancing_test |
Theory
A battery pack is a series string of cells. In an ideal pack every cell has identical capacity and resistance, so all cells charge and discharge together. In practice cells differ slightly. Over many cycles the differences grow: the weakest cell hits its voltage limit first, which stops the whole string from charging fully, while the strongest cell reaches the low-voltage limit first during discharge. This reduces the usable pack capacity and stresses the outlier cells.
Cell balancing is the BMS process that equalises cell voltages (or SOC) so the pack can be used over its full capacity range. Balancing is usually performed near the top of charge, where small voltage differences are easiest to detect.
The diagnostic exercises the balancing system by cycling the pack between a configured upper SOC and lower SOC several times. Each full cycle forces the BMS to re-balance the cells; recording the SOC trajectory across cycles verifies that the pack reaches both targets every time and that the EMS/PCS power path works in both directions.
Settings needed
All values are read from diagnostic_test_mode in
emsConfig/ems/ems_control_setting.json. The nested object is the canonical
form; the flat keys are kept as a legacy fallback.
"diagnostic_test_mode": {
"min_soc": 45,
"max_soc": 55,
"number_of_cycles": 1,
"cell_balancing_test": {
"min_soc": 45,
"max_soc": 55,
"number_of_cycles": 1
}
}
| Key | Default | Meaning |
|---|---|---|
min_soc |
45 |
Lower SOC target (%) for the discharge phase |
max_soc |
55 |
Upper SOC target (%) for the charge phase |
number_of_cycles |
1 |
Number of charge/discharge repetitions |
Validation: 0 <= min_soc < max_soc <= 100 and number_of_cycles >= 1.
Optional environment overrides:
| Variable | Default | Meaning |
|---|---|---|
EMS_CELL_BALANCE_POLL_INTERVAL |
10 |
SOC poll interval during a phase, seconds |
EMS_CELL_BALANCE_MAX_POLLS_PER_PHASE |
720 |
Max polls per charge/discharge phase (2 h at 10 s) |
EMS_CELL_BALANCE_SOC_TOLERANCE_PCT |
1 |
Stop tolerance around the target SOC (%) |
Model actions required in emsConfig/pcs/power_sequences/<MODEL>.json:
read_soc— read SOC from the PCS/BMS.change_power— set the PCS power (negative = charge, positive = discharge). The charge/discharge power magnitude is taken frompower_limits.max_charge_kw/max_discharge_kw(fallbackrated_power_kw, then100kW).
Prerequisites
Before the test runs:
- At least one active PCS is configured and Modbus-reachable.
- Every available PCS must return a valid SOC reading — the test aborts with
prerequisite_failedotherwise, because the SOC targets cannot be verified. - The PCS model must define both
read_socandchange_poweractions. - Every register required by
read_socandchange_powerexists in the PCS device register map (emsConfig/pcs/<pcs>/pcs_register_full.json, falling back toemsConfig/pcs/pcs_register.json). A missing register aborts the test and is reported inregister_checks. pymodbusis installed.
Testing procedure
- Phase 1 — Prerequisite check. Confirm at least one PCS is available, then
verify every register required by
read_socandchange_poweris defined in the device register map. A missing device or missing register aborts the test asprerequisite_failed. - Phase 2 — SOC validation. Read SOC from every PCS and require all reads to succeed.
- Phase 3 — Initialization. Stop every PCS, wait 10 seconds, start every PCS.
- Phase 4 — Configuration validation. Validate
min_soc,max_soc,number_of_cyclesand the environment overrides. Invalid values returnconfiguration_invalid. - Phase 5 — Cycling. For each cycle:
- Command charge power and poll SOC until every PCS reaches
max_soc - tolerance. - Command discharge power and poll SOC until every PCS reaches
min_soc + tolerance. - Record the SOC sample of every poll for the report graph.
- Always command zero power at the end (including on failure) so the PCS is never left charging/discharging after the test.
Report output
The report (measurements) contains:
min_soc,max_soc,number_of_cycles.cycle_events— per-PCS power-command event log.soc_samples— every SOC poll withcycle,phase,elapsed_sec.completed_cyclesandpcs_counton success.
A line graph (cell-balancing-soc-by-pcs) plots SOC (%) against elapsed time
for each PCS.
Pass / fail summary
| Result | Condition |
|---|---|
pass |
All cycles completed (every PCS reached both targets each cycle) |
test_failed |
A power command failed or a phase did not reach its SOC target |
configuration_invalid |
Invalid min_soc/max_soc/number_of_cycles or env values |
prerequisite_failed |
No PCS available, any PCS failed to report SOC, or a required register missing from the register map |
initialization_failed |
Stop / wait / start sequence failed |
Time budget. The shipped window (
45–55%, one cycle) takes roughly 20–25 minutes on the simulator, because SOC moves atpower / rated_energy— 100 kW into a 215 kWh pack is about 0.0121 %/s, so a 10 % swing takes about 14 minutes per phase. A full0–100% window cannot complete at all: one phase would need about 2.15 h, which already exceeds the default poll budget of720polls ×10s = 2 h, so the test would run for hours and never reach its targets. Keep the window narrow relative to the achievable SOC rate, or raiseEMS_CELL_BALANCE_MAX_POLLS_PER_PHASEif you deliberately want a long run.