diff --git a/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_calibrate_the_fzp_scanner.md b/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_calibrate_the_fzp_scanner.md new file mode 100644 index 00000000..03fe6cd2 --- /dev/null +++ b/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_calibrate_the_fzp_scanner.md @@ -0,0 +1,128 @@ +# How to calibrate the FZP scanner of flOMNI + +Source of `local_contact_only-howto_calibrate_the_fzp_scanner.pdf`. The original text is kept unchanged; the +section "Update 2026-10-20" at the end lists what the present flOMNI loop (PREEMPT_RT, 100 µs, branch `rt_preemt`) +needs in addition. + +```text +This is a description of how to calibrate the FZP scanner of flOMNI + +Rmemeber to do all modifications for both directions x and y! + +1. Align flOMNI without the FZP scanner. This implies disabling the +FZP scanner completely. To do so, in OrchestraHMI edit the parameters +of the FZP scanner as follows. +(a) Module PID_i_FZP: Set Param FAST_FZP_PID_LOOP(0) to 2. Then the FZP +will just remain +statically centered to the capacitive sensor position in closed loop. +(b) Module PID_i: Set Param FAST_FZP_PID_LOOP(0) to 0. If this is +negative, the FZP scanner will move ahead in a point-by-point scan by +that amount. +(c) Module PID_i: Set Param FAST_FZP_PID_LOOP(5) to 0. If this is +larger than zero the sample stage motion is stopped if the position is +reached by the FZP scanner (which is the case when the scanner is not +active). Zero means thus full compensation by the sample stage. + +In this state the setup can be aligned, and the affine matrix for +ptychography can be found. This refers then purely to the alignment of +the interferometer and X-ray detector. + +2. In the next step we perform a scan (with a small beam and small +range) such that only the FZP scanner is used and the sample stage +will not move. + +Before we start ensure that the Correction Matrix for the capacitive +sensors is cleared. + +To do this change the parameters of the flOMNI control +loop as follows: + +(a) Module AnalogInput_6259: Set parameter MatrixCorr to 1 0 0 1 +(b) Module PID_j_fzp: Set Param FAST_FZP_PID_LOOP(0) to 1 to re-activate +the FZP scanner. +(c) Module PID_i: Set Param FAST_FZP_PID_LOOP(5) to 10, so up to 10 +volts output of the fast PID is accepted before starting a movement of +the sample stage. +(d) Module PID_i: Param FAST_FZP_PID_LOOP(4) 0 +(e) Module PID_i: Param FAST_FZP_PID_LOOP(6) 1 + with d and e it will now stabilize the sample stage position at zero +(f) Module PID_i: Param FAST_FZP_PID_LOOP(0) remains 0 (no move ahead +in a scan) + +With these settings perform a scan. Use a field of view matching the +range of the FZP scanner. Watch the sample stage position in Orchestra +to ensure it does not change! +A good range should be 2.8 microns in x and 1.8 microns in y. +Reconstruct this scan with Michal's position refinement code and ask +for an update of the FZP matrix. This can then be put into the +AnalogInput_6259 module. +I guess one has to have the matrix found for the interferometer in the +reconsturction code, such that the new matrix of the FZP scanner will +adjust the coordinate system of the FZP scanner to the system of the +interferometer. Later these positions are used together and should +match in direction. + +3. Back to default operating values: +(a) Module PID_i: Set Param FAST_FZP_PID_LOOP(0) to -0.5, for up to +0.5 microns move ahead in a scan. +All other parameters are already as supposed to be. +Default values for the sample stage pid, fast FZP parameter are "- +0.5,0,0,0,0.1,0.5,0" +Default values for the fzp pid, fast FZP parameter are "1,0.0001,0.1,- +4,0,0,0" +``` + +## Update 2026-10-20 (flOMNI loop on PREEMPT_RT, mpc2844) + +The loop has new modules since the text above was written (flOMNI `FeedbackLoop/tuning_guide.md`, +`feedback_report.md` 5.6, 6n, 6o, 6q). Parameters are changed in the web HMI (`http://mpc2844:8080`, tab +Parameters) instead of OrchestraHMI. `i` = x or y, as above. Module names now: `PID_x`, `PID_y` (sample stage), +`PID_x_fzp`, `PID_y_fzp` (FZP scanner), `AnalogInput_6289` (was `AnalogInput_6259`). + +**FAST_FZP_PID_LOOP has 7 elements** (`PID.cpp`). Sample stage PIDs: (0) move-ahead (negative, µm, point-by-point +scans only), (4) FZP error threshold (µm) and (5) FZP drive limit (V) for holding the sample stage while the FZP +takes the step (5 = 0: never held), (6) 1 = hold the sample stage at 0. FZP PIDs: (0) mode (1 operation, 2 FZP +centred on its cap sensor = disabled, 3 not commissioned, 4 debug), (1)–(3) min / max / gain of the old velocity +correction (−4 before 2026-10-19, now 0: replaced by the feedforward). + +**In addition to step 1 (FZP disabled):** + +- `Feedforward`: `enable` 0,0 — the static FZP feedforward adds its drive also in FZP mode 2. +- `AbbeCorrection`: `enable` 0 (default until the signs are known). +- `TargetSelect_x`, `TargetSelect_y`: `use_final` 0; `OnTargetTrigger`: `WaitForSlew` 1 (defaults). +- `FreqGen`: `enable` 0 (excitation for measurements; default). + +**In addition to step 2 (FZP-only calibration scan):** + +- FZP range: `PID_x_fzp` / `PID_y_fzp` `Ub` / `Lb` are ±1.5 V in operation (the cap sensors are calibrated over + about ±2 V only). For the field of view above (2.8 × 1.8 µm) widen them, e.g. to ±10 V (FZP ≈ 0.13 µm/V in x, + ≈ 0.05 µm/V in y). The feedforward stays off (`enable` 0,0) during this scan. +- The detector trigger (`OnTargetTrigger`) checks the relative error sample vs FZP (tolerance / hold time from the + ConstEmitter, BEC `interferometer_trigger_*`, default 10 nm / 3 ms) and waits `MinDelay_ms` (15 ms). + +**Step 3, default operating values (replace the values in the text above):** + +| Module | Parameter | Value | +|---|---|---| +| `PID_x`, `PID_y` | `FAST_FZP_PID_LOOP` | `0,0,0,0,0.1,0,0` (no move-ahead: −0.5 µm does not fit the ±1.5 V FZP range) | +| `PID_x_fzp` | `FAST_FZP_PID_LOOP`, `Ub` / `Lb` | `1,0.0001,0.1,0,0,0,0`, ±1.5 V | +| `PID_y_fzp` | `FAST_FZP_PID_LOOP`, `Ub` / `Lb` | `1,0.0005,0.02,0,0,0,0`, ±1.5 V | +| `Feedforward` | `enable`; `ff_limit`, `out_min` / `out_max` | 1,1; ±1.5 V (as the FZP `Ub` / `Lb`) | +| `OnTargetTrigger` | `WaitForSlew`, `MinDelay_ms` | 1, 15 | +| `TargetSelect_x`, `TargetSelect_y` | `use_final` | 0 | +| `AbbeCorrection` | `enable` | 0 (until the signs are known) | +| `AnalogInput_6289` | `MatrixCorr` | the new matrix from the calibration | + +Check afterwards: web HMI tab **Loop check**, level 1 (it expects these values and lists live values that differ +from the `.xmp` files); save the new values as default (Parameters → Unsaved changes) or in the `.xmp`. + +**After the calibration (per experiment): faster scans, exposure during the motion.** With the FZP calibrated +over a wider range the FZP can take the small steps alone (flOMNI `feedback_report.md` 6q, tested at ±7 V): + +- `PID_x_fzp` / `PID_y_fzp` `Ub` / `Lb` and the `Feedforward` limits to the calibrated range (e.g. ±7 V); +- `TargetSelect_x` / `_y` `use_final` 1 (the FZP aims at the new point at once, the sample stage follows its + S-curve) and `OnTargetTrigger` `WaitForSlew` 0 (trigger on the relative error only); optionally `MinDelay_ms` 0; +- optionally move-ahead, sized to the FZP range: `PID_x` (0) e.g. −0.5, `PID_y` (0) e.g. −0.2. + +Measured with 101 ms exposures: 0.2–1 µm steps trigger after 4.5–5.8 ms instead of 17–32 ms; the error during the +exposure grows with the step (1 µm: ≈ 6 nm max instead of 2.5 nm), so the setting depends on the experiment. diff --git a/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_calibrate_the_fzp_scanner.pdf b/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_calibrate_the_fzp_scanner.pdf index 81ce9c8a..013f519d 100644 Binary files a/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_calibrate_the_fzp_scanner.pdf and b/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_calibrate_the_fzp_scanner.pdf differ diff --git a/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_limit_the_fzp_scanner_range.md b/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_limit_the_fzp_scanner_range.md new file mode 100644 index 00000000..a953ca6a --- /dev/null +++ b/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_limit_the_fzp_scanner_range.md @@ -0,0 +1,36 @@ +# How to limit the FZP scanner range of flOMNI + +Source of `local_contact_only-howto_limit_the_fzp_scanner_range.pdf`. The original text is kept unchanged; the +section "Update 2026-10-20" lists what the present flOMNI loop (PREEMPT_RT, 100 µs, branch `rt_preemt`) needs in +addition. + +```text +to limit the fzp scanner ranges +in PID_ FAST FZP PID LOOP +0: reduce to small ahead movement range, such as -0.05 +4: reduce error threshold, eg 0.01 +5: inform PID that FZP range is small, such as 0.1 + +in PID_ _FZP +limit the analog output LB and UB +``` + +## Update 2026-10-20 (flOMNI loop on PREEMPT_RT, mpc2844) + +The limited range is the present operating state: `PID_x_fzp` / `PID_y_fzp` `Ub` / `Lb` = ±1.5 V because the cap +sensors are calibrated over about ±2 V only (flOMNI `feedback_report.md` 6n). FZP ≈ 0.13 µm/V in x, ≈ 0.05 µm/V in y, +so ±1.5 V ≈ ±0.19 µm (x) / ±0.08 µm (y). In the sample stage PIDs (`PID_x`, `PID_y`) `FAST_FZP_PID_LOOP` is +`0,0,0,0,0.1,0,0`: no move-ahead, (5) = 0 (the sample stage always compensates fully). + +Changing the FZP range now involves, in addition to the text above: + +- **`Feedforward`** (static FZP feedforward): `ff_limit`, `out_min` / `out_max` to the same values as the FZP `Ub` / + `Lb` (they limit drive + feedforward). +- **`FreqGen`** `out_min` / `out_max` (channels 0 / 1) limit the FZP drive only while an excitation is running + (measurements). +- **`OnTargetTrigger`** `WaitForSlew` and **`TargetSelect_x` / `_y`** `use_final`: keep the defaults (1 / 0) with a + small range. `use_final` 1 + `WaitForSlew` 0 ("exposure during the motion") only makes sense when the FZP range + covers the scan step; steps larger than the range then still wait for the sample stage. +- Move-ahead (0) must fit into the range: at ±1.5 V at most ≈ −0.05 µm (x) — so in operation it stays 0. +- After a change: web HMI tab **Loop check** level 1 (expected settings) and, with the beamline ready, the scan test + (level 4: positioning time, stability during the exposure per step size). diff --git a/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_limit_the_fzp_scanner_range.pdf b/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_limit_the_fzp_scanner_range.pdf index 66e18ac1..abf9ea98 100644 Binary files a/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_limit_the_fzp_scanner_range.pdf and b/csaxs_bec/bec_ipython_client/plugins/flomni/docs/local_contact_only-howto_limit_the_fzp_scanner_range.pdf differ