EMS Backend HTTP API
Developer documentation for the EMS backend now lives in this
reference/folder alongside this page: seeems_backend_dev_readme.md(index),ems_settings_pull.md,ems_http_api_endpoints.md,ems_backend_deployment.mdanddiagnostic_test_parameters.md. Laravel integration files are inlaravel/README.md.
The Python EMS service runs in the ems-backend container and listens on port 8080 by default. The Laravel application must call it server-side using the Docker network name:
http://ems-backend:8080
The diagnostic test service is available at:
POST /api/v1/ems/diagnostic-tests
GET /api/v1/ems/diagnostic-tests
GET /api/v1/ems/diagnostic-tests/report/latest
See EMS diagnostic tests for command, scheduling, status, XML report, and upload contracts.
Active diagnostics suspend all normal BESS dispatch, stop external control processes, clear pending automatic setpoints, and queue one zero-power command per active PCS before normal mode execution can resume.
Do not use ems-backend from browser JavaScript. Container DNS names are available to Laravel inside Docker, not necessarily to a user's browser.
Authentication
Between ems-frontend and ems-backend no token is needed. The settings API is deliberately
unauthenticated: it is reachable only on the Docker network (nothing is published to the host)
and ems_control_setting.json is written only by ems-frontend, so a token adds nothing on
that hop. Any Authorization header you send is ignored, so existing callers keep working.
The start script launches the API with an empty --bearer-token, and the handler's
_authorized() accepts every request when its token is empty:
def _authorized(self) -> bool:
if not self.bearer_token:
return True
return self.headers.get("Authorization", "") == f"Bearer {self.bearer_token}"
To turn the check back on, pass a token in the server launch in
start_ems_client_in_docker.sh:
--bearer-token "$EMS_SETTINGS_API_TOKEN"
The shared token is still used in the other direction. ems-backend pushes settings to
ems-frontend and reads its token from emsConfig/ems/ems_api_config.json
(ems_control_json.bearer_token), so that file must keep a non-empty token. Disabling the
inbound check does not affect it.
Endpoints
Health
GET http://ems-backend:8080/api/v1/ems/health
Response:
{
"status": "ok",
"service": "ems-backend"
}
Read settings
GET http://ems-backend:8080/api/v1/ems/settings
Returns the current ems_control_setting.json object.
Replace settings
PUT http://ems-backend:8080/api/v1/ems/settings
Content-Type: application/json
The request body must be the complete settings object. The backend atomically replaces emsConfig/ems/ems_control_setting.json; the running EMS reads this file on its next control cycle.
POST is also accepted for clients that cannot send PUT.
Example:
{
"ems_operation_mode": "MANUAL",
"ems_control_mode": "local_control",
"functions": {
"Manual_Operation": {
"enabled": true,
"operation_type": "CHARGE",
"power_setpoint_kw": 60
}
}
}
Send ems_control_setting.json to the endpoint
Run this from your workstation, with your edited ems_control_setting.json in the current
directory. It copies the file to the Docker host, stages it into ems-frontend, and PUTs it:
scp ems_control_setting.json root@192.168.6.116:/tmp/ems_control_setting.json
ssh root@192.168.6.116 '
docker cp /tmp/ems_control_setting.json ems-frontend:/tmp/ems_control_setting.json &&
docker exec ems-frontend curl -sS -X PUT \
-H "Content-Type: application/json" \
--data-binary @/tmp/ems_control_setting.json \
http://ems-backend:8080/api/v1/ems/settings'
The response body is the stored settings object, re-serialised by the backend — the same
content you sent, around 60 KB. A successful call returns HTTP 200 and starts like:
{"metadata": {"schema_version": "20251020.113351", ...
If you are already on the Docker host and would rather not copy the file into a container,
pipe it in instead. docker exec -i forwards your stdin to curl:
docker exec -i ems-frontend curl -sS -X PUT \
-H "Content-Type: application/json" \
--data-binary @- \
http://ems-backend:8080/api/v1/ems/settings < ems_control_setting.json
Over ssh, the same call without staging anything on the server:
ssh root@192.168.6.116 \
'docker exec -i ems-frontend curl -sS -X PUT \
-H "Content-Type: application/json" \
--data-binary @- \
http://ems-backend:8080/api/v1/ems/settings' < ems_control_setting.json
All three are interchangeable. POST is accepted in place of PUT.
Why curl runs inside a container: ems-backend:8080 has no host-published port —
ems-backend publishes 1540, which does not serve these routes, so
http://localhost:1540/api/v1/ems/... from the host fails. ems-frontend shares the Docker
network and has curl installed.
Read the live file, and keep a backup before replacing it:
# the settings the EMS is running from
ssh root@192.168.6.116 \
'docker exec ems-frontend curl -sS http://ems-backend:8080/api/v1/ems/settings' \
> ems_control_setting.json
# the copy inside the container, timestamped
ssh root@192.168.6.116 'docker exec ems-backend cp \
/app/EnergySyc_EMS_ES100Cx12S/emsConfig/ems/ems_control_setting.json \
/app/EnergySyc_EMS_ES100Cx12S/emsConfig/ems/ems_control_setting.json.bak-$(date +%F-%H%M%S)'
The write is atomic and the running EMS re-reads the file on its next control cycle, so confirm it landed by watching the file itself — the timestamp should be seconds old:
ssh root@192.168.6.116 'docker exec ems-backend stat -c "%y %s bytes" \
/app/EnergySyc_EMS_ES100Cx12S/emsConfig/ems/ems_control_setting.json'
Notes:
--data-binarypasses the file through byte-for-byte;--data @filewould let curl strip newlines out of the JSON.docker exec -iis required for the piped forms, otherwise curl never sees stdin.- No token is required (see Authentication). A body that is not a JSON object returns
400and leaves the file untouched. - To roll back, send the
.bak-*file saved above the same way.
Read all current values
GET http://ems-backend:8080/api/v1/ems/readings
Response shape:
{
"timestamp": 1769374275562,
"source": "ems-backend",
"devices": {
"pcs1_lastValue": {
"timestamp": 1769374275562,
"pcs_soc_state_of_charge_item": 55.2
},
"gridMeter_lastValue": {
"timestamp": 1769374275562,
"gridMeter_active_power_total_kw": 1.02
}
}
}
The keys under devices are the JSON filename stems from lastValue/.
Read one device
GET http://ems-backend:8080/api/v1/ems/readings/pcs1_lastValue
GET http://ems-backend:8080/api/v1/ems/readings/gridMeter_lastValue
Response:
{
"timestamp": 1769374275562,
"source": "ems-backend",
"device": "gridMeter_lastValue",
"readings": {
"gridMeter_active_power_total_kw": 1.02
}
}
Laravel integration
The workspace does not contain the Laravel source tree, so the following files are copy-ready examples for the ems-frontend application.
Environment
EMS_BACKEND_URL=http://ems-backend:8080
# No token is needed for this hop - see Authentication. Uncomment only if you
# re-enable the inbound check on the backend.
# EMS_BACKEND_TOKEN=replace-with-a-long-random-token
Controller
Create app/Http/Controllers/EmsBackendController.php:
<?php
namespace App\Http\Controllers;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;
class EmsBackendController extends Controller
{
private function client()
{
return Http::baseUrl(rtrim(config('services.ems_backend.url'), '/'))
->acceptJson()
->asJson()
->timeout((int) config('services.ems_backend.timeout', 10));
}
public function health()
{
return response()->json($this->client()->get('/api/v1/ems/health')->throw()->json());
}
public function settings()
{
return response()->json($this->client()->get('/api/v1/ems/settings')->throw()->json());
}
public function updateSettings(Request $request)
{
$settings = $request->json()->all();
abort_unless(is_array($settings), 422, 'Settings must be a JSON object');
abort_unless(
isset($settings['ems_operation_mode']) && is_string($settings['ems_operation_mode']),
422,
'ems_operation_mode is required'
);
return response()->json(
$this->client()->put('/api/v1/ems/settings', $settings)->throw()->json()
);
}
public function readings()
{
return response()->json($this->client()->get('/api/v1/ems/readings')->throw()->json());
}
public function deviceReadings(string $device)
{
abort_unless(preg_match('/^[A-Za-z0-9_.-]+$/', $device), 422, 'Invalid device name');
return response()->json(
$this->client()->get('/api/v1/ems/readings/' . rawurlencode($device))->throw()->json()
);
}
}
Add to config/services.php:
'ems_backend' => [
'url' => env('EMS_BACKEND_URL', 'http://ems-backend:8080'),
'token' => env('EMS_BACKEND_TOKEN'),
'timeout' => env('EMS_BACKEND_TIMEOUT', 10),
],
Add to routes/api.php:
use App\Http\Controllers\EmsBackendController;
Route::prefix('ems')->controller(EmsBackendController::class)->group(function () {
Route::get('/health', 'health');
Route::get('/settings', 'settings');
Route::put('/settings', 'updateSettings');
Route::post('/settings', 'updateSettings');
Route::get('/readings', 'readings');
Route::get('/readings/{device}', 'deviceReadings');
});
The browser calls Laravel, for example GET /api/ems/readings and PUT /api/ems/settings. Laravel calls http://ems-backend:8080 internally and keeps the EMS container name and bearer token away from browser code.
Container startup
The EMS Docker entrypoint starts the Python API automatically. Configure:
EMS_SETTINGS_API_PORT=8080
EMS_SETTINGS_API_TOKEN is no longer required for inbound requests (see Authentication). The
start script passes an empty --bearer-token unless you restore it.
Expose the port only to the Docker network or reverse proxy as appropriate. The Python service binds to 0.0.0.0 inside ems-backend.