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
- Format detection. A file is treated as structured when its root object contains a
categorieskey; anything else is read as a flat map (address-keyed objects or a list of nodes withaddress). Only the structured form is documented here. - Flattening. The structured map is flattened to
address -> node. Only two levels belowcategoriesare parsed by the merge tool, so the category name carries all the structure (<block>__<subcategory>,<block>__control__<subcategory>,plant__<metric>). - Lazy reads. Nothing is bulk-loaded into the datastore. A register's
valueis 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). - 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.pywritespcs_write_queue.json, and the PCS client drains it. A setpoint written straight into apcsN__control__*register lands in the device map; commanding the inverter from an external system is done through the external-control bridge on port1541(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_onlynode, and writes of any kind whileems_control_modeislocal_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
scaleon the register node when present, otherwise the devicescale. SOC and SOH needscale: 1(percent) while power in the same device usesscale: 0.1(kW), so those nodes declarescaleexplicitly 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 checkreporting_pcs_countnext 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.