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:
scaledeclared on the register node, if present;- 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:
- set
ems_control_mode: external_control(settings file / frontend); @2reads2and the bridge process starts within one cycle;- bridge log shows
eligible=['pcs1', 'pcs2']once SOC is available; - restore the previous control mode ->
@2reads0, bridge stops, andems_main.logresumes 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.