Last-value template configuration
Purpose
lastValue_template.json controls which decoded device values are retained in the current last-value snapshot and sent to the EMS sensor-data API.
The active PCS, grid-meter, and solar-meter clients use the templates before writing their lastValue/*.json snapshots and before posting readings to:
http://ems-nginx/api/v1/ems/insert-ems-sensor-data
Database inserts and timestamped historical batch files retain the complete decoded record.
Template locations
PCS templates are stored per device:
emsConfig/pcs/pcs1/lastValue_template.json
emsConfig/pcs/pcs2/lastValue_template.json
...
emsConfig/pcs/pcs12/lastValue_template.json
Other templates are stored in their device configuration folders, for example:
emsConfig/grid_energy_meter/lastValue_template.json
emsConfig/solar_energy_meter/lastValue_template.json
emsConfig/frequency_meter/lastValue_template.json
emsConfig/bess_energy_meter/lastValue_template.json
emsConfig/air_condition_unit/lastValue_template.json
File structure
Each template contains one or more model definitions:
{
"schema_version": 1,
"component_type": "pcs",
"device_ids": ["pcs1"],
"models": {
"EPCS105": {
"register_map": "pcs_register_full.json",
"readings": [
{
"key": "pcs_soc_state_of_charge_item",
"register_name": "soc_state_of_charge_item",
"address": 3005,
"data_type": "UINT16",
"registers": 1,
"access": "read_only",
"read_from_device": true,
"include_in_last_value": true,
"send_to_api": true
}
]
}
}
}
Root fields
| Field | Meaning |
|---|---|
schema_version |
Template format version. Currently 1. |
component_type |
Device family, such as pcs or gridEnergyMeter. |
device_ids |
Device instances that use the template. |
models |
Model-specific register selections. |
Reading fields
| Field | Meaning |
|---|---|
key |
Exact key emitted by the device client and placed in API/last-value JSON. |
register_name |
Register name from the source register map. |
address |
Modbus register address in decimal. |
data_type |
Decoder type, such as UINT16, INT16, UINT32, FLOAT32, or BOOL. |
registers |
Number of consecutive 16-bit Modbus registers used by the value. |
access |
Register-map access classification. |
read_from_device |
Declares that the register is intended for polling. See the runtime note below. |
include_in_last_value |
Include the field in lastValue/<device>_lastValue.json. |
send_to_api |
Include the field in the API reading object. |
Configure the default readings
Each generated model starts with every addressable register from its referenced register map. To reduce the selection:
- Open the template in the required device folder.
- Find the active model under
models. - Add or remove entries in its
readingsarray. - Copy register metadata from the model's referenced
register_mapfile. - Keep
keyidentical to the decoded output key used by the client. - Set
include_in_last_valueandsend_to_apifor the required destination. - Restart the corresponding client process.
For PCS, source register names receive the pcs_ prefix. For example, soc_state_of_charge_item becomes pcs_soc_state_of_charge_item.
Do not invent an address or data type. Confirm both against the commissioned device register map.
Add one PCS register
Suppose pcs_register_full.json contains:
"soh_state_of_health_item": {
"address": 3006,
"data_type": "UINT16",
"registers": 1,
"rw_type": "read_only"
}
Add this object to the EPCS105.readings array:
{
"key": "pcs_soh_state_of_health_item",
"register_name": "soh_state_of_health_item",
"address": 3006,
"data_type": "UINT16",
"registers": 1,
"access": "read_only",
"read_from_device": true,
"include_in_last_value": true,
"send_to_api": true
}
You can remove any entries that are not needed by the installation. Keep power, energy, power factor, SOC, and critical alarm fields required by EMS control and monitoring.
Configure other device types
The same schema is used for every device family. The important differences are the template location, model name, source register map, and output-key prefix.
| Device | Template folder | Model | Register map | Output-key prefix | Runtime filtering |
|---|---|---|---|---|---|
| PCS | emsConfig/pcs/pcs1 through pcs12 |
EPCS105 |
pcs_register_full.json |
pcs_ |
Active |
| Grid meter | emsConfig/grid_energy_meter |
Schneider PM8000, ME231 |
gridMeter_register_default.json, gridMeter_register_ME231.json |
gridMeter_ |
Active |
| Solar meter | emsConfig/solar_energy_meter |
Schneider PM8000 |
solarMeter_register.json |
solarMeter_ |
Active |
| Frequency meter | emsConfig/frequency_meter |
Schneider PM8000 |
frequencyMeter_register.json |
frequencyMeter_ |
Template prepared |
| FFR meter | emsConfig/ffr_energy_meter |
Schneider PM8000 |
ffrMeter_register.json |
ffrMeter_ |
Template prepared |
| BESS energy meter | emsConfig/bess_energy_meter |
Schneider PM8000 |
bess_energy_meter_register_full.json |
bess_energy_meter_ |
Template prepared |
| BMU | emsConfig/bmu |
generic_lfp_bms |
bmu_register_1.json through bmu_register_10.json |
None | Template prepared |
| Air conditioner | emsConfig/air_condition_unit |
Generic Industrial AC Modbus Profile v1.0 |
ac_register.json |
ac_ |
Template prepared |
| Liquid cooling | emsConfig/liquid_cooling_unit |
CHILLER-X200 |
cooling_register.json |
cooling_ |
Template prepared |
| Fire safety | emsConfig/fire_safety_system |
Generic Aerosol Fire Suppression Modbus Profile v1.0 |
fss_register.json |
fss_ |
Template prepared |
| Sensor block | emsConfig/sensor_block |
SensorB Block Profile v1.0 |
sensorB_register.json |
sensorB_ |
Template prepared |
Active means the current production client imports last_value_template.py and applies the destination flags. Template prepared means the configuration file exists, but that device's polling process must call filter_last_value() before the flags affect runtime output.
Grid meters
The grid-meter template contains a separate section for each supported model:
{
"models": {
"Schneider PM8000": {
"register_map": "gridMeter_register_default.json",
"readings": []
},
"ME231": {
"register_map": "gridMeter_register_ME231.json",
"readings": []
}
}
}
Set each grid meter's model in ems_control_setting.json. The client selects the corresponding model section and register map. Do not add an ME231 register to the PM8000 section unless both devices use the same address and encoding.
Example ME231 active-power entry:
{
"key": "gridMeter_active_power_total_kw",
"register_name": "active_power_total_kw",
"address": 3066,
"data_type": "FLOAT32",
"registers": 2,
"access": "read_only",
"read_from_device": true,
"include_in_last_value": true,
"send_to_api": true
}
After restart, check the instance-specific output. The first meter uses the legacy filename; additional meters include their number:
lastValue/gridMeter_lastValue.json
lastValue/gridMeter2_lastValue.json
...
Solar meter
Edit:
emsConfig/solar_energy_meter/lastValue_template.json
Example power-factor entry:
{
"key": "solarMeter_pf_total",
"register_name": "pf_total",
"address": 3150,
"data_type": "FLOAT32",
"registers": 2,
"access": "read_only",
"read_from_device": true,
"include_in_last_value": true,
"send_to_api": true
}
The filtered snapshot is written to:
lastValue/solarMeter_lastValue.json
Frequency, FFR, and BESS energy meters
These meter templates use the same general PM8000 pattern as the grid and solar meters. Keep the device-specific key prefix:
frequencyMeter_active_power_total_kw
ffrMeter_active_power_total_kw
bess_energy_meter_active_power_total_kw
Their default templates prioritize total active, reactive, and apparent power, energy, total power factor, and alarm registers. The current production startup script does not launch clients that consume these three templates, so adding or removing fields will not affect runtime until their client calls filter_last_value().
BMU
The BMU folder contains register maps for Cl1_P1 through Cl1_P10. They share the generic_lfp_bms model and one template selection.
BMU keys do not receive an additional prefix. Examples include:
soc
soh
pack_general_alarm
cell_overvoltage_alarm
cell1_voltage_v
When adding a BMU value, confirm that the register is valid for all BMU instances or introduce separate model definitions and register maps.
AC, cooling, fire safety, and sensor blocks
Use the source map named in the device table and retain its client output prefix. The defaults emphasize operational measurements and alarms:
- AC: power, consumed energy, alarm bitmap, fault state, temperatures, and input status.
- Cooling: cooling power, consumed energy, alarm code, temperatures, speeds, mode, and setpoint.
- Fire safety: alarm/fault bitmaps and gas, smoke, and heat alarm thresholds/states.
- Sensor block: alarm bitmap, flood inputs, and door inputs.
These templates are ready for configuration but are not currently applied by a production client in start_ems_client_in_docker.sh.
Enable or disable a destination
A reading can be kept locally without sending it remotely:
{
"key": "gridMeter_current_l1_a",
"register_name": "current_l1_a",
"address": 1000,
"data_type": "FLOAT32",
"registers": 2,
"access": "read_only",
"read_from_device": true,
"include_in_last_value": true,
"send_to_api": false
}
It can also be sent to the API without being retained in the local latest-value file by reversing those two flags. Keep at least one field enabled for each destination. If no fields are enabled for a destination, the filter treats the template as invalid and fails open with the full reading.
Model selection
The client selects the model section using the model from ems_control_setting.json.
Model comparison ignores punctuation and letter case. A configured PCS model such as EPCS105-AM resolves to the single EPCS105 template definition. Grid templates contain separate Schneider PM8000 and ME231 definitions.
When a template contains only one model, that definition is also used as the fallback.
API payload
readings is sent as an array of JSON objects, not as an escaped JSON string:
{
"gateway_id": "GTW-ems100CX",
"multyData": [
{
"component_type": "EMS",
"device_id": "PCS1",
"model": "EPCS105-AM",
"readings": [
{
"timestamp": 1789198617103,
"pcs_timestamp": 1789198617103,
"pcs_soc_state_of_charge_item": 50
}
]
}
]
}
If an API response or database value appears as "{\"timestamp\":...}", the receiving application has encoded the JSON object a second time. The EMS sender rejects pre-encoded string readings.
Regenerate defaults
From the EMS application directory:
python3 generate_last_value_templates.py
This regenerates all templates with every addressable register from each model's register map. It overwrites manual removals and flag changes. Commit or back up customized templates before running it.
Runtime behavior
send_to_api: trueincludes the key in the API reading.include_in_last_value: trueincludes the key in the local latest-value snapshot.- Timestamps and device identity metadata are retained automatically.
- A missing or invalid template fails open in the polling clients: the complete reading is sent and a warning is logged.
- PCS control setpoint publishing requires a complete current PCS snapshot. It does not send or save a setpoint-only record when a configured template field is missing.
read_from_devicecurrently documents polling intent. The active clients still decode their complete register maps before applying template output filters.
Validation and troubleshooting
Validate JSON syntax:
python3 -m json.tool emsConfig/pcs/pcs1/lastValue_template.json >/dev/null
Inspect the latest local result:
jq . lastValue/pcs1_lastValue.json
Enable outgoing API payload logging:
export EMS_API_DEBUG_JSON=1
Restart the EMS clients after changing a template. If a field is missing or null, confirm that:
keyexactly matches the decoded key in the full device reading.- The register exists in the referenced register map.
- The address, type, width, and endianness match the physical device.
- The relevant selection flag is
true. - The configured device model resolves to the intended template model.