How to Read and Write Simulator Registers
Purpose
Inspect and change the register values a simulated device serves, and — critically — tell apart the three different things that can write a register. Confusing them is the most common source of "the simulator is not responding" reports.
Prerequisites
- Simulator stack up, target device served.
- For the EMS-side pages:
ems-backendreachable athttp://ems-backend:8080.
The three write paths
| # | Path | Page | Writes to | Recorded where |
|---|---|---|---|---|
| 1 | Manual simulator edit | Config Editor (/) |
The simulated device's document | Config Editor's own save; no Modbus involved |
| 2 | EMS Modbus write | EMS Modbus (/ems-modbus) |
The EMS's Modbus server | Nothing in the simulator log |
| 3 | EMS → simulated device | none (the EMS does it) | The simulated device over Modbus | write_commands.jsonl, visible in Write Monitor |
Path 3 is the one the brief calls "EMS register writes". Paths 1 and 2 are both manual, but they target different systems.
Path 1 — Reading and changing simulated registers
Read
- Open Config Editor (
/) and pick a device. The page callsGET /api/<device>. - The register rows are shown with their addresses, names and current values.
Write
- Edit the value in the row.
- Save. This posts to
pcs.devices.update(POST /devices/{device}/update). - The controller forwards it as
PATCH /api/<device>with anupdatesmap. - Use
updates(merge) rather thandocument(replace) unless you intend to replace the entire register document —documentdiscards anything you did not send.
Confirm it is being served
Read the register back over Modbus. If the document changed but the Modbus value did not, the server has not reloaded — restart the simulator container or run the sync tool.
Path 2 — Reading and writing the EMS's own registers
The EMS Modbus page targets the EMS, not the simulator:
host: ems-backend port: 1540
Set from config/bess_simulator.php (ems_modbus_host, ems_modbus_port).
- Fill in rows in the table.
- Read filled rows posts to
ems.modbus.readand fills in current values. - Write filled rows posts to
ems.modbus.writeand writes them.
Use this to feed the EMS an input it would normally get from a device, or to read a value the EMS is exposing.
The EMS Registers page (/ems-registers) shows the merged map the EMS Modbus
server loads, flattened to one row per register, from
GET /api/v1/ems/register-map (page size 100, cached 60 s).
A write here is judged on what the register holds afterwards
The controller reports success based on the register's resulting value, not on the transport's status code. A successful Modbus write that leaves the value unchanged therefore reports as a failure — correctly.
Path 3 — Observing what the EMS writes to the simulator
Do not poll for this; use the write log. See HOW_TO_MONITOR_EMS_COMMANDS.
Worked examples
| Goal | Page | Register | How |
|---|---|---|---|
| PCS active power setpoint | Config Editor | the model's active-power setpoint address | Edit the value, save, then read it back |
| Grid frequency | Config Editor | grid meter frequency register | Write a value outside the alarm band to force a frequency alarm |
| Grid voltage | Config Editor | grid meter voltage register | Same approach for over/under-voltage |
| Battery SOC | Config Editor | BMS SOC register | Set low to drive the low-SOC alarm |
| Battery temperature | Config Editor | BMS temperature register | Set high to drive the overtemperature alarm |
| Alarm-related bits | Config Editor or the Alarms page | the alarm bitmap register | Prefer the Alarms page: it knows which bits belong to which alarm |
| EMS input register | EMS Modbus | any EMS-exposed register | Set the row, then Write filled rows |
Prefer the Alarms page for anything alarm-shaped
A trigger there writes a value that is known to satisfy the rule. Editing the raw bitmap by hand can set bits that belong to other alarms, or leave a bit set so the alarm will not clear.
Verification
| Check | Expected |
|---|---|
| Read after write (path 1) | Modbus returns the new value |
| Unrelated registers intact after a save (path 1) | Unchanged — proof updates was used |
| Read rows (path 2) | Values fill in, no error banner |
| Write rows (path 2) | Reported success only if the value actually changed |
| Write reached a simulated device (path 3) | A row in Write Monitor with the right port and register |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Save appears to work, Modbus unchanged | Simulator not reloaded from the document | Restart the simulator container |
| Other registers wiped | document was sent instead of updates |
Resend with updates |
| EMS Modbus write reports failure | Value did not change | Check the register is writable and the value differs |
| Nothing in Write Monitor after an EMS write | The EMS wrote to its own server (path 2), not to a device | That is the expected difference between path 2 and path 3 |
| Register map page stale | 60 s cache | Wait, or reload once the cache expires |