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:
- The scheduled pull from
ems-frontendevery 5 seconds. PUT/POSTfrom 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).