EMS diagnostic tests
Current scope
The diagnostic subsystem provides the execution structure for frontend-triggered and scheduled EMS tests:
- Authenticated trigger and status API
- Test-number validation and catalog
- Immediate single-test execution
- Scheduled single or multiple tests
- Atomic
ems_control_setting.jsonstatus updates - XML report generation
- Configurable XML upload to the EMS frontend
- Extensible Python handler registry
Test-specific electrical procedures are not implemented yet. Until a handler is registered, a requested test completes with the XML outcome not_implemented. This is deliberate: it proves the complete command/report flow without pretending that an equipment test passed.
Local EMS endpoints
The Python EMS HTTP server exposes:
| Method | Path | Purpose |
|---|---|---|
POST |
/api/v1/ems/diagnostic-tests |
Trigger or schedule a test command |
GET |
/api/v1/ems/diagnostic-tests |
Return current state, queue, schedules, and test catalog |
GET |
/api/v1/ems/diagnostic-tests/report/latest |
Download the latest XML report |
All endpoints use the same bearer authentication as the existing settings API.
From another Docker service, use:
http://ems-backend:8080/api/v1/ems/diagnostic-tests
Browser code should call a frontend/Laravel proxy instead of using the Docker service name directly.
Immediate test trigger
Example test 24 request:
curl -X POST http://ems-backend:8080/api/v1/ems/diagnostic-tests \
-H "Authorization: Bearer $EMS_BACKEND_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"Selected_radio_button_name": "General Functionality Test",
"mode_number": "24",
"date-time": "",
"test_status_active": true,
"multi_select": {
"modes": [],
"scheduled_time": ""
}
}'
The server returns HTTP 202 with a generated run_id and state queued.
The correct status field is test_status_active. The backend can still read the legacy misspelling during migration, but all status responses and settings updates use the corrected key.
Scheduled test
Provide an ISO 8601 date and time in either date-time or multi_select.scheduled_time:
{
"Selected_radio_button_name": "Peak Shaving Simulation",
"mode_number": "26",
"date-time": "2026-09-20T14:30:00+02:00",
"test_status_active": false,
"multi_select": {
"modes": [],
"scheduled_time": ""
}
}
Timezone-aware timestamps are recommended. A timestamp without a timezone is interpreted as UTC. If the scheduled timestamp is in the past, the test is queued immediately.
Before the due time, status is scheduled and test_status_active remains false. When execution begins it changes to true; after report generation and upload processing it changes back to false.
Exclusive BESS operation interlock
While test_status_active is true, diagnostics have exclusive control of the BESS. ems_main.py checks the local status before external-control and operation-mode dispatch.
When the interlock first engages, EMS:
- Stops the frequency-regulation subprocess if it is running.
- Stops the external-control bridge if it is running.
- Removes pending automatic power setpoints whose source is
control_logic. - Queues one
0 kWcommand for every active PCS with sourcediagnostic_interlock. - Skips all normal BESS control dispatch until the diagnostic finishes.
The blocked paths include:
- Scheduled charge/discharge
- Peak shaving
- Valley filling
- Arbitrage
- Anti-backflow
- Manual charge/discharge dispatch
- Frequency regulation
- External control
Manual start/stop commands, raw maintenance commands, and commands explicitly tagged for diagnostics are not removed from the PCS queue. The zero-power command is queued only once when the interlock changes from inactive to active.
Settings synchronization continues, but an active local diagnostic block is preserved when other settings are pulled from the frontend. This prevents a stale remote false value from releasing the interlock during a long-running test.
After report generation and result-upload processing, the diagnostic service sets test_status_active to false. On the next EMS cycle, normal dispatch resumes using the currently configured EMS operation and control modes.
Multiple scheduled tests
Use multi_select.modes to execute several tests in one run and XML report:
{
"Selected_radio_button_name": "Multiple Schedule Tests",
"mode_number": "53",
"test_status_active": false,
"multi_select": {
"modes": [2, 8, 20, 24],
"scheduled_time": "2026-09-20T15:00:00Z"
}
}
The modes run sequentially in the listed order. Duplicate mode numbers are removed. A scheduled command is deduplicated by its selected mode numbers and scheduled timestamp.
Settings-based trigger
The frontend may also deliver the command through the existing settings pull by updating diagnostic_test_mode in ems_control_setting.json:
{
"diagnostic_test_mode": {
"Selected_radio_button_name": "General Functionality Test",
"mode_number": "24",
"date-time": "",
"test_status_active": true,
"multi_select": {
"modes": [],
"scheduled_time": ""
}
}
}
The background watcher detects the transition to true, executes it once, creates the report, and resets the field to false.
For schedules delivered through settings, leave test_status_active false and provide a future schedule timestamp. The scheduler arms the test from the timestamp.
Runtime settings fields
The service preserves the command fields and adds runtime state:
{
"diagnostic_test_mode": {
"Selected_radio_button_name": "General Functionality Test",
"mode_number": "24",
"test_status_active": false,
"run_id": "d6455365-88bf-4663-91c5-b03d7afaf923",
"state": "completed",
"updated_at": "2026-09-20T12:30:02.200+00:00",
"started_at": "2026-09-20T12:30:01.100+00:00",
"completed_at": "2026-09-20T12:30:02.200+00:00",
"last_report": "/app/diagnostic_reports/diagnostic_d6455365-88bf-4663-91c5-b03d7afaf923.xml",
"result_upload": {
"status": "disabled"
}
}
}
Possible states are idle, scheduled, queued, running, completed, and error.
Test catalog
GET /api/v1/ems/diagnostic-tests returns the complete test catalog. Mode 22 is intentionally absent because it was not included in the supplied test list. Modes 1 through 21 and 23 through 53 are recognized.
Each catalog entry includes:
{
"mode_number": 24,
"name": "General Functionality Test",
"description": "",
"implemented": false
}
FFR modes 30 through 52 include the supplied verification objective in description. implemented becomes true when a Python handler is registered for that mode.
XML report
Reports are stored under the repository root:
diagnostic_reports/diagnostic_<run_id>.xml
Container path:
/app/diagnostic_reports/diagnostic_<run_id>.xml
One XML file is generated per run. A multiple-schedule run contains several <Test> elements in that one file.
Default placeholder report:
<?xml version='1.0' encoding='utf-8'?>
<DiagnosticTestReport schemaVersion="1.0">
<RunId>d6455365-88bf-4663-91c5-b03d7afaf923</RunId>
<GatewayId>GTW-ems100CX</GatewayId>
<Tests>
<Test modeNumber="24">
<Name>General Functionality Test</Name>
<Status>completed</Status>
<Outcome>not_implemented</Outcome>
<Passed>false</Passed>
<Summary>Diagnostic structure is ready; test-specific procedure is not implemented yet.</Summary>
<Measurements />
</Test>
</Tests>
</DiagnosticTestReport>
Download the latest report:
curl http://ems-backend:8080/api/v1/ems/diagnostic-tests/report/latest \
-H "Authorization: Bearer $EMS_BACKEND_TOKEN" \
-o diagnostic-result.xml
Result upload configuration
Configure diagnostic_test_results_api in emsConfig/ems/ems_api_config.json:
{
"diagnostic_test_results_api": {
"enabled": true,
"url": "http://ems-nginx/api/v1/ems/diagnostic-test-results",
"timeout_sec": 30,
"verify_ssl": true
}
}
The bearer token falls back to ems_control_json.bearer_token. The report is sent as the raw request body with:
Content-Type: application/xml
X-Diagnostic-Run-Id: <run_id>
The configured upload is disabled by default until the real frontend result endpoint is confirmed. Local XML generation and latest-report download work regardless of upload configuration.
Add a real test implementation
Add test logic to EnergySyc_EMS_ES100Cx12S/ems_diagnostic_handlers.py. The HTTP service imports that module at startup. A handler receives a context object and returns a result object:
from ems_diagnostic_tests import register_diagnostic_test
@register_diagnostic_test(24)
def run_general_functionality_test(context):
return {
"outcome": "pass",
"passed": True,
"summary": "All configured components responded.",
"measurements": {
"pcs_online": 12,
"grid_meter_online": True
}
}
The handler must return a dictionary. Unhandled exceptions are captured as an error result and do not stop the diagnostic worker.
Additional plugin modules can be loaded as a comma-separated list:
export EMS_DIAGNOSTIC_HANDLER_MODULES=ems_diagnostic_handlers,site_diagnostic_handlers
Restart ems_http_api after adding or changing handlers so registration decorators run again.
When real procedures are added, keep equipment safety checks inside the handler: authorization, operating mode, SOC limits, power limits, contactor state, test timeout, cancellation, and restoration to a safe final state.
Restart and verify
Restart ems_http_api after deploying the new service code. Verify:
curl http://ems-backend:8080/api/v1/ems/diagnostic-tests \
-H "Authorization: Bearer $EMS_BACKEND_TOKEN"
Check the EMS HTTP process log under /app/logs/ems_http_api.log and generated XML files under /app/diagnostic_reports/.