How to Verify Command Sequences
Purpose
Prove that a model-specific multi-step command sequence actually executed correctly: right commands, right order, right values, arrived at the right device.
Prerequisites
- Simulator stack up; target device served and mapped to a port.
- The sequence exists in the EMS backend — sequences are an EMS concept, not a simulator one.
- The EMS is in simulator mode so its commands reach the simulated device.
Where sequences live
A sequence is a list of steps under a model key:
emsConfig/<category>/sequences/<prefix>_command_sequences.json
models.<MODEL>.actions.<sequence_name> = [ step, step, ... ]
PCS is the exception worth knowing about, because its sequences sit in their own directory:
emsConfig/pcs/power_sequences/<MODEL>.json # e.g. EPCS105.json
A step names an operation (read_holding, write_register, …), an address, and
for writes a value. Values may contain ${parameter} placeholders, which is how
a sequence takes runtime inputs. Full schema:
DEVICE_COMMAND_SEQUENCE_FRAMEWORK and
HOW_TO_ADD_DEVICE_COMMAND_SEQUENCE.
Honest status of the verifier
The brief this guide was written against asks for a step-by-step verification table:
| Step | Expected Command | Received Command | Result |
|---|---|---|---|
The simulator's own dashboard has no such interface. There is no sequence
editor, no sequence browser and no automatic expected-vs-received comparison in
bess-simulator-frontend; the routes that exist are the ten pages listed in the
BESS Simulator user guide, and none of them is a
sequence verifier.
The EMS does have one. /command-sequence-edit (view
commandSequenceEditor.blade.php) is a sequence editor with a Test Sequence
control. It posts to the engine at /api/v1/ems/command-sequences/test and
renders one row per step — the operation, the value written, the value read back
and a PASS/FAIL verdict — which is the table the brief asks for, produced
automatically. Prefer that page.
It also carries the safety property worth relying on: the engine refuses any target that is not recognisably a simulator, and never reads an authorisation flag from the request body, so a test run cannot reach real hardware.
What the simulator contributes to either route:
- the Write Monitor, which records every write with time, port, register and value
- register read-back, to confirm the device reached the expected state
This guide covers the manual route, which stays useful when you want the raw Modbus frames rather than a verdict.
Step-by-step procedure
Step 1 — Establish a clean baseline
- Open Write Monitor (
/monitor). - Press Clear log.
Without this, writes from the previous test are indistinguishable from this one.
Step 2 — Read the sequence definition for the device's model
Identify the device's model (see HOW_TO_CONFIGURE_SIMULATED_DEVICES), then open that model's sequence file and write down the expected steps in order: operation, address, value.
Step 3 — Run the sequence
Run it from the EMS — the alarm action path (HOW_TO_EXECUTE_SEQUENCE_FROM_ALARM) or directly:
curl -s -X POST http://ems-backend:8080/api/v1/ems/command-sequences/test \
-H 'Content-Type: application/json' \
-d '{"device_type":"pcs","action":"<sequence_name>"}'
HTTP callers can only ever run against a simulator; the endpoint refuses a non-simulator endpoint and never reads an authorisation flag from the body.
Step 4 — Read the received commands
Back on Write Monitor, read the new rows in time order. Each row gives
port, register, value and time.
Step 5 — Build the comparison table
Using the model's real definition, fill this in yourself. The rows below are an illustration of the shape only — they are not a real sequence definition:
| Step | Expected (from the model's definition) | Received (from Write Monitor) | Result |
|---|---|---|---|
| 1 | read address A |
no write expected | PASS if no write to A |
| 2 | write address B = value V |
port P, register B, value V | PASS |
| 3 | delay N s | timestamps N apart | PASS |
| 4 | write address C = value W |
port P, register C, value V | FAIL — wrong value |
Never assert these rows
Replace every address and value with the ones in the selected model's sequence file. A verification table not built from the actual definition proves nothing.
Step 6 — Verify the resulting device state
A sequence is only correct if the device ended up in the expected state. Read the relevant registers back (HOW_TO_READ_WRITE_SIMULATOR_REGISTERS) and compare against the sequence's intent.
Step 7 — Check order and timing
time is second-resolution. That is enough to see that step 2 came after step 1,
and to notice a missing delay, but not enough to measure sub-second timing.
Worked example — START BESS on PCS1
EMS -> writes -> PCS1 (port 1501)
- Clear the log.
- Note the expected steps from
emsConfig/pcs/power_sequences/<MODEL>.jsonundermodels.<MODEL>.actions.start(the name in your build). - Run it.
- Confirm each write arrived on port 1501. A write on 1502 means you are looking at PCS2.
- Read the status/active-power registers back and confirm the PCS reports running.
A repeat of the same register/value pair on every poll is normal — that is a control loop re-asserting a setpoint, not a duplicated step.
Verification
| Check | Expected |
|---|---|
| Commands arrived | One or more rows on the expected port |
| Order | Timestamps ascending, matching the definition's order |
| Values | Register and value match the definition (after ${parameter} substitution) |
| Delays | Consecutive timestamps separated by at least the configured delay |
| Device state | Read-back shows the intended state |
| No strays | No writes to addresses absent from the definition |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| No rows appeared | Sequence ran against a non-simulator endpoint, or the EMS is not in SIM mode | Re-run against the simulator; check MODBUS_MODE |
| Rows on the wrong port | Wrong device selected | Match port against the device table |
| Value differs from the definition | ${parameter} default or caller-supplied override |
Read the actual parameters passed |
| Only the first step arrived | A later step failed or timed out in the EMS | Check the EMS execution report for the failing step |
| Everything passes but the device state is wrong | Sequence is wrong, not the simulator | Fix the model's sequence file |