Skip to content

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_simulator compose 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-backend reachable at the URL configured in config/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

  1. Open Dashboard (/dashboard).
  2. Press Scan. This posts to pcs.scan (POST /dashboard/scan), and the backend re-reads its emsConfig/ tree.
  3. 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

  1. Still on Dashboard, pick the model in the model selector.
  2. 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.

  1. Open Active Models (/devices/models).
  2. Pull the device table from the EMS. If the response is empty the EMS side is the problem, not the simulator — check ems.modbus reachability first.
  3. Apply the model/devices to the simulator. The selection is saved through POST /devices/models.
  4. Reload the page; the saved model should be preselected.

Step 4 — Edit one device's registers

  1. Open Config Editor (/). It lists the devices from GET /api/scan.
  2. Choose a device — the page fetches GET /api/<device>.
  3. Edit the register rows and save. Saving posts to POST /devices/{device}/update.
  4. The update reaches the backend as PATCH /api/<device> with an updates map, so unrelated registers in the document are preserved. Sending document instead 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