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.jsoncan 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:
- Pull settings from the frontend.
- Save the received settings locally.
- Use the updated local settings for EMS control.
- 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:
- Load the local EMS control settings.
- Load the current
lastValuedata. - Execute one EMS control cycle.
- Print detailed debug information.
- 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.
14. Recommended Development Workflow
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
15. Recommended Verification
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.