PCS Client Version 21 - Full Usage Guide
1. Purpose
pcs_client_save_data_v21_ES100CX12S.py is the PCS Modbus TCP polling and command client. It:
- Reads PCS registers and saves the latest values.
- Supports
pcs1throughpcs12. - Reads each PCS endpoint, model, status, and timing settings from the EMS configuration.
- Sends data to the configured database and EMS API.
- Processes queued PCS write commands.
- Executes model-specific ordered register sequences through
pcs_power_sequence.py. - Supports dynamic charge/discharge setpoints from peak shaving, schedules, anti-backflow, valley filling, manual mode, and arbitrage.
- Records Modbus transactions in a rotating log file.
2. Required files
Use this directory structure from the EMS application root:
EnergySyc_EMS_ES100Cx12S/
├── pcs_client_save_data_v21_ES100CX12S.py
├── pcs_power_sequence.py
├── emsConfig/
│ ├── ems/
│ │ ├── ems_control_setting.json
│ │ └── ems_api_config.json
│ └── pcs/
│ ├── power_sequences/
│ │ ├── EPCS105.json
│ │ └── MODEL_TEMPLATE.json
│ ├── pcs1/
│ │ ├── pcs_register_full.json
│ │ ├── pcs_modbus_config.json
│ │ ├── pcs_alarm_code.json
│ │ ├── lastValue_template.json
│ │ └── pcs_write_queue.json
│ └── pcs2/ ... pcs12/
├── lastValue/
├── pcsData/
└── logs/
The model filename does not have to exactly match the configured model, but the JSON model or one of its aliases must match.
3. Python requirements
The client requires Python 3.10 or later and pyModbusTCP:
python3 -m pip install pyModbusTCP
The EMS project may also require its existing MariaDB/API modules.
4. PCS settings
For every enabled PCS, ems_control_setting.json must provide a device model and Modbus connection information. The exact surrounding structure can follow the existing EMS settings format, but each PCS must resolve these values:
{
"device": {
"device_id": "PCS-001",
"model": "EPCS105",
"ip": "192.168.50.10",
"port": 502,
"unit_id": 5
},
"status": "active",
"refresh_rate_ms": 3000,
"power_limits": {
"max_charge_kw": 100,
"max_discharge_kw": 100
}
}
Confirm that the actual setting uses the same keys already expected by the EMS settings loader.
5. Model-specific sequence file
Example emsConfig/pcs/power_sequences/EPCS105.json:
{
"model": "EPCS105",
"aliases": ["EPCS105-EN", "EnjoyPCS EPCS105"],
"actions": {
"start": [
{
"operation": "write_single",
"address": "0x0291",
"value": 1,
"encoding": "u16",
"verify": true
},
{
"operation": "delay",
"seconds": 10
}
],
"change_power": [
{
"operation": "write_single",
"address": "0x0D57",
"value": "${power_kw}",
"encoding": "signed_i16",
"scale": 10,
"verify": true
}
],
"stop": [
{
"operation": "write_single",
"address": "0x0D57",
"value": 0,
"encoding": "signed_i16",
"scale": 10,
"verify": true
},
{
"operation": "delay",
"seconds": 1
},
{
"operation": "write_single",
"address": "0x0291",
"value": 0,
"encoding": "u16",
"verify": true
}
]
}
}
For EPCS105, positive active power means discharge and negative active power means charge. The 0x0D57 power value is scaled by 10. Therefore:
| EMS request | Raw signed value | 16-bit register word |
|---|---|---|
25 kW discharge |
250 |
250 |
-20 kW charge |
-200 |
65336 |
0 kW |
0 |
0 |
6. Supported sequence operations
Write one register
{
"operation": "write_single",
"address": "0x0D57",
"value": "${power_kw}",
"encoding": "signed_i16",
"scale": 10,
"verify": true
}
Write multiple registers
{
"operation": "write_multiple",
"address": "0x1000",
"values": [1, 2, "${parameter_name}"],
"encoding": "u16",
"verify": true
}
Read holding registers
{
"operation": "read_holding",
"address": "0x1000",
"count": 2,
"store_as": "status_words"
}
Read input registers
{
"operation": "read_input",
"address": "0x2000",
"count": 2
}
Check an expected value
{
"operation": "read_holding",
"address": "0x1000",
"count": 1,
"expect": 1
}
Add a delay
{"operation": "delay", "seconds": 2}
Milliseconds are also supported:
{"operation": "delay", "milliseconds": 500}
Operations execute in the exact order shown in the action list. A failed write, failed read, or verification mismatch stops that command and creates an error acknowledgement.
7. Starting the client
Run one PCS:
python3 -u pcs_client_save_data_v21_ES100CX12S.py --pcs pcs1
Run with Modbus console debugging:
python3 -u pcs_client_save_data_v21_ES100CX12S.py --pcs pcs1 --debug
Use environment variables:
PCS=pcs2 DEBUG=1 python3 -u pcs_client_save_data_v21_ES100CX12S.py
Run all enabled PCS devices:
python3 -u pcs_client_save_data_v21_ES100CX12S.py --pcs auto
Show the built-in command help:
python3 pcs_client_save_data_v21_ES100CX12S.py --help
8. Sending model-specific commands
Commands are placed in:
emsConfig/pcs/<pcs_id>/pcs_write_queue.json
Set dynamic power
{
"commands": [
{
"id": "set-power-001",
"action": "set_power_kw",
"power_kw": 25,
"ts_ms": 1787900000000
}
]
}
For charging, use a negative EPCS105 setpoint:
{
"commands": [
{
"id": "charge-001",
"action": "set_power_kw",
"parameters": {"power_kw": -20}
}
]
}
Start PCS
{
"commands": [
{"id": "start-001", "action": "start"}
]
}
Stop PCS
{
"commands": [
{"id": "stop-001", "action": "shutdown"}
]
}
Accepted action aliases include start, startup, stop, shutdown, set_power, set_power_kw, change_power, pq, and vf.
9. EMS automatic power control
The updated control logic submits dynamic power commands to this queue. Peak shaving and the other EMS modes do not directly write a fixed PCS register. The PCS client:
- Loads the pending command.
- Re-reads the current model for that PCS.
- Loads the matching model sequence JSON.
- Substitutes the current dynamic
power_kwvalue. - Executes all configured reads, writes, and delays in order.
- Verifies writes when
verifyis enabled. - Saves the latest acknowledgement.
Fast EMS control cycles are coalesced so only the newest unapplied automatic power setpoint is retained. Manual, start, and stop commands are preserved.
The queue is active and required. It is protected by <queue>.lock, processes at most five commands per cycle, drops commands older than one hour, removes successful or invalid commands, and retains transient failures for retry. Queue files for pcs3 through pcs12 may be absent until their first command because they are created lazily.
10. Acknowledgement file
The latest result is written to:
emsConfig/pcs/<pcs_id>/pcs_write_ack.json
A successful sequence includes the PCS model, action, timestamp, and per-step results. An error includes the exception text and original command.
PCS v21 stores one latest-result object, not an acknowledgement history. Older checked-in files may contain a JSON list; that is a legacy format and is replaced by an object when the next command is processed. The acknowledgement is diagnostic output and is not currently read by EMS control logic.
10.1. PCS alarm-code file
The per-PCS file is:
emsConfig/pcs/<pcs_id>/pcs_alarm_code.json
It is intended to map a numeric alarm code to a display name, message, and severity. With the current EPCS105 register map it is functionally unused: the alarm helper looks for pcs_alarm_code, alarm_code, or pcs_alarms, but none of these decoded fields exists. Individual EPCS105 alarm and fault registers are still read and sent normally.
All 12 alarm-code files are currently identical legacy copies. Keep them for older clients/register maps, or redesign the alarm aggregation before removing them.
See PCS runtime JSON files for complete queue processing, acknowledgement statuses, legacy-format handling, alarm-map limitations, and operational checks.
11. Main output files
Depending on the selected PCS, the client maintains files such as:
lastValue/pcs1_lastValue.json
pcsData/pcs1_data_YYYYMMDD_HHMMSS.json
emsConfig/pcs/pcs1/pcs_write_ack.json
../logs/pcs_modbus.log
The fields written to the PCS last-value snapshot and sent to the EMS API are selected by:
emsConfig/pcs/<pcs_id>/lastValue_template.json
Each PCS template uses the EPCS105 model definition and initially contains every addressable register from pcs_register_full.json. Remove unneeded entries manually while retaining the power, energy, SOC, and alarm values required by the installation. The configured runtime model EPCS105-AM resolves to this template model.
See Last-value template configuration for the complete schema, editing workflow, API behavior, regeneration command, and troubleshooting steps.
12. Log configuration
Defaults:
- Log:
../logs/pcs_modbus.log - Maximum size: 10 MiB
- Rotated backups: 5
Override rotation size and backup count with:
export PCS_MODBUS_LOG_MAX_BYTES=20971520
export PCS_MODBUS_LOG_BACKUP_COUNT=10
The application user must have permission to create the directory and write the file.
Detailed Modbus command debug log
Set device.debug_enabled in emsConfig/ems/ems_control_setting.json:
{
"device": {
"debug_enabled": true
}
}
PCS v21 separates outbound commands from inbound values:
../logs/debug_modbus_command_send.log
../logs/debug_modbus_command_receive.log
The send log contains model-sequence writes, direct queue writes, delays, and command errors. The receive log contains polling reads and write-verification readbacks.
Grid and solar clients create equivalent device-specific files:
../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
The current grid and solar clients only perform Modbus reads. Their receive logs contain polling values and errors. Their send logs are created at startup for clarity and future write support, but remain empty during normal read-only operation.
Frequency regulation and the standalone frequency-meter client use:
../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 regulation receive log records frequency input registers and decoded Hz values. The regulation send log records every PCS power dispatch, including PCS ID, IP/port/unit, register 8004, signed requested kW, command direction, and encoded 16-bit value. The standalone frequency meter is read-only, so its receive log contains polling traffic and its send log remains empty.
The paths are anchored to the repository root, one directory above the EMS application. Changing the process working directory does not move the logs. In the container, the full paths are:
/app/logs/debug_modbus_command_send.log
/app/logs/debug_modbus_command_receive.log
The setting is re-read when ems_control_setting.json changes. Set it to false to stop new debug events. Both files use JSON Lines: every line is one complete JSON object in chronological order.
PCS v21 creates both files at startup even when debugging is disabled. When debug_enabled is false, the files remain empty. The settings path is anchored to the EMS application, so the debug flag works even when the client is launched from another working directory.
Example EPCS105 power sequence:
{"time":"2026-09-14T10:15:30.120+00:00","direction":"send","pcs_id":"pcs1","ip":"192.168.1.50","port":502,"unit_id":5,"part":"sequence:EPCS105-AM:change_power","operation":"write_single_register","status":"ok","register":3415,"register_hex":"0x0D57","count":1,"values":[500],"step":1,"model":"EPCS105-AM","requested_action":"set_power_kw","action":"change_power"}
{"time":"2026-09-14T10:15:30.126+00:00","direction":"receive","pcs_id":"pcs1","ip":"192.168.1.50","port":502,"unit_id":5,"part":"sequence:EPCS105-AM:change_power","operation":"verify_read_holding_registers","status":"ok","register":3415,"register_hex":"0x0D57","count":1,"values":[500],"step":1,"model":"EPCS105-AM","requested_action":"set_power_kw","action":"change_power"}
The first event is in the send log and the second is in the receive log. Together they show that PCS 1 at 192.168.1.50:502, unit ID 5, wrote decimal register 3415 (0x0D57) with encoded value 500, then read the same value back. requested_action is the incoming command, action is the canonical sequence name, and step preserves operation order.
Inspect or filter the log:
tail -F ../logs/debug_modbus_command_send.log ../logs/debug_modbus_command_receive.log
jq -c 'select(.pcs_id == "pcs1")' ../logs/debug_modbus_command_send.log
jq -c 'select(.part | startswith("sequence:"))' ../logs/debug_modbus_command_receive.log
jq -c 'select(.status != "ok")' ../logs/debug_modbus_command_send.log
Override rotation size and backup count if required:
export DEBUG_MODBUS_COMMAND_LOG_MAX_BYTES=20971520
export DEBUG_MODBUS_COMMAND_LOG_BACKUP_COUNT=5
The log locations are fixed under the repository root logs/ directory and cannot be redirected to /var or the application subfolder. Detailed debug logging records all polling reads and can grow quickly, especially the receive log. Enable it while commissioning or troubleshooting, then disable it for normal operation. Each file rotates independently at 20 MiB and retains five backups.
13. Docker example
Example command inside the EMS container:
docker exec -it ems-backend bash
cd /app/EnergySyc_EMS_ES100Cx12S
python3 -u pcs_client_save_data_v21_ES100CX12S.py --pcs pcs1 --debug
For normal service operation, add the same command to the container startup script or process supervisor without --debug if console output is not needed. File logging remains active.
14. Commissioning checks
Before connecting to a real PCS:
- Confirm the PCS IP, port, unit ID, and model.
- Confirm every configured register against the commissioned firmware register map.
- Confirm the sign convention for charge and discharge.
- Confirm scaling and signed/unsigned encoding.
- Start with a small power setpoint.
- Check the transaction log and read-back result.
- Confirm actual PCS power independently from the PCS HMI or meter.
- Test start, zero-power, charge, discharge, and stop actions.
- Verify SOC limits and EMS per-PCS power limits.
15. Troubleshooting
Model is missing
Confirm that the PCS has a model in ems_control_setting.json.
No sequence matches the model
Confirm that a JSON file exists in emsConfig/pcs/power_sequences/ and that its model or aliases matches the setting.
Queue command is not processed
Check:
- PCS status is active.
- The PCS client process is running.
pcs_write_queue.jsoncontains a validcommandslist.- The queue and lock files are writable.
- The acknowledgement and Modbus log for an error.
Read-back mismatch
Check register address, unit ID, encoding, scaling, PCS write permissions, operating state, and firmware-specific behavior.
No log file
Confirm that the repository-root logs/ directory is writable and look for the startup debug line showing the absolute transaction-log path. In Docker, all EMS logs are under /app/logs.