Skip to content

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:

  1. ems_operation_mode == "PAYLOAD_DIAGNOSTIC_TEST" — selecting the mode.
  2. diagnostic_test_mode.test_status_active is 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 kW commands with source diagnostic_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 via diagnostic_test_mode.mode_number and Selected_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 kW while 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.