Skip to content

Settings Pull

Automatic settings sync to the portal is off. ems-frontend writes emsConfig/ems/ems_control_setting.json through PUT /api/v1/ems/settings (see ems_backend_http_api.md) and the EMS loop reads that file from disk, so nothing needs to poll on an interval. The pull path described here still exists and still works, but every automatic caller stops at the enabled gate below; only an explicit CLI pull goes to the network.

Configuration

emsConfig/ems/ems_api_config.json is the only place the URL and token are defined.

{
  "ems_control_json": {
    "url": "http://ems-frontend/api/v1/bess/GTW-ems100CX/ems-settings/get-ems",
    "push_url": "http://ems-frontend/api/v1/bess/GTW-ems100CX/ems-settings/get-ems",
    "bearer_token": "<EMS_SETTINGS_API_TOKEN>",
    "timeout_sec": 10,
    "verify_ssl": true,
    "refresh_interval_sec": 5,
    "pull_dir": "ems_pull_setting"
  }
}
Key Meaning
url Pull endpoint
push_url Push endpoint, falls back to url
bearer_token Sent as Authorization: Bearer <token>
timeout_sec HTTP timeout
refresh_interval_sec Pull interval in seconds
pull_dir Folder for pulled files, relative to the project root
enabled Set to true to let automatic callers pull again. Absent or false means pulling is opt-in and stays off.

The pull uses the Docker service name ems-frontend, so traffic stays inside the Docker network and never leaves the host. Both containers must be on the same network. If the Laravel application is served by a separate web container, use that container name instead.

The equivalent manual request from inside ems-backend is:

curl --location 'http://ems-frontend/api/v1/bess/GTW-ems100CX/ems-settings/get-ems' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <EMS_SETTINGS_API_TOKEN>'

The same endpoint is reachable publicly at https://ems.gess-sweden.com/api/v1/bess/GTW-ems100CX/ems-settings/get-ems. Use that only for testing from outside the Docker network.

Files written on a successful pull

These writes only happen when pulling is enabled, or when someone runs the CLI pull below.

File Contents
ems_pull_setting/ems_pull_setting.json Raw API response exactly as received
ems_pull_setting/ems_control_setting.json Extracted EMS settings
emsConfig/ems/ems_control_setting.json Active cache read by the EMS

All writes are atomic, so a reader never sees a half-written file.

Response envelope

The portal wraps the EMS settings. The real settings are nested under scada_settings:

{
  "ems_gateway": "GTW-ems100CX",
  "ems_model": "EMS-100CX12S",
  "selected_function": "peak-shaving",
  "scada_settings": {
    "ems_operation_mode": "PEAK_SHAVING",
    "ems_control_mode": "SCADA_control",
    "general_settings": { "pcs": { "pcs1": {} } },
    "functions": {}
  }
}

_unwrap_settings() extracts scada_settings. A bare settings object, or one nested under data, settings, or ems_settings, is also accepted.

Safety guard

_is_usable_settings() rejects a payload that lacks ems_operation_mode or a non-empty general_settings.pcs.

If the guard rejects the payload:

  • The raw pull is still saved for inspection.
  • The active cache keeps its previous contents.
  • A warning is printed.

Without this guard, an envelope or error body written straight to the active cache would leave the EMS with no operation mode and no active PCS, so it would fall back to IDLE and stop dispatching.

Running the pull

Nothing pulls automatically any more: the poller service is not started by start_ems_client_in_docker.sh, and every automatic caller stays on the local file while enabled is false. A manual pull always works, because the CLI passes allow_when_disabled=True on purpose:

# one-off pull into emsConfig/ems/ems_control_setting.json
python3 ems_settings_api.py pull --force --debug

# explicit poller, only if you want the old interval behaviour back
python3 ems_settings_api.py poll --interval 5 --debug

Push the active settings back to the portal:

python3 ems_settings_api.py push --method PUT

Where the pull used to happen

Every automatic caller now stops at the enabled gate before any HTTP request is made:

Call site When it used to run
ems_main.py _load_json() and its loop refresh Every cycle, and on --pull-interval
ems_getters.py ems_get_value() On demand; the module is currently unreferenced
poll_settings_forever() Standalone poller process
CLI pull / poll Manual only; these pass allow_when_disabled=True

control_logic_updated.py imports the helper but does not call it. The pull path still writes all three files atomically, so a reader never sees a half-written file.