BESS Simulator — User Guide
The BESS Simulator is a complete reimplementation of a GESS site's field devices on a Docker network. The EMS backend talks to it over Modbus TCP exactly as it talks to real hardware, so an EMS configuration can be exercised without any physical equipment.
Purpose
Use the simulator to:
- Prove an EMS configuration end to end — device polling, alarms, alarm actions and command sequences — before touching real hardware.
- Inject faults (a register value that violates an alarm rule) and watch what the EMS does about it.
- Observe every register write the EMS sends, with raw and decoded values.
- Edit simulated device configuration without a hardware programmer.
Prerequisites
| Requirement | Detail |
|---|---|
| Compose profile | bess_simulator — none of the three simulator containers start without it |
| Containers | bess-simulator-nginx, bess-simulator-frontend, bess-simulator-backend |
| Networks | The simulator containers join both web and db |
| EMS backend | Needed only for the pages that read EMS state (Active Models, EMS Registers, Alarm maps) |
Bring the stack up from /opt/gess-stack:
cd /opt/gess-stack
docker compose -f docker-compose.maria.yml --profile bess_simulator up -d
Where the simulator lives
| Item | Value |
|---|---|
| Public URL | https://bess-sim.gess-sweden.com |
| Host-only URL | http://localhost:9698 |
| Frontend app | bess-simulator-frontend:/var/www/html (PHP-FPM on 9000) |
| Register API | http://bess-simulator-backend:8000 |
| Modbus TCP | bess-simulator-backend:1501 – :1515 |
| Database | mariadb:3306, database bess_simulator_db |
Request path for a browser hit:
browser -> traefik:443 (or nginx:9698) -> bess-simulator-nginx:80
-> bess-simulator-frontend:9000 (FastCGI)
-> bess-simulator-backend:8000 (Register API)
The full URL inventory — every endpoint, both request directions, and the Docker DNS reasoning — is in DOCKER_NETWORK_AND_API.
The dashboard pages
Every page in the top navigation bar, and what it is for:
| Page | URL | What it does |
|---|---|---|
| Dashboard | /dashboard |
Scans the simulator's emsConfig/ tree, shows the discovered devices and lets you pick the active model |
| Config Editor | / |
Browse and edit the per-device register document the simulator serves |
| Active Models | /devices/models |
The manufacturer/model inventory; pulls the device table from the EMS and applies it to the simulator |
| Write Monitor | /monitor |
Every Modbus write the simulator has received, newest first |
| EMS Modbus | /ems-modbus |
Read and write registers on the EMS's own Modbus server (ems-backend:1540) |
| EMS Registers | /ems-registers |
The merged register map the EMS Modbus server loads, flattened to one row per register |
| OCPP Charging | /ocpp |
The simulated charge points, their state, and the plug/unplug control |
| BESS Blade | /blade |
A live component view built from the BESS blade map |
| Alarms | /alarms |
Trigger and clear alarm rules on the simulated devices, and watch what is firing now |
| Alarm Thresholds | /alarms/thresholds |
Edit the numeric limits behind the alarm rules, per device |
Help and documentation
Two things give you the guides from inside the dashboard:
- A Help control in the top navigation bar. It resolves to the guide for the page
you are on, from the route name, so it is always the right page rather than a fixed
link. Ten pages carry one.
/simulator-healthdoes not: it answerstext/plainand renders no page, so there is nothing to attach a control to. - The Help & Documentation tree on the Dashboard. Every guide, grouped by task: Getting Started, Device Simulation, Alarms & Protection, Commands & Registers, Configuration, EMS Integration Testing, Reference.
The guides live in the EMS V2 MkDocs site, built from ES100CX12S/docs, so EMS and
simulator pages share one source of truth rather than a copy that drifts. The simulator
serves that site itself at /docs/<page>; a folder link redirects to its index.html,
so /docs/HOW_TO_USE_PCS_SIMULATOR and /docs/HOW_TO_USE_PCS_SIMULATOR/index.html
both work.
Two settings decide where the links point. Both read the environment, so development and production need no code change:
'base_url' => env('SIMULATOR_DOCS_BASE_URL', '/docs'),
'site_path' => env('SIMULATOR_DOCS_SITE_PATH', 'docs_build/ems-site'),
SIMULATOR_DOCS_BASE_URL— the public prefix of a guide link. Point it at another host if the guides are published elsewhere.SIMULATOR_DOCS_SITE_PATH— where the built site is read from when this front end serves it, relative to the application root.
The built site is not in git. A docs change is deployed by copying the build into
docs_build/ems-site inside the container. /var/www/html is a host bind mount
(/opt/gess-stack/bess-simulator/frontend/app), so the copy lands on the host path and
survives a container restart.
Only two paths are served from that tree, and both are checked before a file is
returned: a request outside the build folder, and a request for a page that does not
exist, both answer 404.
A folder link answers 302, not 200
/docs/HOW_TO_USE_PCS_SIMULATOR redirects to
/docs/HOW_TO_USE_PCS_SIMULATOR/index.html. A check that does not follow redirects
will report every guide as broken. Use curl -L.
Simulated devices
bess-simulator-backend runs one Modbus TCP server per device that is not in the
deny list — 25 of them at the time of writing:
| Port | Device | Register document |
|---|---|---|
1501, 1502, 1509, 1510 |
PCS1, PCS2, PCS9, PCS10 |
emsConfig/pcs/pcs<N>/pcs_register_full.json |
1513 |
Grid meter | emsConfig/grid_energy_meter/grid_meter1/gridMeter_register_full.json |
1514 |
Solar meter | emsConfig/solar_energy_meter/solar_meter1/solarMeter_register_full.json |
1520–1524 |
Door, flood, smoke, heat and temperature sensors | emsConfig/<family>/<key>/<doc>_register_full.json |
1531, 1532 |
BESS meter, FFR meter | emsConfig/bess_energy_meter/…, emsConfig/ffr_energy_meter/… |
1630–1641 |
EV Charger 1 … EV Charger 12 |
emsConfig/ev_charger/ev_charger<N>/ev_charger_register_full.json |
frequency_meter1 (1515) and bmu1 … bmu10 (1543–1552) do have ports
declared in start_simulator.sh, but they sit in the deny list, so nothing listens
there. Enumerate the live set with:
docker exec bess-simulator-backend ps -eo args | grep '[m]odbus_server'
The EMS selects between simulation and hardware with one variable pair, which is why the same logical device is expected at a different port in each mode:
MODBUS_MODE: SIM
MODBUS_SIM_HOST: bess-simulator-backend
MODBUS_SIM_PORT_BASE: 1501
MODBUS_REAL_HOST: 192.168.50.10
MODBUS_REAL_PORT_BASE: 1516
Frontend to backend
The simulator frontend holds no device state of its own. It reads and writes the
simulator through the Register API, whose base URL comes from
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),
| Method | Path | Purpose |
|---|---|---|
GET |
/health |
Liveness |
GET |
/api/models, /api/model |
Model inventory / active model |
GET |
/api/devices?model= |
Devices for a model |
GET |
/api/scan |
Whole emsConfig/ inventory |
GET |
/api/<device> |
One device's register document |
PATCH |
/api/<device> |
Replace (document) or merge (updates) registers |
GET / DELETE |
/api/write-commands |
Read / clear the write log |
<device> is a path and may contain slashes — pcs/pcs1, grid, and so on.
Do not use localhost for the backend URL
Inside the frontend container localhost is the container itself. The
backend is reached by its service name, bess-simulator-backend, because
both containers share a user-defined bridge network.
Starting sequence
- Confirm the profile is up:
docker ps --format '{{.Names}}' | grep bess. - Open
https://bess-sim.gess-sweden.com/dashboard. - Press Scan on the Dashboard to have the simulator re-read its
emsConfig/tree, then choose the active model. - Open Active Models and pull the device table from the EMS so the two sides agree on which devices exist and at which unit ids.
- Open Alarms — the page should list the site's alarm rules as discovered from the EMS settings.
Verification
| Check | How | Expected |
|---|---|---|
| Register API alive | docker exec ems-backend curl -s http://bess-simulator-backend:8000/health |
{"status":"ok"} |
| Modbus servers listening | docker exec bess-simulator-backend ps -eo args then look for modbus_server |
25 servers, ports spanning 1501–1641; the set follows the deny list |
| Devices discovered | curl -s http://bess-simulator-backend:8000/api/scan via any container |
a count and a devices list |
| Frontend can reach the API | open /dashboard and press Scan |
the device list changes without an error banner |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| nginx returns 502 | PHP-FPM bound to 127.0.0.1:9000 |
The image must sed www.conf to listen = 9000 |
| "database unreachable" | Container not attached to the db network |
Check docker inspect ... .NetworkSettings.Networks |
Public URL 404s but :9698 works |
Traefik cannot see the container | The project must be started from /opt/gess-stack so the hardcoded traefik.docker.network=gess-stack_web label matches |
| 401 on every API call | Token set on one side only | BESS_SIMULATOR_API_TOKEN must equal REGISTER_API_TOKEN |
/api/scan times out |
Large emsConfig/ tree |
Raise BESS_SIMULATOR_API_TIMEOUT above the default 10 s |
More in BESS_SIMULATOR_TROUBLESHOOTING.