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:
- Response — applying a controlled heat load raises the battery temperature, proving the load produces heat and the temperature-sensor path reports it.
- 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 to0 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 belowmax_temp_c. - The PCS model must define the
change_powerandread_socactions. - Every register required by the test —
read_soc,change_powerand the configured temperature register — exists 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 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. - Phase 2 — SOC safety window. Read SOC from every PCS; abort if any value
is outside
[min_soc, max_soc]. - Phase 3 — Baseline temperature. Read temperature from every PCS; abort
if any value is above
max_temp_cor already at/abovetarget_temp_c. - Phase 4 — Heat load. Command
heat_load_kw, then sample the temperature everypoll_interval_secforduration_sec. Abort immediately if any sample exceedsmax_temp_c. - Always command
0 kWat the end (including on failure). - Phase 5 — Evaluation. Check that the maximum temperature reached at
least
target_temp_cand never exceededmax_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 withpcs,temp_c,phase(baseline/heat_load),elapsed_secanddate_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) andtemp_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.