Skip to content

BESS Simulator Troubleshooting

Purpose

Work out why a simulator test did not behave, in the order that actually narrows the cause: is the simulator up, is the device served, did the command arrive, was it applied.

Diagnostic order

Work down this list. Each step eliminates a whole class of cause.

  1. Is the simulator up? /simulator-health (pcs.simulator_health) in this application, and /healthz (pcs.health) for a bare liveness answer. Note that the Register API's own liveness endpoint is a different thing again: http://bess-simulator-backend:8000/health.
  2. Is the device served? The Alarms page's Devices and Triggerable tiles.
  3. Did the command arrive? Write Monitor.
  4. Was it applied? Read the register back.
  5. Did the EMS act on it? The EMS's own alarm list and logs.

Skipping to step 4 is the usual mistake; it cannot distinguish "never arrived" from "arrived and was rejected".

Communication errors

Symptom Likely cause Check
EMS reports device offline Device not served, or wrong port Device list; the live server list from docker exec bess-simulator-backend ps -eo args. Ports span 1501–1641 and follow the deny list
Simulator unreachable Container down or still starting /simulator-health
Write Monitor empty EMS pointed at hardware MODBUS_MODE, sim port base
Writes on the wrong port Wrong device selected The port column, not the device name
Client IP unexpected Another client is writing Compare with the EMS container's address
Register map load stuck Large archive (120 s budget) Wait before retrying

Incorrect register values

Symptom Likely cause Fix
Value looks absurd (e.g. 65403) Unsigned read of a signed value Decode against the register's type — 65403 is -133
Unrelated registers vanished document sent instead of updates Restore from backup; resend as a merge
Value rejected on save Outside the register's permitted range or wrong type Re-read the row, correct the type
Edited value but Modbus unchanged Simulator not reloaded Restart, then re-read

Missing EMS commands

Symptom Likely cause
Alarm fired, no commands The alarm has no actions list. In the live configuration all 713 alarm-map files have none — this is the normal state, not a fault
Commands only partly arrived failure_action: abort and a later step failed
Sequence not found Wrong model, or the action is absent from that model's file
Nothing at all EMS not in simulator mode
OCPP commands "missing" They are not Modbus and never appear in the Write Monitor

Failed command sequences

Symptom Likely cause
Order wrong mode is parallel where sequential was intended
Values wrong ${parameter} default, or a caller override you did not expect
A step never ran Delay/timeout/retry on the preceding action
Sequence ran, device state wrong The sequence definition is wrong, not the simulator
Validation rejects a field Mixing the alarm-action vocabulary (abort/skip/retry/recovery_sequence) with the PCS step vocabulary (on_failure: abort/continue)

Where the data lives

Question Source
What did the EMS write? write_commands.jsonl → Write Monitor
What does the device hold now? Config Editor read-back, or a Modbus read
What alarms exist? GET /api/v1/ems/alarms/definitions
What is firing? GET /api/v1/ems/alarms
What does the EMS hold? EMS Registers, EMS Modbus pages
Are the OCPP sessions alive? The OCPP page

Simulator debugging

Read the write log directly

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()))
"

An empty result with the EMS running means the EMS is not writing to the simulator.

Prove the whole path in four steps

  1. Clear the log (POST /monitor/clear).
  2. Trigger the action.
  3. Read the log — did rows appear, on the right port, with the right values?
  4. Read the register back — does it hold the value?

Only step 3 succeeding and step 4 failing is a genuine "received but not applied".

Known gaps — do not chase these as bugs

Gap Effect
No search box on the Alarms page Browse by device section
No sequence verifier in the simulator dashboard Use the EMS command-sequence editor's Test Sequence, which returns a per-step PASS/FAIL record
All ten BMUs sit in the deny list No BMU port is listening; enable one on Active Models and restart the simulator
A device reported enabled that no port serves The flag only means "absent from the deny list"; match the register path named after --json in SCRIPTS
Frequency meter missing from the device enumeration Its alarms may not be listed
Stale *_modbus_config.json Every PCS names port 1501; ignore these for the port map
Alarm maps carry no actions Triggering runs nothing until actions are written

Escalation checklist

Before reporting a fault, collect: the simulator health response, the device list count, the write-log excerpt around the failure, the register read-back, and the alarm's action list. Those five answer almost every question.