Skip to content

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 from power_limits.max_charge_kw / max_discharge_kw (fallback rated_power_kw, then 100 kW).

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_failed otherwise, because the SOC targets cannot be verified.
  • The PCS model must define both read_soc and change_power actions.
  • Every register required by read_soc and change_power exists in the PCS device register map (emsConfig/pcs/<pcs>/pcs_register_full.json, falling back to emsConfig/pcs/pcs_register.json). A missing register aborts the test and is reported in register_checks.
  • pymodbus is installed.

Testing procedure

  1. Phase 1 — Prerequisite check. Confirm at least one PCS is available, then verify every register required by read_soc and change_power is defined in the device register map. A missing device or missing register aborts the test as prerequisite_failed.
  2. Phase 2 — SOC validation. Read SOC from every PCS and require all reads to succeed.
  3. Phase 3 — Initialization. Stop every PCS, wait 10 seconds, start every PCS.
  4. Phase 4 — Configuration validation. Validate min_soc, max_soc, number_of_cycles and the environment overrides. Invalid values return configuration_invalid.
  5. Phase 5 — Cycling. For each cycle:
  6. Command charge power and poll SOC until every PCS reaches max_soc - tolerance.
  7. Command discharge power and poll SOC until every PCS reaches min_soc + tolerance.
  8. Record the SOC sample of every poll for the report graph.
  9. 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 with cycle, phase, elapsed_sec.
  • completed_cycles and pcs_count on 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 at power / 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 full 0–100 % window cannot complete at all: one phase would need about 2.15 h, which already exceeds the default poll budget of 720 polls × 10 s = 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 raise EMS_CELL_BALANCE_MAX_POLLS_PER_PHASE if you deliberately want a long run.