Skip to content

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

  1. Config Editor → the BMU device → the SOC register.
  2. Write a value. Low SOC drives the low-SOC alarm; the simulator's permitted range is enforced on save.
  3. 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 enabled flag does not mean "has a running server". It only means the file is absent from the deny list. bmu/bmu_register_1.json reports as enabled, for instance, while no SCRIPTS entry serves that file at all. Match on the register path: the path a port serves is the one named after --json in SCRIPTS.
  • 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