Skip to content

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-health does not: it answers text/plain and 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

  1. Confirm the profile is up: docker ps --format '{{.Names}}' | grep bess.
  2. Open https://bess-sim.gess-sweden.com/dashboard.
  3. Press Scan on the Dashboard to have the simulator re-read its emsConfig/ tree, then choose the active model.
  4. 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.
  5. 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.