Skip to content

BESS Simulator Documentation Coverage Matrix

Purpose

Every simulator function, where it lives, what documents it, and whether it actually works. This is the honest inventory: where the brief asked for something that does not exist, it says so rather than pointing at a guide that describes an imagined feature.

Dashboard pages and their real routes

Verified from routes/web.php in bess-simulator-frontend.

Page URL Route name Controller
Write Monitor /monitor pcs.monitor PcsRegisterController
Home / Config Editor / pcs.index PcsRegisterController
Dashboard /dashboard pcs.dashboard PcsRegisterController
Active Models /devices/models pcs.device_models PcsRegisterController
EMS Modbus /ems-modbus ems.modbus EmsModbusController
EMS Registers /ems-registers ems.registers EmsRegisterController
OCPP Charging /ocpp ocpp.charging OcppChargingController
BESS Blade /blade pcs.blade BessBladeController
Alarms /alarms alarms.index AlarmController
Alarm Thresholds /alarms/thresholds alarms.thresholds AlarmController

Ten pages. There is no Help page among them — the centralized Help section is described below and is reached from the dashboard.

Documentation inventory

File Location Covers
BESS_SIMULATOR_USER_GUIDE ES100CX12S/docs Umbrella guide: pages, ports, data sources, workflows
BESS_SIMULATOR_DOCKER_NETWORK_AND_API ES100CX12S/docs (mirrored) Networks, ports, register API
HOW_TO_CONFIGURE_SIMULATED_DEVICES ES100CX12S/docs Device and model selection
HOW_TO_TRIGGER_SIMULATOR_ALARM ES100CX12S/docs Triggering and clearing alarms
HOW_TO_MONITOR_EMS_COMMANDS ES100CX12S/docs The Write Monitor and its limits
HOW_TO_VERIFY_COMMAND_SEQUENCES ES100CX12S/docs Verifying multi-step sequences
HOW_TO_EDIT_SIMULATOR_CONFIG ES100CX12S/docs Every editor and the save path
HOW_TO_READ_WRITE_SIMULATOR_REGISTERS ES100CX12S/docs The three distinct write paths
HOW_TO_TEST_EMS_ALARM_ACTIONS ES100CX12S/docs Alarm → EMS → sequence → reset
HOW_TO_USE_PCS_SIMULATOR ES100CX12S/docs PCS simulation
HOW_TO_USE_BMS_SIMULATOR ES100CX12S/docs BMS simulation and its port limitation
HOW_TO_USE_EV_CHARGER_SIMULATOR ES100CX12S/docs OCPP charge point
HOW_TO_SIMULATE_GRID_CONDITIONS ES100CX12S/docs Voltage, frequency, power
HOW_TO_TEST_EMS_WITH_SIMULATOR ES100CX12S/docs SELF TEST vs PAYLOAD DIAGNOSTIC TEST
BESS_SIMULATOR_TROUBLESHOOTING ES100CX12S/docs Diagnosis by elimination

Shared EMS guides linked rather than duplicated: HOW_TO_ADD_NEW_ALARM, HOW_TO_EDIT_ALARM_THRESHOLDS, HOW_TO_ADD_ALARM_ACTION, HOW_TO_ADD_DEVICE_COMMAND_SEQUENCE, HOW_TO_EXECUTE_SEQUENCE_FROM_ALARM, HOW_TO_TEST_DEVICE_COMMAND_SEQUENCE, DEVICE_COMMAND_SEQUENCE_FRAMEWORK, EMS_PROTECTION_FRAMEWORK.

Coverage matrix

# Function Frontend view Backend handler Documentation Help link Implemented Documented Verified
1 PCS simulation Home / Config Editor, Write Monitor Register API GET /api/<device>; Modbus servers on 1501, 1502, 1509, 1510 HOW_TO_USE_PCS_SIMULATOR /docs/HOW_TO_USE_PCS_SIMULATOR/ Partial Complete Tested
2 BMS simulation Home / Config Editor Register API; BMU Modbus servers declared on 1543–1552 (all ten sit in the deny list, so none is listening) HOW_TO_USE_BMS_SIMULATOR /docs/HOW_TO_USE_BMS_SIMULATOR/ Partial Complete Tested
3 Grid meter simulation Home / Config Editor Modbus 1513 HOW_TO_SIMULATE_GRID_CONDITIONS /docs/HOW_TO_SIMULATE_GRID_CONDITIONS/ Implemented Complete Tested
4 Solar meter simulation Home / Config Editor Modbus 1514 HOW_TO_SIMULATE_GRID_CONDITIONS same Implemented Complete Tested
5 Frequency meter simulation Home / Config Editor Modbus 1515 is declared, but frequency_meter1 sits in the deny list so it is not listening; it is also absent from the device enumeration HOW_TO_SIMULATE_GRID_CONDITIONS same Partial Complete Tested
6 EV charging pile simulation OCPP Charging GET/POST /api/ocpp/charging HOW_TO_USE_EV_CHARGER_SIMULATOR /docs/HOW_TO_USE_EV_CHARGER_SIMULATOR/ Implemented Complete Tested
7 Modbus TCP communication Write Monitor 25 servers running, spread over 1501–1641; the set follows the deny list HOW_TO_MONITOR_EMS_COMMANDS /docs/HOW_TO_MONITOR_EMS_COMMANDS/ Implemented Complete Tested
8 OCPP 1.6J (2.0.1 not deployed) OCPP Charging ocpp-backend central system at ws://ocpp-backend:9000/ocpp/<cp>; client starts with the simulator HOW_TO_USE_EV_CHARGER_SIMULATOR same Partial Complete Tested
9 Device register reading/writing Home, EMS Modbus Register API; PATCH /api/<device> HOW_TO_READ_WRITE_SIMULATOR_REGISTERS /docs/HOW_TO_READ_WRITE_SIMULATOR_REGISTERS/ Implemented Complete Tested
10 Register value editing Home / Config Editor POST /devices/{device}/update HOW_TO_READ_WRITE_SIMULATOR_REGISTERS same Implemented Complete Tested
11 Alarm generation / clearance Alarms, Alarm Thresholds POST /alarms/trigger, /alarms/reset, /alarms/reset-active HOW_TO_TRIGGER_SIMULATOR_ALARM /docs/HOW_TO_TRIGGER_SIMULATOR_ALARM/ Implemented Complete Tested
12 Command sequence execution EMS sequence editor (/command-sequence-edit) CommandSequencesController; engine behind /api/v1/ems/command-sequences/test, executor in alarm_actions.py HOW_TO_VERIFY_COMMAND_SEQUENCES /docs/HOW_TO_VERIFY_COMMAND_SEQUENCES/ Implemented Complete Tested
13 EMS command monitoring Write Monitor GET /monitor/data, DELETE /api/write-commands HOW_TO_MONITOR_EMS_COMMANDS /docs/HOW_TO_MONITOR_EMS_COMMANDS/ Implemented Complete Tested
14 Device configuration editing Home, Active Models GET/POST /devices/models, pull-ems, apply-ems-devices HOW_TO_EDIT_SIMULATOR_CONFIG /docs/HOW_TO_EDIT_SIMULATOR_CONFIG/ Implemented Complete Tested
15 Alarm / register map editing Alarm Thresholds, EMS Registers POST /alarms/thresholds/device, POST /ems-registers/pull HOW_TO_EDIT_SIMULATOR_CONFIG, HOW_TO_EDIT_ALARM_THRESHOLDS both Implemented Complete Tested
16 Frequency/voltage/current/power simulation Home / Config Editor Register API + Modbus HOW_TO_SIMULATE_GRID_CONDITIONS same Implemented Complete Tested
17 Grid-forming / grid-following PCS simulator (driven from the EMS test API) PCS sequences mode_pq / mode_vf, both writing mode register 0x5066 (20582) HOW_TO_USE_PCS_SIMULATOR /docs/HOW_TO_USE_PCS_SIMULATOR/ Implemented Complete Tested
18 Communication failure simulation Active Models (per-device enable checkbox) POST /api/device-enabled writes emsConfig/device_enabled.json; start_simulator.sh skips those SCRIPTS entries HOW_TO_TEST_EMS_WITH_SIMULATOR /docs/HOW_TO_TEST_EMS_WITH_SIMULATOR/ Implemented Complete Tested (write path; the port going away needs a restart)
19 EMS operational mode testing EMS frontend ems-backend HOW_TO_TEST_EMS_WITH_SIMULATOR /docs/HOW_TO_TEST_EMS_WITH_SIMULATOR/ Implemented Complete Tested
20 BESS / EV diagnostic testing Alarms, OCPP ems_diagnostic_handlers.py and run_diagnostic_test.sh; 53-mode catalog plus XML reports behind /api/v1/ems/diagnostic-tests HOW_TO_TEST_EMS_WITH_SIMULATOR same Partial Complete Tested
21 Real-time monitoring and debugging Write Monitor, Simulator Health, BESS Blade /monitor/data, /simulator-health, /blade/data HOW_TO_MONITOR_EMS_COMMANDS, BESS_SIMULATOR_TROUBLESHOOTING both Implemented Complete Tested
22 Context-sensitive Help Nav Help control (10 pages) config('simulator_docs.pages') keyed by route name BESS_SIMULATOR_USER_GUIDE per-page, e.g. /docs/HOW_TO_USE_PCS_SIMULATOR/ Implemented Complete Tested
23 Documentation served in-app Dashboard Help tree, nav Help control GET /docs/{path?} (simulator.docs) BESS_SIMULATOR_USER_GUIDE /docs/ Implemented Complete Tested

Requested fields the monitor cannot supply

The brief asks the command monitor to show these. They are not in the write log, and no documentation pretends otherwise:

Field Status
Timestamp, source, target device, protocol, command type, register address, raw value Available
Manufacturer/model Join required (port → device → model)
Register name, scaled value, data type Join required against the register map
Sequence name Not available by design — a Modbus write carries no sequence identity
Command result Not recorded (reception only)
Device response Not recorded

Notable live findings

These were observed on the deployed system and are the reason several rows above say Partial:

  1. All 713 alarm-map files carry no actions list. The alarm-action executor is fully implemented but unused in production. Triggering an alarm runs nothing until actions are written.
  2. No PCS command-sequence gap. PCS sequences exist at emsConfig/pcs/power_sequences/<MODEL>.json for EPCS105, SINEXCEL_PWS1_250K and SUNGROW_SC250UD, and the engine resolves them.
  3. All PCS *_modbus_config.json files name the same port (1501, unit 5), and there is no bmu_modbus_config.json. Those files do not describe the live layout — start_simulator.sh is the authority, and it currently opens 25 servers spread over 1501–1641 (see the network and API guide). portLabel() in PcsRegisterController and its copy in monitor.blade.php still assume the old 1501–1512 PCS / 1513 grid / 1514 solar / 1515 frequency mapping, so the Write Monitor labels every other live port as a bare Port N.
  4. The frequency meter's alarm map is readable but the meter is absent from the 103-device enumeration the alarm reader uses — a real inconsistency between the map reader and the device enumerator.
  5. The deny list demonstrably gates the Modbus servers. Enabling frequency_meter1 and restarting made port 1515 appear and answer Modbus (83 02, a Modbus exception reply — the point is that the server answered at all); restoring the entry and restarting removed it again. Both directions observed over real restarts, ending with the deny list back at its 51 entries and 25 servers running.
  6. The restart endpoint is asynchronous, and that can swallow a write's reply. POST /api/restart/containers answers {"status": "restart_scheduled", "delay_seconds": 2.0} and returns before the container cycles, so a readiness probe immediately afterwards succeeds against the very container that is about to go down. A write issued inside that window can be answered by a process killed mid-request: the reply is lost, and the empty response does not tell the caller whether the write landed. Re-read device_enabled.json after any write made near a restart rather than trusting the POST's result.
  7. The diagnostic tests are gated on an operational mode. All 53 catalog modes report implemented: true, but running one while the EMS is in MANUAL is refused: {"error": "payload_diagnostic_mode_required", "current_mode": "MANUAL", "required_mode": "PAYLOAD_DIAGNOSTIC_TEST"}. Switch the mode first.
  8. The simulator hostname has a stale fallback masked by an environment variable. 43 *_modbus_config_sim.json files (275 occurrences across PCS, grid meter, solar meter, EMS and frequency meter) name "ip": "modbus-simulator", which does not resolve on the stack network. Host resolution runs MODBUS_SIM_HOST env → control device.ip → component config ip, and the env var is set to bess-simulator-backend, so the fallback is never consulted and diagnostic connections succeed today. Unset the variable, or wire a device that bypasses it, and each connection fails with Cannot connect to modbus-simulator:<port> — which is exactly the failure recorded in the 2026-10-07 report, predating the current configuration.
  9. ocpp-backend forwards every OCPP action to the EMS. The central system relays each message to https://gessgo.gess-sweden.com/api/v1/ocpp/<Action>, so an OCPP failure surfaces on the EMS side as those forwards stopping rather than as a simulator-side error.

Verification status legend

Value Meaning
Tested The behaviour was exercised and observed
Not tested Documented from code and configuration, but not exercised end to end
Missing The function does not exist in the codebase
Partial The function exists with an important limitation, stated in its guide