Skip to content

EMS Backend Developer Documentation

Documentation for the Python EMS service running in the ems-backend container.

Document Contents
ems_settings_pull.md 5-second settings pull, files written, payload handling
ems_http_api_endpoints.md HTTP endpoints served to the Laravel frontend
ems_backend_deployment.md Container processes, environment variables, startup
ems_troubleshooting.md Common failures and checks
diagnostic_test_parameters.md Diagnostic test mode JSON schema and per-test parameters
diagnostic_tests/01_state_of_health.md Test 01 — SOH estimation: theory, settings, prerequisites, procedure
diagnostic_tests/02_state_of_charge.md Test 02 — SOC validation: theory, settings, prerequisites, procedure
diagnostic_tests/03_cell_balancing.md Test 03 — cell balancing: theory, settings, prerequisites, procedure
diagnostic_tests/04_internal_resistance.md Test 04 — internal resistance: theory, settings, prerequisites, procedure
diagnostic_tests/05_thermal_response.md Test 05 — thermal response: theory, settings, prerequisites, procedure
ems_schedule_control.md Scheduled charge/discharge slots and setpoints

Laravel-side integration documentation lives in laravel/README.md; the copy-paste code files remain in EnergySyc_EMS_ES100Cx12S/laravel_dev_help/.

Architecture

ems-frontend    --(pull every 5s)-->  ems-backend  --> ems_control_setting.json --> ems_main.py
ems-frontend    --(HTTP settings)-->  ems-backend  --> ems_control_setting.json
Modbus devices  --(collectors)----->  lastValue/*.json --> ems-backend --> ems-frontend

Settings sources

Two writers update the EMS control settings:

  1. The scheduled pull from ems-frontend every 5 seconds.
  2. PUT/POST from the Laravel frontend through the HTTP API.

Both write the same file atomically. The last write wins, so a frontend change is replaced on the next successful pull if the pull endpoint still returns the old value. Persist the change on the frontend side when it must survive.

Control flow

ems_main.py re-reads the settings every cycle and dispatches by ems_operation_mode. Changes to the settings JSON take effect on the next control cycle without restarting any process.

Key modules

File Role
ems_settings_api.py Settings pull, JSON cache, HTTP API, poller
ems_main.py Control loop and mode dispatch
control_logic_updated.py Control strategies and PCS setpoints
pcs_cmds_all_in_one.py Modbus writes to PCS
ems_diagnostic_tests.py Diagnostic test engine, registry, XML reports, upload
ems_diagnostic_handlers.py Site-specific diagnostic test procedures
ems_schedule_control.py Scheduled charge/discharge decision (slot parsing, powerSetpoint)

Diagnostic tests can be driven from the shell with ./run_diagnostic_test.sh (see ems_http_api_endpoints.md).