Skip to content

How to Edit Simulator Configuration

Purpose

Change what the simulator serves and how it behaves: device documents, model assignments, register maps, alarm limits and the runtime itself.

Prerequisites

  • Simulator stack up.
  • Access to the simulator dashboard.

What lives where

Page Route Edits
Config Editor / A device's register document
Dashboard /dashboard Device scan, model selection, register-map load
Active Models /devices/models Model assignment per device
Alarm Thresholds /alarms/thresholds Numeric limits in the alarm map
EMS Registers /ems-registers The EMS's merged register map

Back up before you load

Load register maps fetches an archive from ems-backend and writes it over emsConfig. That overwrites existing device documents. Take a backup first — see the last section.

Device documents — Config Editor

  1. Open Config Editor (/) and pick a device. The page calls GET /api/<device>.
  2. Edit register values in the rows.
  3. Save. This posts to pcs.update (POST /devices/{device}/update), which the controller forwards as PATCH /api/<device>.

Send updates (a merge) rather than document (a replacement) unless you mean to replace the whole document. document discards every key you did not send — the usual cause of "all my other registers vanished".

Validate before you save

The simulator only accepts values its register definition permits. If a save is rejected, the value violates the address's type or an allowed range; re-read the row and correct the type rather than retrying the same value.

Model assignment — Active Models and Dashboard

Devices are served according to their assigned manufacturer/model, because the model decides which register and alarm files apply.

Dashboard

  1. Scan (pcs.scan, POST /dashboard/scan) — discover devices in the configuration.
  2. Select model (pcs.model.select, POST /dashboard/model) — set the model for a device.
  3. Load register maps (pcs.register_maps, POST /dashboard/register-maps) — fetch and apply register maps from ems-backend. This is the overwriting operation; it gets a 120 s budget because it downloads an archive.

Active Models

  • GET /devices/models lists devices and their models.
  • pcs.device_models.save saves an edit.
  • pcs.device_models.pull_ems pulls the model list from the EMS.
  • pcs.device_models.apply_ems_devices applies the EMS's device list.

The EMS is the source of truth for device inventory. Pull first, edit second.

Register maps — EMS Registers

POST /ems-registers/pull refreshes the merged register map from GET /api/v1/ems/register-map. The page shows it flattened, one row per register, 100 rows at a time, cached for 60 s.

Alarm limits — Alarm Thresholds

  1. Choose the device type and search for the device.
  2. The page loads that device's rules from /alarms/thresholds/device.
  3. Filter with the row search.
  4. Edit a limit — validation runs as you type; the header shows devices / rules / errors / warnings.
  5. Save device posts to alarms.thresholds.save. Revert discards edits.

A rule with non-zero warnings still saves. Warnings flag a limit that looks unusual, or a field absent from the register map — not a hard error. Details: HOW_TO_EDIT_ALARM_THRESHOLDS.

Restarting the simulator

Register and alarm files are read when the simulator starts. After editing files outside the UI, apply them:

Restart posts to pcs.restart_simulator (POST /system/restart-simulator), which brings the simulator container back up and polls until it answers, up to 240 s.

/simulator-health (pcs.simulator_health) reports whether it is back.

Configuration workflow

Select Device -> Identify Model -> Load Configuration -> Edit
   -> Validate -> Save -> Reload -> Verify
Stage Where Confirms
Select device Config Editor The device document was found
Identify model Active Models The right model's files apply
Load configuration Config Editor / Alarm Thresholds Rows loaded
Edit In place —
Validate Inline, on save No error count
Save Post to the route Flash message, no error
Reload Restart the simulator Health endpoint returns again
Verify Read the register back New value is served

Backups

Before anything that writes emsConfig, copy the whole tree out of the container:

docker exec bess-simulator-backend \
  tar czf /tmp/emsConfig-backup-$(date +%F-%H%M).tgz \
  /app/EnergySyc_EMS_ES100Cx12S_BESS_simulator/emsConfig
docker cp bess-simulator-backend:/tmp/emsConfig-backup-$(date +%F-%H%M).tgz .

Restore by extracting over emsConfig and restarting. Compare with sha256sum rather than trusting a diff of two listings.

Preserving unrelated fields

Every editor patches only the keys it owns. Keep that property: never hand-write a whole JSON file when an editor can change one field, and when you must edit by hand, change only the intended keys. A wholesale rewrite is how unrelated fields get lost.

Troubleshooting

Symptom Cause Fix
Other registers lost after a save document sent instead of updates Restore from backup, resend with updates
Model change has no effect Simulator not restarted Restart, then re-read a register
Save rejected Value violates the register's type or range Re-read the row, correct the type
Load register maps looks stuck Large archive, up to 120 s budget Wait it out before retrying
Restart never reports healthy Simulator container failed to start Check its logs; health polls for up to 240 s
Threshold warnings non-zero but save works Warning, not an error Read the warning; it names the field