Skip to content

EMS Backend HTTP API

Developer documentation for the EMS backend now lives in this reference/ folder alongside this page: see ems_backend_dev_readme.md (index), ems_settings_pull.md, ems_http_api_endpoints.md, ems_backend_deployment.md and diagnostic_test_parameters.md. Laravel integration files are in laravel/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-binary passes the file through byte-for-byte; --data @file would let curl strip newlines out of the JSON.
  • docker exec -i is 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 400 and 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.