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:
emsConfig/ems/ems_control_setting.template.json— the repository source of truth.database/seeders/EmsSettingTableSeeder.php— the seeded document (mirror it exactly).- The live
ems_control_setting.jsonon the host —PUTthe document, or splice the same block in place so the rest of the file stays byte-identical. 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
- Decide whether it is a value (add to the device entries in all three JSON
copies) or structure (also update
component_detailsand the panel). - Add the key with its default to the template and the seeder, and to each of the 12 piles — not just pile 1.
- For a panel control, add the markup inside the pile's pane with the correct
data-json-path, and a label incruds.php. - Add a control of the matching type: a switch for booleans,
numberfor figures,selectfor enums — otherwise the value is stored as a string. - 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 aswww-dataavoids root-owned compiled views). - 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 |