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:
- the EMS is in
SELF_TEST, simulator_urlis configured, and- the
device_type:fieldpair is inallow_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_TESTdoes 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-checkGET /api/v1/ems/alarms/activeafterwards, 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.