Skip to content

EMS --debug-local Mode Guide

1. Purpose

The --debug-local option is intended for EMS development and troubleshooting when you want to test the EMS using only the local control settings file.

When --debug-local is enabled, the EMS uses:

emsConfig/ems/ems_control_setting.json

as the only source for EMS control settings.

This prevents settings from the frontend/API from overwriting local test changes during debugging.


2. Main Behavior

Run:

python3 ems_main.py --debug-local

When this option is active:

  • EMS settings are read directly from the local JSON file.
  • Frontend/API settings pull is disabled.
  • Frontend/API settings push is disabled.
  • Normal verbose debug output is enabled automatically.
  • The EMS control loop continues to operate normally using the local settings.
  • Changes made locally to ems_control_setting.json can be tested without being replaced by frontend settings.

3. Local Settings File

The debug-local mode uses:

emsConfig/ems/ems_control_setting.json

Important values read from this file include:

ems_operation_mode
ems_control_mode
general_settings.pcs
general_settings.lastvalue_read_refresh_rate
functions

Examples include:

{
  "ems_operation_mode": "PEAK_SHAVING",
  "ems_control_mode": "Internal_EMS"
}

PCS enable/disable settings are read from:

general_settings.pcs.pcs1.status
general_settings.pcs.pcs2.status
...
general_settings.pcs.pcs12.status

Example:

"pcs1": {
  "status": "active"
}

4. Starting EMS in Normal Mode

Normal EMS operation:

python3 ems_main.py

In normal mode, EMS settings may be synchronized with the frontend according to the configured API settings.

The frontend settings API configuration is normally located in:

emsConfig/ems/ems_api_config.json

Normal mode may therefore:

  1. Pull settings from the frontend.
  2. Save the received settings locally.
  3. Use the updated local settings for EMS control.
  4. Push local settings back to the frontend according to the configured push interval.

5. Starting EMS in Debug Local Mode

Use:

python3 ems_main.py --debug-local

Expected startup messages:

[EMS][DEBUG-LOCAL] ENABLED
[EMS][DEBUG-LOCAL] settings source = LOCAL ONLY: emsConfig/ems/ems_control_setting.json
[EMS][DEBUG-LOCAL] frontend settings PULL = DISABLED
[EMS][DEBUG-LOCAL] frontend settings PUSH = DISABLED

These messages confirm that the EMS is isolated from frontend settings synchronization.


6. Run One Debug Cycle

For a quick test, use:

python3 ems_main.py --debug-local --once

This will:

  1. Load the local EMS control settings.
  2. Load the current lastValue data.
  3. Execute one EMS control cycle.
  4. Print detailed debug information.
  5. Exit.

This is useful when testing changes to a control function without continuously running the EMS.


7. Debug Local with Refresh Rate Override

The normal EMS loop refresh rate is read from:

general_settings.lastvalue_read_refresh_rate

You can override it from the command line.

Example:

python3 ems_main.py --debug-local --hz 2

This runs the EMS control loop at:

2 Hz

or approximately one cycle every:

0.5 seconds

8. Print Last-Value Keys

To inspect the values being loaded from the lastValue folder:

python3 ems_main.py --debug-local --print-keys

This prints the number of merged runtime keys and a sample of the keys available to the EMS control logic.

This is useful when checking whether grid meter, solar meter, PCS, frequency meter, or other runtime data is available to a control function.


9. Frontend Synchronization Behavior

Normal Mode

python3 ems_main.py

Frontend synchronization can operate according to:

--pull-interval
--push-interval

Example:

python3 ems_main.py --pull-interval 5 --push-interval 5

Debug Local Mode

python3 ems_main.py --debug-local

The program internally forces:

pull interval = 0
push interval = 0

Therefore command-line values such as:

python3 ems_main.py --debug-local --pull-interval 5 --push-interval 5

still do NOT enable frontend synchronization.

--debug-local has priority.


10. Why Push Is Also Disabled

The main requirement of debug-local mode is to prevent the frontend from replacing the locally edited EMS settings.

Push is also disabled for safety.

For example, during testing you may temporarily change:

ems_operation_mode
PCS status
power limits
SOC limits
manual power setpoint
peak shaving limits
anti-backflow limits
frequency regulation settings

If push remained enabled, these temporary test settings could be sent to the frontend.

For this reason debug-local mode isolates settings synchronization in both directions:

Frontend -> EMS    DISABLED
EMS -> Frontend    DISABLED

11. EMS Control Logic Still Runs Normally

Debug-local mode changes only how EMS control settings are obtained.

It does not disable the EMS controller itself.

For example, if the local JSON contains:

"ems_operation_mode": "PEAK_SHAVING"

the EMS will run the Peak Shaving controller.

If it contains:

"ems_operation_mode": "MANUAL"

the EMS will run the Manual controller.

Other supported modes include:

ANTI_BACKFLOW
MANUAL
IDLE
PEAK_SHAVING
VALLEY_FILLING
SCHEDULED_CHARGE_DISCHARGE
ARBITRAGE
FREQUENCY_REGULATION

The available behavior depends on the implementation in ems_main.py and control_logic_updated.py.


12. External Control Mode

The local JSON also contains:

ems_control_mode

If the local setting selects external control, the normal EMS behavior related to the external control bridge will still apply.

Debug-local mode does not override the selected EMS control mode.

It only prevents frontend settings synchronization.


13. Frequency Regulation Mode

If the local control file contains:

"ems_operation_mode": "FREQUENCY_REGULATION"

the EMS may start the external frequency regulation process configured by ems_main.py.

Debug-local mode does not disable this controller.

Therefore use care when testing on real hardware.


Step 1 — Edit local EMS settings

Edit:

nano emsConfig/ems/ems_control_setting.json

or use your preferred editor.

Step 2 — Validate JSON

Example:

python3 -m json.tool emsConfig/ems/ems_control_setting.json > /dev/null

If the command returns without an error, the JSON syntax is valid.

Step 3 — Run one test cycle

python3 ems_main.py --debug-local --once

Step 4 — Review debug output

Check:

EMS operation mode
EMS control mode
enabled PCS list
refresh rate
control function result
Modbus command/debug output
cycle execution time

Step 5 — Run continuously if required

python3 ems_main.py --debug-local

Step 6 — Return to normal operation

Stop the debug process with:

Ctrl+C

Then start EMS normally:

python3 ems_main.py

After starting with:

python3 ems_main.py --debug-local

verify that the following lines appear:

[EMS][DEBUG-LOCAL] ENABLED
[EMS][DEBUG-LOCAL] frontend settings PULL = DISABLED
[EMS][DEBUG-LOCAL] frontend settings PUSH = DISABLED

You should NOT see periodic messages such as:

[EMS][API] pulling settings from frontend...

and you should NOT see periodic settings push messages such as:

[EMS][API] pushing settings:

during debug-local operation.


16. Troubleshooting

Local changes disappear

Make sure the EMS was started with:

python3 ems_main.py --debug-local

If normal mode is used, the API-first settings loader may update the local JSON from the frontend.


Debug-local option not recognized

Check:

python3 ems_main.py --help

You should see:

--debug-local

If not, verify that the patched ems_main.py is the file being executed.

You can check:

pwd
ls -l ems_main.py

JSON read error

Validate:

python3 -m json.tool emsConfig/ems/ems_control_setting.json

Correct any JSON syntax error before restarting EMS.


Wrong operation mode executes

Check:

ems_operation_mode

inside:

emsConfig/ems/ems_control_setting.json

Example:

"ems_operation_mode": "MANUAL"

Then restart or rerun the debug-local EMS process.


17. Command Summary

Normal EMS:

python3 ems_main.py

Verbose normal debug:

python3 ems_main.py --debug

Local-only debugging:

python3 ems_main.py --debug-local

One local debug cycle:

python3 ems_main.py --debug-local --once

Local debug with key inspection:

python3 ems_main.py --debug-local --print-keys

Local debug at 2 Hz:

python3 ems_main.py --debug-local --hz 2

Detailed EMS help:

python3 ems_main.py --help-detail

18. Important Safety Note

--debug-local prevents settings synchronization with the frontend, but it does not make EMS control commands simulation-only.

If the configured PCS IP addresses and ports point to real hardware, the selected EMS control function may still issue real Modbus commands.

For offline testing, make sure the local configuration points to the intended simulator or test environment before running active control modes.


19. Summary

Use:

python3 ems_main.py --debug-local

when you want:

Local ems_control_setting.json
        |
        v
    ems_main.py
        |
        v
   EMS control logic

without:

Frontend/API pull

and without:

Frontend/API push

This provides an isolated local settings environment for EMS control development and debugging.