Skip to content

Device models API

GET /api/v1/ems/device-models

Lists every device type the EMS knows, and the models available for each, by reading the register files under emsConfig. A caller uses this to populate a model picker before asking for a device's register map or flipping a device's model.

Served by ems_settings_api.py server inside the ems-backend container on port 8080, alongside the settings, readings, diagnostic and alarm endpoints.

Where the answer comes from

There is no model registry to keep in step: the models are the register files. A register file is named

<stem>_register[_<unit>]___<model>.json
  • device type — the emsConfig folder the file lives in (pcs, bmu, air_condition_unit, …)
  • model — whatever follows the triple underscore, e.g. pcs_register_full___epcs105.json is the epcs105 model of the PCS register map, bmu_register_9___bmu300.json is a bmu300

A register file with no ___ is the default map and is not reported as a model. It is surfaced only as the boolean has_default, so a picker can still offer "default" when every unit should run the un-modelled map.

Only files whose name contains register count, so alarm maps (pcs_alarm_code___epcs105.json), modbus configs and templates are ignored, as are .bak-* copies and the backup/bakup/tmp/lastValue trees.

The optional selected_models list per type comes from selected_model.json, which records the model the EMS has switched on. It is empty for a type that file does not mention (for example bmu), which is not an error.

curl

curl -s \
  -H "Authorization: Bearer $EMS_SETTINGS_API_TOKEN" \
  http://ems-backend:8080/api/v1/ems/device-models

From the Docker host, the same call inside the network:

docker exec ems-backend sh -c '
  curl -s -H "Authorization: Bearer $EMS_SETTINGS_API_TOKEN" \
    http://127.0.0.1:8080/api/v1/ems/device-models'

Response

200 OK, application/json.

{
  "config_root": "/app/EnergySyc_EMS_ES100Cx12S/emsConfig",
  "device_type_count": 12,
  "default_model": "ME231",
  "device_types": {
    "pcs": {
      "models": ["epcs105", "sinexcel_pws1_250k", "sungrow_sc250ud"],
      "device_count": 12,
      "has_default": true,
      "register_file_count": 36,
      "selected_models": ["EPCS105"]
    },
    "bmu": {
      "models": ["bmu100", "bmu200", "bmu300"],
      "device_count": 10,
      "has_default": true,
      "register_file_count": 40,
      "selected_models": []
    },
    "ups": {
      "models": ["ups_10k", "ups_20k", "ups_30k"],
      "device_count": 1,
      "has_default": true,
      "register_file_count": 4,
      "selected_models": []
    }
  }
}
Field Meaning
config_root The emsConfig folder that was scanned
device_type_count Number of device types found
default_model The model selected_model.json records globally, "" when unset
device_types Keyed by type folder name
device_types.<type>.models Every model that has register files, sorted — the answer
device_types.<type>.device_count Instances of that type: unit folders (12 PCS) or per-unit files (10 BMU)
device_types.<type>.has_default Whether an un-modelled register file exists
device_types.<type>.register_file_count Register files matched, models and default alike
device_types.<type>.selected_models Model codes in force per selected_model.json, usually one

A type with an empty models array (bess_energy_meter, ffr_energy_meter) has a single default register file and no model variants. That is normal.

Errors

Status Body Meaning
401 — Missing or wrong bearer token
404 — Unknown route
500 {"error": "device_model_scan_failed", "detail": "..."} emsConfig could not be read

The route is checked by the same bearer-token gate as every other path, so it answers 401 whenever a token is configured. On this deployment the start script launches the server with --bearer-token "", so that gate is open and calls succeed without a header — acceptable only because the service listens on the internal Docker network and Laravel is the sole caller.

Calling it from ems-frontend

Laravel reaches the service at http://ems-backend:8080 over the internal Docker network; browsers never call it directly. config/ems.php already holds the URL and token as ems.backend_url and ems.backend_token.

Copy the shape used by the neighbouring operationStatus() call in app/Http/Controllers/Api/V1/EMS/EMSOutBoundDataController.php:

/**
 * Available device models per device type.
 * Endpoint: GET /api/v1/ems/device-models
 */
public function deviceModels()
{
    $url   = rtrim(config('ems.backend_url'), '/') . '/api/v1/ems/device-models';
    $token = config('ems.backend_token');

    $ch = curl_init();
    curl_setopt_array($ch, [
        CURLOPT_URL            => $url,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 10,
        CURLOPT_CONNECTTIMEOUT => 5,
        CURLOPT_HTTPGET        => true,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_SSL_VERIFYPEER => true,
        CURLOPT_SSL_VERIFYHOST => 2,
        CURLOPT_HTTPHEADER     => [
            'Accept: application/json',
            'Content-Type: application/json',
            'Authorization: Bearer ' . $token,
        ],
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    $error    = curl_error($ch);
    curl_close($ch);

    if ($response === false) {
        return response()->json([
            'system' => 'EMS',
            'status' => 'connection_failed',
            'error'  => $error,
        ], 502);
    }

    $data = json_decode($response, true);

    if (json_last_error() !== JSON_ERROR_NONE) {
        return response()->json([
            'system'    => 'EMS',
            'status'    => 'invalid_response',
            'http_code' => $httpCode,
            'raw'       => $response,
        ], 502);
    }

    return response()->json($data, $httpCode);
}

Then expose it in routes/api.php next to the other EMS outbound routes, protected by the same middleware as operation-status.

To pull a single list straight out of the payload in Blade or a service class:

$models = $data['device_types']['pcs']['models'] ?? [];

Integration check

# Through Laravel (what the frontend calls)
curl -s http://<ems-frontend-host>/api/v1/ems/device-models

# Straight at the backend, to tell a Laravel problem from a backend one
docker exec ems-frontend sh -c '
  curl -s -H "Authorization: Bearer $EMS_BACKEND_TOKEN" \
    http://ems-backend:8080/api/v1/ems/device-models'

Server option

The path is configurable like the other routes:

python3 ems_settings_api.py server \
  --device-models-path /api/v1/ems/device-models

Default: /api/v1/ems/device-models. The startup banner prints the resolved path and --debug echoes it.