EMS Settings Configuration and Synchronization
Overview
The EMS settings system uses the following main files:
emsConfig/ems/
├── ems_control_setting.json
└── ems_api_config.json
The EMS runtime reads its control configuration from:
emsConfig/ems/ems_control_setting.json
The frontend API connection settings are stored in:
emsConfig/ems/ems_api_config.json
The EMS periodically synchronizes the control settings with the frontend.
1. EMS API Configuration
File:
emsConfig/ems/ems_api_config.json
Example:
{
"ems_control_json": {
"url": "http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/get-ems",
"push_url": "http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/push-ems",
"bearer_token": "Bearer <API_TOKEN>",
"timeout_sec": 10,
"verify_ssl": true,
"refresh_interval_sec": 5,
"pull_dir": "ems_pull_setting"
}
}
Settings
url
Frontend endpoint used to pull the latest EMS settings.
Example:
http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/get-ems
Because the EMS backend and frontend are running in Docker, the Docker service/container name is used instead of a fixed IP address.
ems-nginx
Docker DNS resolves this automatically when both containers are connected to the same Docker network.
push_url
Frontend endpoint used to push the current EMS settings.
Example:
http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/push-ems
bearer_token
Authorization token used for both pulling and pushing settings.
Example:
"bearer_token": "Bearer <API_TOKEN>"
The EMS API code accepts either:
Bearer 5|xxxxxxxx
or:
5|xxxxxxxx
The HTTP request will send:
Authorization: Bearer 5|xxxxxxxx
The token should normally be read from ems_api_config.json.
The environment variable:
EMS_HARDWARE_BEARER_TOKEN
is only used as a fallback if no token exists in the configuration file.
timeout_sec
HTTP timeout for the frontend API request.
Example:
"timeout_sec": 10
This means the EMS waits up to 10 seconds for the frontend API before treating the request as failed.
verify_ssl
Controls SSL certificate verification for HTTPS API connections.
Example:
"verify_ssl": true
For the current internal Docker communication, HTTP is used:
http://ems-nginx
so SSL verification does not normally affect the internal Docker request.
refresh_interval_sec
Default settings synchronization period.
Example:
"refresh_interval_sec": 5
This means settings are normally synchronized every 5 seconds.
pull_dir
Folder used to store copies of settings received from the frontend.
Example:
"pull_dir": "ems_pull_setting"
The EMS may store:
ems_pull_setting/
├── ems_pull_setting.json
└── ems_control_setting.json
ems_pull_setting.json contains the raw frontend response.
ems_control_setting.json contains the unwrapped EMS settings used by the EMS.
2. Main EMS Control Settings
File:
emsConfig/ems/ems_control_setting.json
This is the main runtime control file used by ems_main.py.
Important settings include:
ems_operation_mode
ems_control_mode
general_settings.pcs
general_settings.lastvalue_read_refresh_rate
Manual_Operation
functions
3. EMS Operation Mode
Setting:
"ems_operation_mode": "MANUAL"
Supported operation modes currently referenced by ems_main.py include:
IDLE
ANTI_BACKFLOW
MANUAL
STOP_ALL
PEAK_SHAVING
FFR
SCHEDULED_CHARGE_DISCHARGE
ARBITRAGE
FREQUENCY_REGULATION
VALLEY_FILLING
The value is converted to uppercase internally.
Example:
"ems_operation_mode": "PEAK_SHAVING"
causes the EMS to run the peak-shaving controller.
4. EMS Control Mode
Setting:
"ems_control_mode": "local_control"
Supported normalized values are:
local_control
scada_control
external_control
The code also accepts several aliases.
Examples:
local
internal
internal_control
are normalized to:
local_control
Examples:
external
external_ems
external_ems_control
are normalized to:
external_control
When external_control is selected, the normal local EMS dispatch is skipped and the external-control bridge is started.
5. PCS Enable / Disable Settings
PCS configuration is read from:
general_settings.pcs
Example structure:
{
"general_settings": {
"pcs": {
"pcs1": {
"status": "active"
},
"pcs2": {
"status": "active"
},
"pcs3": {
"status": "inactive"
}
}
}
}
A PCS is enabled only when:
"status": "active"
For example:
pcs1 = active
pcs2 = active
pcs3 = inactive
results in:
Enabled PCS: pcs1, pcs2
PCS count: 2
6. EMS Main Loop Refresh Rate
The EMS main control loop refresh rate is read from:
general_settings.lastvalue_read_refresh_rate
Example:
"lastvalue_read_refresh_rate": 1.0
This value is interpreted as Hertz.
Therefore:
1.0 Hz = one EMS control cycle every 1 second
2.0 Hz = one cycle every 0.5 seconds
0.5 Hz = one cycle every 2 seconds
This is separate from the frontend settings pull/push interval.
7. Pull and Push Synchronization
The current synchronization sequence is:
Frontend
|
| GET settings
v
EMS pulls settings
|
v
ems_control_setting.json updated
|
v
EMS control logic uses new settings
|
v
EMS pushes current settings
|
| POST settings
v
Frontend
The important rule is:
PULL FIRST
PUSH SECOND
This prevents an older local EMS configuration from overwriting a newer configuration that was just changed in the frontend.
8. Pull Operation
The pull endpoint is read from:
ems_control_json.url
Example:
http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/get-ems
A successful pull should produce a log similar to:
[EMS][API] pulling settings from frontend...
[EMS][API] settings pull successful -> emsConfig/ems/ems_control_setting.json
The received settings are validated before replacing the live control JSON.
The pulled settings must contain valid EMS configuration information including:
ems_operation_mode
general_settings.pcs
If required settings are missing, the EMS keeps the existing local cache.
9. Push Operation
The push endpoint is read from:
ems_control_json.push_url
Example:
http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/push-ems
The frontend expects a payload envelope similar to:
{
"ems_gateway": "GTW-ems100CX",
"ems_model": "EMS-100CX12S",
"is_remote_operable": false,
"selected_function": "peak-shaving",
"scada_settings": {
"...": "contents of ems_control_setting.json"
}
}
The complete EMS control JSON is placed inside:
scada_settings
A successful push produces:
[EMS][API] pushing settings: emsConfig/ems/ems_control_setting.json -> http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/push-ems
[EMS][API] settings push successful for GTW-ems100CX
10. Gateway ID
The BESS / EMS gateway ID is resolved from the settings JSON.
Resolution order:
1. Explicit command-line / function argument
2. device.gateway_id
3. metadata.gateway_id
Example:
{
"metadata": {
"gateway_id": "GTW-ems100CX"
}
}
This ID is used in the API URL.
Example:
/api/v1/bess/GTW-ems100CX/ems-settings/get-ems
and:
/api/v1/bess/GTW-ems100CX/ems-settings/push-ems
11. Synchronization Intervals
The default frontend synchronization interval is:
5 seconds
ems_main.py supports separate pull and push intervals.
Example:
python3 ems_main.py --pull-interval 5 --push-interval 5
Disable pushing:
python3 ems_main.py --push-interval 0
Disable pulling:
python3 ems_main.py --pull-interval 0
Run with debug output:
python3 ems_main.py --debug
12. Manual API Testing
Test Pull
python3 ems_settings_api.py pull --force --debug
Expected successful output includes:
[EMS][API] settings pull successful
Test Push
python3 ems_settings_api.py push --debug
Expected successful output:
[EMS][API] settings push successful for GTW-ems100CX
Continuous Pull Test
python3 ems_settings_api.py poll --interval 5 --debug
This continuously pulls settings every 5 seconds.
Continuous Push Test
If the push-poll command is enabled in the installed version:
python3 ems_settings_api.py push-poll --interval 5 --debug
This continuously pushes the local settings every 5 seconds.
13. Normal EMS Startup
Run:
python3 ems_main.py
Typical startup:
[EMS] PCS enabled (ems_control_setting.json): 3 -> ['pcs1', 'pcs2', 'pcs3']
[EMS] ems_operation_mode = MANUAL
[EMS] ems_control_mode = local_control
[EMS] Refresh rate from ems_control_setting.json: 1.000 Hz
[EMS] Settings pull enabled: every 5.0s
[EMS] Settings push enabled: every 5.0s -> http://ems-nginx
Every 5 seconds the EMS should show both synchronization operations:
[EMS][API] pulling settings from frontend...
[EMS][API] settings pull successful -> emsConfig/ems/ems_control_setting.json
[EMS][API] pushing settings: emsConfig/ems/ems_control_setting.json -> http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/push-ems
[EMS][API] settings push successful for GTW-ems100CX
14. Docker Networking
The EMS backend communicates with the frontend using the Docker service name:
ems-nginx
instead of an IP address.
Example:
http://ems-nginx/api/...
Both containers must be connected to the same Docker network.
Test DNS resolution from the EMS backend container:
getent hosts ems-nginx
Test the frontend HTTP service:
curl -v http://ems-nginx/
15. Troubleshooting
HTTP 404 Not Found
Example:
HTTP Error 404: Not Found
This normally means Docker connectivity works but the API path is incorrect.
Correct push path:
/api/v1/bess/<gateway_id>/ems-settings/push-ems
Correct pull path:
/api/v1/bess/<gateway_id>/ems-settings/get-ems
HTTP 401 Unauthorized
Example:
HTTP Error 401: Unauthorized
Check:
emsConfig/ems/ems_api_config.json
and verify:
"bearer_token": "Bearer <valid token>"
Run:
python3 ems_settings_api.py push --debug
to confirm that a bearer token is configured.
Do not print the actual token in normal production logs.
Push Works but Pull Is Not Visible
Run:
python3 ems_main.py --debug
or:
python3 ems_settings_api.py pull --force --debug
The updated EMS code should also show successful pulls during normal operation.
Pulled Settings Are Rejected
If the log shows:
pulled settings missing ems_operation_mode or general_settings.pcs
the frontend response structure does not contain the required EMS settings in the expected location.
The frontend response should provide the control settings directly or inside one of the supported wrapper objects such as:
scada_settings
data
settings
ems_settings
16. Recommended Production Configuration
Recommended:
{
"ems_control_json": {
"url": "http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/get-ems",
"push_url": "http://ems-nginx/api/v1/bess/GTW-ems100CX/ems-settings/push-ems",
"bearer_token": "Bearer <API_TOKEN>",
"timeout_sec": 10,
"verify_ssl": true,
"refresh_interval_sec": 5,
"pull_dir": "ems_pull_setting"
}
}
Recommended EMS startup:
python3 ems_main.py --pull-interval 5 --push-interval 5
For troubleshooting:
python3 ems_main.py --debug
17. File Summary
emsConfig/ems/ems_api_config.json
API URLs, token, timeout and synchronization configuration.
emsConfig/ems/ems_control_setting.json
Active EMS runtime configuration.
ems_pull_setting/ems_pull_setting.json
Raw copy of the frontend API response.
ems_pull_setting/ems_control_setting.json
Unwrapped copy of the latest valid frontend EMS configuration.
ems_settings_api.py
Handles API pull, push, caching and local settings HTTP services.
ems_main.py
Main EMS dispatcher and periodic settings synchronization.
18. Security
The API bearer token provides access to EMS configuration endpoints.
Recommended practices:
- Do not commit real bearer tokens to public repositories.
- Do not print bearer tokens in production logs.
- Rotate a token if it is exposed.
- Limit API permissions to the required EMS endpoints.
- Keep frontend API traffic inside the Docker network where possible.