How to build emsConfig/ems/ems_register_full.json
Status: DRAFT for review. Facts are taken from the documents and source files named beside them. Anything marked TODO is not yet confirmed and must be filled in before the build script is written. Do not treat the TODO items as guesses to implement — they are open questions.
Source of truth for the interface: docs/integration/EnergySync_EMS100CX12S_register_map.md
(1180 lines).
1. What this file is
From the header table of the register-map document:
| Applies to | EMS backend EnergySyc_,
register map emsConfig/ems/ems_register_full.json |
| Interface | Modbus TCP, EMS register map server port 1540, unit id 1 |
| Direct ctrl| Modbus TCP, external control bridge port 1541, unit id 1 |
| Status | Verified against the running Docker stack (see Validation report) |EMS_ES100Cx12S
- It is served live, raw, per request, by
ems_settings_api.pyatGET /api/v1/ems/register-map(DEEPCOPILOT_PATCHES.md, rowEMS-REGISTER-MAP). - Expected size: 6,385 registers — "The exhaustive address-by-address list — all 6,385
registers ... is generated separately under
docs/reference/register-map/index.md" (register-map doc, §1). - Address range: 1 .. 32082 in the current map.
@0is invalid, and so is any address past the map's extent; the map is 1-based PDU addresses (§3).
2. Where it lives
EnergySyc_EMS_ES100Cx12S/emsConfig/ems/ems_register_full.json
Not emsConfig/ems_register_full.json — that path does not exist. The ems/ subdirectory is
part of it.
3. Inputs
Two categories, per §1: "The map is generated from the EMS's own register map file and the settings file."
3.1 Device register images
| family | source dir | model | register file | status |
|---|---|---|---|---|
| PCS | emsConfig/pcs/pcs1 .. pcs12 |
EPCS105, plus a ..._sinexcel_pws1_250k variant |
pcs_register_full___<model>.json |
active — 51 files |
| BESS energy meter | emsConfig/bess_energy_meter |
Schneider PM8000 |
bess_energy_meter_register_full.json |
active |
| AC | emsConfig/air_condition_unit |
ac_max, ac_pro, ac_std |
ac_register___<model>.json |
active — 4 files |
| grid / freq / solar meters | per family dir | ME231 |
meter_register*.json |
2 files |
| sensors | per family dir | DS1, TS1, SS1 |
sensor*.json |
12 files |
| BMU | emsConfig/bmu |
Cl1_P1 .. Cl1_P10 |
bmu_register_1..10.json |
see warning below |
Per-family *_modbus_config.json sits alongside and carries the device list, unit ids and
device-wide scale (§3.3: "Where a register declares no scale, the device-wide scale
applies").
The model-to-file mapping is tabulated in docs/reference/last_value_templates.md:142:
| PCS | emsConfig/pcs/pcs1 through pcs12 | EPCS105 | pcs_register_full.json | ...
| BESS energy meter | emsConfig/bess_energy_meter | Schneider PM8000 | bess_energy_m...
Selection rule — exactly one register file per device.
- Only files whose name ends in
_register_full.jsonare used. - Each device must have exactly one such file. If a device has none, or more than one, the build fails and reports the device — it does not guess.
- Files carrying a model or variant suffix after the extension stub
(
..._register_full___<model>.json), and every*.bak-*file, are excluded by this rule.
3.2 Settings-derived registers
emsConfig/ems/ems_control_setting.json. §2 lists it as an input, and §3.3 places the settings
registers among the scaled groups. TODO: confirm from §6–8 how these registers are keyed and
whether the set is derived dynamically from the settings file's keys or fixed.
4. Generation procedure, as documented
§1 — "The map is generated from the EMS's own register map file and the settings file, so it is the authoritative description of the interface."
§2 — "Device register maps | JSON on disk |
emsConfig/pcs/pcsN/pcs_register_full*.json| PCS register image. Written by the PCS client with the values it polls, read by the map server."
last_value_templates.md:91— "Each generated model starts with every addressable register from its referenced register map"
last_value_templates.md:103— "Do not invent an address or data type. Confirm both against the commissioned device register map."
last_value_templates.md:332— "This regenerates all templates with every addressable register from each model's register map"
last_value_templates.md:366— validation rule: "The register exists in the referenced register map."
TODO (blocking): the command or tool referred to at last_value_templates.md:332. Also
whether the same generator produces both the last-value templates and ems_register_full.json,
or whether the map is a separate step.
5. Adjustments already applied to this file
From DEEPCOPILOT_PATCHES.md:
| patch | effect |
|---|---|
EMS-REGISTER-MAP |
ems_settings_api.py routes GET /api/v1/ems/register-map; serves ems_register_full.json raw, read per request |
EMS-REGISTER-MAP-GROUPS |
9 command registers added (ac1, fss1); 2 bitmap-definition keys preserved |
EMS-REGISTER-MAP-PROVENANCE |
pcs1 nodes re-stamped to the map the merge resolves (___sinexcel_pws1_2...) |
A rebuild is therefore a merge and re-stamp, not a from-scratch generation. The 2
bitmap-definition keys must survive, the 9 command registers must be re-applied, and the pcs1
nodes must be re-stamped to whichever pcs_register_full___* variant the merge resolves.
6. Output schema
Verified — the per-device source shape, from
EMS_template_codes/ems_modbus_server_dynamic_nofilter_v14.py:15:
{ device_id, component_type, model, read_batches, categories{ <cat>{ read_only{}, read_write{} } } }
Also confirmed by reading a real file
(emsConfig/pcs/pcs1/pcs_register_full___sinexcel_pws1_250k.json): 7 top-level keys starting
device_id, component_type, model, read_batches; device_id -> "pcs1".
Verified — the consumers' expectation: a flat map keyed by integer address.
bess_energy_meter_modbus_server_simulator_v9.py declares:
def load_register_map(json_path) -> Tuple[Dict[int, dict], Dict[int, RegisterDef]]
and ems_modbus_client_v5.py:6 states "Now uses a flat ems_register_full.json structure".
TODO (blocking): the per-register entry fields — name, dtype, scale, category, device — and how a register's device/provenance is expressed when the keys are plain addresses. Confirm from §6–8 of the register-map document.
7. Validation
- Register count is 6,385 (§1).
- Reads:
@1and@32082are inside the current map;@0returns exception 02 (§3). The upper boundary must be re-measured against the deployed server. - Function codes 3, 6, 16 are the meaningful ones; ½/⅘ answer with empty data (§3.1).
- Load the rebuilt file through
load_register_map()and compare the address count against the sum of the sources. - Compare against the generated reference list under
docs/reference/register-map/index.md. - Port 1540 must still answer after the rebuild — the map is read per request, so no restart should be needed.
- TODO: quote the Validation report (§14) as the formal acceptance test.
7a. Post-generation coverage test (mandatory)
The build is not complete until every key of every source file is proven present in the output.
For each device register file selected in section 3.1:
- Load the device file and collect its complete key set — all keys, recursively.
- Load the generated
ems_register_full.json. - For every key collected in step 1, assert it is present in the generated map and associated with that device.
- Report per-device key counts and the list of any missing keys.
A single missing key fails the build. The test must exit non-zero, print the device and the
missing key(s), and leave the previous ems_register_full.json in place rather than a partial
file.
This is a coverage check, not a sample check: it walks every key of every device, not a subset, and it is what proves the map is complete rather than merely plausible.
8. Rebuild procedure (step by step)
- Back up the current
emsConfig/ems/ems_register_full.json. - Collect inputs for every active family, excluding all
*.bak-*files. - Run the generator to fold the per-device register images into the flat address-keyed map.
- Re-apply the two documented adjustments: the 9
ac1/fss1command registers, and thepcs1provenance re-stamp. - Validate per section 7 — count, boundary addresses, loader round-trip.
- Confirm
GET /api/v1/ems/register-mapserves the new content.
9. Open questions to settle before the script is written
- The generator command/tool referenced at
last_value_templates.md:332. - The per-register schema (§6–8) — the single biggest gap.
- The §14 validation report and its exact acceptance criteria.
- Whether BMU maps belong in the combined file, given
docs/reference/bmu_simulator.md:40: "TheemsConfig/bmu/*.jsonregister maps are not actively used anymore in this version." - Which PCS variant is the "resolved" one for the re-stamp.
- Whether settings-derived registers are fixed or generated from the settings file's keys.
- The warning at
docs/reference/pcs_runtime_json_files.md:179-181: "None of those keys exists in the currentpcs_register_full.json... The current map is therefore functionally unused with EPCS105" — establish whether a rebuild changes runtime behaviour at all.
Known warnings from the documentation
- "Do not invent an address or data type. Confirm both against the commissioned device register
map." (
last_value_templates.md:103) - "The
emsConfig/bmu/*.jsonregister maps are not actively used anymore in this version." (bmu_simulator.md:40) - "The current map is therefore functionally unused with EPCS105, even though the helper is ..."
(
pcs_runtime_json_files.md:181) - The control loop re-reads
ems_control_setting.jsonevery cycle (nominally 1 s), so map/settings changes take effect without a restart (register-map doc §2).