EMS Device ID, Model and Gateway Resolution
Required configuration rule
There is one gateway for the complete EMS.
EMS gateway priority
The gateway ID must be resolved in this order:
emsConfig/ems/ems_control_setting.jsondevice.gateway_idemsConfig/ems/ems_control_setting.jsonmetadata.gateway_id(compatibility fallback)emsConfig/ems/ems_api_config.jsonems_gateway.gateway_id- Existing
*_data_api.gateway_idvalues are accepted only as legacy fallback.
The gateway ID is not a per-device setting.
Device ID and model priority
For every PCS, grid meter, solar meter, frequency meter, FSS, AC unit, cooling unit, door sensor, flood sensor, smoke detector, heat sensor, temperature sensor and sensor block:
- Read
device_idandmodelfrom that device's entry inems_control_setting.json. - If either value is missing/empty, read only that missing value from the corresponding section of
ems_api_config.json. - If the value is absent in both files, treat the identity as incomplete and do not invent a model number.
Preferred control-setting structure
{
"device": {
"gateway_id": "GTW-ems100CX"
},
"general_settings": {
"pcs": {
"pcs1": {
"status": "active",
"device_id": "PCS1",
"model": "E-215",
"device": {
"ip": "bess-simulator-backend",
"port": 1501,
"unit_id": 5
}
}
},
"grid_meters": {
"grid_meter1": {
"status": "active",
"device_id": "GRIDMETER1",
"model": "PM8000",
"device": {
"ip": "bess-simulator-backend",
"port": 1513,
"unit_id": 2
}
}
},
"solar_meters": {
"solar_meter1": {
"status": "active",
"device_id": "SOLARMETER1",
"model": "PM8000",
"device": {
"ip": "bess-simulator-backend",
"port": 1514,
"unit_id": 3
}
}
}
}
}
API fallback structure
The API config is primarily for URL/token/timeout/SSL settings, but may contain fallback identity values.
{
"ems_gateway": {
"gateway_id": "GTW-ems100CX"
},
"pcs_data_api": {
"url": "http://ems-nginx/api/insert-multi-device-data",
"device_ids": {
"pcs1": "PCS1",
"pcs2": "PCS2"
},
"models": {
"pcs1": "E-215",
"pcs2": "E-215"
}
},
"grid_meter_data_api": {
"device_id": "GRIDMETER1",
"model": "PM8000"
},
"solar_meter_data_api": {
"device_id": "SOLARMETER1",
"model": "PM8000"
}
}
Shared Python resolver
Use ems_device_identity.py.
from ems_device_identity import require_device_identity
identity = require_device_identity(
"pcs",
pcs_id,
debug=DEBUG,
)
gateway_id = identity["gateway_id"]
device_id = identity["device_id"]
model = identity["model"]
Grid meter:
identity = require_device_identity(
"grid_meter",
"grid_meter1",
debug=DEBUG,
)
Solar meter:
identity = require_device_identity(
"solar_meter",
"solar_meter1",
debug=DEBUG,
)
API payload
All device telemetry pushes should use the resolved identity:
{
"gateway_id": "<one resolved EMS gateway>",
"multyData": [
{
"component_type": "EMS",
"device_id": "<device-specific ID>",
"model": "<device-specific model>",
"readings": []
}
]
}
component_type remains EMS for EMS hardware telemetry according to the current API configuration.
Important behavior
- Changing a device ID or model in
ems_control_setting.jsontakes effect without editing the API config. ems_api_config.jsonis only the fallback for identity.- The common EMS gateway is resolved once and used by every device.
- No per-device gateway IDs are needed.
- If a device has no model in either file, the strict resolver reports the missing field rather than silently using a wrong model.