Skip to content

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 pcs1 through pcs12.
  • 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:

  1. Loads the pending command.
  2. Re-reads the current model for that PCS.
  3. Loads the matching model sequence JSON.
  4. Substitutes the current dynamic power_kw value.
  5. Executes all configured reads, writes, and delays in order.
  6. Verifies writes when verify is enabled.
  7. 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:

  1. Confirm the PCS IP, port, unit ID, and model.
  2. Confirm every configured register against the commissioned firmware register map.
  3. Confirm the sign convention for charge and discharge.
  4. Confirm scaling and signed/unsigned encoding.
  5. Start with a small power setpoint.
  6. Check the transaction log and read-back result.
  7. Confirm actual PCS power independently from the PCS HMI or meter.
  8. Test start, zero-power, charge, discharge, and stop actions.
  9. 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.json contains a valid commands list.
  • 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.