docs(omny): TODO for the OMNY real-time loop features in BEC (loop settings / profiles, move_xyz + trigger after a move, trigger source, top-up gate, scan statistics)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01M8zoDvEVcT4jbFjSNU9Rii

csaxs_bec/bec_ipython_client/plugins/omny/AI_docs/TODO_rt_loop_features.md

@@ -0,0 +1,59 @@
+# TODO: OMNY real-time loop features in BEC (as flOMNI)
+
+Status: **not implemented in BEC.** The features exist in the OMNY real-time loop since 2026-11-04 / 05 (OMNY repo,
+branch `capz-unify`, on mpc-omny); Mirko: BEC comes later, when he can test it. Planning item in RT-system
+`docs/omny-todo.md` O23 (+ O21). Values and measurements: OMNY `docs/feedback_report.md`, `docs/tuning_guide.md`,
+`docs/soft_trigger.md`, `OMNY/OMNYcontrol/loopsettings/README.md`.
+
+The flOMNI implementation is the model for all items; OMNY differs only in the server (OMNY_server, port 3333,
+single client) and the web HMI host (`http://mpc-omny:8080`).
+
+## 1. Loop settings and profiles
+
+- Loop has a web HMI loop-settings definition `OMNY/OMNYcontrol/loopsettings/omny.json`, REST `/api/settings`
+  (same API as flOMNI).
+- Profiles: `normal` (default, = the .xmp), `high_res`, `low_res` (trigger tolerance 10 / 5 / 50 nm, error average
+  2.4 ms, hold 3 / 3 / 1 ms, target shaper 1 / 1 / 0.5).
+- Settings: `trigger_tolerance_nm`, `trigger_hold_ms`, `trigger_filter_ms`, `trigger_min_delay_ms`, `trigger_on_move`,
+  `trigger_soft` (never saved), `soft_exposure_ms`, `soft_latency_ms`, `trigger_topup`, `target_shaper_scale`,
+  `tracking_target_y` / `_z`, `psd_threshold_low`. Groups `trigger_source` and `motion` only between scans.
+- BEC: an `OmnyLoopSettings` device as `FlomniLoopSettings` (`devices/omny/flomni_loop_settings.py`,
+  `webhmi_client.py`) and the realtime-system helpers of `flomni_realtime_system.py` (profile select, show, set).
+- Write access needs the API token: the web HMI config on mpc-omny names `~/loop-data/webhmi/api_token` (file not
+  created yet, 2026-11-05) - create it as on flOMNI, never in a repo.
+
+## 2. move_xyz and the trigger after a move
+
+- OMNY_server `p x,y,z`: all three targets change in the same loop step; with `OnTargetTrigger` `trigger_on_move` = 1
+  exactly one detector trigger per command once on target (`pa<axis>,<v>`: one per axis command). Tested 8 / 8 with the
+  soft trigger and with a trigger box (2026-11-04 / 05).
+- BEC: `move_xyz(x, y, z)` in `rt_omny_ophyd.py` as `RtFlomniController.move_xyz`, and the switch as
+  `trigger_set_after_move(True/False)` (flOMNI `flomni_realtime_system.py`, also `trigger_set_soft(True/False, exposure_ms)`).
+
+## 3. Trigger source at every scan start (hardware / soft)
+
+- `OnTargetTrigger` `soft_trigger` 1: no hardware trigger leaves the loop, the loop emulates the detector exposure
+  (`soft_exposure_ms` after `soft_latency_ms`) on the detector-exposing line. The loop always starts with hardware (0).
+- BEC: set the source at every scan start as `flomni_fermat_scan.py` (hardware when the beamline / detector is found,
+  soft otherwise with `soft_exposure_ms` = exposure time x frames per trigger).
+
+## 4. Top-up gate
+
+- `OnTargetTrigger` `TopUp` (loop setting `trigger_topup`): -1 = ignored (default), 0 / 1 = level of the gate input
+  (OMNY: DI PFI19 of the PCI-6602 comedi0) that allows triggers; ignored with the soft trigger. Same semantics on
+  flOMNI since 2026-11-05 (flOMNI default changed from 0 to -1).
+- BEC: decide where the top-up mode is set (beamline config / scan parameter), as on flOMNI.
+
+## 5. Scan statistics (RT-system O21)
+
+- `RtOMNYFlyer._report_statistics` as `RtFlomniFlyer` (per-point std x / y during the exposures, time split); guard the
+  division by `read_counter` (0 points). OnTargetTrigger output 4 = positioning time per point (ms) if wanted.
+
+## 6. Notes for the device / restart logic
+
+- After a loop restart the loop angle is 0: send `a<rad>` (BEC 0 deg = 0.505762 rad, hardware offset) before `J1`; set
+  the z target to the present capz before `J1` (capz is absolute); tracker on with `T1` (now by mailbox, no CoreRTIF;
+  no protocol change for BEC).
+- `sc` (scan clear) gives no reply outside the server's debug mode.
+- Large moves (tested to 100 um in x / y / z / xyz, 2026-11-05) need the tracker steppers enabled (z tracker range
+  about +-21 um of sample z without the stepper).