Skip to content

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 (default 5000) and device.save_interval_ms (default 15000), 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 directory lastValue/ 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

  1. Logical register map — the discriminator and the OCPP payload → register mapping (§3.2).
  2. Model list — which charger models get a register_full___<model>.json override, and what the model strings are.
  3. Session identity — is a charging session an EMS concept (its own row) or just transient state in the last-value document?
  4. Port allocation — settled: 1630–1641 are served by the simulator and no other family uses that range (§7.3).
  5. 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.
  6. Charge-point identity — nothing maps CP-00n on the OCPP side to ev_charger n / dlb_ev_device_id (§7.1).
  7. The ems_settings row — resolved. It no longer holds a pre-EV document. EmsSettingTableSeeder writes all 18 general_settings groups including ev_charging_piles (12 piles, 21 dlb_ev_* keys each) and RegisterCommonDeviceTableSeeder writes the matching component_details.ev_charging_piles entry with no_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 full migrate --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

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.