Skip to content

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.