Skip to content

Diagnostic Test 05 — Thermal Response Test

Mode number 5
Registered handler thermal_response_test → _run_test_05_thermal_response in ems_diagnostic_handlers.py
Model actions change_power (heat load), read_soc (SOC window)
Temperature source Configurable Modbus register read directly
Parameters diagnostic_test_mode.thermal_response_test

Theory

When a battery charges or discharges, current flows through the cells' internal resistance and generates heat — Joule heating, P = I²R. Without adequate thermal management this heat would push the cells outside their safe operating window, accelerating degradation and, in the worst case, causing a thermal runaway. The thermal management system (air cooling, liquid cooling, fans, heat exchanger) must therefore remove heat at least as fast as the battery produces it.

The Thermal Response Test verifies that closed loop end to end:

  1. Response — applying a controlled heat load raises the battery temperature, proving the load produces heat and the temperature-sensor path reports it.
  2. Safety — the temperature never exceeds the configured safety limit while the load is applied, proving the cooling system keeps the battery inside its safe envelope.

A battery that heats too fast (weak cooling) fails on the safety limit. A battery whose temperature does not rise at all under load fails on the response target, which usually indicates a faulty temperature sensor, a missing thermal coupling, or that the heat load was never actually applied.

The test applies heat_load_kw (a PCS power setpoint; positive = discharge, negative = charge) for duration_sec, samples a temperature register every poll_interval_sec, then returns the PCS to zero power.

Settings needed

All values live under diagnostic_test_mode.thermal_response_test in emsConfig/ems/ems_control_setting.json. The nested object is canonical; flat keys are a legacy fallback; every key also has a built-in default.

Safety / eligibility

Key Default Meaning
min_soc 20 Minimum SOC (%) required before the heat load
max_soc 80 Maximum SOC (%) allowed before the heat load
max_temp_c 55.0 Safety limit — the test aborts immediately if any sample exceeds this

Heat load & measurement

Key Default Meaning
heat_load_kw 50.0 PCS power applied to generate heat (positive = discharge, negative = charge)
duration_sec 300 How long the heat load is held (seconds)
poll_interval_sec 10.0 Temperature sampling interval during the load (seconds)
target_temp_c 45.0 Response target — the maximum temperature must reach at least this

Temperature register map (site-specific)

The temperature register address, encoding and scale must match the actual Modbus map. Confirm them before the first run.

Key Default Meaning
temp_register 1500 Holding register holding the temperature
temp_encoding float32 u16, i16, u32, i32, or float32
temp_scale 1.0 Scale applied to the raw value (for u16/i16 only)

For float32 / u32 / i32 the register is read as two consecutive words (big-endian); u16 / i16 read a single word. temp_scale is applied after the raw decode, so a BMS that reports temperature in tenths of a degree would use i16 with temp_scale = 0.1.

Example configuration:

"diagnostic_test_mode": {
  "thermal_response_test": {
    "min_soc": 20,
    "max_soc": 80,
    "target_temp_c": 45.0,
    "duration_sec": 300,
    "heat_load_kw": 50.0,
    "max_temp_c": 55.0,
    "poll_interval_sec": 10.0,
    "temp_register": 1500,
    "temp_encoding": "float32",
    "temp_scale": 1.0
  }
}

Model actions required in emsConfig/pcs/power_sequences/<MODEL>.json:

  • change_power — used to apply the heat load and to return to 0 kW.
  • read_soc — used for the SOC safety window.

Prerequisites

Before the test runs:

  • At least one active PCS is configured and Modbus-reachable.
  • Every available PCS returns a valid SOC, and every SOC lies within [min_soc, max_soc].
  • Every available PCS returns a valid temperature reading, and its baseline temperature is below target_temp_c (there must be thermal headroom to observe a response) and at or below max_temp_c.
  • The PCS model must define the change_power and read_soc actions.
  • Every register required by the test — read_soc, change_power and the configured temperature register — 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 the test (SOC, power setpoint and temperature) is defined in the device register map. A missing device or missing register aborts the test as prerequisite_failed.
  2. Phase 2 — SOC safety window. Read SOC from every PCS; abort if any value is outside [min_soc, max_soc].
  3. Phase 3 — Baseline temperature. Read temperature from every PCS; abort if any value is above max_temp_c or already at/above target_temp_c.
  4. Phase 4 — Heat load. Command heat_load_kw, then sample the temperature every poll_interval_sec for duration_sec. Abort immediately if any sample exceeds max_temp_c.
  5. Always command 0 kW at the end (including on failure).
  6. Phase 5 — Evaluation. Check that the maximum temperature reached at least target_temp_c and never exceeded max_temp_c.

Report output

The report (measurements) contains:

  • heat_load_kw, duration_sec, poll_interval_sec.
  • target_temp_c, max_temp_c.
  • baseline_temp_c — per-PCS temperature before the load.
  • max_temp_reached_c — highest temperature recorded during the load.
  • temperature_samples — every sample with pcs, temp_c, phase (baseline / heat_load), elapsed_sec and date_time.
  • command_events — power-command event log.

A line graph (thermal-response-temp-by-pcs) plots temperature (°C) against elapsed seconds for each PCS.

Pass / fail summary

Result Condition
pass Load completed, temperature reached target_temp_c, and never exceeded max_temp_c
failed Safety limit exceeded, or maximum temperature did not reach the target
error A read/command failed or the heat-load sequence did not complete
prerequisite_failed No PCS, SOC outside window, baseline temperature outside the safe window, or a required register missing from the register map

Register-map caution. The default temp_register (1500) and temp_encoding (float32) are placeholders. Confirm them against the real BMS/thermal-device Modbus map before the first run, otherwise the measured temperature (and therefore the pass/fail result) will be wrong.