Skip to content

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:

  1. Open the template in the required device folder.
  2. Find the active model under models.
  3. Add or remove entries in its readings array.
  4. Copy register metadata from the model's referenced register_map file.
  5. Keep key identical to the decoded output key used by the client.
  6. Set include_in_last_value and send_to_api for the required destination.
  7. 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: true includes the key in the API reading.
  • include_in_last_value: true includes 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_device currently 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:

  • key exactly 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.