Skip to content

Frontend Usage

Frontend code calls Laravel routes only. It must not call http://ems-backend:8080 directly.

Read settings

const response = await fetch('/api/ems/settings', {
    headers: { Accept: 'application/json' },
});

if (!response.ok) {
    throw new Error(`Unable to read EMS settings: ${response.status}`);
}

const settings = await response.json();

Save settings

Send the complete settings document. This example updates a locally edited object and sends the whole object to Laravel:

const response = await fetch('/api/ems/settings', {
    method: 'PUT',
    headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
        'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content ?? '',
    },
    body: JSON.stringify(settings),
});

if (!response.ok) {
    const error = await response.json().catch(() => ({}));
    throw new Error(error.message ?? `Unable to save EMS settings: ${response.status}`);
}

const savedSettings = await response.json();

Poll all readings

const response = await fetch('/api/ems/readings', {
    headers: { Accept: 'application/json' },
});

if (!response.ok) {
    throw new Error(`Unable to read EMS telemetry: ${response.status}`);
}

const { devices, timestamp } = await response.json();
const gridPower = devices.gridMeter_lastValue?.gridMeter_active_power_total_kw;
const pcs1Soc = devices.pcs1_lastValue?.pcs_soc_state_of_charge_item;

Use a polling interval appropriate for the UI, such as 1 to 5 seconds. The Python backend reads the existing last-value files and does not provide historical time-series data through this endpoint.

Read one device

const response = await fetch('/api/ems/readings/gridMeter_lastValue', {
    headers: { Accept: 'application/json' },
});

const payload = await response.json();
const activePower = payload.readings.gridMeter_active_power_total_kw;

UI behavior recommendations

  • Show a stale-data indicator when a device timestamp is old.
  • Treat missing values as unavailable, not as zero.
  • Disable the save button while a settings update is in progress.
  • Display the backend error message when Laravel returns 502.
  • Refresh settings after a successful save using the response returned by Laravel.