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.
- 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. - Is the device served? The Alarms page's Devices and Triggerable tiles.
- Did the command arrive? Write Monitor.
- Was it applied? Read the register back.
- 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
- Clear the log (
POST /monitor/clear). - Trigger the action.
- Read the log — did rows appear, on the right port, with the right values?
- 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.