Skip to content

Work log — 10 October 2026

Everything recorded here is taken from the commit history of the two repositories for the last 24 hours: the engine monorepo (ES100CX12S) and the EMS frontend (GESS_SCADA2_V0.0.8_20.02.2025_git). Sections marked verified were checked against the running stack on 192.168.6.116; the rest is what the commits themselves record.

Contents

  1. Alarm configuration management
  2. EV charging piles
  3. SELF TEST and PAYLOAD DIAGNOSTIC TEST
  4. Alarm records in TimescaleDB
  5. Fixes and health reporting
  6. Commit index

1. Alarm configuration management

The day's main line of work. It started with alarm maps being unreachable from outside the Docker network and ended with thresholds, delays and hysteresis editable from the browser.

1.1 The API at /alarm-map-edit

ems-nginx proxies only / and *.php to Laravel, so the engine's /api/v1/ems/alarms/maps could not be reached from off the host. 27c202be published it through the frontend instead, at /alarm-map-edit.

Publishing it was not enough: the web middleware group in app/Http/Kernel.php ends with App\Http\Middleware\RequireAuthentication, a backstop that denies every path not listed in its $publicPaths. The route answered {"message":"Unauthenticated."} without ever reaching its controller, which 6e0b6e80 fixed by adding the path. The trap is worth remembering: php artisan route:list shows such a route with middleware ['web'] only, so a 401 that never reached the controller looks exactly like a controller refusal.

The API contract (02ce2dc98, 6f7aef769):

Request Behaviour
GET with device_type + device_id that device's map, with hash, errors, warnings, severities, operators, register_fields
GET with neither the engine's editor index — every device with its model, map file, hash and entry counts
PUT validate, back up, write atomically
PUT with a stale expected_hash 409 alarm_map_conflict
PUT whose entries clean to the existing map changed: false, and nothing is written or backed up
unknown device 404 alarm_map_not_found

That no-op contract is the safe way to prove write access end to end without altering anything.

Authorization is asymmetric on purpose. A bearer token matching EMS_SETTINGS_API_TOKEN or EMS_BACKEND_TOKEN may read and write; a browser session may not PUT, because the route is CSRF-exempt so scripts can write.

1.2 The editor

02430a8e turned the URL into both things at once: an API client (Accept: application/json, or a bearer token) still gets JSON, while a browser signed in as Admin gets the editor page, rendered by AlarmDefinitionsController::edit. One implementation, so the page and the API cannot drift apart.

Three things the editor gained:

  • A device selector built at runtime from the engine's index — 103 devices across 10 distinct models when checked, PCS carrying model EPCS105. Nothing is hardcoded, so a new device or model appears with no frontend change.
  • A scope banner, because the blast radius of a save is the map file, not the model: it names the file and every other device reading it (matched by map_path).
  • A save that returns to the page it came from, constrained to our own paths so it cannot become an open redirect.

abaced6f recorded the four files under patch id EMS-ALARM-MAP-API. The registry matters here specifically: a future re-apply that restored only the route and the middleware entry would leave the page serving JSON again.

1.3 Six extended alarm keys — engine work

The blocker was that the evaluator had no state at all. evaluate_device_alarms read the current value, compared it, and appended a row: an alarm was active exactly while its comparison held. Hysteresis and delays cannot exist without remembering the previous cycle, which is why six keys were being stored in the map files and silently ignored.

be943db6a made them real:

Key Behaviour Refused when
enabled false keeps the entry in the file and catalogue but it can never raise not a boolean
recovery_value hysteresis — once latched, holds until the value passes back beyond this threshold it sits on the firing side (>= 60 with 65), which would latch forever
trigger_delay seconds the condition must hold before activating negative or not a number
recovery_delay seconds the condition must stay clear before clearing negative or not a number
data_type how the value is read; coercion applied contradicts the register map's declared type
register_address the register address; can also name the field, so an alarm can be defined by address alone contradicts the field's known address, or matches no register

Design decisions worth keeping:

  • State lives in <stem>_alarmState.json beside the readings, named that way because _lastvalue_stems globs *_lastValue.json and would otherwise enumerate it as a device.
  • State is written only for entries that use these keys, so a map that does not ask for them writes no file and evaluates exactly as before.
  • Defaults reproduce the old behaviour. No recovery_value means the alarm clears the moment the condition stops holding; no delays means the same cycle.
  • Validation gates what evaluation then trusts (validate_entries), so the evaluator never sees an unvalidated value. Errors refuse the whole save.

1.4 The editor columns

8e4e40e2 added six columns to the edit table and ace71944 added the same six to the "Add an alarm" row, which previously forced a create-then-reopen to set them.

Two details that are easy to get wrong and were handled deliberately:

  • data_type is offered from the types the device's registers actually declare, via the engine's new data_types payload (['BOOL','FLOAT32','INT16','UINT16','UINT32'] for a PCS), so the list cannot propose something the save would refuse.
  • enabled posts a hidden 0 alongside its checkbox, because a checkbox posts nothing at all when unchecked and the editor must tell "off" apart from "not edited". It is stored only when false, so switching an alarm back on removes the key instead of rewriting every entry to say enabled: true.

The controller had to change with the view, and not cosmetically: Laravel's validate() returns only validated keys, so an input with no rule is stripped and the save drops it silently. Both the entries.* and new.* rule sets, and cleanEntry()'s numeric coercion list, needed the new keys.

1.5 Verification (verified)

Check Result
Engine tests tests/test_alarm_extended_keys.py 9 passing
Legacy entry with no new keys identical evaluation, no state file written
Hysteresis cycle, >= 60 with recovery_value: 55 65 active, 61 active, 58 still active, 50 cleared
Trigger delay does not fire on the first cycle; fires once the timer elapses
Recovery delay holds active until the timer elapses, then clears
State file and device discovery _lastvalue_stems returns only pcs1, never the state file
Validation, 13 cases accepts the valid, refuses the firing-side recovery, negative delay, non-boolean enabled, mismatched address and mismatched data type
Live build_alarm_count() {active_alarm_count: 0, by_severity: {}, devices_with_alarms: 0}
Live SELF TEST 294 synthetic alarms, 102 devices, 114 critical / 90 major / 90 warning
Live invalid PUT ×3 400 alarm_map_rejected for negative delay, firing-side recovery, non-boolean enabled
Map file after every probe byte-identical md5 and mtime — nothing was written
/alarm-map-edit as a browser 200 HTML with selector, scope banner, 96 editable inputs, hash guard
Same URL as an API client 200 JSON, 190 entries
Same URL anonymously 302 to /login

1.6 Known gaps

  • A new alarm created from the UI has not been exercised end to end. The validation rules and cleanEntry() are in place, but the browser form path was verified structurally, not driven. My attempt to test it through the JSON API was inconclusive: a JSON PUT to /alarm-map-edit goes to the API passthrough, which forwards only device_type, device_id, expected_hash and entries, so the new key was dropped before reaching the form controller. That is the wrong door for such a test; headless Chrome with a session and CSRF token is the right one.
  • No live threshold change has been made. Tests 4–7 and 12 of the original requirement — change a threshold, reload, confirm the EMS acts on it, confirm activation and clearance against the BESS simulator — each need a real change to a live alarm map and have not been run.
  • recovery_value does not invert the operator. It reuses the trigger operator with the recovery operand, so >= 60 with recovery_value: 55 clears below 55. That is the conventional reading, but it is a choice, not the only one.

1.7 Supporting fixes

9265f7f5 title-cased the payload diagnostic test labels in resources/lang/en/cruds.php. The mode selector renders each option through trans('cruds.emsSettings.<Key>'), and three entries were in capitals while every sibling was title case — Manual, Peak Shaving, Frequency Regulation, and Self_Test => 'Self Test' immediately beside it. Values only, keys untouched. Note for next time: Diagnostic_Test_Suite is defined in two page blocks and both were caps, so a label fix needs an exact-match script that asserts how many occurrences it expects before writing.


2. EV charging piles

Twelve chargers were added as their own device family and brought under EMS control.

  • d15eaefd — EMS General Settings gained an EV Charging Piles category with 12 chargers; 787bc028 aligned the seeded component entry with the real sibling shape.
  • b4c6812f3 registered ev_charging_piles as its own device family; e84aab6c seeded the piles as active with model EVC1.
  • 2a8f0bac8 and c0b1309bc produced per-device maps plus the register-map registry entry, regenerating ems_register_full.json with the 12 EV charger blocks.
  • 52687aac and 4935b8b21 added DLB (dynamic load balancing) controls, per pile.
  • bd9bb336a made the engine poll all 12 piles and evaluate their alarms; 0545cf305 recorded that polling and alarms are implemented and verified.
  • Documentation: 0a04a1cfd (integration + settings reference, and the device-category procedure), 491d8f0c7 (cross-reference to the platform-side OCPP docs), c8d6d6f14 (resolved EV open question 7, recorded a migrate:fresh hazard).

3. SELF TEST and PAYLOAD DIAGNOSTIC TEST

Two operational modes were split apart and given their own verification path.

  • 3ea0a67b3 and 35a916a3 added the SELF TEST mode: radio button, label and seeded configuration; 93cac71da documented the mode page and the how-to for adding a mode.
  • 5a3dfe95 added the Self Test configuration tab; af4a2683, 20b4b725 and 26c1f5e9 built the self test runner page, moving labels into a @php block and then dropping the inline one.
  • f40ee4824 added the full alarm diagnostic test API with XML reports and TimescaleDB storage; 3d30eeaf7, 449dbb61f and 59d4ea9c3 fixed the settling delay, indentation, visible write errors and the case where an already-active alarm was wrongly required to clear.
  • 6e7a02eff drives the simulator URL and allow-list from the Self_Test block.
  • 4c082411f, b86108904, bf0f33416, f8ab6c1d3, f3c9f41ec and 45a6e7581 renamed DIAGNOSTIC TEST to PAYLOAD DIAGNOSTIC TEST across the engine, fixed a broken multi-line import in ems_main, and repaired a payload-mode guard that was never defined at runtime.
  • 81b1538fa recorded the SELF TEST / PAYLOAD DIAGNOSTIC TEST mode split in memory.

4. Alarm records in TimescaleDB

  • 6ac5bd0e records active alarms in TimescaleDB every second; 645b1a32 added the ems_test_reports hypertable migration for alarm diagnostic reports.
  • 3a97297a gave the alarm collector a 10 s request timeout and logged the effective value.
  • Frontend migrations 2026_10_11_000001_create_active_alarm_records_table.php and 2026_10_12_000001_create_ems_test_reports_table.php back these.
  • ae28aa63 fixed migrate:fresh failing on the TimescaleDB migrations.

5. Fixes and health reporting

  • 9fd92e1a5 gave EMS health registers their second register for 32-bit fields.
  • 4b01d7e3e made health ignore units the settings declare inactive; 030232b2e stopped reporting a poller as stale when its devices are switched off.
  • 3d5424e31 writes device archives flat into the family folder, like grid and solar.
  • a2efed01c resolved the simulator register name for an alarm rule field.
  • a114f6bad recorded the EMS register-map deploy pitfalls: live values in the map, and host Python 3.6.
  • d2ce4d348 standardised running ems-frontend artisan as www-data.
  • folder_cleaner.py and device_duplicate.py were added.

6. Commit index

Engine (ES100CX12S)

Commit Subject
98b5b2717 docs(memory): correct the alarm-key entry to describe the new engine support
be943db6a feat(alarms): make enabled, hysteresis and trigger/recovery delays real
ed4979240 docs: document the alarm-map editor and separate its two write paths
71309863e docs(memory): record the label-duplication trap and the container tinker quirk
6f7aef769 docs: note the alarm-map listing and 404 behaviour
65f2b322e docs(memory): record the web-group auth backstop and the alarm-map API
02ce2dc98 docs: record the alarm-map no-op PUT contract
5520c833b docs: document the alarm-map API route on the public hostname
b4ee7526f docs(memory): record simulator pull-blocker and restart timing lessons
c8d6d6f14 docs: resolve EV open question 7 and record the migrate:fresh hazard
45a6e7581 docs: finish the PAYLOAD DIAGNOSTIC TEST rename
3671309de rename the remaining DIAGNOSTIC_TEST references
81b1538fa docs(memory): record the SELF TEST / PAYLOAD DIAGNOSTIC TEST mode split
f3c9f41ec docs: rename DIAGNOSTIC TEST to PAYLOAD DIAGNOSTIC TEST
f8ab6c1d3 return after the payload mode 409 response
bf0f33416 fix payload mode guard never being defined at runtime
b86108904 fix broken multi-line import in ems_main
4c082411f rename DIAGNOSTIC TEST to PAYLOAD DIAGNOSTIC TEST
0545cf305 docs(ev): polling and alarms are implemented and verified
bd9bb336a feat(ev): poll the 12 EV charging piles and evaluate their alarms
5c554f301 docs(ev): record the verified simulator state
a114f6bad docs(memory): record the EMS register-map deploy pitfalls
c0b1309bc chore(ev): regenerate ems_register_full.json with the 12 EV charger blocks
2a8f0bac8 feat(ev): device maps for 12 EV charging piles + registry entry
491d8f0c7 docs: cross-reference the platform-side EV/OCPP documentation
0a04a1cfd docs: EV charging pile integration + settings reference
5a0aff21c docs: record the EMS general-settings data-source layout
4935b8b21 EMS: per-pile DLB settings for EV Charging Piles
b4c6812f3 EMS: register ev_charging_piles as its own device family
d2ce4d348 docs: run ems-frontend artisan as www-data everywhere
91c36ec8e docs: how an EMS operation mode is added
93cac71da docs(ems): SELF TEST mode page and the add-a-mode how-to
6e7a02eff ems(alarm-diag): drive simulator URL and allow-list from Self_Test
3ea0a67b3 feat(ems): SELF TEST operational mode for the alarm diagnostic test
59d4ea9c3 fix(ems): do not demand that an already-active alarm clears
449dbb61f fix(ems): repair the indentation broken by the previous commit
3d30eeaf7 fix(ems): settle before the TimescaleDB check, longer clear timeout
a2efed01c fix(ems): resolve the simulator register name for an alarm rule field
f40ee4824 feat(ems): full alarm diagnostic test API with XML reports and TimescaleDB storage
4b01d7e3e fix(health): ignore units the settings declare inactive
030232b2e ems: do not report a poller as stale when its devices are switched off
3d5424e31 ems: write device archives flat into the family folder
3b8219658 docs: add a practical guide to accessing EMS alarms
9fd92e1a5 EMS health registers: give 32-bit fields their second register

Frontend (GESS_SCADA2_V0.0.8_20.02.2025_git)

Commit Subject
ace71944 feat(ems): offer the extended keys when adding an alarm
8e4e40e2 feat(ems): edit the extended alarm keys in the map editor
abaced6f docs: list the editor files under patch id EMS-ALARM-MAP-API
02430a8e feat(ems): make /alarm-map-edit a real editor, with a dynamic selector
9265f7f5 fix(ems): title-case the payload diagnostic test labels
f9343ab6 docs: record the RequireAuthentication entry in the patch registry
6e0b6e80 fix(ems): let /alarm-map-edit reach its controller
27c202be feat(ems): expose the alarm-map API at /alarm-map-edit
ae28aa63 fix migrate:fresh failing on the TimescaleDB migrations
7de6db4c rename the payload diagnostic labels on the EMS settings page
3feef66c rename DIAGNOSTIC TEST to PAYLOAD DIAGNOSTIC TEST in the settings UI
e84aab6c feat(ev): seed the EV piles as active with model EVC1
52687aac EMS: DLB controls for every EV charging pile
787bc028 EMS: align the seeded EV component entry with the real sibling shape
d15eaefd EMS General Settings: add EV Charging Piles category with 12 chargers
26c1f5e9 ems: drop the inline @php from the self test runner
20b4b725 ems: build the self test runner labels in a @php block
af4a2683 ems: self test page with a radio button per diagnostic test
5a3dfe95 ems: Self Test configuration tab
35a916a3 ems: SELF TEST radio button, label and seeded configuration
645b1a32 ems: ems_test_reports hypertable migration
3a97297a alarm-collector: 10 s alarm request timeout, log the effective value
6ac5bd0e feat(ems): record active alarms in TimescaleDB every second

7. Open items carried forward

  1. Drive the alarm editor's add-an-alarm form end to end (headless Chrome, with a session and CSRF token). The JSON API is the wrong door for this test.
  2. Run the live threshold change and confirm activation and clearance against the BESS simulator.
  3. Decide whether recovery_value should invert the operator rather than reuse it.
  4. Consider whether enabled: false should delete the entry instead of keeping it.
  5. The worklog page is not in mkdocs.yml's navigation yet.