Skip to content

SELF_TEST

Reserves the EMS for the full alarm diagnostic test. The mode runs no plant control, so a diagnostic alarm trigger cannot disturb live operation.

Mode string SELF_TEST (EMS_OP_SELF_TEST)
Dispatcher ems_main.py — dedicated branch (no control action)
Config block functions.Self_Test.alarm_diagnostic_test
Status Implemented
Scope EMS verification only — payload (BESS / EV pile) testing is PAYLOAD_DIAGNOSTIC_TEST

Behaviour

The dispatch chain has a dedicated branch that intentionally does nothing:

elif mode == ems_operation_modes.EMS_OP_SELF_TEST:
    # SELF TEST runs no plant control: the alarm diagnostic test drives the
    # registers, and a concurrent dispatch would fight it.
    pass

The loop still runs, still loads telemetry, and still performs its start/stop bookkeeping for the fast controllers exactly as IDLE does:

  • The frequency-regulation fast controller is stopped when the mode is not FREQUENCY_REGULATION.
  • The external-control bridge is stopped when is_external_control_active() is false.

What the mode adds is permission, not behaviour: a diagnostic run that writes to a device register is only allowed while the EMS is in SELF_TEST.

Why the mode exists

Triggering a real alarm means driving a device register out of range. If the plant were also being dispatched, the EMS would be reacting to a fault it is simultaneously being told to ignore, and a protection function could act on the fake value. Removing dispatch for the duration of the test is what makes the diagnostic safe, and it is why the three opt-ins below are all required.

Configuration

"functions": {
  "Self_Test": {
    "enabled": true,
    "description": "Reserves the EMS for the full alarm diagnostic test. ...",
    "alarm_diagnostic_test": {
      "include_self_test_alarms": true,
      "appear_timeout_s": 30,
      "clear_timeout_s": 45,
      "row_settle_s": 8,
      "max_alarms_per_device": 0,
      "simulator_url": null,
      "allow_simulator_register_writes": []
    }
  }
}

Every field is editable from the Self Test tab of the EMS Configuration Operation page. See Adding an EMS Operation Mode for the field-by-field reference and for data-json-empty, which is what makes the allow-list clearable from the UI.

Three independent opt-ins

A device write happens only when all three are true:

  1. the EMS is in SELF_TEST,
  2. simulator_url is configured, and
  3. the device_type:field pair is in allow_simulator_register_writes.

The allow-list takes rule fields from the device alarm map (frequency_hz), not reading keys (gridMeter_frequency_hz). A run that would write to a device is refused with 409 self_test_mode_required in any other mode; a run that touches no device (the synthetic SELFTEST-nnn alarms) is allowed in every mode.

API

Method Endpoint Purpose
POST /api/v1/ems/diagnostics/alarms/run Run one device
POST /api/v1/ems/diagnostics/alarms/run-all Run every active device
GET /api/v1/ems/diagnostics/alarms/status/{test_id} Progress
POST /api/v1/ems/diagnostics/alarms/stop/{test_id} Stop safely
GET /api/v1/ems/diagnostics/reports Stored reports (paged)
GET /api/v1/ems/diagnostics/reports/{test_id}/xml XML report

Results are stored in the TimescaleDB ems_test_reports hypertable.

Safety

The safest way to run an alarm test, because no power or reactive setpoint is written while it is selected.

Caution: like IDLE, selecting SELF_TEST does not clear the PCS write queue or force the PCS to zero. A command queued by the previous mode will still be applied by the PCS client. To test alarms on a plant that is actually running, stop the plant first.

Caution: a test that is cancelled mid-trigger can leave the simulator register holding the trigger value. The engine reverts each trigger before moving on, but a hard stop (container restart, stop/{test_id} while a write is in flight) can skip that. Re-check GET /api/v1/ems/alarms/active afterwards, and remember that some simulators recompute derived registers (power factor from power and current), so a full simulator restart may be the only way back to nominal.

Outputs

None. The mode writes no control command.