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:
- All 713 alarm-map files carry no
actionslist. The alarm-action executor is fully implemented but unused in production. Triggering an alarm runs nothing until actions are written. - No PCS command-sequence gap. PCS sequences exist at
emsConfig/pcs/power_sequences/<MODEL>.jsonforEPCS105,SINEXCEL_PWS1_250KandSUNGROW_SC250UD, and the engine resolves them. - All PCS
*_modbus_config.jsonfiles name the same port (1501, unit 5), and there is nobmu_modbus_config.json. Those files do not describe the live layout —start_simulator.shis the authority, and it currently opens 25 servers spread over 1501–1641 (see the network and API guide).portLabel()inPcsRegisterControllerand its copy inmonitor.blade.phpstill assume the old 1501–1512 PCS / 1513 grid / 1514 solar / 1515 frequency mapping, so the Write Monitor labels every other live port as a barePort N. - 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.
- The deny list demonstrably gates the Modbus servers. Enabling
frequency_meter1and restarting made port1515appear 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. - The restart endpoint is asynchronous, and that can swallow a write's reply.
POST /api/restart/containersanswers{"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-readdevice_enabled.jsonafter any write made near a restart rather than trusting the POST's result. - The diagnostic tests are gated on an operational mode. All 53 catalog
modes report
implemented: true, but running one while the EMS is inMANUALis refused:{"error": "payload_diagnostic_mode_required", "current_mode": "MANUAL", "required_mode": "PAYLOAD_DIAGNOSTIC_TEST"}. Switch the mode first. - The simulator hostname has a stale fallback masked by an environment
variable. 43
*_modbus_config_sim.jsonfiles (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 runsMODBUS_SIM_HOSTenv → controldevice.ip→ component configip, and the env var is set tobess-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 withCannot connect to modbus-simulator:<port>— which is exactly the failure recorded in the 2026-10-07 report, predating the current configuration. ocpp-backendforwards every OCPP action to the EMS. The central system relays each message tohttps://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 |