How to Configure Simulated Devices
Purpose
Give the simulator a device inventory and hand each simulated device the register document it serves over Modbus. Everything the EMS reads from a simulated device comes out of that document, so configuring the simulator correctly is what makes EMS testing meaningful.
Prerequisites
- The
bess_simulatorcompose profile is up (nginx,frontend,backend). - The simulator's
emsConfig/tree is populated. The backend reads it, the frontend never invents it. - For the EMS-sourced steps:
ems-backendreachable at the URL configured inconfig/bess_simulator.php.
How a device is identified
A simulator device is addressed by a path, not a single name:
<device_type>/<device_key> e.g. pcs/pcs1
The device's register document lives at:
emsConfig/<device_dir>/<device_key>/<key>_register_full.json
| Device family | Live ports | Document |
|---|---|---|
pcs |
1501, 1502, 1509, 1510 | pcs_register_full.json |
grid_energy_meter |
1513 | gridMeter_register_full.json |
solar_energy_meter |
1514 | solarMeter_register_full.json |
ev_charger |
1630–1641 | ev_charger_register_full.json |
bess_energy_meter, ffr_energy_meter |
1531, 1532 | bess_energy_meter_register_full.json, ffrMeter_register_full.json |
| door / flood / smoke / heat / temperature sensors | 1520–1524 | <family>_register_full.json |
frequency_meter |
1515 declared, in the deny list, not listening | frequencyMeter_register_full.json |
Only four of the twelve PCS, and one each of the twelve grid and solar meters, are
served. Never read a port number as a device index: start_simulator.sh assigns
the ports and serves only the devices that are not in the deny list — 25 servers
across 1501–1641 at the time of writing. Enumerate the live set with:
docker exec bess-simulator-backend ps -eo args | grep '[m]odbus_server'
Step-by-step procedure
Step 1 — Scan the configuration tree
- Open Dashboard (
/dashboard). - Press Scan. This posts to
pcs.scan(POST /dashboard/scan), and the backend re-reads itsemsConfig/tree. - The discovered devices appear as a list. If the list is empty, the tree is empty or unreadable — see BESS_SIMULATOR_TROUBLESHOOTING.
Step 2 — Choose the active model
- Still on Dashboard, pick the model in the model selector.
- This posts to
pcs.model.select(POST /dashboard/model) and is the model the simulator reports for the devices it serves.
Step 3 — Reconcile with the EMS device table
The EMS and the simulator must agree on which devices exist and at which unit id.
- Open Active Models (
/devices/models). - Pull the device table from the EMS. If the response is empty the EMS side is
the problem, not the simulator — check
ems.modbusreachability first. - Apply the model/devices to the simulator. The selection is saved through
POST /devices/models. - Reload the page; the saved model should be preselected.
Step 4 — Edit one device's registers
- Open Config Editor (
/). It lists the devices fromGET /api/scan. - Choose a device — the page fetches
GET /api/<device>. - Edit the register rows and save. Saving posts to
POST /devices/{device}/update. - The update reaches the backend as
PATCH /api/<device>with anupdatesmap, so unrelated registers in the document are preserved. Sendingdocumentinstead replaces the whole document.
Step 5 — Confirm the simulator is serving the change
Read the register back over Modbus (see HOW_TO_READ_WRITE_SIMULATOR_REGISTERS). A change that is saved but not served means the Modbus server was not reloaded.
Configuration reference
config/bess_simulator.php:
'backend_url' => env('BESS_SIMULATOR_BACKEND_URL', 'http://bess-simulator-backend:8000'),
'api_token' => env('BESS_SIMULATOR_API_TOKEN', ''),
'timeout' => env('BESS_SIMULATOR_API_TIMEOUT', 10),
Backend-side, the Register API's own token is REGISTER_API_TOKEN. If one side
sets it and the other does not, every call returns 401.
Expected behaviour
| Action | Expected |
|---|---|
| Scan | A non-empty device list, matching emsConfig/ |
| Model select | The choice survives a page reload |
| Save registers | 200 from the update route; the new value is readable over Modbus |
| Apply EMS devices | Simulator device list matches the EMS device table |
EMS integration
The simulator does not push anything to the EMS. The EMS polls the simulated
Modbus servers on its own schedule, using the ports in MODBUS_SIM_PORT_BASE.
Changing a simulated register changes what the next EMS poll reads — nothing more.
Verification
# Devices the backend discovered
docker exec bess-simulator-backend curl -s http://127.0.0.1:8000/api/scan
# One device's document
docker exec bess-simulator-backend curl -s http://127.0.0.1:8000/api/pcs/pcs1
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Scan returns nothing | emsConfig/ not mounted into the backend |
Check the compose volume for /app/emsConfig |
| Save has no effect on Modbus | Modbus server not reloaded from the document | Restart the backend, or use the sync tool |
| 422 on save | A register failed type/range validation | Read the field names in the response |
| Unrelated registers lost | Caller sent document instead of updates |
Send updates |