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
emsConfigfolder the file lives in (pcs,bmu,air_condition_unit, …) - model — whatever follows the triple underscore, e.g.
pcs_register_full___epcs105.jsonis theepcs105model of the PCS register map,bmu_register_9___bmu300.jsonis abmu300
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.