How to Test the EMS with the Simulator
Purpose
Use the simulator as the target for EMS functional testing: prove the EMS talks to its devices, polls them, applies operational modes, detects alarms, and handles communication failure — without touching real equipment.
Prerequisites
- Simulator stack up and serving the devices under test.
ems-backendrunning and configured for the simulator.- The alarm maps and sequences you intend to exercise already exist.
The two test categories — keep them apart
The EMS has two distinct kinds of test, and the brief for this work requires that they stay separate. Mixing them makes results meaningless.
| SELF TEST | PAYLOAD DIAGNOSTIC TEST | |
|---|---|---|
| Question it answers | Does the EMS itself work? | Does the equipment perform as specified? |
| Subject | EMS functionality | BESS / EV charging equipment characteristics |
| Covers | Device communication, polling, operational modes, alarms, system health | Operational and performance characteristics of the plant |
| Simulator's role | A well-behaved target that answers predictably | A target whose performance is being characterised |
| Typical failure found | A comms or configuration fault | A performance shortfall |
A fault found by SELF TEST is an EMS or wiring problem. A finding from a PAYLOAD DIAGNOSTIC TEST is a statement about equipment. Do not report one as the other.
SELF TEST scenarios the simulator supports
Device communication
- Confirm the simulated devices are served — the Alarms page's Devices and Triggerable tiles are a quick check.
- Start the EMS and let it poll. Polling is configured per device
(
poll_interval_ms, commonly 3000 ms) and values are saved everysave_interval_ms. - Watch the EMS report a connected state for each device.
Polling and value updates
Drive a value in the simulator and confirm the EMS's view changes within a poll interval. Use the Config Editor to write the value and read it back, then compare with the EMS.
Operational mode selection
Change the EMS's operation mode and confirm its commands change accordingly — the commands appear in the Write Monitor on the correct port.
Operation mode also gates clearance actions
The mode is not cosmetic: a clearance action only runs if the operation mode is in that action's allowed set. See HOW_TO_TEST_EMS_ALARM_ACTIONS.
Alarm detection
Trigger an alarm from the Alarms page and confirm the EMS raises it with the right code and severity, and records it.
Alarm-triggered command sequences and protection
The full end-to-end path is its own guide: HOW_TO_TEST_EMS_ALARM_ACTIONS.
Frequency regulation and peak shaving
Drive the frequency or load values at the meter, then read the EMS's commands from the Write Monitor. Verify direction and magnitude at each step.
Dynamic load balancing
With an EV session running, reduce the available power and confirm the EMS issues the limiting command and the charger's power follows. Remember: the charger's response is OCPP and will not appear in the Write Monitor, but the EMS's Modbus action elsewhere will.
System health
/simulator-health (pcs.simulator_health) and /healthz (pcs.health) report
whether the simulator front end is up. The Register API has its own liveness
endpoint, http://bess-simulator-backend:8000/health, which is a different check —
use both before blaming the EMS for a comms failure.
Communication failure handling
Two mechanisms exist, and they are not equivalent.
Failing one device only — the deny list
Each simulated Modbus server is one entry in the SCRIPTS array of
start_simulator.sh. The dashboard's Active Models page writes a deny list to
emsConfig/device_enabled.json, and the start script skips every SCRIPTS entry
whose register path appears in it. A skipped entry means that device's port is
never opened, so the EMS sees that device — and only that device — stop answering.
- Confirm the device's register path in
SCRIPTS(the value after--json). The deny list matches on that path, so a path no entry serves will do nothing. - On Active Models (
/devices/models), uncheck the device and save. This posts toPOST /api/device-enabledand persists the deny list. - Restart the simulator so the start script re-reads the list.
- Watch the EMS: how long until it reports the fault, what it reports, and what protection it applies.
- Restore: re-check the device on Active Models and restart again.
Verified on the test host: the write path works end to end. Disabling a device
added its path to device_enabled.json and the device immediately reported as
disabled; restoring the original list returned the file byte-for-byte to its
previous contents. The port itself only disappears at the next start, which is
why step 3 is not optional.
Two things to know:
enabledon that page does not mean "has a running server". It only means the file is absent from the deny list. Match on the register path.- Three
SCRIPTSentries can never be switched off:SOC dynamics, the Register API and the OCPP client. The OCPP client is exempt on purpose — "the charger is the point of the simulation". To fail OCPP, break connectivity to the OCPP server instead.
Failing everything at once
Stopping the simulator container (POST /system/restart-simulator brings it back)
takes every device it serves off the air at once. Use it for a plant-wide outage,
not for isolating one device.
A register-driven fault is not a transport failure
A "communication fault" alarm in an alarm map is register-driven: it fires when a register holds a fault value, which the EMS may or may not treat identically to a genuine transport failure. Test both, and do not assume they are the same path.
PAYLOAD DIAGNOSTIC TEST
The EMS ships a real diagnostic harness: run_diagnostic_test.sh drives the
catalog and reports behind /api/v1/ems/diagnostic-tests. All 53 modes in the
catalog report implemented: true.
Two preconditions have to hold before a run means anything:
- The EMS must be in
PAYLOAD_DIAGNOSTIC_TESTmode. FromMANUALthe run is refused outright withpayload_diagnostic_mode_required/current_mode: MANUAL/required_mode: PAYLOAD_DIAGNOSTIC_TEST. - The simulator host must resolve. Host resolution runs
MODBUS_SIM_HOSTenv → controldevice.ip→ component configip. The variable is set on the test host, so tests connect, but 43*_modbus_config_sim.jsonfiles carry a stale fallback ("ip": "modbus-simulator") that does not resolve on the stack network. If the variable is ever unset, every test fails withCannot connect to modbus-simulator:<port>— which is the failure recorded in the 2026-10-07 report. Confirm the host resolves before blaming the test:
docker exec ems-backend getent hosts bess-simulator-backend
Running one
docker exec ems-backend sh -c 'cd /app/EnergySyc_EMS_ES100Cx12S && ./run_diagnostic_test.sh --list'
docker exec ems-backend sh -c 'cd /app/EnergySyc_EMS_ES100Cx12S && ./run_diagnostic_test.sh 1'
docker exec ems-backend sh -c 'cd /app/EnergySyc_EMS_ES100Cx12S && ./run_diagnostic_test.sh --report'
The XML report names the device, host, port and unit id it used, so a failed run points straight at whichever precondition broke.
What a simulated run does not tell you
The simulator supplies a target and records what arrives. What it does not provide is a performance model — it serves the values you write, it does not simulate equipment dynamics, ramp rates, efficiencies or thermal behaviour. A payload diagnostic test run against the simulator therefore characterises the EMS's test procedure, not the plant.
Be explicit about that in any report: results from a simulated run are not equipment performance data.
Verification
| Check | Expected |
|---|---|
| Communication | EMS reports every served device connected |
| Polling | A written value appears on the EMS side within one interval |
| Operational mode | EMS commands change with the mode |
| Alarm detection | Correct code and severity, recorded |
| Sequence execution | Commands in the Write Monitor, correct port and order |
| Comms fault | EMS reports it; recovery after restore |
| Categories | SELF TEST and PAYLOAD DIAGNOSTIC TEST reported separately |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| EMS reports a device offline | Device not served, or wrong port | Check it appears in the simulator's device list |
| Value written but EMS unchanged | EMS polls another device for that quantity | Find the polled device |
| Simulator looks down | Container stopped or still starting | /simulator-health; restart polls for up to 240 s |
| Commands never arrive | EMS configured for hardware | Check MODBUS_MODE and the sim port base |
| Test results look like equipment data | A simulated run reported as a payload test | Separate the categories |