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:
- Open the EMS command-sequence editor for the PCS model and select
mode_pqormode_vf. - Press Test Sequence with
pcs1as the target. The engine refuses any target that is not recognisably a simulator, so this cannot reach real hardware. - Read the result: step 1 is a
write_singleto0x5066followed by averify_read_holdingof the same address. Both must reportPASS. - Confirm the new mode in the simulator by reading register
20582for that device — seeHOW_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 |