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:
pcs_idis correct.unit_idis correct.raw_valuehas the intended sign.encoded_valuehas the expected ×10 scaling.- A
VERIFYentry follows the write. readbackequals the encoded value.status=OKis present.
Example calculations:
25 kWdischarge becomes250.-20 kWcharge becomes signed-200, transmitted as unsigned word65336.0 kWbecomes0.
9. Check a start sequence
rg 'action=start|0x0291|operation=DELAY' ../logs/pcs_modbus.log
For EPCS105, the expected order is:
- Write
1to0x0291. - Verify the write.
- 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:
- Write
0to0x0D57. - Verify zero power.
- Wait for the configured settling delay.
- Write
0to0x0291. - 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.