Skip to content

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:

  1. emsConfig/ems/ems_control_setting.json
  2. device.gateway_id
  3. emsConfig/ems/ems_control_setting.json
  4. metadata.gateway_id (compatibility fallback)
  5. emsConfig/ems/ems_api_config.json
  6. ems_gateway.gateway_id
  7. Existing *_data_api.gateway_id values 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:

  1. Read device_id and model from that device's entry in ems_control_setting.json.
  2. If either value is missing/empty, read only that missing value from the corresponding section of ems_api_config.json.
  3. 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.json takes effect without editing the API config.
  • ems_api_config.json is 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.