Skip to content

How to Use the PCS Simulator

Purpose

Simulate one or more PCS (power conversion system) units: start and stop, active and reactive power, charge and discharge, status transitions, and the alarms that protection depends on.

Prerequisites

  • Simulator stack up.
  • The PCS devices exist in emsConfig/pcs/ and are assigned a model.
  • The EMS points at the simulated ports, not real hardware.

Ports — the PCS range

Port Device
1501 PCS1
1502 PCS2
… …
1512 PCS12
1513 Grid Meter
1514 Solar Meter
1515 Frequency Meter

This mapping comes from portLabel() in PcsRegisterController and is confirmed by live traffic. A write on 1502 is PCS2 — use the port column in the Write Monitor, not the device name you think you selected.

Do not infer the port map from *_modbus_config.json

In the shipped emsConfig, every PCS unit's pcs_modbus_config.json names ip: 127.0.0.1, port: 1501, unit_id: 5 — all of them identical, and there is no bmu_modbus_config.json at all. Those files do not describe the live port layout. The layout above does.

Where a PCS's configuration lives

Thing Path
Register document emsConfig/pcs/pcs<N>/pcs_register_full.json
Alarm map emsConfig/pcs/pcs<N>/…_alarm_code.json (model variants add ___<MODEL>)
Config emsConfig/pcs/pcs<N>/pcs_modbus_config.json
Power sequences emsConfig/pcs/power_sequences/<MODEL>.json

PCS sequences live in their own directory, not beside the other categories' sequence files. Models present in a stock install: EPCS105, SINEXCEL_PWS1_250K, SUNGROW_SC250UD, plus MODEL_TEMPLATE.

What you can simulate

Start and stop

Run the model's start / stop sequence — see HOW_TO_VERIFY_COMMAND_SEQUENCES. Watch the Write Monitor for the writes on the unit's port, then read the status register back to confirm the transition.

Active power

The change_power sequence takes a runtime parameter, ${power_kw}, substituted into the step's value. Sign convention follows the model: positive is discharge, negative is charge. Verify by reading the active-power register back and decoding it against the register's own type — raw values are unsigned on the wire, so a negative setpoint appears as a large number (65403 is -133).

Reactive power

Same mechanism as active power, against the model's reactive-power register. Drive it through the Config Editor or a sequence.

Charge and discharge

These are directions of active power, not separate modes: charge is negative, discharge positive. There is no independent "charge mode" register to set.

Status changes

Write the status register through the Config Editor and watch the EMS follow it. The EMS's view is what matters — a status only the simulator believes is not a simulation of anything.

PCS alarms

Use the Alarms page for anything alarm-shaped; it writes a value known to satisfy the rule. Editing the raw bitmap by hand can set bits belonging to other alarms. See HOW_TO_TRIGGER_SIMULATOR_ALARM.

The brief's example alarms map onto this as follows:

Alarm How to drive it
Overtemperature Write a temperature above the rule's limit
Overvoltage Write a voltage above the limit
Communication fault See below — the simulator has no register-level comms-fault trigger

Switching operating mode — grid-following (PQ) and grid-forming (VF)

The PCS register maps carry a writable mode register, and every PCS model ships a sequence that writes it, so both operating modes are simulated:

Item Value
Register mode_pq_vf_command_item, address 20582 (0x5066)
Grid-following mode_pq writes 0
Grid-forming mode_vf writes 1
Models carrying both sequences EPCS105, SINEXCEL_PWS1_250K, SUNGROW_SC250UD
Sequence file emsConfig/pcs/power_sequences/<MODEL>.json

Verified on the test host against pcs1 at bess-simulator-backend:1501: mode_pq wrote 0x5066 = 0 and read it back, mode_vf wrote 0x5066 = 1 and read it back, then mode_pq restored 0. All three runs reported PASS.

To switch mode yourself:

  1. Open the EMS command-sequence editor for the PCS model and select mode_pq or mode_vf.
  2. Press Test Sequence with pcs1 as the target. The engine refuses any target that is not recognisably a simulator, so this cannot reach real hardware.
  3. Read the result: step 1 is a write_single to 0x5066 followed by a verify_read_holding of the same address. Both must report PASS.
  4. Confirm the new mode in the simulator by reading register 20582 for that device — see HOW_TO_READ_WRITE_SIMULATOR_REGISTERS.

The same sequence can be attached as an alarm action, so a protection event switches mode automatically — see HOW_TO_ADD_ALARM_ACTION.

Failing one device on purpose (communication-failure simulation)

The dashboard can take a single simulated device off the air. On Active Models each device carries an enable checkbox; unchecking one records it in the deny list at emsConfig/device_enabled.json, and start_simulator.sh skips that device's Modbus server the next time the simulator starts. The full procedure, including how to restore the device, is in HOW_TO_TEST_EMS_WITH_SIMULATOR.

The OCPP client is deliberately exempt from the deny list, so the EV charger's own OCPP connection cannot be failed this way.

Functions the brief asks for that are NOT implemented

Requested Status
PCS status change caused by the simulator autonomously The simulator serves values; it does not run a PCS state machine. A start sequence writes the start register, and the EMS then observes the transition

Everything else the brief lists for the PCS is implemented; the coverage matrix in BESS_SIMULATOR_COVERAGE_MATRIX carries the per-function inventory.

Verification

Check Expected
Start sequence Writes on the unit's port, status register reaches running
change_power Power register holds the substituted value
Read-back Decoded value matches the intent, including sign
Alarm trigger Violating value in the register; EMS reports the alarm
Wrong PCS? Compare the port column, not the device name

Troubleshooting

Symptom Cause Fix
No writes on the expected port Sequence resolved for a different model Confirm the model, and that its sequence file defines the action
Power register holds an odd large number Two's-complement negative Decode against the register's type
Alarm never fires Register the rule watches is not the one you wrote Check the Watched register column
Sequence not found Action absent from this model's file Add it — see HOW_TO_ADD_DEVICE_COMMAND_SEQUENCE
All units share a port in the config files Stale *_modbus_config.json Ignore them; use the port table above