Skip to content

EMS Operational Task Preconditions

An EMS operational mode can read as running (ems_operation_status, @3) while dispatching nothing to the PCS units. This page lists the preconditions that must hold before any operational task (Peak Shaving, Valley Filling, Arbitrage, Frequency Regulation, ...) actually commands power, plus the exact log lines and registers used to confirm each one.

All values below were verified against the running Docker stack (ems-backend + bess-simulator-backend, EMS map server on port 1540, unit 1).


1. Command acceptance: EMS control mode

Register Name Values
@2 ems_control_mode 0 local_control, 1 scada_control, 2 external_control

The Modbus server refuses writes while the control mode is local_control. A refused write is silent: function code 06 echoes the value you sent, but the register keeps its previous value and the settings file is not modified.

Verified on the live server:

Sent FC6 echo @2 after Settings file
@1 = 10 (valid mode, local control) 10 2 (unchanged) unchanged
@1 = 99 (invalid mode, local control) 99 2 (unchanged) unchanged
@1 = 8 (external control) 8 8 ems_operation_mode: POWER_FACTOR_CORRECTION

Rule: always read back the register (and @3) after a write. Never trust the FC6 echo as acknowledgement.

Switching the control mode is done from the device UI / settings API (the EMS reads ems_control_setting.json; see ems_http_api_endpoints.md), because the Modbus server itself will not accept the change while the mode is local_control.


2. Dispatch gate: per-PCS SOC

Every task evaluates each PCS and only dispatches to units with a usable SOC inside the configured limits.

Symptom Meaning
eligible=NONE (SOC blocked/missing) no PCS has a usable SOC - the task runs but commands nothing
eligible=['pcs1', 'pcs2'] both units passed the SOC gate and will receive setpoints

SOC data path (each hop verified live):

PCS simulator (@3005, uint16, percent)
  -> PCS client read batch "Analog_1" (3000 + 20)
  -> emsConfig/lastValue/pcsN_lastValue.json  key: pcs_soc_state_of_charge_item
  -> EMS task gate -> setpoint -> pcs_write_queue.json -> PCS client -> PCS

If the last hop shows a blocked task, check the PCS map's SOC register (bc_battery_cluster.soc_state_of_charge_item, @3005) and the per-device SOC limits in ems_control_setting.json (functions.<mode>.soc_limits.*, min_soc_pct / max_soc_pct). A SOC of 0 blocks charge and discharge alike.


3. Register scaling: node scale overrides device scale

The PCS client resolves a register's engineering unit as:

  1. scale declared on the register node, if present;
  2. otherwise the device scale (device.scale).

This matters where one device uses different units per register. Example for the EPCS105 PCS:

Register Address Data type Node scale Engineering value
bc_battery_cluster.soc_state_of_charge_item 3005 UINT16 1 percent (raw 48 -> 48 %)
bc_battery_cluster.soh_state_of_health_item 3006 UINT16 1 percent
active power (setpoint/feedback) 3415 INT16 device 0.1 kW (raw 65386 -> -15.0 kW)

Before the scale: 1 nodes were added, the device scale of 0.1 was applied to SOC (48 -> 4.8), which is below min_soc_pct: 10 and therefore blocked every task.

Rule for integrators: when a vendor register's unit differs from the device default, declare scale on that register node in the register map rather than changing the device scale.


4. Setting SOC for commissioning and tests

SOC is owned by the PCS simulator. Set it through the simulator register API (http://bess-simulator-backend:8000), which rewrites the register file the simulator serves:

curl -s -X PATCH "http://bess-simulator-backend:8000/api/pcs/pcs1/pcs_register_full" \
  -H 'Content-Type: application/json' \
  -d '{"updates": [{"name": "soc_state_of_charge_item", "value": 48}]}'

Verified response (note the model-resolved device id):

{"device": "pcs/pcs1/pcs_register_full___epcs105",
 "updated": [{"name": "soc_state_of_charge_item", "address": 3005, "value": 48,
              "data_type": "UINT16", "registers": 1, "rw_type": "read_only"}]}

Always PATCH the canonical device id (pcs/pcs1/pcs_register_full); the API resolves it to the per-model variant that the simulator actually serves. The response's device field confirms which file was written.

The external SOC write wins over the simulator's SOC dynamics: soc_dynamics.py re-reads the register file each step and adopts a value that differs from the one it wrote, so a commanded SOC sticks and then integrates from there with the applied power.


5. Confirming a task actually dispatched

Check Where Expected
Mode / status Modbus @1, @3 @1 = requested mode, @3 = same enum name
Gate /app/logs/ems_main.log eligible=['pcs1', 'pcs2']
Dispatch /app/logs/ems_main.log - pcs1: charge 15.000 kW -> OK
Command queue emsConfig/.../pcs_write_queue.json set_power_kw entries per PCS
PCS receipt PCS simulator @3415 (INT16, 0.1 kW) e.g. 65386 = -15.0 kW

@3 ems_operation_status reports the effective mode running in ems_main, so it is the register to poll for "did my mode start".


6. External PCS control path

There are two Modbus TCP endpoints:

Port Server Purpose
1540 EMS register map server read all telemetry, read/write EMS settings, select operational mode
1541 external control bridge direct PCS power command while the EMS runs in external_control

The bridge starts only while ems_control_mode = external_control and stops when the mode changes (@2 = 2 -> bridge process present; @2 = 0 -> bridge gone, normal EMS dispatch resumes within one cycle).

Verified sequence on the live stack:

  1. set ems_control_mode: external_control (settings file / frontend);
  2. @2 reads 2 and the bridge process starts within one cycle;
  3. bridge log shows eligible=['pcs1', 'pcs2'] once SOC is available;
  4. restore the previous control mode -> @2 reads 0, bridge stops, and ems_main.log resumes the operational mode (pcs1/pcs2 charge 15.000 kW -> OK).

The bridge command register and encoding are documented in ems_external_control_register.json (holding_registers.total_power_kw, @24000): sign-magnitude, bit 15 = charge, bits 0-14 = magnitude in 0.1 kW.