How to Use the BMS Simulator
Purpose
Simulate battery measurements — state of charge, voltage, current, temperature — and the alarm conditions that follow from them, so the EMS's BMS handling and battery protection can be exercised.
Prerequisites
- Simulator stack up.
- The BMU devices exist in
emsConfig/bmu/.
What the simulator actually serves
The BMU units are configured as bmu1 … bmu10, each with its own register
document:
emsConfig/bmu/bmu<N>/bmu_register_full.json
They are visible and editable in the Config Editor (/) — that is the
supported way to drive BMS values.
The most important limitation: there is no BMS Modbus port
The simulator exposes 25 Modbus TCP servers, spread over 1501–1641:
| Ports | Devices |
|---|---|
| 1501, 1502, 1509, 1510 | PCS1, PCS2, PCS9, PCS10 |
| 1513 | Grid Meter |
| 1514 | Solar Meter |
| 1520–1524 | Door, flood, smoke, heat and temperature sensors |
| 1531, 1532 | BESS Meter, FFR Meter |
| 1630–1641 | EV Charger 1 … EV Charger 12 |
frequency_meter1 (1515) and bmu1 … bmu10 (1543–1552) do have ports declared
in start_simulator.sh, but every one of them sits in the device deny list, so no
server listens on those ports.
No BMU server is listening today. There is no bmu_modbus_config.json in
emsConfig/bmu/, and no BMU range in portLabel(). So:
- You can edit BMU registers and see them in the Config Editor.
- You cannot currently receive an EMS write at a BMU over Modbus, because there is nowhere for it to arrive.
- A BMS value reaches the EMS through another device's report (a PCS typically reports its battery, or the BESS energy meter), not through a BMU connection of its own.
Before writing a test that depends on the EMS writing to a BMU, confirm which device actually carries that data in your configuration. Treating the BMU as independently addressable will produce a test that cannot pass.
Simulating battery measurements
State of charge
- Config Editor → the BMU device → the SOC register.
- Write a value. Low SOC drives the low-SOC alarm; the simulator's permitted range is enforced on save.
- Read back to confirm, then check the EMS's view — the EMS polls a specific device, so a change only shows up where it reads from.
Voltage and current
Same procedure against the voltage and current registers. Watch the sign convention: charge and discharge current typically differ by sign, and raw Modbus values are unsigned — 65403 is -133.
Temperature
Write the temperature register. For an overtemperature alarm, prefer the Alarms page, which writes a value known to satisfy the rule rather than a temperature you have to guess.
Charge and discharge limits
Set the limit registers through the Config Editor. These exist as served values; the simulator does not enforce them against the power flow — it serves what you write and lets the EMS decide.
Diagnosing via the register report
The frontend's register view for a unit is built from that unit's register file
plus its model variant, and it is expensive enough to have its own timeout
(blade_register_timeout, 20 s) and a short cache (8 s). If a unit's registers
fail to load while others load fine, that unit's file is the thing to inspect,
not the network.
Functions the brief asks for that are NOT implemented
| Requested | Status |
|---|---|
| BMS alarms beyond the configured map | Only alarms present in the alarm map can be triggered |
BMS communication failure
Each BMU has its own entry in the SCRIPTS array of start_simulator.sh, with
its own register file and port:
| BMU | Port | Register file |
|---|---|---|
bmu1–bmu10 |
1543–1552 |
emsConfig/bmu/bmuN/bmu_register_full.json |
Unchecking a device on Active Models adds its register path to the deny list
at emsConfig/device_enabled.json, and start_simulator.sh skips the matching
SCRIPTS entry at the next start. That is a genuine per-device communication
failure — the BMU simply stops listening.
In the current test deployment all ten entries are already in the deny list, so no BMU port is listening. That is why BMU values are editable through the config editor and readable through the Register API, but are not addressable over Modbus.
Two things to know before relying on this:
- The
enabledflag does not mean "has a running server". It only means the file is absent from the deny list.bmu/bmu_register_1.jsonreports as enabled, for instance, while noSCRIPTSentry serves that file at all. Match on the register path: the path a port serves is the one named after--jsoninSCRIPTS. - The setting takes effect at the next simulator start, not immediately.
Independent BMU Modbus addressing
Available for a BMU that is not in the deny list — bmu1–bmu10 are declared on
ports 1543–1552. Enable one on Active Models and restart the simulator.
See HOW_TO_TEST_EMS_WITH_SIMULATOR for the full fail-and-restore procedure.
Verification
| Check | Expected |
|---|---|
| SOC edit | Read-back shows the new value in the Config Editor |
| Alarm trigger | Rule's watched register holds a violating value |
| EMS detected | Alarm appears the EMS side |
| EMS polled it | The value appears on whichever device the EMS actually polls |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Edited a BMU, EMS saw nothing | The EMS does not poll BMUs directly | Find the device that carries battery data and edit that |
| No BMU port to write to | All ten BMUs are in the deny list, so no BMU server is started | Enable the BMU on Active Models and restart the simulator, then write to its port (1543–1552) |
| Low-SOC alarm will not fire | Triggered on a device the EMS does not poll | Trigger on the polled device |
| Value rejected on save | Outside the register's permitted range | Re-read the row and correct the type |