EV Charging Piles — EMS Integration
Status: device model, register maps, polling and alarms are implemented and verified on the test stack; DLB allocation, OCPP control and history storage are still pending. Sections marked Implemented have been built and verified on the test stack. Sections marked Pending describe the target design that still has to be written; they are stated as facts about where the code must go, not as claims that it exists. Anything marked TODO is an open question that must be settled before implementation.
Applies to: EMS backend EnergySyc_EMS_ES100Cx12S, BESS simulator EnergySyc_EMS_ES100Cx12S_BESS_simulator, and ems-frontend.
Interface: Modbus TCP and OCPP 1.6J / 2.0.1, through one EMS device abstraction.
Devices: ev_charger1 … ev_charger12, category ev_charging_piles.
Related: EV Charging Pile Settings, PCS Runtime JSON Files, Last-value Templates, Alarm Mapping & Endpoints.
1. Scope
The EMS must treat an EV charging pile as a first-class device: polled, alarmed, controlled, logged, self-tested and simulated, exactly like a PCS unit — while staying a separate device category so that nothing about PCS changes.
The governing rule is extend, do not fork. Every mechanism named in this document already exists for PCS; the EV work is to register a new category with that machinery, not to build a parallel stack. Where an EV-specific concept has no PCS equivalent (OCPP, charging sessions, smart charging) it is introduced as an adapter that produces the same EMS data structures.
2. Where EV piles sit in the device model
A device category is defined in two independent places. Both must be updated for a category to work end to end:
| Layer | File | Carries |
|---|---|---|
| Panel + API values | emsConfig/ems/ems_control_setting.json → general_settings.<category>.<deviceN> |
communication, device, DLB and status fields the EMS reads and writes |
| Panel structure | register_common_devices.attribute_json → component_details.<category> |
identity, no_of_components, data_visible_keys, general_settings_key |
emsConfig/ems/ems_control_setting.json is what the EMS reads at runtime and is
gitignored (.gitignore:29); ems_control_setting.template.json is the
versioned structure. A structural change must reach both.
The runtime identity of a device comes from ems_device_identity.SECTION_MAP
(EnergySyc_EMS_ES100Cx12S/ems_device_identity.py:35), a prefix → category map.
ev_charger → ev_charging_piles is registered there; the same prefix is
registered in ems_alarm_status.py, timescale_insert_v1.py
(DEVICE_TYPE_TO_SETTINGS_GROUP) and device_duplicate.py (SETTINGS_GROUPS).
A category is not a device
Registering the category makes the panel and the settings API work. It does not create register maps, pollers, alarms or simulator ports. Those are the file-level steps in §4.
3. Register mapping and communication
3.1 The register-full contract
Every device type is described by a register map. For PCS the file is
emsConfig/pcs/pcs1/pcs_register_full.json, with model overrides beside it:
| File | Role |
|---|---|
pcs_register_full.json |
the device's default register set |
pcs_register_full___epcs105.json |
override for model EPCS105 |
pcs_register_full___sinexcel_pws1_250k.json |
override for model Sinexcel PWS1 250K |
pcs_register_full___sungrow_sc250ud.json |
override for model Sungrow SC250UD |
pcs_alarm_code.json (+___<model>) |
alarm code → description/severity, same override pattern |
pcs_modbus_config.json (+_real, _sim) |
transport endpoints for real and simulated hardware |
pcs_write_queue.json |
pending control writes |
lastValue_template.json |
shape of the device's last-value document |
The authoritative description of the format is
docs/integration/EnergySync_EMS100CX12S_register_map.md
and docs/reference/ems_register_full.md.
The build convention is defined in How to build ems_register_full.json.
An EV pile must produce the same shape, so nothing downstream needs to know that the device is a charger:
emsConfig/ev_charger/ev_charger1/
├── ev_charger_register_full.json # default register set
├── ev_charger_register_full___<model>.json # per-model overrides
├── ev_charger_alarm_code.json # alarm codes, same override pattern
├── ev_charger_modbus_config.json # transport endpoints
├── ev_charger_write_queue.json # pending control writes
└── lastValue_template.json # last-value shape
Status: Implemented. All 12 folders exist in both repos (ev_charger1..12),
each with the register map, modbus_config.json, write queue, last-value
template and alarm codes. The PCS folder was the pattern, and no PCS file was
renamed or repackaged.
3.2 Two transports, one abstraction
| Charger | Transport | How EMS sees it |
|---|---|---|
| Modbus TCP charger | physical registers | straight through, as PCS |
| OCPP 1.6J / 2.0.1 charger | OCPP messages | logical register map: a mapping that turns OCPP MeterValues, StatusNotification, TransactionEvent and friends into the same register addresses and lastValue keys |
The logical map is the key idea: an OCPP charger gets a
ev_charger_register_full.json whose entries are not wire addresses but named
sources resolved from received OCPP messages. Everything above the map
(polling schedule, lastValue writer, alarm evaluator, historian) is unchanged.
Write direction is the mirror image: a register write whose target is an OCPP
logical register is translated into the corresponding OCPP command
(RemoteStartTransaction, RemoteStopTransaction, SetChargingProfile, …).
TODO — decide whether the logical map reuses the register_type field or
introduces a source: ocpp discriminator, and which OCPP payload each EV
register derives from. This must be settled before the register map is written.
4. Polling, lastValue and connection monitoring
Status: implemented and verified on the test stack. The piles are polled by the generic register-map client, one thread per pile, exactly as the sensor, UPS and cooling families are.
- Polling uses the same driver, schedule and interval keys as PCS. The interval
comes from the device entry:
device.poll_interval_ms(default5000) anddevice.save_interval_ms(default15000), read per cycle, so a change takes effect without a restart. - Latest values are written through the standard last-value store: the template
per device folder (
lastValue_template.json) plus the runtime directorylastValue/at the repository root. The structure, timestamps and validity rules are defined in Last-value Templates. - Communication state is part of the device entry (
status: active|inactive) and of the last-value document; a failed read must leave the previous value marked stale rather than blanking it. - Each charger polls on its own address/port and keeps its own failure counter, so one dead charger cannot stall the other eleven.
For OCPP chargers the update path differs in timing but not in shape: values
arrive from MeterValues notifications rather than from a read cycle, and the
logical map applies them to the same lastValue keys. Heartbeats
(heartbeat_interval_s) are the connection monitor; the meter interval
(meter_interval_s) is the effective OCPP polling rate.
4.2 How the piles are wired
The family goes through the generic component client rather than a new poller:
| Entry point | What it does |
|---|---|
component_client_save_data_v1.COMPONENTS['ev_charger'] |
device type, folder prefix, per-unit config/register paths, data_dir evChargerData, insert None |
UNIT_PREFIX['ev_charger'] |
folder prefix, so unit n is emsConfig/ev_charger/ev_charger<n>/ |
build_units() api_section / section |
ev_charger_data_api / ev_charging_piles — the settings group the piles are discovered from |
start_ems_client_in_docker.sh |
start_py "ev_charger_client" component_client_save_data_v1.py --component ev_charger |
folder_cleaner.py |
evChargerData joins the swept measurement folders |
build_units() reads the piles from general_settings.ev_charging_piles and
gives each its own thread, port and last-value file, so adding a thirteenth pile
is a settings edit rather than a code change.
4.3 Evidence from the test stack
| Check | Result |
|---|---|
| Client start | ev_charger_client started (PID 1173), error log empty |
| Connections | all 12 piles connected to bess-simulator-backend ports 1630–1641, 70 fields each, poll 5000 ms / save 15 000 ms |
| lastValue | 12 files refreshed every save cycle, 72 keys each (70 registers plus timestamps) |
| EMS push | [OK][API] ev_chargerN: pushed 1 reading(s) (device_id=EV-CHARGER-00N) -> HTTP 200 |
The failure mode to watch: a pile whose settings model is empty makes
require_device_identity() raise inside the push, which kills that pile's poll
thread while its lastValue file still looks fresh.
5. Alarms
Status: implemented and verified. Each pile carries
ev_charger_alarm_code.json with 27 codes (EVC-1001 … EVC-1027) and real
rules: every field resolves against the register map, and the live report
evaluates all 12 piles.
Follow the PCS workflow exactly: an alarm-code file per device (with per-model
overrides), detection during the poll cycle, severity classification, activation
and clearance with timestamps, active-alarm tracking, history, and publication to
the EMS alarm API. The end points and the code→register relationship are
documented in alarm-mapping-and-endpoints.md
and alarm-code-to-register-relationship.md.
EV-specific alarm sources that must be mapped:
| Source | Example | Severity |
|---|---|---|
| Modbus/OCPP communication loss | charger unreachable, no heartbeat | fault |
| Charger fault registers | OCPP Faulted, vendor error codes |
fault |
| Charging state anomalies | SuspendedEVSE while a session should run |
warning |
| Session errors | start rejected, stop failed, id_tag refused | warning |
Active alarms must land in the same TimescaleDB active_alarm_records path used
by PCS; see alarms-api.md.
5.1 Evidence from the test stack
| Step | Result |
|---|---|
| Baseline | 12 EV rows, evaluated: true, has_reading: true, active_alarm_count: 0 |
Fault injected — communication_fault = 1 on ev_charger1 through the simulator's Register API |
EVC-1001 Charger Communication Fault, severity major, value true, raised within one poll cycle (~5 s) |
Fault cleared — communication_fault = 0 |
alarm gone, active_alarms: 0 |
Two details worth keeping: the report lists a device whose settings group is
inactive under devices_not_live instead of dropping it silently, and a stalled
poller is caught by EVC-1027, which watches __reading_age_s__ — a < 1
threshold combined with ignore_zero can never fire.
6. Control functions
Status: Pending for EV.
Control reuses the PCS command mechanism — queue, validation, authorisation, logging, acknowledgement and failure reporting:
| Capability | Modbus charger | OCPP charger |
|---|---|---|
| Enable / disable charging | register write | ChangeAvailability |
| Start / stop session | register write | RemoteStartTransaction / RemoteStopTransaction |
| Set power limit | register write | SetChargingProfile |
| Set current limit | register write | SetChargingProfile |
| Read status / session info | register read | StatusNotification, TransactionEvent |
| Charging schedule | register write | SetChargingProfile (charging profile) |
| DLB command | register write | SetChargingProfile (dynamic limit) |
Commands travel through the device's ev_charger_write_queue.json and the
existing command-sequence mechanism, so acknowledgement, timeout and failure
handling stay identical to PCS. Every command must be logged where PCS commands
are logged.
7. BESS simulator
Status: implemented and verified on the test stack. Each pile is a Modbus TCP server on its own port, and the container also presents 12 OCPP 1.6 charge points.
| Piece | Implementation |
|---|---|
| Device config | emsConfig/ev_charger/ev_charger1..12/ in the simulator repo, kept in step with the EMS copy by register_map_sync.py |
| Modbus server | the existing generic register-map server (pcs_modbus_server_dynamic_nofilter_v15.py), one instance per pile — no EV-specific server code, exactly as the meters, UPS and sensor families are served |
| Port allocation | 1630–1641, one per pile, matching device.port in the settings and each pile's ev_charger_modbus_config.json |
| Launcher | one entry per pile in start_simulator.sh |
| Write path | a write to a read_write register is persisted back into the pile's map, so a limit the EMS assigns is visible on disk and survives the server |
| Register API | register_api_server.py, reused unchanged |
Verified against the running stack: all 12 piles answer a Modbus read from inside
ems-backend (power 4000, session energy 4002, SOC 4020, session state 4060,
charging 4064, OCPP status 4068, comm fault 4080, power limit 4122), and a write
to max_power_limit_kw is read back and persisted to the map on disk.
7.1 OCPP simulation
ocpp_charger_state.py defines the charge-point state shared between processes:
ocpp_charger_control.json (written by the Register API when the operator plugs
a vehicle in or out, read by the service) and ocpp_charger_status.json
(written by the service, read by the API), both keyed by charge-point id with
atomic writes. The charge point service lives in ocpp_client/server (central
system) and ocpp_client/client (charge point).
ocpp_client/chargers.json configures 12 charge points, CP-001 … CP-012:
"charge_points": [ { "cp_id": "CP-001", "connector_id": 1, "id_tag": "GESS123", "enabled": true } ]
cp_service.py runs every enabled entry in charge_points, so the container
presents 12 charge points against the one central system. The settings side
carries the matching dlb_ev_connector_id, but the cp_id ↔ dlb_ev_device_id
mapping (CP-00n ↔ ev_charger n) is not wired anywhere yet — see §11.
The simulator-wide parameters (server_url ws://ocpp-backend:9000/ocpp/{cp_id},
heartbeat_interval_s: 30, meter_interval_s: 5, max_power_kw: 22.0) are
already consistent with the settings defaults. All 12 charge points connect and
exchange Heartbeats with the central system on the test stack.
Note
max_power_kw: 22.0 in chargers.json is the same figure as the DLB default
dlb_ev_max_power_kw: 22. Keep them in step: the simulator is the yardstick
the EMS allocation is measured against.
7.2 Keeping the simulator and the EMS in step
The simulator's maps are a copy of the EMS's, and register_map_sync.py keeps
them honest: it fetches GET /api/v1/ems/register-maps from ems-backend and
writes every archive member over the local copy, never deleting anything. Run it
after the EMS side changes, not before.
It applies nothing when called with no arguments — with none it prints its docstring and returns 0, so a silent no-op looks like success:
# inside the simulator container
python3 register_map_sync.py --url http://ems-backend:8080/api/v1/ems/register-maps
The report ends with added / replaced / unchanged / left alone; the 12 EV
maps show as added: 12 on the first run. Replaced files are copied to
.register_map_backup first. The operator triggers the same apply through the
Register API (register_map_sync.sync(...)).
7.3 Verified on the test stack
| Check | Result |
|---|---|
| Servers listening | ports 1630–1641 open in bess-simulator-backend |
| Read path from the EMS | all 12 piles answer read_holding_registers from inside ems-backend — power 4000, session energy 4002, SOC 4020, session state 4060, charging 4064, OCPP status 4068, comm fault 4080, power limit 4122 |
| Map defaults are served | max_power_limit_kw (4122) reads 22, the DLB default |
| Write path | write_register(4122, 16) on piles 1 and 12 reads back and persists into the pile's map on disk |
| OCPP | CP-001 … CP-012 connected, each exchanging Heartbeats with the central system |
8. Dynamic load balancing
The EMS DLB function allocates available capacity across connected piles. The
settings side of this is implemented: every pile carries its own
dlb_ev_* block (21 keys — see
EV Charging Pile Settings).
Reported per pile: dlb_ev_enabled, dlb_ev_priority, dlb_ev_weight,
dlb_ev_max_power_kw, dlb_ev_min_power_kw, dlb_ev_max_current_a,
dlb_ev_min_current_a, dlb_ev_number_of_phases, dlb_ev_phase_assignment,
dlb_ev_connector_id, dlb_ev_power_ramp_up_kw_sec,
dlb_ev_power_ramp_down_kw_sec, dlb_ev_allow_pause, dlb_ev_allow_resume,
dlb_ev_session_priority, dlb_ev_energy_target_kwh, dlb_ev_departure_time,
dlb_ev_soc_target_percent, dlb_ev_offline_policy,
dlb_ev_fallback_current_a and dlb_ev_device_id.
The allocation loop itself is Pending. It must: detect connected piles, read
current consumption, compute headroom, allocate by priority then weight, request
limits (Modbus write or OCPP SetChargingProfile), then verify that the
simulated piles actually follow the assigned limits.
9. Diagnostics: SELF TEST and PAYLOAD DIAGNOSTIC TEST
Status: mode split implemented; EV payload tests pending.
EV piles join the existing diagnostic framework rather than getting a private
test path (diagnostic_tests.md). Since the
rename, the framework has two operational modes with different jobs, and which
one a test needs is part of the request:
| Test | Required mode |
|---|---|
| Pile communication, register read/write, OCPP connection | SELF TEST |
| EV charger alarm activation and clearance | SELF TEST |
| Charging power and current performance, charging efficiency | PAYLOAD DIAGNOSTIC TEST |
| Charging ramp rate, interruption and recovery, session performance | PAYLOAD DIAGNOSTIC TEST |
| Energy measurement accuracy | PAYLOAD DIAGNOSTIC TEST |
| Dynamic load-balancing response | PAYLOAD DIAGNOSTIC TEST |
SELF TEST (modes/self-test.md) verifies the EMS and
its communication; PAYLOAD DIAGNOSTIC TEST
(modes/diagnostic-test.md) measures connected
equipment. The former DIAGNOSTIC TEST mode is now PAYLOAD DIAGNOSTIC TEST; the
old name still resolves, and no numeric mode ID changed.
A request in the wrong mode is rejected with 409
payload_diagnostic_mode_required and is never silently switched:
$ curl -X POST .../api/v1/ems/diagnostic-tests -d '{"device_id":"ev_charger1"}'
HTTP 409 required_mode=PAYLOAD_DIAGNOSTIC_TEST current_mode=MANUAL
Results use the same XML reporting framework and the same TimescaleDB storage.
test_type is now classified PAYLOAD DIAGNOSTIC TEST or SELF TEST
(ems_alarm_diagnostics.py); rows written before the rename keep the historical
DIAGNOSTIC TEST value and stay readable.
10. Configuration and database integration
Every item below is part of "adding the category". The settings-side items are implemented; the device-side items are implemented as far as the device maps and the simulator go, and pending for the runtime features (polling, alarms, DLB, history).
| Item | Where | Status |
|---|---|---|
ems_control_setting.json (+ .template.json) |
emsConfig/ems/ |
Implemented — category + 12 devices + 21 DLB keys each |
EmsSettingTableSeeder.php, RegisterCommonDeviceTableSeeder.php |
ems-frontend/database/seeders |
Implemented — mirror the JSON |
| Device configuration files | emsConfig/ev_charger/ev_charger1..12/ |
Implemented — register map, modbus_config.json, write queue, last-value template, alarm codes, identity maps |
| Default and per-model register maps | same folders | Implemented — one 70-register default map; per-model overrides pending |
| Alarm configuration files | same folders | Implemented — 27 alarm codes; alarm evaluation wiring pending |
| EMS polling configuration | device.poll_interval_ms, device.save_interval_ms |
Implemented as settings; the poll scheduler does not yet pick the family up |
| Simulator configuration | emsConfig/ev_charger/, start_simulator.sh, ocpp_client/chargers.json |
Implemented — 12 Modbus servers + 12 OCPP charge points (§7) |
| EMS settings API | ems_settings_api.py |
Implemented — category flows through GET/PUT /api/v1/ems/settings |
| TimescaleDB storage and reporting | historian + active_alarm_records |
Pending for EV data and EV alarms |
10.1 Migrating and seeding the test deployment
php artisan migrate:fresh --seed does not drop ems_test_reports or
active_alarm_records. Both live on the timescale connection, and
migrate:fresh only clears the default connection, so the tables survive and
up() takes its already-exists branch. That branch used to re-create indexes
that were already there, so the first etr_idx_test_id aborted the whole chain:
SQLSTATE[42P07]: Duplicate table: relation "etr_idx_test_id" already exists
Fixed in ae28aa63: both migrations now create only the indexes missing from
pg_indexes, which also lets the branch do what its comment claims — finish a
partially applied migration rather than fail on it. active_alarm_records had
the opposite bug in the same branch and skipped its indexes entirely.
APP_ENV=production also makes the command prompt for confirmation, so pass
--force when running it non-interactively; without it the command answers "no"
and silently does nothing.
State verified afterwards on the test deployment: 359 migrations applied with
none pending, 12 piles in both scada_settings_json and
register_common_devices.component_details, and the rendered settings page lists
all 12 piles.
11. Open questions
- Logical register map — the discriminator and the OCPP payload → register mapping (§3.2).
- Model list — which charger models get a
register_full___<model>.jsonoverride, and what the model strings are. - Session identity — is a charging session an EMS concept (its own row) or just transient state in the last-value document?
Port allocation— settled:1630–1641are served by the simulator and no other family uses that range (§7.3).- OCPP version — the scaffold is OCPP 1.6; confirm whether 2.0.1 must be a separate charge-point service or a mode of the existing one.
- Charge-point identity — nothing maps
CP-00non the OCPP side toev_charger n/dlb_ev_device_id(§7.1). - The
ems_settingsrow — resolved. It no longer holds a pre-EV document.EmsSettingTableSeederwrites all 18general_settingsgroups includingev_charging_piles(12 piles, 21dlb_ev_*keys each) andRegisterCommonDeviceTableSeederwrites the matchingcomponent_details.ev_charging_pilesentry withno_of_components: 12, so a save from the settings editor round-trips the EV category instead of dropping it. Confirmed on the test deployment with a fullmigrate --seed(§10.1).
12. End-to-end verification checklist
Run in this order. Items 1, 2, 3, 4, 5, 6, 7 and 15 have been exercised on the test stack (item 6 by fault injection); the rest wait on the DLB, control and history work.
| # | Check | How |
|---|---|---|
| 1 | 12 piles configured | GET /api/v1/ems/settings → general_settings.ev_charging_piles has 12 devices |
| 2 | Independent Modbus per charger | connect to each of 1630–1641, read the register map |
| 3 | OCPP connectivity and messages | 12 charge points connected; boot, heartbeat, status, meter values observed |
| 4 | Register mapping and lastValue | poll a charger, confirm lastValue/ updates and validity/staleness marks |
| 5 | Polling interval | change poll_interval_ms, confirm the cadence changes without restart |
| 6 | Alarms | force a fault, confirm activation, severity, timestamp and clearance |
| 7 | Active alarms in TimescaleDB | query active_alarm_records for the EV device |
| 8 | Start / stop charging | command, acknowledgement, and session state change |
| 9 | Power and current limits | write a limit, confirm it persists and is reported back |
| 10 | DLB across chargers | allocate, then confirm each pile holds its assigned limit |
| 11 | Disconnection and recovery | kill a charger, confirm fault + stale values, restart, confirm recovery |
| 12 | Per-charger payload diagnostics | run the diagnostic test for one charger in PAYLOAD DIAGNOSTIC TEST mode |
| 13 | SELF TEST | run the mode, confirm EV piles appear in the report |
| 16 | Wrong-mode submit rejected | POST a payload test while another mode is active; expect 409 payload_diagnostic_mode_required (done) |
| 14 | Simulator frontend | monitor and control all 12 from the panel |
| 15 | PCS unaffected | confirm general_settings.pcs and PCS registers are byte-identical after every EV change |
13. Related documents
- EV Charging Pile Settings — every key, default and the synchronisation procedure
- Register map interface — the interface contract
- How to build
ems_register_full.json— register map construction - PCS Runtime JSON Files — per-device JSON files
- Last-value Templates — lastValue structure
- Alarm Mapping & Endpoints · Alarms API
- Device Identity Config · Device Folder Manager
- PCS Simulator · Start Simulator
Adjacent EV documentation. The SCADA/GESS platform docs (frontend repo,
docs_build_EV/) cover the other half of the story: registering a charger in the
platform, EV admin and permissions, connector setup and OCPP onboarding —
reference/EVCharger_Setup_Flow.md, reference/SCADA_Admin_Configure_EV.md,
reference/MoreConnectors_toEVCharger.md, reference/EV_FAQs.md. Those describe the
platform product; this page and its sibling describe the EMS side, where an EV
pile is a polled device with its own category. Keep them in step: a charger that
exists on the platform but not in general_settings.ev_charging_piles is invisible
to the EMS.