Skip to content

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.py at GET /api/v1/ems/register-map (DEEPCOPILOT_PATCHES.md, row EMS-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. @0 is 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.json are 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: @1 and @32082 are inside the current map; @0 returns 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:

  1. Load the device file and collect its complete key set — all keys, recursively.
  2. Load the generated ems_register_full.json.
  3. For every key collected in step 1, assert it is present in the generated map and associated with that device.
  4. 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)

  1. Back up the current emsConfig/ems/ems_register_full.json.
  2. Collect inputs for every active family, excluding all *.bak-* files.
  3. Run the generator to fold the per-device register images into the flat address-keyed map.
  4. Re-apply the two documented adjustments: the 9 ac1/fss1 command registers, and the pcs1 provenance re-stamp.
  5. Validate per section 7 — count, boundary addresses, loader round-trip.
  6. Confirm GET /api/v1/ems/register-map serves the new content.

9. Open questions to settle before the script is written

  1. The generator command/tool referenced at last_value_templates.md:332.
  2. The per-register schema (§6–8) — the single biggest gap.
  3. The §14 validation report and its exact acceptance criteria.
  4. Whether BMU maps belong in the combined file, given docs/reference/bmu_simulator.md:40: "The emsConfig/bmu/*.json register maps are not actively used anymore in this version."
  5. Which PCS variant is the "resolved" one for the re-stamp.
  6. Whether settings-derived registers are fixed or generated from the settings file's keys.
  7. The warning at docs/reference/pcs_runtime_json_files.md:179-181: "None of those keys exists in the current pcs_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/*.json register 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.json every cycle (nominally 1 s), so map/settings changes take effect without a restart (register-map doc §2).