Skip to content

ems_register_full.json - the EMS register map

EnergySyc_EMS_ES100Cx12S/emsConfig/ems/ems_register_full.json is the single register map the EMS Modbus server serves on port 1540 (unit 1). Every telemetry value, every EMS setting and every PCS / BMU / meter / auxiliary control register a client can see is declared in this one file.

The current map declares 6385 registers across 73 device blocks - 5879 read-only and 506 read-write - spanning addresses @1 .. @32082.

Do not hand-edit it for structure changes: it is generated. Use the generator described under Regenerating the map.

Who touches the file

Process Direction What it does
EMS_template_codes/ems_modbus_server_dynamic_nofilter_v14.py reads Loads the map (--json, default emsConfig/ems_register_full.json), serves the registers over Modbus TCP, and follows the map's mtime to pick up edits without a restart
EnergySyc_EMS_ES100Cx12S/ems_merge_register_map.py writes structure Merges every device register map into the full map, assigns the address plan, and annotates ems_control_setting.json with the layout
EnergySyc_EMS_ES100Cx12S/ems_sync_register_values.py writes values Round-trips values between this map and the device maps (--direction to-ems / to-device) and recomputes the plant aggregates
EnergySyc_EMS_ES100Cx12S/tools/generate_register_map_docs.py reads Generates the published address plan and the per-area reference pages from the map
ems_external_control_bridge.py reads (indirectly) Reads a PCS device map directly for SOC; it never parses the full map

The device maps under emsConfig/pcs, emsConfig/bmu, emsConfig/... are the upstream sources: the full map is a flattened superset of them, with each device's registers copied into its own address block.

How the server consumes the map

  1. Format detection. A file is treated as structured when its root object contains a categories key; anything else is read as a flat map (address-keyed objects or a list of nodes with address). Only the structured form is documented here.
  2. Flattening. The structured map is flattened to address -> node. Only two levels below categories are parsed by the merge tool, so the category name carries all the structure (<block>__<subcategory>, <block>__control__<subcategory>, plant__<metric>).
  3. Lazy reads. Nothing is bulk-loaded into the datastore. A register's value is encoded and pushed into the databank the first time it is seeded, and read on demand. Computed registers are recomputed on read (see Computed registers).
  4. Reload on change. A watcher thread polls the file's mtime. When it changes the server rebuilds the address index, refreshes the structured context, grows the databank to cover any appended addresses, and seeds only the new addresses - so values already served, including client writes, are never clobbered.

Because the span grows on reload, appending registers to the map does not require restarting the server; a register that arrives with the file is readable after the next poll. The databank is only ever sized from the map itself, so a register that exists in the map is never answered with an illegal data address exception.

Top-level schema

Key Type Contents
device_id string Block id of the owner: ems
component_type string EMS
model string EMS100CX12S
read_batches array (4) Coalesced read plans for the EMS-owned telemetry the clients fetch in one request: Energies (@2700 x 50), Currents (@3000 x 20), Voltages (@3020 x 20), Power & PF & Freq (@3054 x 120) - each with name, start_register, count, word_size, endianness
categories object (483) The registers themselves - see below
structure object The merge tool's declaration of the scheme: device_telemetry, device_controls, plant_aggregates, block_base (25000), preserved_categories
device_index object (73) Per block: model, source_map, base, end, registers, nodes, telemetry_categories, control_categories, read_batches
control_index object (33) For each block that exposes writable registers: name, category, ems_address, device_address, data_type - the list a control client needs. Blocks with no writable register are absent, so this is smaller than device_index
aggregate_index object (12) The computed plant registers: category, operation, sources, ems_address, unit
layout object Mirror of structure for consumers that want the plan without parsing the scheme text: scheme, block_base, category_prefix, preserved_categories, generated
settings_index object (158) Keyed by settings key (e.g. functions__Peak_Shaving__soc_limits__min_soc_pct): category, group, ems_address, data_type, settings_path. 157 register nodes carry the same settings_* triple

categories

Each entry is a block whose body holds one or both access buckets, and every bucket maps a register name to its node. Groups may nest one extra level - that is how the settings tree is represented (functions -> Peak_Shaving -> soc_limits -> min_soc_pct).

"categories": {
  "pcs1__control__remote_control": {
    "read_write": {
      "active_power_set_kw": {
        "address": 25299,
        "data_type": "INT16",
        "registers": 1,
        "value": 0,
        "rw_type": "read_write",
        "device": "pcs1",
        "device_map": "pcs/pcs1/pcs_register_full___epcs105.json",
        "device_category": "remote_control",
        "device_address": 3415
      }
    }
  },
  "ems__control": {
    "read_write": {
      "functions__Peak_Shaving__soc_limits__min_soc_pct": {
        "address": 44,
        "data_type": "INT16U",
        "registers": 1,
        "value": 10,
        "device": "ems",
        "settings_source": "ems/ems_control_setting.json",
        "settings_path": ["functions", "Peak_Shaving", "min_soc_pct"],
        "settings_kind": "int"
      }
    }
  }
}

The three naming families, and what they mean:

Category shape Access Meaning
<block>__<subcategory> read_only Device telemetry mirrored from a device map (PCS, BMU, UPS, AC, cooling, fire, sensors, meters)
<block>__control__<subcategory> read_write Device control registers mirrored from a device map
plant__power, plant__voltage, plant__current, plant__ac_power read_only Plant aggregates computed by the server, not mirrored from any device
ems__control, ems__status both EMS settings and status, backed by ems_control_setting.json
alarms, energies, currents, voltages, power, power_factor, frequency read_only Preserved EMS telemetry categories - they keep the addresses they were first published with

Node fields

Field Nodes Meaning
address 6385 PDU address in the served map. Add 40001 for tools that display 4xxxx holding registers
data_type 6385 Wire encoding - see Data types
registers 6385 Registers occupied (1, 2 for 32-bit types)
value 5148 The value the server serves when the node has no other source. For device-mirrored and aggregate nodes this is only the seed
device 6323 Block that owns the register (pcs3, bmu1, ups1, ems, ...)
device_map 6165 Source device map, relative to emsConfig/
device_category 6165 Category inside the source device map
device_address 6165 Address inside the source device map (= address - block base, except for preserved EMS categories)
rw_type 4880 Per-node read_only / read_write, used where the bucket is not enough (device mirrors)
settings_source / settings_path / settings_kind 157 Settings backing: file, key path, and kind (enum, control_mode, int, bool, float)
enum 48 Value-to-name map for coded registers
unset 43 Settings key that is absent from the settings file today; the register serves 0 until it is set
derived 1 Register the EMS computes rather than stores (ems__status.active_function_count)
aggregate / expression / unit 12 Computed register: aggregate group, the expression evaluated on read, engineering unit
relocated_from 1 Original address, when the merge had to move a register to resolve an overlap inside the preserved EMS section

Backing kinds

Every register is backed in exactly one of four ways. What a client writes and what it reads back depends on which one applies.

1. Device mirrors (6165 registers)

Telemetry and control registers for PCS, BMU, UPS, AC, cooling, fire safety, sensors and meters. The node carries device_map + device_category + device_address, which is how a value can be traced back to the device map file.

  • Read: the value last written into the map, or the value a client wrote.
  • Write: the write is applied to the map (and, for backed control registers, pushed to the device map file). For PCS setpoints, the path the EMS itself uses to command the hardware is its task path - control_logic_updated.py writes pcs_write_queue.json, and the PCS client drains it. A setpoint written straight into a pcsN__control__* register lands in the device map; commanding the inverter from an external system is done through the external-control bridge on port 1541 (see External PCS control path).

2. Settings-backed registers (157 registers)

ems__control and the EMS status block: everything from the operating mode to each function's SOC limits. Backed by ems_control_setting.json (settings_source), with the key path in settings_path.

  • Read: the current contents of the settings file.
  • Write: the server updates the register and rewrites the settings file. Two gates apply and both are silent: writes to a read_only node, and writes of any kind while ems_control_mode is local_control / Internal_EMS. The FC6 echo returns the value you sent while the register and the file stay unchanged - always read the register back after a write. Details and the verified rejection matrix: Operational task preconditions.

3. Preserved EMS telemetry (50 registers)

alarms, energies, currents, voltages, power, power_factor, frequency. These have no device_map and no settings key: they are seeded from value and keep their original addresses so existing readers keep working.

Read them as placeholders. They are not refreshed from a device by the map itself; a register that is part of a device block is the one to read for live data (for example grid_meter1 for the grid meter, not the power category).

4. Computed registers (12 registers)

The plant aggregates in plant__power, plant__voltage, plant__current and plant__ac_power. They are declared twice on purpose - as a node with aggregate / expression / unit, and in aggregate_index with the operation and the sources the expression reads.

The server computes them on read: when a read overlaps an aggregate address, the expression is evaluated against the current source values and the result is encoded into the databank. aggregate_index drives this generically, so a different plant layout only needs a different map.

Register Address Operation Sources
plant__power.total_active_power_kw @32061 sum(voltage*current/1000) bc_battery_cluster voltage x current, for every PCS in the spec
plant__power.total_current_a @32063 sum(current) bc_battery_cluster.cluster_current_a
plant__power.pcs_online_count @32065 count(voltage valid) bc_battery_cluster.cluster_voltage_v
plant__voltage.dc_voltage_avg_v / _min_v / _max_v @32066 / @32068 / @32070 mean / min / max of voltage bc_battery_cluster.cluster_voltage_v
plant__current.dc_current_avg_a / _max_a / _min_a @32072 / @32074 / @32076 mean / max / min of current bc_battery_cluster.cluster_current_a
plant__ac_power.total_active_power_kw / total_reactive_power_kvar @32078 / @32080 sum(...) pcs three_phase_total_active_power_kwh / three_phase_total_reactive_power_kvar, active units only
plant__ac_power.reporting_pcs_count @32082 count(... valid) pcs three_phase_total_active_power_kwh, active units only

The DC aggregates read every block listed in sources.blocks. The AC aggregates set active_only and read only the blocks marked active in the settings file. Two naming wrinkles in the AC group are worth knowing: the source field behind the power total is named three_phase_total_active_power_kwh in the PCS map, and its source category is pcs (the PCS AC measurement block) rather than bc_battery_cluster.

See the generated Plant aggregates page for the full per-register source lists.

Reading over Modbus

Property Value
Endpoint 1540 TCP, unit 1 (host mapping EMS_MODBUS_SERVER_PORT in the compose file)
Address style PDU addresses, exactly as in the map; add 40001 for 4xxxx clients
Block rule One request must stay inside the databank. A block is address-contiguous, but the map only fills the registers the device maps declare, so size a request from the addresses you actually need
Highest address @32082 (plant__ac_power); reading past the last declared register returns an illegal data address exception
Multi-register values Served high word first, per the map's endianness

Writing over Modbus

Guard Behaviour
Node is read_only Refused silently: the write is replaced by the old value, no exception is returned
ems_control_mode is local_control Refused silently for every register, including settings
ems_control_mode is scada_control or external_control Accepted
Accepted write Register updated, settings file rewritten for settings-backed nodes, device map written for device mirrors

The control mode itself is switched from the device UI / settings API, not over Modbus - the Modbus server will not accept the change while the mode is local_control.

Two scale rules to keep in mind

  • Register scaling. The engineering unit of a value is scale on the register node when present, otherwise the device scale. SOC and SOH need scale: 1 (percent) while power in the same device uses scale: 0.1 (kW), so those nodes declare scale explicitly rather than changing the device default.
  • Unit membership. A plant aggregate reads its sources regardless of whether the unit is active, unless the spec sets active_only. Inactive units contribute their last value, so check reporting_pcs_count next to a total.

Regenerating the map

cd EnergySyc_EMS_ES100Cx12S

# structure changes (new device map, new category, new register)
python3 ems_merge_register_map.py --dry-run    # report what would change
python3 ems_merge_register_map.py              # incremental: keeps existing addresses
python3 ems_merge_register_map.py --rebuild    # reassign every address (breaks clients)

# values only (device maps <-> full map, plus aggregates)
python3 ems_sync_register_values.py --check
python3 ems_sync_register_values.py --direction to-ems
python3 ems_sync_register_values.py --direction to-device   # SCADA writes back

# publish the reference pages
python3 tools/generate_register_map_docs.py
python3 tools/generate_register_map_docs.py --check   # non-zero when pages are stale

The incremental default is the safe one: it adds new registers and leaves existing addresses alone, so live clients keep working. --rebuild reassigns the whole plan and invalidates every address a client has cached.

Every unit must also be declared in the BLOCKS table of ems_merge_register_map.py. A device map that no block declares still sits on disk but is never published: the block is absent from device_index, and annotate_control_setting() skips it without complaint, so the unit's settings entry keeps whatever register_map was written there previously. The map carried 30 blocks until the remaining meter and air-conditioning units were declared; a fresh generation now yields 73.

ems_merge_register_map.py also annotates ems_control_setting.json with the resulting device_index / control_index, which is how the settings file and the map stay in step.

Verifying the served map

# mode / status as the client sees them (PDU addresses, unit 1)
python3 - <<'PY'
from pymodbus.client import ModbusTcpClient
c = ModbusTcpClient("192.168.6.116", port=1540); c.connect()
print(c.read_holding_registers(1, 3, slave=1).registers)   # [mode, control_mode, status]
print(c.read_holding_registers(32061, 2, slave=1).registers)  # total_active_power_kw
c.close()
PY

Expected: @1 holds the mode that was accepted, @3 reports the mode the EMS loop is actually running, and the aggregate read returns a computed float rather than the JSON seed. If an aggregate reads as its seed, the server is serving a stale copy of the map - check the file's mtime against the server log.