Skip to content

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() reads test_status_active (with the legacy misspelling test_status_acitve as a fallback) and suppresses normal control while it is truthy.
  • Selection — _mode_numbers() prefers multi_select.modes; when that is empty it uses mode_number. Idle state is mode_number: null and multi_select.modes: [].
  • Scheduling — _scheduled_time() prefers date-time and falls back to multi_select.scheduled_time.
  • Write-back — after a run, _update_settings() writes mode_number, test_status_active, run_id, state, and updated_at, preserves every per-test key, and re-adds the legacy flat min_soc/max_soc/ number_of_cycles via setdefault. 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": "" }
}