diff --git a/csaxs_bec/bec_ipython_client/plugins/OMNY_shared/AI_docs/TODO_interferometer_signal_trend.md b/csaxs_bec/bec_ipython_client/plugins/OMNY_shared/AI_docs/TODO_interferometer_signal_trend.md new file mode 100644 index 00000000..d4514bed --- /dev/null +++ b/csaxs_bec/bec_ipython_client/plugins/OMNY_shared/AI_docs/TODO_interferometer_signal_trend.md @@ -0,0 +1,114 @@ +# TODO: interferometer signal-strength trend on the webpage + +Status: **proposed, not implemented.** Discussed 2026-09-19. This is a design +note to capture the idea before it's lost -- no code changes yet. + +## Goal + +A new section on the flomni/lamni/omny status webpage showing the trend of +interferometer signal strength over time (a sparkline/chart, not a live +readout), so drift/degradation is visible at a glance across a session or +beamtime, not just from an interactive `show_signal_strength_interferometer()` +call in the moment. + +## Sampling design + +- **Very low rate on purpose**: roughly one data point per hour, or less -- + explicitly *not* per-projection. A tomo scan already calls a signal-strength + check regularly (flomni: every projection, see below), but sampling that + often would produce far too many points for a trend view (tens of points + per hour per axis) for no benefit -- this is about long-term drift, not + per-projection diagnostics. +- **Timestamped, so per-axis cadence can differ freely.** Each data point is + `(timestamp, value)`; there's no requirement that every axis be sampled at + the same time or the same rate. An axis that's cheap to read opportunistically + (e.g. already fetched as a side effect of something else) can be sampled + more often than one that costs a dedicated round-trip, and the trend for + each axis is still valid independently. Staleness/eventual-consistency + between axes, or between this and the live scan, is fine -- the goal is a + general trend, not point-in-time precision. +- **Retention**: apply the lesson from `eps_alarm_history.json`'s HTTP 413 + bug (see `docs/developer/...` -- fixed 2026-09-18 in `eps_status_generator.py`, + `_MAX_UPLOAD_BYTES`/`_shrink_to_fit`): cap this ring buffer by *both* count + and a hard byte budget from the start, reusing that same pattern, not just + a count cap discovered insufficient after the fact. + +## Per-setup reality check (2026-09-19 survey -- see below for what's actually there) + +The three setups' interferometer-read primitives are **not interchangeable** +-- this can't be one generic helper at the RT-controller layer: + +| Setup | Read primitive | Axes/channels | Threshold/check helper | +|---|---|---|---| +| flomni | `RtFlomniController.read_ssi_interferometer(axis_number)` (`rt_flomni_ophyd.py:462`), generic `j{n}` socket read | 0-3 | `laser_tracker_check_signalstrength()` (`rt_flomni_ophyd.py:466`) -- reads axis 1, warns only, does not act | +| LamNI | **no equivalent single-axis reader.** `RtLamniController.show_signal_strength_interferometer()` (`rt_lamni_ophyd.py:268`) reads 3 channels (ST FZP horizontal/vertical, angle) via distinct `J2`/`J3`/`J7` commands | 3 (different meaning than flomni's 0-3) | none -- no `min_signal`/`low_signal` threshold logic exists in this file at all | +| omny | `RtOMNYController.laser_tracker_check_and_wait_for_signalstrength()` (`rt_omny_ophyd.py:270`) -- different behavior class: polls and *auto-triggers* `omny_interferometer_align_tracking()` if below `low_signal`, not just a warning. `show_signal_strength_interferometer()` (`rt_omny_ophyd.py:736`) reads 5 channels via a `self.ssi` dict from `feedback_get_status_and_ssi()` | 5 (OSA FZP Y/X, ST OSA Y/X, Angle) | yes, but actively corrective, not passive | + +There is no shared `csaxs_bec`-level RT-controller base across the three +(`RtFlomniController`/`RtLamniController`/`RtOMNYController` each subclass the +generic external `ophyd_devices.utils.controller.Controller` directly). LamNI +also doesn't reuse the one shared local module that does exist +(`csaxs_bec/devices/omny/rt/rt_ophyd.py`'s `RtSignalRO`/etc., used by flomni +and omny) -- it redefines its own parallel Signal classes. + +**Conclusion**: the shared piece of this feature should be the trend +storage/rendering (a common global-var shape + webpage section), not the +signal read itself. Each setup needs its own small adapter that knows its own +axis semantics and feeds the shared throttled-stash helper. + +## Where the throttled read would hook in, per setup + +- **flomni**: `laser_tracker_check_signalstrength()` is already called once + per projection during `tomo_scan()` (`flomni.py:3624`) -- cheapest option is + to throttle *at that call site* (check "have I stashed a data point in the + last hour?" before writing one), reusing an already-happening RT round-trip + rather than adding a new one. +- **LamNI**: confirmed (2026-09-19 survey) there is **no** scan-time + signal-strength call anywhere in the LamNI plugin -- `show_signal_strength` + (`lamni.py:724`) is a manual/interactive-only helper, never called from + `tomo_scan_projection` or `tomo_scan`. There's no existing per-projection + hook to throttle against, so this would need a separate low-rate timer + instead -- the natural fit is `WebpageGeneratorBase`'s own `_cycle()` loop + (`OMNY_shared/webpage_generator_base.py`, default 15s cadence, already runs + continuously including when idle), which already has a documented + subclass-override hook for instrument-specific data + (`_collect_setup_data()`, used today by `FlomniWebpageGenerator`/ + `LamniWebpageGenerator` for temperatures/sample name/etc.) -- add the + throttle check there instead of in the scan loop. +- **omny**: blocked on a prerequisite -- **omny has no working webpage + generator at all right now.** `omny_webpage_generator.py` looks like one + (defines `WebpageGeneratorBase`, `FlomniWebpageGenerator`, a + `make_webpage_generator()`, etc.) but is confirmed dead/orphaned: nothing + in `omny.py`/`omny/__init__.py` imports it, and the real factory + (`OMNY_shared/webpage_generator_base.py` ~line 1409) explicitly falls + through to the plain base class for the omny session with a comment noting + this file is "an unwired, stale duplicate." Building a real + `OmnyWebpageGenerator` subclass is a prerequisite for this feature on omny, + not just an extra per-setup adapter -- do not revive the stale duplicate + as-is. + +## Suggested shape (for whenever this is implemented) + +- A global var, e.g. `interferometer_signal_trend`, holding a small + ring-buffer list of `{timestamp, axis, value}` (or per-axis sub-lists), + written via a proxy class mirroring `_ProgressProxy`/`_TomoQueueProxy` + (`OMNY_shared/tomo_queue_mixin.py`) -- the established pattern in this + codebase for cross-process/cross-thread state via + `client.get_global_var`/`set_global_var`. +- A shared rendering piece (webpage HTML/JS section, sparkline or simple line + chart) that reads this same global var shape regardless of which setup + wrote it, so the display code doesn't need to know about per-setup axis + differences -- only each setup's adapter does. +- Byte-budget-capped storage per the eps history lesson above. + +## Open questions (not yet decided) + +- Exact axis(es) worth trending per setup -- flomni's axis 1 is free (already + read every projection); trending flomni's other 3 axes, or any of LamNI's/ + omny's channels, means new dedicated round-trips on whatever cadence is + chosen for those. +- Whether sampling should continue during idle time between scans (needs a + timer-based approach for all three setups, not just LamNI/omny) or only + while a scan is actively running (cheaper, but leaves gaps covering the + most interesting idle-drift periods). +- Exact webpage layout/placement of the new section -- not designed yet. diff --git a/csaxs_bec/bec_ipython_client/plugins/flomni/AI_docs/Webpage.md b/csaxs_bec/bec_ipython_client/plugins/flomni/AI_docs/Webpage.md index 18554f43..a9eca2cb 100644 --- a/csaxs_bec/bec_ipython_client/plugins/flomni/AI_docs/Webpage.md +++ b/csaxs_bec/bec_ipython_client/plugins/flomni/AI_docs/Webpage.md @@ -198,6 +198,13 @@ cannot drift. - **Consider**: the PSI **EPICS archiver REST interface** to sidestep CA firewall concerns. +### Interferometer signal-strength trend (proposed, not implemented) +- See `OMNY_shared/AI_docs/TODO_interferometer_signal_trend.md` for the full + design note (2026-09-19) — a new webpage section trending interferometer + signal strength over time, sampled at ~1 point/hour or less (not + per-projection). Blocked on omny specifically needing a real + `OmnyWebpageGenerator` built first (its current file is dead/unwired code). + ### Deferred - **LamNI**: fill in `LamniWebpageGenerator` — real `tomo_type` key values in `TOMO_TYPES`, device paths / `_collect_setup_data()`, `LamNI.png`. Add a