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
- Open Config Editor (
/) and pick a device. The page callsGET /api/<device>. - Edit register values in the rows.
- Save. This posts to
pcs.update(POST /devices/{device}/update), which the controller forwards asPATCH /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
- Scan (
pcs.scan,POST /dashboard/scan) — discover devices in the configuration. - Select model (
pcs.model.select,POST /dashboard/model) — set the model for a device. - Load register maps (
pcs.register_maps,POST /dashboard/register-maps) — fetch and apply register maps fromems-backend. This is the overwriting operation; it gets a 120 s budget because it downloads an archive.
Active Models
GET /devices/modelslists devices and their models.pcs.device_models.savesaves an edit.pcs.device_models.pull_emspulls the model list from the EMS.pcs.device_models.apply_ems_devicesapplies 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
- Choose the device type and search for the device.
- The page loads that device's rules from
/alarms/thresholds/device. - Filter with the row search.
- Edit a limit — validation runs as you type; the header shows
devices / rules / errors / warnings. - 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 |