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
- Alarm configuration management
- EV charging piles
- SELF TEST and PAYLOAD DIAGNOSTIC TEST
- Alarm records in TimescaleDB
- Fixes and health reporting
- 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.jsonbeside the readings, named that way because_lastvalue_stemsglobs*_lastValue.jsonand 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_valuemeans 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_typeis offered from the types the device's registers actually declare, via the engine's newdata_typespayload (['BOOL','FLOAT32','INT16','UINT16','UINT32']for a PCS), so the list cannot propose something the save would refuse.enabledposts a hidden0alongside 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 sayenabled: 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 JSONPUTto/alarm-map-editgoes to the API passthrough, which forwards onlydevice_type,device_id,expected_hashandentries, so thenewkey 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_valuedoes not invert the operator. It reuses the trigger operator with the recovery operand, so>= 60withrecovery_value: 55clears 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;787bc028aligned the seeded component entry with the real sibling shape.b4c6812f3registeredev_charging_pilesas its own device family;e84aab6cseeded the piles as active with modelEVC1.2a8f0bac8andc0b1309bcproduced per-device maps plus the register-map registry entry, regeneratingems_register_full.jsonwith the 12 EV charger blocks.52687aacand4935b8b21added DLB (dynamic load balancing) controls, per pile.bd9bb336amade the engine poll all 12 piles and evaluate their alarms;0545cf305recorded 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 amigrate:freshhazard).
3. SELF TEST and PAYLOAD DIAGNOSTIC TEST
Two operational modes were split apart and given their own verification path.
3ea0a67b3and35a916a3added the SELF TEST mode: radio button, label and seeded configuration;93cac71dadocumented the mode page and the how-to for adding a mode.5a3dfe95added the Self Test configuration tab;af4a2683,20b4b725and26c1f5e9built the self test runner page, moving labels into a@phpblock and then dropping the inline one.f40ee4824added the full alarm diagnostic test API with XML reports and TimescaleDB storage;3d30eeaf7,449dbb61fand59d4ea9c3fixed the settling delay, indentation, visible write errors and the case where an already-active alarm was wrongly required to clear.6e7a02effdrives the simulator URL and allow-list from theSelf_Testblock.4c082411f,b86108904,bf0f33416,f8ab6c1d3,f3c9f41ecand45a6e7581renamed DIAGNOSTIC TEST to PAYLOAD DIAGNOSTIC TEST across the engine, fixed a broken multi-line import inems_main, and repaired a payload-mode guard that was never defined at runtime.81b1538farecorded the SELF TEST / PAYLOAD DIAGNOSTIC TEST mode split in memory.
4. Alarm records in TimescaleDB
6ac5bd0erecords active alarms in TimescaleDB every second;645b1a32added theems_test_reportshypertable migration for alarm diagnostic reports.3a97297agave the alarm collector a 10 s request timeout and logged the effective value.- Frontend migrations
2026_10_11_000001_create_active_alarm_records_table.phpand2026_10_12_000001_create_ems_test_reports_table.phpback these. ae28aa63fixedmigrate:freshfailing on the TimescaleDB migrations.
5. Fixes and health reporting
9fd92e1a5gave EMS health registers their second register for 32-bit fields.4b01d7e3emade health ignore units the settings declare inactive;030232b2estopped reporting a poller as stale when its devices are switched off.3d5424e31writes device archives flat into the family folder, like grid and solar.a2efed01cresolved the simulator register name for an alarm rule field.a114f6badrecorded the EMS register-map deploy pitfalls: live values in the map, and host Python 3.6.d2ce4d348standardised runningems-frontendartisan aswww-data.folder_cleaner.pyanddevice_duplicate.pywere 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
- 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.
- Run the live threshold change and confirm activation and clearance against the BESS simulator.
- Decide whether
recovery_valueshould invert the operator rather than reuse it. - Consider whether
enabled: falseshould delete the entry instead of keeping it. - The worklog page is not in
mkdocs.yml's navigation yet.