Skip to content

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.json status 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:

  1. Stops the frequency-regulation subprocess if it is running.
  2. Stops the external-control bridge if it is running.
  3. Removes pending automatic power setpoints whose source is control_logic.
  4. Queues one 0 kW command for every active PCS with source diagnostic_interlock.
  5. 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/.