How to Monitor EMS Commands
Purpose
See every Modbus write the simulator receives, as it happens. This is how you prove that a command sequence issued by the EMS actually reached a device, at which register, with which value, and at what time.
Prerequisites
- The simulator stack is up.
- The EMS is configured to talk to the simulated devices
(
MODBUS_MODE=SIM), otherwise nothing will arrive to monitor.
Where the data comes from
The Modbus servers in bess-simulator-backend install a pymodbus request tracer.
Every write is appended as one JSON line to:
/app/EnergySyc_EMS_ES100Cx12S_BESS_simulator/write_commands.jsonl
Only write function codes are recorded:
| Function code | Name |
|---|---|
0x05 |
write_single_coil |
0x06 |
write_single_register |
0x0F |
write_multiple_coils |
0x10 |
write_multiple_registers |
Reads are deliberately not logged — polling happens continuously and would drown the signal.
The log is capped at 5 MB. When it exceeds that, it is trimmed to the most recent 2000 entries. Logging failures are swallowed on purpose so that a full disk can never break the simulator.
Every entry has exactly these fields:
{"time": "2026-10-12 09:28:22", "epoch": 1791797302.154, "port": 1501,
"client_ip": "172.19.0.12", "client_port": 60906, "fc": 6,
"function": "write_single_register", "register": 3415, "value": 65403, "count": 1}
The Write Monitor page
Open Write Monitor (/monitor). The table has one row per received write:
| Column | Source field | Notes |
|---|---|---|
| Time | time |
Reception time, second resolution |
| Simulator | port |
Mapped to a device label (1501 → PCS1) |
| Client IP | client_ip |
The EMS container's address on the shared network |
| Client Port | client_port |
Ephemeral source port |
| Function | function |
From the function code, e.g. write_single_register |
| Register | register |
Modbus register address |
| Value | value |
Raw register value as received |
| Registers | count |
How many registers the write covered |
The page refreshes itself every 2 seconds through
pcs.monitor.data (GET /monitor/data). Clear log empties the file via
DELETE /api/write-commands.
Step-by-step procedure
Step 1 — Open the monitor before you trigger anything
Go to Write Monitor. It should show historical writes; if it says "No write commands recorded yet", nothing has been written since the log was last cleared.
Step 2 — Clear the log to get a clean baseline
Press Clear log. This is important: it makes the next sequence you test unambiguous.
Step 3 — Issue the EMS action
Trigger the alarm, run the sequence, or change the setpoint from the EMS side.
Step 4 — Read the rows
Within one poll interval rows appear. Read them bottom-up by time to see the order commands arrived in.
Step 5 — Correlate with the sequence definition
Take the register column and look the address up in the model's register
document. That is the only reliable way to name the register and to decode the
value — the log does not carry names.
Step 6 — Decode the value yourself
Values are raw and unsigned on the wire. For example:
| Raw | Reads as | Because |
|---|---|---|
65403 |
-133 |
Two's complement over 16 bits: 65403 - 65536 |
[50] |
one register, value 50 | A multiple-register write of length 1 |
A storage register holding 65403 is the same as -133 only if the register is signed. Whether it is signed comes from the register map, not from the monitor.
What the monitor does NOT tell you
The brief for this feature asks for register names, scaled values, data types, sequence names, command results and device responses. The write log does not contain any of those, and this guide will not pretend otherwise:
| Requested field | Status | Why |
|---|---|---|
| Timestamp | Available | time, epoch |
| Source | Partial | client_ip / client_port; the protocol carries no application identity |
| Target device | Available | Derived from port |
| Manufacturer/Model | Missing | Not in the log; resolvable only by joining port → device → model |
| Protocol | Available | Implied: Modbus TCP |
| Command type | Available | fc / function |
| Register address | Available | register |
| Register name | Missing | Requires a join against the device's register map |
| Raw value | Available | value |
| Scaled value | Missing | Scaling lives in the register map |
| Data type | Missing | Same |
| Sequence name | Missing by design | A Modbus write carries no sequence identity. Correlation metadata would be needed; per the brief this must not be invented |
| Command result | Missing | The log records reception, not acceptance |
| Device response | Missing | The Modbus response is not captured |
Received vs accepted vs applied
The log proves received. It does not prove accepted or applied. To go further, read the register back afterwards and compare — see HOW_TO_READ_WRITE_SIMULATOR_REGISTERS. A write that is received but not reflected in the register is either rejected by the simulator's validation or written to a different address than you assume.
Verification
# Count entries by device port
docker exec bess-simulator-backend python3 -c "
import json, collections
c = collections.Counter()
for line in open('/app/EnergySyc_EMS_ES100Cx12S_BESS_simulator/write_commands.jsonl'):
line = line.strip()
if line:
c[json.loads(line)['port']] += 1
print(sorted(c.items()))
"
In the live stack this returns, for example:
[(1501, 15), (1502, 15), (1510, 15)]
— i.e. three PCS devices had each received 15 writes.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Monitor empty while the EMS is running | EMS is writing to real hardware ports, not the simulator | Check MODBUS_MODE / MODBUS_SIM_PORT_BASE |
| Rows appear then vanish | Log trimmed at 5 MB | Lower limit, or clear the log before each test |
| Client IP is unexpected | Another client is writing | Compare against the EMS container's address |
| Value looks wrong | Signed vs unsigned interpretation | Decide from the register map's data type |
Writes to 3415 repeatedly |
The EMS is re-asserting a setpoint each poll | Normal for a control loop; not a fault |