Skip to content

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