Skip to content

PCS Modbus Command Log Viewing Guide

1. What is logged

PCS Client Version 21 records:

  • Holding-register reads
  • Input-register reads used in configured sequences
  • Single-register writes
  • Multiple-register writes
  • Dynamic power values before and after encoding
  • Register addresses in decimal and hexadecimal
  • Remote IP, TCP port, and Modbus unit ID where available
  • PCS ID, model, action, and sequence step
  • Write verification read-back
  • Sequence delays
  • Failed operations and command exceptions

Errors do not depend on debug mode. Process stderr and error-like stdout lines are always written to ../logs/pcs_client_error.log, and structured Modbus failures are always written to ../logs/pcs_modbus_error.log. Successful detailed send/receive transactions remain controlled by device.debug_enabled.

2. Default log location

From the EMS application root:

../logs/pcs_modbus.log

Show its absolute path:

readlink -f ../logs/pcs_modbus.log

The client also prints the absolute path at startup when debug mode is enabled.

3. Enable console debug output

python3 -u pcs_client_save_data_v21_ES100CX12S.py --pcs pcs1 --debug

Or:

DEBUG=1 python3 -u pcs_client_save_data_v21_ES100CX12S.py --pcs pcs1

Debug mode prints transactions to the terminal. The rotating file log is written even when console debugging is disabled.

4. View the latest log entries

tail -n 100 ../logs/pcs_modbus.log

Watch new transactions live:

tail -F ../logs/pcs_modbus.log

Use -F, rather than lowercase -f, when possible because -F continues following the log after rotation.

Stop live viewing with Ctrl+C.

4.1 Frequency logs

Frequency regulation has separate command and response logs:

tail -F ../logs/debug_frequency_regulation_modbus_command_send.log \
  ../logs/debug_frequency_regulation_modbus_command_receive.log

The send log shows PCS power commands written by the fast frequency controller. The receive log shows frequency-meter register words and the decoded Hz value.

The standalone frequency-meter polling client uses:

tail -F ../logs/debug_frequency_meter_modbus_command_send.log \
  ../logs/debug_frequency_meter_modbus_command_receive.log

Its send file is currently empty because the standalone meter client performs reads only.

5. View logs in Docker

If the log is inside ems-backend:

docker exec -it ems-backend tail -F /app/logs/pcs_modbus.log

Find the file if the application directory differs:

docker exec ems-backend find /app -type f -name pcs_modbus.log -print

View the PCS process console:

docker logs --tail 200 -f ems-backend

If the PCS client runs in another container, replace ems-backend with that container name.

6. Example entries

Power write:

2026-08-28 08:15:10.125 INFO pcs_id=pcs1 model=EPCS105 unit_id=5 action=change_power step=1 operation=WRITE_SINGLE address=3415 address_hex=0x0D57 raw_value=25 encoded_value=250

Verification:

2026-08-28 08:15:10.141 INFO pcs_id=pcs1 model=EPCS105 unit_id=5 action=change_power step=1 operation=VERIFY address=3415 address_hex=0x0D57 readback=250 status=OK

Normal holding-register read:

2026-08-28 08:15:11.003 INFO READ_HOLDING status=OK remote=192.168.50.10:502 unit_id=5 address=3415 address_hex=0x0D57 count=1 values=[250]

7. Useful filters

Show only writes:

rg 'WRITE_SINGLE|WRITE_MULTIPLE|fc=write_' ../logs/pcs_modbus.log

Show only reads:

rg 'READ_HOLDING|READ_INPUT' ../logs/pcs_modbus.log

Show errors and failed operations:

rg 'ERROR|FAILED|mismatch' ../logs/pcs_modbus.log

Show EPCS105 power-register activity:

rg '0x0D57' ../logs/pcs_modbus.log

Show power-on/off register activity:

rg '0x0291' ../logs/pcs_modbus.log

Show one PCS:

rg 'pcs_id=pcs1\b' ../logs/pcs_modbus.log

Show one Modbus unit:

rg 'unit_id=5\b' ../logs/pcs_modbus.log

Show one remote endpoint:

rg 'remote=192\.168\.50\.10:502' ../logs/pcs_modbus.log

Follow only writes live:

tail -F ../logs/pcs_modbus.log | rg --line-buffered 'WRITE|VERIFY'

Follow only errors live:

tail -F ../logs/pcs_modbus.log | rg --line-buffered 'ERROR|FAILED|mismatch'

If rg is unavailable, use grep -E instead.

8. Check a dynamic power command

For EPCS105, find both the write and verification of register 0x0D57:

rg '0x0D57.*(WRITE|VERIFY)|operation=(WRITE|VERIFY).*0x0D57' ../logs/pcs_modbus.log

Confirm:

  1. pcs_id is correct.
  2. unit_id is correct.
  3. raw_value has the intended sign.
  4. encoded_value has the expected ×10 scaling.
  5. A VERIFY entry follows the write.
  6. readback equals the encoded value.
  7. status=OK is present.

Example calculations:

  • 25 kW discharge becomes 250.
  • -20 kW charge becomes signed -200, transmitted as unsigned word 65336.
  • 0 kW becomes 0.

9. Check a start sequence

rg 'action=start|0x0291|operation=DELAY' ../logs/pcs_modbus.log

For EPCS105, the expected order is:

  1. Write 1 to 0x0291.
  2. Verify the write.
  3. Wait 10 seconds.

10. Check a stop sequence

rg 'action=stop|0x0D57|0x0291|operation=DELAY' ../logs/pcs_modbus.log

For the supplied EPCS105 sequence, the expected order is:

  1. Write 0 to 0x0D57.
  2. Verify zero power.
  3. Wait for the configured settling delay.
  4. Write 0 to 0x0291.
  5. Verify shutdown command.

11. Log rotation

Default rotation settings:

  • Current file: pcs_modbus.log
  • Maximum current file size: 10 MiB
  • Backups: 5

Rotated files normally appear as:

pcs_modbus.log
pcs_modbus.log.1
pcs_modbus.log.2
pcs_modbus.log.3
pcs_modbus.log.4
pcs_modbus.log.5

Search the current and rotated logs:

rg '0x0D57' ../logs/pcs_modbus.log*

12. Change log retention

export PCS_MODBUS_LOG_MAX_BYTES=20971520
export PCS_MODBUS_LOG_BACKUP_COUNT=10
python3 -u pcs_client_save_data_v21_ES100CX12S.py --pcs pcs1

For Docker Compose:

environment:
  PCS_MODBUS_LOG_MAX_BYTES: "20971520"
  PCS_MODBUS_LOG_BACKUP_COUNT: "10"

Restart the container after changing environment variables.

13. Copy logs from Docker

docker cp ems-backend:/app/logs/pcs_modbus.log ./pcs_modbus.log

Copy the complete log directory, including rotated files:

docker cp ems-backend:/app/logs ./ems-logs

14. Troubleshooting

Log file does not exist

Run once with --debug and read the displayed absolute path. Confirm that the application user can write to the parent directory.

ls -ld logs

Permission denied

Give the container/application user ownership of the selected log directory. Use the actual UID and GID used by the service:

chown -R <uid>:<gid> /path/to/logs

Reads appear but writes do not

Check whether pcs_write_queue.json contains a command and inspect pcs_write_ack.json for rejected or invalid actions.

Write appears without successful verification

Search for ERROR, FAILED, or mismatch. Confirm the PCS permits reading the written register and that the register does not automatically change its value.

Too many polling entries

Filter by WRITE, VERIFY, PCS ID, or address. You can also increase the configured log size and backup count. Do not disable write verification solely to reduce log volume.