Skip to content

EV Charging Pile Settings

Status: implemented and verified on the test stack. Every key, default and procedure below was checked against the running system. Anything unverified is marked TODO.

Applies to: ems_control_setting.json (tracked template + runtime copy), EmsSettingTableSeeder.php, RegisterCommonDeviceTableSeeder.php, and the ems-frontend settings panel.

Category: ev_charging_piles, devices ev_charger1 … ev_charger12.

Related: EV Charging Pile Integration, EMS Settings Configuration, Settings Pull.


1. Where the settings live

A device category is stored in two places, and both are required:

# Store Path Drives
1 Control settings document emsConfig/ems/ems_control_setting.json → general_settings.ev_charging_piles the values the panel shows and the API reads/writes
2 Component manifest register_common_devices.attribute_json → component_details.ev_charging_piles how many sub-tabs the panel renders and whether the @for loop runs

There is a repository-side copy of each, so the state survives a rebuild:

Repository file Mirrors
emsConfig/ems/ems_control_setting.template.json the control settings document for a new site
database/seeders/EmsSettingTableSeeder.php the same document, seeded into ems_settings
database/seeders/RegisterCommonDeviceTableSeeder.php the component manifest

The runtime emsConfig/ems/ems_control_setting.json is gitignored (.gitignore:29): it is what the container actually reads (/app/EnergySyc_EMS_ES100Cx12S/emsConfig/ems/ems_control_setting.json) and it changes while the stack runs. The template is the versioned structure, so a new category or key that is not written to the template will be missing from the next site rebuild.

The panel needs the gateway

/emsConfigurationOperation requires ?gateway_id=<gateway_key> (for the test stack, GTW-ems100CX). Without it the query returns nothing, $componentCount is empty and every device pane renders zero iterations — while still returning HTTP 200. Never judge a panel change without the parameter.

2. Device entry reference

Each pile is a device entry under general_settings.ev_charging_piles. All 12 share one shape; only identity, port and dlb_ev_device_id differ.

"ev_charger7": {
    "communication": { "protocol": "modbus-tcp", "ip_address": "" },
    "device": {
        "ip": "bess-simulator-backend",
        "port": 1636,
        "unit_id": 1,
        "poll_interval_ms": 5000,
        "save_interval_ms": 15000,
        "log_level": "INFO",
        "endianness": "big",
        "ems_key": "ems",
        "scale": 1,
        "datatype": "BITMAP32"
    },
    "status": "inactive",
    "device_id": "EV-CHARGER-007",
    "model": "",
    "dlb_ev_enabled": true,
    "...": "21 DLB keys — see §3"
}
Key Type Default Meaning
communication.protocol string modbus-tcp transport; ocpp16j / ocpp201 for OCPP chargers
communication.ip_address string "" charger-side address, blank while simulated
device.ip string bess-simulator-backend host the EMS connects to
device.port int 1630 + (n − 1) → 1630…1641 one port per pile
device.unit_id int 1 Modbus unit/slave id
device.poll_interval_ms int 5000 read cadence
device.save_interval_ms int 15000 historian write cadence
device.log_level string INFO per-device log verbosity
device.endianness string big word order for multi-register values
device.ems_key string ems settings section the device belongs to
device.scale int 1 engineering-unit multiplier
device.datatype string BITMAP32 register word layout
status string inactive active starts polling; ships inactive so nothing is polled until installed
device_id string EV-CHARGER-001…012 human identity, also used by the panel
model string "" model string; selects the register/alarm overrides

3. DLB settings reference

21 keys per pile, flat on the device entry, so each charger is independently configurable. Panel control types are given because the collector types a value from the element: checkbox → boolean, number → number, select/text → string.

Key Meaning Type Default Panel control
dlb_ev_enabled participate in DLB bool true switch
dlb_ev_device_id pile identifier used by the DLB allocator string ev_charger_<n> text
dlb_ev_priority charging priority, 1 = highest int 5 number
dlb_ev_weight weight for proportional allocation num 1 number
dlb_ev_max_power_kw maximum permitted charging power (kW) num 22 number
dlb_ev_min_power_kw minimum charging power when active (kW) num 4.1 number
dlb_ev_max_current_a maximum charging current (A) num 32 number
dlb_ev_min_current_a minimum charging current (A) num 6 number
dlb_ev_number_of_phases number of phases int 3 number
dlb_ev_phase_assignment phase(s) used enum L1 L2 L3 THREE_PHASE THREE_PHASE select
dlb_ev_connector_id OCPP connector / EVSE reference int 1 number
dlb_ev_power_ramp_up_kw_sec maximum power increase rate (kW/s) num 2 number
dlb_ev_power_ramp_down_kw_sec maximum normal decrease rate (kW/s) num 5 number
dlb_ev_allow_pause EMS may suspend charging bool true switch
dlb_ev_allow_resume EMS may resume charging bool true switch
dlb_ev_session_priority priority of the current session int 5 number
dlb_ev_energy_target_kwh requested energy target (kWh) num 0 number
dlb_ev_departure_time expected vehicle departure time string "" text
dlb_ev_soc_target_percent target SOC, if available (%) int 80 number
dlb_ev_offline_policy behaviour when the charger is unreachable enum STOP FIXED_LIMIT LOCAL_CONTROL STOP select
dlb_ev_fallback_current_a safe current limit on communication failure (A) num 0 number

4. Component manifest entry

component_details.ev_charging_piles must carry the same seven keys as its siblings (solar_meters, door_sensors):

"ev_charging_piles": {
    "identity": "ev_charger",
    "no_of_components": 12,
    "connet_to_key": "mainline",
    "data_visible_keys": {},
    "wire_line_direction_key": null,
    "more_detail_dashboard_conifgs": { "display": false, "display_readings_keys": [], "chart_configs": {} },
    "general_settings_key": { "main_keys": ["status", "device_id", "model"], "device": ["scale", "datatype"] }
}
Key Why it matters
no_of_components the panel renders @for($i = 1; $i <= ($componentCount['ev_charging_piles'] ?? 0); $i++) — this is the sub-tab count
identity the prefix used to name fields and to match the device family
general_settings_key which device keys appear as main settings
connet_to_key where the device attaches on the single-line diagram
data_visible_keys readings offered to the dashboard; empty until registers exist
wire_line_direction_key power-flow direction source; null (no readings yet)
more_detail_dashboard_conifgs chart block; display: false avoids a chart pointing at values that do not exist

identity is ev_charger — the same string registered in the backend identity maps, so the device family resolves as itself and never as PCS.

5. Panel wiring

Layer File What was added
Tab strip resources/views/emsConfigurationOperation.blade.php [$componentCount['ev_charging_piles'] ?? 0, 'general_settings_ev_charger', 'cruds.emsSettings.EV_Charging_Piles']
Panes same file one sub-tab-pane per pile, id="general_settings_ev_charger{{ $i }}", with a DLB card of 21 controls
Bindings same file every control carries data-json-path="general_settings.ev_charging_piles.ev_charger{{ $i }}.<key>"
Labels resources/lang/en/cruds.php 24 keys under emsSettings: DLB_EV_Settings, DLB_EV_ON, DLB_EV_OFF and one per DLB setting
Hydration resources/views/emsConfigurationsettingScript.blade.php existing generic hydration handles the pile fields

A control is collected from its data-json-path, and the value's type comes from the element (getValueFromInput in emsConfigurationsettingScript.blade.php): checkbox → boolean, number → Number(...) (empty → null), radio → data-json-value, text → string (empty → null).

6. API contract

Item Value
Endpoint GET / PUT /api/v1/ems/settings
Where inside the ems-backend container, port 8080 (not published to the host)
Backing file emsConfig/ems/ems_control_setting.json, written by PUT
Read path pulls are opt-in and disabled, so GET serves the local file
Guard _is_usable_settings rejects an incomplete payload rather than overwriting the live cache
# from inside the ems-backend container
python3 - <<'PY'
import json, urllib.request, sys
sys.path.insert(0, "/app/EnergySyc_EMS_ES100Cx12S")
import ems_settings_api as api
url = "http://127.0.0.1:8080" + api.DEFAULT_GET_PATH
cfg = json.load(urllib.request.urlopen(url))
piles = cfg["general_settings"]["ev_charging_piles"]
print(len(piles), "piles;", len([k for k in piles["ev_charger1"] if k.startswith("dlb_ev_")]), "DLB keys")
PY

7. Synchronisation between the four stores

The three JSON copies and the manifest must agree. Apply a change to all of them, in this order:

  1. emsConfig/ems/ems_control_setting.template.json — the repository source of truth.
  2. database/seeders/EmsSettingTableSeeder.php — the seeded document (mirror it exactly).
  3. The live ems_control_setting.json on the host — PUT the document, or splice the same block in place so the rest of the file stays byte-identical.
  4. register_common_devices.attribute_json + RegisterCommonDeviceTableSeeder.php — only when the structure changes (a new category or a different count).

Edits are additive: a new key is appended inside the device object, and the existing keys stay untouched, so a diff shows insertions and at most the previous line gaining a comma. Back up before editing:

cp -p emsConfig/ems/ems_control_setting.json /opt/gess-stack/ems/backup/<name>/ems_control_setting.before.json

8. Adding or changing a setting

  1. Decide whether it is a value (add to the device entries in all three JSON copies) or structure (also update component_details and the panel).
  2. Add the key with its default to the template and the seeder, and to each of the 12 piles — not just pile 1.
  3. For a panel control, add the markup inside the pile's pane with the correct data-json-path, and a label in cruds.php.
  4. Add a control of the matching type: a switch for booleans, number for figures, select for enums — otherwise the value is stored as a string.
  5. Apply to the live file and reload the panel (clear the compiled views after a Blade change: docker exec -u www-data ems-frontend php artisan view:clear; running artisan as www-data avoids root-owned compiled views).
  6. Verify with §9.

9. Verification recipe

Check Expected
File parses python3 -m json.tool emsConfig/ems/ems_control_setting.json
12 piles, 21 DLB keys each every ev_charger<n> has all 21 dlb_ev_* keys
Panel renders 12 panes; with ?gateway_id=…, dlb_ev_ appears 504 times (21 × 12 × 2: id + binding)
Labels resolve cruds.emsSettings.DLB_EV does not appear in the rendered HTML
API round-trip PUT a changed value, GET it back with the expected JSON type
PCS untouched general_settings.pcs byte-identical before and after; existing categories unchanged