PCS runtime JSON files
Overview
Each PCS configuration folder can contain these runtime files:
emsConfig/pcs/<pcs_id>/pcs_write_queue.json
emsConfig/pcs/<pcs_id>/pcs_write_ack.json
emsConfig/pcs/<pcs_id>/pcs_alarm_code.json
They do not have the same lifecycle:
| File | Classification | Used by |
|---|---|---|
pcs_write_queue.json |
Active and required for PCS commands | EMS control producers and PCS v21 consumer |
pcs_write_ack.json |
Active diagnostic output | Written by PCS v21; not read by current EMS control logic |
pcs_alarm_code.json |
Legacy with the current EPCS105 map | Alarm helper is called, but no compatible alarm-code register exists |
PCS write queue
Purpose
pcs_write_queue.json is the command boundary between EMS control logic and the PCS Modbus client. Peak shaving, anti-backflow, valley filling, schedules, manual mode, arbitrage, and external control submit commands through this file.
The control functions do not open a separate Modbus connection. They enqueue a command, and pcs_client_save_data_v21_ES100CX12S.py applies it using the same connection used for polling.
Location and format
emsConfig/pcs/pcs1/pcs_write_queue.json
emsConfig/pcs/pcs2/pcs_write_queue.json
...
emsConfig/pcs/pcs12/pcs_write_queue.json
{
"commands": [
{
"id": "ems-set-power-1789198617103",
"action": "set_power_kw",
"power_kw": 50,
"ts_ms": 1789198617103,
"source": "control_logic"
}
]
}
The root must be an object containing a commands array. An empty queue is:
{
"commands": []
}
Queue files do not need to be pre-created for every PCS. The writer creates the PCS directory and queue file when the first command is submitted.
Producers
control_logic_updated.py writes automatic power commands. ems_external_control_bridge.py uses the same control helper, so external setpoints enter the same queue.
Automatic set_power_kw commands are coalesced. If a newer automatic setpoint is submitted before the previous one is applied, only the newest unapplied automatic setpoint is retained. Manual, start, and stop commands are preserved.
Consumer behavior
PCS v21:
- Locks
<queue>.lockwith an exclusive file lock. - Loads the
commandsarray. - Processes up to five commands per polling cycle.
- Re-reads the configured PCS model for model-specific actions.
- Executes the matching sequence from
emsConfig/pcs/power_sequences/. - Verifies configured writes by reading the register back.
- Writes the latest acknowledgement.
- Removes successful, expired, or invalid commands from the queue.
- Retains transient Modbus failures for retry.
Commands with a nonzero timestamp older than 3,600 seconds are dropped with acknowledgement status dropped_old.
Do not edit the queue while the EMS is writing it. Use the same lock protocol for programmatic producers. For a manual maintenance test, stop automatic EMS control first so it does not replace the test setpoint.
PCS write acknowledgement
Purpose
pcs_write_ack.json records the latest result produced while consuming the queue. It is useful for commissioning, diagnostics, and external monitoring.
No current EMS control mode reads this file to decide its next action. A successful return from the queue writer means the command was queued, not that the physical PCS accepted it. Check the acknowledgement and Modbus log for the final result.
Current v21 format
PCS v21 overwrites the file with one latest-result object:
{
"id": "ems-set-power-1789198617103",
"pcs_id": "pcs1",
"model": "EPCS105-AM",
"status": "ok",
"ts_ms": 1789198617200,
"action": "set_power_kw",
"sequence": [
{
"step": 1,
"operation": "write_single",
"address": 3415,
"value": 500,
"readback": 500
}
],
"cmd": {
"action": "set_power_kw",
"power_kw": 50
}
}
Address 3415 is hexadecimal 0x0D57. With scale 10, 50 kW is encoded as register value 500.
Possible statuses include:
| Status | Meaning |
|---|---|
ok |
Write succeeded and configured verification passed. |
ok_no_readback |
Raw write succeeded but no readback was available. |
ok_mismatch |
Raw write returned success but readback differed. |
error |
Validation, sequence, Modbus, or readback operation failed. |
dropped_old |
Command exceeded the configured maximum age. |
An error acknowledgement includes an error string and the original cmd.
Legacy list format
Some checked-in or older installations contain an array of historical acknowledgements:
[
{"id": "old-command-1", "status": "ok"},
{"id": "old-command-2", "status": "ok"}
]
This list format is obsolete for v21. The next processed command replaces it with the latest-result object. The append_write_ack() function remaining in v21 is unused legacy code; active paths call save_write_ack_latest().
The acknowledgement file is also created lazily. Its absence means no command result has been written for that PCS in the current filesystem; it does not by itself mean PCS polling is down.
PCS alarm-code map
Intended behavior
pcs_alarm_code.json maps a numeric alarm code to display metadata:
{
"ALM-1001": {
"alarm_display_name": "Over Voltage",
"message": "Voltage exceeded safe operating range",
"severity": "critical"
}
}
The polling loop calls append_alarm_from_entry_values() after decoding registers. The helper can create an alarm object containing the code, display name, message, severity, address, data type, and acknowledgement state.
Current EPCS105 limitation
The helper only searches a decoded PCS reading for these keys:
pcs_alarm_code
alarm_code
pcs_alarms
None of those keys exists in the current pcs_register_full.json or generated PCS last-value records. Consequently, the helper returns before opening pcs_alarm_code.json.
The current map is therefore functionally unused with EPCS105, even though the helper is called every polling cycle. The PCS still exposes its individual alarm and fault fields directly. The current register map produces many fields such as:
pcs_l1_insulation_fault
pcs_l1_communication_fault
pcs_pcs_alarm_present
pcs_system_fire_alarm_fault_flag
All 12 PCS alarm-code files are currently identical copies. Keep them only for backward compatibility with older register maps or clients.
Make alarm-code mapping active
To use this mapping mechanism with another PCS model:
- Confirm that the physical PCS exposes a numeric alarm-code register.
- Add that register to the model register map with an output key recognized by the helper.
- Add all real numeric/string code values to
pcs_alarm_code.json. - Confirm that the code value's string form exactly matches the map key.
- Run the PCS client with
--debugand verify thatentry["alarm"]is created. - Add the code key and
alarmmetadata to the last-value template if they must be sent to the API.
Do not map individual Boolean fault registers as though they were one numeric alarm code. For EPCS105, aggregate the existing individual flags in dedicated logic or continue sending them directly.
Operational checks
Inspect all three files for one PCS:
jq . emsConfig/pcs/pcs1/pcs_write_queue.json
jq . emsConfig/pcs/pcs1/pcs_write_ack.json
jq . emsConfig/pcs/pcs1/pcs_alarm_code.json
Follow Modbus command results:
tail -F ../logs/pcs_modbus.log
Errors are always available, even when debug mode is disabled:
tail -F ../logs/pcs_client_error.log ../logs/pcs_modbus_error.log
See EMS logging for all process and Modbus-family error files.
For a complete ordered trace with PCS number, endpoint, sequence part, register, and values, enable:
{
"device": {
"debug_enabled": true
}
}
Then inspect the separate JSON Lines logs:
tail -F ../logs/debug_modbus_command_send.log ../logs/debug_modbus_command_receive.log
jq -c 'select(.part | startswith("sequence:"))' ../logs/debug_modbus_command_send.log
jq -c 'select(.part | startswith("sequence:"))' ../logs/debug_modbus_command_receive.log
debug_modbus_command_send.log contains writes, delays, and command errors. debug_modbus_command_receive.log contains polling reads and verification readbacks. Each event includes time, direction, pcs_id, ip, port, unit_id, part, operation, status, and, when addressed, register, register_hex, count, and values. Sequence events also include step, model, requested_action, and action.
Grid and solar meters use separate files in the same repository-root directory:
../logs/debug_grid_meter_modbus_command_send.log
../logs/debug_grid_meter_modbus_command_receive.log
../logs/debug_solar_meter_modbus_command_send.log
../logs/debug_solar_meter_modbus_command_receive.log
Their events use device_type and device_id fields. The current clients are read-only, so normal traffic appears in the receive files and the send files remain empty.
Frequency services use another four root files:
../logs/debug_frequency_regulation_modbus_command_send.log
../logs/debug_frequency_regulation_modbus_command_receive.log
../logs/debug_frequency_meter_modbus_command_send.log
../logs/debug_frequency_meter_modbus_command_receive.log
The frequency-regulation send log identifies each PCS dispatch and includes the power register, requested signed kW, charge/discharge direction, and encoded register word. Its receive log records the frequency input and decoded Hz. The standalone frequency-meter client only reads Modbus, so its send file is an empty placeholder. Run python3 frequencyMeter_client_save_data_v1.py when standalone meter logging and last-value persistence are required; it is not started by the standard script because it currently exits when the meter is unavailable.
Inside the deployed container:
docker exec ems-backend jq . \
/app/EnergySyc_EMS_ES100Cx12S/emsConfig/pcs/pcs1/pcs_write_ack.json
When a command is not applied, check the queue first, then the latest acknowledgement, and finally the repository-root logs/pcs_modbus.log. A queue becoming empty only proves that the command was consumed or dropped; the acknowledgement determines which result occurred.