Skip to content

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

  1. Open Write Monitor (/monitor).
  2. 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)
  1. Clear the log.
  2. Note the expected steps from emsConfig/pcs/power_sequences/<MODEL>.json under models.<MODEL>.actions.start (the name in your build).
  3. Run it.
  4. Confirm each write arrived on port 1501. A write on 1502 means you are looking at PCS2.
  5. 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