Diagnostic Test Mode
Documents the diagnostic_test_mode object in emsConfig/ems/ems_control_setting.json,
how the diagnostic engine reads it, and the per-test parameter schema.
The engine lives in ems_diagnostic_tests.py; site-specific procedures live in
ems_diagnostic_handlers.py. The HTTP surface is documented in http_api.md.
Per-test documentation
Each implemented test has its own document covering the theory, required settings, prerequisites and the testing procedure:
| Mode | Test | Document |
|---|---|---|
| 1 | State of Health (SOH) Estimation | 01_state_of_health.md |
| 2 | State of Charge (SOC) Validation | 02_state_of_charge.md |
| 3 | Cell Balancing Test | 03_cell_balancing.md |
| 4 | Internal Resistance (Impedance) Test | 04_internal_resistance.md |
| 5 | Thermal Response Test | 05_thermal_response.md |
Location
ems_control_setting.json
└── diagnostic_test_mode
Common fields
| Key | Type | Purpose |
|---|---|---|
Selected_radio_button_name |
string | null | Human-readable name of the selected test (UI state). |
mode_number |
number | string | null | Single test to run. null when idle or when multi_select is used. |
test_status_active |
boolean | Interlock flag. When true, ems_main.py suppresses normal control so a diagnostic can run. |
date-time |
string | ISO-8601 UTC time for a scheduled single-test run ("" when not scheduled). |
multi_select |
object | Batch selection and schedule, see below. |
multi_select:
"multi_select": {
"modes": [],
"scheduled_time": ""
}
modes— list of mode numbers to run together.scheduled_time— ISO-8601 UTC time for a scheduled batch run (""= run immediately).
Mode number reference
The engine maps mode numbers to test names in ems_diagnostic_tests.py
(TEST_NAMES). Mode number 22 is intentionally unused. 53 ("Multiple
Schedule Tests") duplicates 29 and is represented by a single parameter key
(multiple_schedule_tests).
Per-test parameters
Each test below stores its parameters in its own key inside
diagnostic_test_mode. Only the cell-balancing test is implemented today
(ems_diagnostic_handlers.py registers mode 3); the remaining keys hold
defaults ready for future handlers.
Battery pack / cell level
| Mode | Key | Parameters |
|---|---|---|
| 1 | soh_estimation |
min_soc, max_soc, reference_capacity_kwh, number_of_cycles |
| 2 | soc_validation |
min_soc, max_soc, tolerance_pct, settle_time_sec |
| 3 | cell_balancing_test |
min_soc, max_soc, number_of_cycles |
| 4 | internal_resistance_test |
min_soc, max_soc, pulse_current_a, pulse_duration_sec, pulse_direction, settle_time_sec, rest_time_sec, number_of_pulses, max_pack_resistance_mohm, max_cell_resistance_mohm, max_resistance_deviation_pct, min_pack_voltage_v, max_pack_voltage_v, max_cell_temp_c, cell_voltage_start_register, cell_voltage_count, cell_voltage_scale_mv, dc_current_register, dc_current_scale_a |
| 5 | thermal_response_test |
min_soc, max_soc, target_temp_c, duration_sec, heat_load_kw, max_temp_c, poll_interval_sec, temp_register, temp_encoding, temp_scale |
| 6 | ocv_check |
min_soc, max_soc, rest_time_sec, tolerance_v |
| 7 | self_discharge_test |
min_soc, max_soc, duration_hours, max_discharge_pct |
PCS / inverter level
| Mode | Key | Parameters |
|---|---|---|
| 8 | grid_synchronization_test |
frequency_hz, voltage_v, phase_angle_deg, sync_timeout_sec |
| 9 | efficiency_test |
min_power_kw, max_power_kw, power_step_kw, duration_sec |
| 10 | harmonics_thd_test |
min_power_kw, max_thd_pct, duration_sec |
| 11 | response_time_test |
setpoint_kw, max_response_time_ms, settling_tolerance_pct |
| 12 | isolation_test |
test_voltage_v, min_insulation_resistance_mohm, duration_sec |
Thermal management
| Mode | Key | Parameters |
|---|---|---|
| 13 | cooling_fan_pump_test |
duration_sec, min_flow_rate_lpm, expected_rpm |
| 14 | heat_exchanger_test |
inlet_temp_c, outlet_temp_c, duration_sec |
| 15 | heater_functionality_test |
target_temp_c, max_power_kw, duration_sec |
System safety / protection
| Mode | Key | Parameters |
|---|---|---|
| 16 | breaker_contactor_test |
number_of_cycles, close_delay_ms, open_delay_ms |
| 17 | fuse_integrity_check |
continuity_threshold_ohm, test_current_a |
| 18 | fire_suppression_diagnostic |
test_duration_sec, agent_pressure_bar |
| 19 | insulation_resistance_test |
test_voltage_v, min_resistance_mohm, duration_sec |
Communication & control
| Mode | Key | Parameters |
|---|---|---|
| 20 | can_modbus_communication_test |
protocol, packet_count, timeout_ms |
| 21 | scada_ems_bms_command_flow_test |
command, timeout_ms, verify_response |
| 23 | alarm_event_reporting_test |
alarm_code, expected_report_ms, verify_ack |
Performance & functional
| Mode | Key | Parameters |
|---|---|---|
| 24 | general_functionality_test |
duration_sec, checks |
| 25 | charge_discharge_cycling_test |
min_soc, max_soc, number_of_cycles, power_kw |
| 26 | peak_shaving_simulation |
peak_threshold_kw, duration_sec, power_kw |
| 27 | black_start_test |
min_soc, ramp_up_time_sec, target_power_kw |
| 28 | ffr_fcrd_test |
frequency_hz, deadband_hz, duration_sec |
| 29 / 53 | multiple_schedule_tests |
schedules, number_of_cycles |
FFR / FFR-D
| Mode | Key | Parameters |
|---|---|---|
| 30 | ffr_01_frequency_measurement_accuracy |
frequency_hz, tolerance_hz, duration_sec |
| 31 | ffr_02_measurement_filter_latency |
max_latency_ms, duration_sec |
| 32 | ffr_03_time_sync_accuracy |
max_offset_ms, source |
| 33 | ffr_04_trigger_threshold_deadband |
under_freq_hz, over_freq_hz, deadband_hz |
| 34 | ffr_05_activation_time |
t90_ms, t100_ms, setpoint_pct |
| 35 | ffr_06_initial_ramp_rate |
min_ramp_rate_kw_s, duration_sec |
| 36 | ffr_07_droop_gain_accuracy |
droop_pct, tolerance_pct |
| 37 | ffr_08_delivery_magnitude_accuracy |
setpoint_pct, tolerance_pct |
| 38 | ffr_09_hold_sustain_duration |
hold_duration_sec, setpoint_pct |
| 39 | ffr_10_energy_availability |
min_soc_reserve_pct, energy_required_kwh |
| 40 | ffr_11_thermal_soc_derating |
max_temp_c, min_soc_pct |
| 41 | ffr_12_ems_pcs_command_latency |
max_latency_ms, sample_count |
| 42 | ffr_13_recovery_to_baseline |
recovery_ramp_kw_s, oscillation_tolerance_pct |
| 43 | ffr_14_bidirectional_behavior |
under_freq_hz, over_freq_hz |
| 44 | ffr_15_saturation_clipping |
max_power_kw, min_power_kw |
| 45 | ffr_16_anti_islanding_ride_through |
ride_through_ms, grid_code |
| 46 | ffr_17_comms_loss_fail_safe |
fail_safe_power_kw, timeout_ms |
| 47 | ffr_18_telemetry_settlement |
sample_rate_hz, send_frequency_ms |
| 48 | ffr_19_event_logging_evidence |
log_format, required_fields |
| 49 | ffr_20_prequalification_replay |
profile_file, duration_sec |
| 50 | ffr_21_aggregation_coordination |
unit_count, response_delay_ms |
| 51 | ffr_22_metering_path_accuracy |
tolerance_pct, meter_id |
| 52 | ffr_23_cyber_controls |
enable_role, disable_role, require_confirm |
Cell balancing parameters (mode 3)
The cell-balancing handler (_cell_balance_parameters in
ems_diagnostic_handlers.py) reads these three values. The nested object is
the canonical form; the flat keys are kept as a legacy fallback, so either
layout works:
"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
}
}
Precedence: cell_balancing_test.min_soc/max_soc/number_of_cycles is used when
present; otherwise the flat min_soc/max_soc/number_of_cycles are used;
otherwise the built-in defaults (0, 100, 3).
The shipped ems_control_setting.json sets both layouts to 45/55/1, so a
run takes roughly 20–25 minutes. A full 0–100 % window cannot finish: one phase
needs about 2.15 h, more than the default poll budget of 720 × 10 s = 2 h.
Note the built-in fallback is still 0/100/3, so deleting these keys brings
the unbounded window back.
Environment overrides for mode 3:
| Variable | Default | Meaning |
|---|---|---|
EMS_CELL_BALANCE_POLL_INTERVAL |
10 |
SOC poll interval, seconds |
EMS_CELL_BALANCE_MAX_POLLS_PER_PHASE |
720 |
Max polls per charge/discharge phase |
EMS_CELL_BALANCE_SOC_TOLERANCE_PCT |
1 |
Stop tolerance around the target SOC |
Internal Resistance parameters (mode 4)
The Internal Resistance (Impedance) handler (_ir_parameters in
ems_diagnostic_handlers.py) applies a DC current pulse and computes resistance
from the resulting voltage/current step:
R = |V_rest - V_pulse| / |I_pulse - I_rest|
Pack voltage is read as the sum of the configured cell-voltage registers; DC current is read from a configured current register. The nested object is the canonical form; flat keys are a legacy fallback, and every key also has a built-in default.
"diagnostic_test_mode": {
"internal_resistance_test": {
"min_soc": 20,
"max_soc": 80,
"pulse_current_a": 50,
"pulse_duration_sec": 10,
"pulse_direction": "discharge",
"settle_time_sec": 5,
"rest_time_sec": 5,
"number_of_pulses": 3,
"max_pack_resistance_mohm": 50.0,
"max_cell_resistance_mohm": 10.0,
"max_resistance_deviation_pct": 20.0,
"min_pack_voltage_v": 700.0,
"max_pack_voltage_v": 900.0,
"max_cell_temp_c": 45.0,
"cell_voltage_start_register": 1860,
"cell_voltage_count": 8,
"cell_voltage_scale_mv": 1,
"dc_current_register": 1801,
"dc_current_scale_a": 0.1
}
}
Safety / eligibility
| Key | Default | Meaning |
|---|---|---|
min_soc |
20 |
Minimum SOC (%) required before the pulse can run |
max_soc |
80 |
Maximum SOC (%) allowed before the pulse can run |
min_pack_voltage_v |
700.0 |
Minimum pack voltage (V) allowed at baseline |
max_pack_voltage_v |
900.0 |
Maximum pack voltage (V) allowed at baseline |
max_cell_temp_c |
45.0 |
Reserved maximum cell temperature (C); enforced by the BMS safety layer |
The test aborts with prerequisite_failed if SOC or baseline pack voltage is
outside its window.
Pulse generation
| Key | Default | Meaning |
|---|---|---|
pulse_current_a |
50 |
Target current step magnitude (A) |
pulse_direction |
discharge |
Pulse sign: discharge (positive power) or charge (negative power) |
pulse_duration_sec |
10 |
Total time the pulse is held (seconds) |
settle_time_sec |
5 |
Stabilization delay after applying the pulse and before measuring (seconds) |
rest_time_sec |
5 |
Recovery delay between pulses and after the final pulse (seconds) |
number_of_pulses |
3 |
Number of pulse cycles to run |
The pulse power is derived per run as
pulse_current_a * baseline_pack_voltage / 1000 (kW), signed by
pulse_direction. After the measurement the PCS is always commanded back to
0 kW, including on failure paths.
Pass / fail thresholds
| Key | Default | Meaning |
|---|---|---|
max_pack_resistance_mohm |
50.0 |
Maximum allowed pack resistance (mOhm) |
max_cell_resistance_mohm |
10.0 |
Maximum allowed average cell resistance (mOhm) |
max_resistance_deviation_pct |
20.0 |
Maximum pulse-to-pulse spread of pack resistance (%) |
Average cell resistance is derived as
pack_resistance_mohm / cell_voltage_count (cells are in series). The test
passes only when every pulse for every PCS stays within all three limits.
Register map (site-specific)
| Key | Default | Meaning |
|---|---|---|
cell_voltage_start_register |
1860 |
First Modbus holding register of the cell-voltage window |
cell_voltage_count |
8 |
Number of cell-voltage registers to read |
cell_voltage_scale_mv |
1 |
Scale factor applied to each raw cell-voltage word (mV) |
dc_current_register |
1801 |
Modbus holding register for DC current |
dc_current_scale_a |
0.1 |
Scale factor applied to the raw (signed 16-bit) current word (A) |
Thermal Response parameters (mode 5)
The Thermal Response handler (_thermal_parameters in
ems_diagnostic_handlers.py) applies a heat load and monitors a temperature
register. See 05_thermal_response.md
for the full theory, procedure and pass/fail rules.
"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
}
}
| Key | Default | Meaning |
|---|---|---|
min_soc / max_soc |
20 / 80 |
SOC safety window before the heat load |
heat_load_kw |
50.0 |
PCS power applied to generate heat (positive = discharge) |
duration_sec |
300 |
Heat-load duration, seconds |
poll_interval_sec |
10.0 |
Temperature sampling interval, seconds |
target_temp_c |
45.0 |
Response target the maximum temperature must reach |
max_temp_c |
55.0 |
Safety limit — abort if exceeded |
temp_register |
1500 |
Temperature holding register (site-specific) |
temp_encoding |
float32 |
u16, i16, u32, i32 or float32 |
temp_scale |
1.0 |
Scale for u16/i16 (e.g. 0.1 for tenths of a degree) |
How the engine consumes the object
- Interlock —
ems_main.py::is_diagnostic_test_active()readstest_status_active(with the legacy misspellingtest_status_acitveas a fallback) and suppresses normal control while it is truthy. - Selection —
_mode_numbers()prefersmulti_select.modes; when that is empty it usesmode_number. Idle state ismode_number: nullandmulti_select.modes: []. - Scheduling —
_scheduled_time()prefersdate-timeand falls back tomulti_select.scheduled_time. - Write-back — after a run,
_update_settings()writesmode_number,test_status_active,run_id,state, andupdated_at, preserves every per-test key, and re-adds the legacy flatmin_soc/max_soc/number_of_cyclesviasetdefault. It writes the whole settings file atomically, so other settings changes made in the same cycle are not lost.
Example
"diagnostic_test_mode": {
"Selected_radio_button_name": null,
"mode_number": null,
"test_status_active": false,
"date-time": "",
"min_soc": 45,
"max_soc": 55,
"number_of_cycles": 1,
"cell_balancing_test": { "min_soc": 45, "max_soc": 55, "number_of_cycles": 1 },
"soh_estimation": { "min_soc": 20, "max_soc": 100, "reference_capacity_kwh": 215, "number_of_cycles": 1 },
"multi_select": { "modes": [], "scheduled_time": "" }
}