PAYLOAD_DIAGNOSTIC_TEST
Runs the payload diagnostic test suite: performance and physical-characteristic tests on connected equipment (BESS and EV charging piles), taking the plant out of normal control.
The EMS's own verification - functionality, communication, alarms, services, databases and system health - belongs to SELF_TEST instead. The two modes are separate on purpose: a self test must be runnable without driving the plant, and a payload test must be runnable without being mistaken for an EMS fault.
| Mode string | PAYLOAD_DIAGNOSTIC_TEST (EMS_OP_PAYLOAD_DIAGNOSTIC_TEST); DIAGNOSTIC_TEST / EMS_OP_DIAGNOSTIC_TEST still resolve |
| Dispatcher | Diagnostic interlock at the top of the ems_main.py loop (before dispatch) |
| Config block | diagnostic_test_mode (top level) and functions.Payload_Diagnostic_Test |
| Status | Implemented (mode now triggers the existing test framework) |
Purpose
Selecting this mode is the operator's signal to run the configured payload test. It does not
implement a new test — it engages the existing diagnostic framework
(ems_diagnostic_tests.py), which was previously only reachable by setting a flag in the config file.
Payload tests it covers, per functions.Payload_Diagnostic_Test:
| Equipment | Tests |
|---|---|
| BESS | FFR/FCR response, active and reactive power response, capacity, internal resistance and |
| impedance, thermal response, open-circuit voltage, grid-forming and grid-following performance | |
| EV charging piles | Charging power and current performance, charging efficiency, dynamic |
| load-balancing response, ramp rate, interruption and recovery, energy measurement accuracy, | |
| session performance |
How it is triggered
is_diagnostic_test_active() now has two triggers, either of which is sufficient:
ems_operation_mode == "PAYLOAD_DIAGNOSTIC_TEST"— selecting the mode.diagnostic_test_mode.test_status_activeis truthy — the flag the diagnostic service sets while a test is in flight (the original, still-supported trigger).
mode = str(settings.get("ems_operation_mode") or "").strip().upper()
if DEPRECATED_MODE_ALIASES.get(mode, mode) == EMS_OP_PAYLOAD_DIAGNOSTIC_TEST:
return True
The mode name is matched case-insensitively, and the retired spellings stay aliased in
DEPRECATED_MODE_ALIASES: DIAGNOSTIC_TEST, DIAGNOSTIC_TESTS (the plural value the old
frontend selector persisted) and PAYLOAD_DIAGNOSTIC_TESTS (the value the renamed selector
persists) all resolve to PAYLOAD_DIAGNOSTIC_TEST. A settings file written before the rename
therefore keeps arming the interlock instead of silently doing nothing.
What happens when it is active
ems_main.py checks the interlock before the mode dispatch chain and continues the loop when it
is engaged:
- Normal control steps do not run at all — no mode dispatches power.
- The diagnostic interlock queues its own
0 kWcommands with sourcediagnostic_interlock(queue_diagnostic_zero_power_commands()), so the plant is held still while tests run. - The diagnostic test list includes numbered tests such as the Grid Synchronization Test
(
ems_diagnostic_tests.py), selected viadiagnostic_test_mode.mode_numberandSelected_radio_button_name.
This is why the mode needs no elif branch of its own. There is still a defensive branch in
the dispatch chain for the case where the interlock file cannot be read — it logs
mode=PAYLOAD_DIAGNOSTIC_TEST but the diagnostic interlock was not engaged instead of a generic
"not implemented" message.
Configuration
diagnostic_test_mode (top level in ems_control_setting.json)
| Key | Meaning |
|---|---|
test_status_active |
Truthy while a test is in flight. Legacy/secondary trigger. (test_status_acitve, a historical typo, is still read as a fallback.) |
mode_number |
Which numbered diagnostic test to run. |
Selected_radio_button_name |
Test name selected in the UI. |
mode_numbers |
Set of test numbers for scheduled diagnostic jobs. |
functions.Payload_Diagnostic_Test (in ems_control_setting.json)
Added alongside functions.Self_Test so the two modes are configured separately:
| Key | Meaning |
|---|---|
enabled |
Whether the payload suite may run |
test_duration_sec |
Nominal test duration |
bess.* |
One flag per BESS test listed above |
ev_charger.* |
One flag per EV charging pile test listed above |
Safety
- Selecting the mode stops normal dispatch entirely; nothing else can write power setpoints.
- The diagnostic interlock holds every PCS at
0 kWwhile active. - The mode is not an emergency stop — use STOP_ALL for that.
Mode gate
A payload diagnostic submit is refused unless this mode is active:
POST /api/v1/ems/diagnostic-tests
HTTP 409
{
"error": "payload_diagnostic_mode_required",
"current_mode": "MANUAL",
"required_mode": "PAYLOAD_DIAGNOSTIC_TEST",
"message": "payload diagnostic test requires the PAYLOAD_DIAGNOSTIC_TEST operational mode, currently MANUAL"
}
The gate runs before the request is validated, so a submit in the wrong mode is reported as a mode problem rather than as a bad device. The EMS never switches operational mode on its own: the operator selects the mode explicitly first. Self tests are gated the same way and require SELF_TEST.
Note: running a payload diagnostic test takes the plant out of service for its duration. Confirm the fleet can tolerate that before selecting this mode remotely.