エンコーダー付きHWPローテータースクリプトの更新

Ushiba-san, YamaT-san, Ikeda

概要
 エンコーダー付きのHWPのトラブルが続いている(K-Log#32783、#32475, etc)
 https://klog.icrr.u-tokyo.ac.jp/osl/?r=32782
 https://klog.icrr.u-tokyo.ac.jp/osl/?r=32475
 これらは指定した角度とのずれが指摘されている。

 PSL, IMC_REFL, IFO_REFLのHWP制御スクリプトの更新を行ないました。
 この対応により、total(deg)はエンコーダーの読み値が反映されます。
 
詳細

関連するEPICSチャンネルの変更
 total(deg): K1:SYS-HWP_{PSL,IMC_REFL,IFO_REFL}_STEP_TOTAL_DEG (動作の変更)
 step(deg): K1:SYS-HWP_{PSL,IMC_REFL,IFO_REFL}_STEP_DEG (変更なし)
 base(deg): K1:SYS-HWP_{PSL,IMC_REFL,IFO_REFL}_CURRENT_DEG  (新規追加)
  =>  コントローラー初期化時の基準位置
 status: K1:SYS-HWP_{PSL,IMC_REFL,IFO_REFL}_STATUS: モーター動作状態 (新規追加)
  => 0:停止、1:動作中

total(deg)の値の算出方法の変更
 変更前:
  total(deg)の値は、step(deg)を動作の度に加算(減算)した値であり、実際のモーターの位置を示していなかった。
 変更後:
  total(deg)の値は、エンコーダーの読み値 + 基準位置base(deg)に変更、実際のモーターの位置が反映される。

step(deg),total(deg)の最小単位の扱いを変更
 変更前: 1(deg)単位
 変更後: 0.001(deg)単位

   モーターの読み値の精度は小数点以下6桁、EPICSは有効数字7桁のため、小数点3桁までは扱えるように対応
   ただし、現状total(deg)は小数点以下は四捨五入しています。

   これはGuardian側の判定が小数点以下に対応できていない為です。
   => 月曜日に小数点以下を対応する予定。
   　　medm_hwp_calib_callback.shのSCALEとINFLATEを変更すると反映される。

DeadBandの値を変更
 変更前: (初期値)0.002
 変更後: 0.003
  エンコーダーの読み値の読み取り誤差の範囲指定を変更した。
  PSLのHWPが停止しない、または停止まで時間がかかる問題があり、停止位置の誤差を緩くした。
   +1deg x 30回動作後、-30deg x 1回を１セットとして、100回繰り返した場合の停止位置を確認
   ずれた量
   0.002:  -0.0451725 deg
   0.003:  -0.0494520 deg

停止処理の変更
 非同期処理でモーターの動作開始から終了まで動作をモーターの動きを0.5sec感覚で監視して、0.1deg以下しか回転しない場合は、異常と判定してモーターを停止する処理追加。

ソースコードの変更点

 /opt/rtcds/userapps/sys/k1/scripts/
 変更: medm_hwp_calib.sh
  ssh呼び出し部分の変更
  EPICS値の変数化
  コールバック付きのコード呼び出し
  小数点以下の対応

 /kagra/apps/agilis/
 旧: agilis-p_control.py
 新: agilis-p_control_with_callback.py
  モーターの監視処理を追加
  DeadBandの値を変更(初期値0.002 -> 0.003)

 /opt/rtcds/userapps/sys/k1/scripts/
 新規: medm_hwp_calib_callback.sh
  k1hwpからk1scriptへのコールバックの受信部
  EPICSチャンネルへの書き込みなど
　<初期化動作>
  リセットコマンド、または電源OFF->ONにより初期化動作が行われる。
  この時、モーターの読み値は0になる。
  total(deg)の値をbase(deg)へコピーする
  total(deg)は、モーターの読み値+base(deg)の値(結果としては何も変化しない)

 上記以外
  /kagra/apps/agilis/
  新規: agilis-p_control_reset.py
  k1hwpX上でのみ動作可能。Agilis-Pコントローラーにリセットコマンドを送る。
  リセットを行うと、次のモーター駆動時に、medm_hwp_calib_callback.shで初期動作化を行う。
  このコマンドはモーターの位置は変化しないです。

注意点
 total(deg)は手動で上書きできない
  変更前: [<<REV],[FWD>>]を押下するとstep(deg)の値をtotal(deg)に減算または加算していた。
  変更後: [<<REV],[FWD>>]を押下するとstep(deg)の値は、base(deg)の値 + HWPモーターの現在位置で上書きされる。
   もし手動でstep(deg) の値を変更したい場合は次の計算をしてbase(deg)を変更する
   base(deg) = 書き換えたい角度 - (total(deg) - base(deg))
 
次回
 Guardianの小数点対応後に、total(deg)への小数点書き込みの対応

===
Update of HWP Rotator Script with Encoder

Ushiba-san, YamaT-san, Ikeda

Overview
 Ongoing trouble with HWP with encoder (K-Log#32783, #32475, etc.)
 https://klog.icrr.u-tokyo.ac.jp/osl/?r=32782
 https://klog.icrr.u-tokyo.ac.jp/osl/?r=32475
 These have been noted to be out of alignment with the specified angles.

 The control scripts for the HWP systems of PSL, IMC_REFL, and IFO_REFL have been updated.
 With this update, the total(deg) value now reflects the encoder readings.

Details

 Changes in Related EPICS Channels

  total(deg): K1:SYS-HWP_{PSL,IMC_REFL,IFO_REFL}_STEP_TOTAL_DEG (Behavior changed)
  step(deg): K1:SYS-HWP_{PSL,IMC_REFL,IFO_REFL}_STEP_DEG (No change)
  base(deg): K1:SYS-HWP_{PSL,IMC_REFL,IFO_REFL}_CURRENT_DEG (Newly added)
  → Reference position upon controller initialization.
  status: K1:SYS-HWP_{PSL,IMC_REFL,IFO_REFL}_STATUS (Newly added)
  → Motor operation status:
   0: Stopped
   1: Running

 Change in Calculation Method of total(deg)

  Before:
   total(deg) was calculated by incrementing (or decrementing) step(deg) each time an operation was performed. This did not reflect the actual motor position.
  After:
   total(deg) is now calculated as:
   total(deg) = Encoder reading + base(deg)
   → The actual motor position is now correctly reflected.

Changes in the Handling of Step Size for step(deg) and total(deg)

 Before: Step size was 1 deg.
 After: Step size is now 0.001 deg.
  Since the motor reading has six decimal places of precision and EPICS supports up to seven significant figures, values up to three decimal places are now handled.
  However, total(deg) currently rounds to the nearest integer due to Guardian's limitation on decimal handling.

  Planned Update:
   Guardian will be updated on Monday to support decimal points values.
   Adjustments can be made by modifying the SCALE and INFLATE parameters in medm_hwp_calib_callback.sh.

Change in DeadBand Value

 Before: Initial value was 0.002.
 After: Updated to 0.003.
  The error tolerance for the stop position has been relaxed.
  It is hoped that this change will correct the problem of PSL HWPs failing to stop or taking too long to stop.
　shift length
   +1deg x 30 times, followed by -30deg x 1 time as a set, 100 times repeated to check the stop position
   0.002: -0.0451725 deg
   0.003: -0.0494520 deg

Change in Stop Processing

　An asynchronous process now monitors the motor movement at 0.5 sec intervals.
　If the motor rotates less than 0.1 deg, it is considered an abnormal state, and the motor is stopped.

Source Code Modifications
Updated Files:

　/opt/rtcds/userapps/sys/k1/scripts/medm_hwp_calib.sh
　Modified SSH call handling.
　EPICS values are now parameterized.
　Callback-enabled function calls added.
　Decimal points support implemented.

　/kagra/apps/agilis/agilis-p_control.py
　→ Replaced with: agilis-p_control_with_callback.py
　　Added motor monitoring functionality.
　　Updated DeadBand value (0.002 → 0.003).

　Newly Added Files:
　/opt/rtcds/userapps/sys/k1/scripts/medm_hwp_calib_callback.sh
　　Handles callback reception from k1hwp to k1script.
　　Writes values to EPICS channels.
　　Initialization Behavior:
    When the reset command is executed or power is cycled (OFF → ON), the motor reading resets to 0.
    total(deg) value is copied to base(deg).
    total(deg) = motor reading + base(deg) (results in no effective change).

 /kagra/apps/agilis/agilis-p_control_reset.py
  Only executable on k1hwpX.
  Sends a reset command to the Agilis-P controller.
  After resetting, the motor initialization process in medm_hwp_calib_callback.sh runs at the next motor activation.
  Note: The reset command does not change the motor position.

Important Notes
 total(deg) Can No Longer Be Manually Overwritten

 Before: Pressing [<<REV] or [FWD>>] adjusted total(deg) by adding or subtracting step(deg).
 After: Pressing [<<REV] or [FWD>>] overwrites step(deg) with:
  base(deg) + Current HWP motor position
  If you need to manually adjust step(deg), update base(deg) as follows:
  base(deg) = Desired angle - (total(deg) - base(deg))

Next Steps
 After Guardian is updated to support decimal points values, total(deg) will be modified to accept decimal points values.