Skip to content

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-backend reachable at http://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

  1. Open Config Editor (/) and pick a device. The page calls GET /api/<device>.
  2. The register rows are shown with their addresses, names and current values.

Write

  1. Edit the value in the row.
  2. Save. This posts to pcs.devices.update (POST /devices/{device}/update).
  3. The controller forwards it as PATCH /api/<device> with an updates map.
  4. Use updates (merge) rather than document (replace) unless you intend to replace the entire register document — document discards 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).

  1. Fill in rows in the table.
  2. Read filled rows posts to ems.modbus.read and fills in current values.
  3. Write filled rows posts to ems.modbus.write and 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