Update PBPS calibration guide

Aramis-Intensity-Diagnostics/PBPS-calibration-guide.md

@@ -1,27 +1,104 @@
-## Operating principle
+## Operating Principle
-Single shot diagnostic to measure relative pulse energy and beam position.  Back-scattered X-rays from a thin target (typically 50 nm silicon nitride) are measured by four photodiodes positioned above, below, left and right of the X-ray beam.
+The PBPS (Photon Beam Position Solid) is a **single-shot diagnostic** used to measure **relative pulse energy and beam position**. It functions by detecting **back-scattered X-rays** from a thin target, typically a **50 nm silicon nitride (Si3N4) film**. The scattered X-rays are captured by four **photodiodes** arranged around the beam:
 
-Position data maintains FEL pointing, while single-shot pulse energy measurements are used to normalise experiment data.  There is one PBPS in the front-end and two further devices per end station.
+- **Top** (Up)
+- **Bottom** (Down)
+- **Left** 
+- **Right** 
 
-## How to use
+These measurements are critical for:
+- **FEL pointing stability** (by tracking beam position)
+- **Experimental data normalization** (by measuring pulse energy)
+
+SwissFEL features **one PBPS in the front-end** and **two PBPS devices per end station**.
+
+---
+
+## How to Use
+### **1. Open the Photon Diagnostics Web App**
+[Click here to open](https://sf-photodiag.psi.ch/app)
+
+### **2. Select the PBPS Device**
+- Navigate to the **Position** or **Calibration** tab.
+- In the **first dropdown menu**, select the PBPS device you want to calibrate.
+
+### **3. Choose the Target**
+- In the **second dropdown menu**, select a target.
+- **Default target:** **50nm Si3N4**.
+
+### **4. Start Calibration**
+- Press the **Calibrate** button.
+- The system will:
+  - Normalize the response of the **four photodiodes**.
+  - **Scan the PBPS device** horizontally and vertically across the FEL beam.
+  - **Update the plots** with the calibration response (takes ~1 minute).
+
+### **5. Analyze the Results**
+- The updated plots show:
+  - **X-axis** → Device motor position (**Horizontal: left plot**, **Vertical: right plot**)
+  - **Y-axis** → Normalized **horizontal or vertical diode pair response**
+- **A good calibration** results in a **straight line** passing through the three scan points.
+
+### **6. Push the Calibration Results**
+- If the calibration looks good, press **"Push results/elog"**.
+- This updates the data processing pipeline and generates an **elog entry**.
+- After an **automated restart (~30s)**, the **PV and BS position & intensity data** will be updated with the new calibration.
 
-1. Open photon diagnostics [web app](https://sf-photodiag.psi.ch/app)
-2. Under Position/calibration tabs,s elect device from drop down menu 1
-3. Select target from drop down menu 2 - default target is 50nm Si3N4
-4. Press calibrate
 <img src="https://docs.google.com/drawings/d/e/2PACX-1vRGynTQ54ugugA_bM9pYc9eZDlet3Z9MSZWn17wJNwAEM2ORiJGoL8O61frpLBVRpFKlzJ7M05a5Mb1/pub?w=1245&h=1039">
 
+---
+
+
 The calibration procedure normalizes the response of the 4 diodes, then scans the device horizontally and vertically over the FEL beam to calibrate the position response.
 
 Once completed (approx 1 minute) the plots are updated with the calibration response.  Plotted on the x axis is the device motor position (horizontal - left plot and vertical - right plot) and on the y axis is plotted the normalized horizontal or vertical diode pair response.  For a good setup the plot should be a straight line through the 3 data points.
 
 If you are happy with the calibration, press the "Push results/elog" button where the new calibration data is sent to the required data processing pipelines.  After an automated restart (~30 seconds) both PV and BS position and intensity data will be calculated with the new calibration.  An elog entry is made detailing the calibration data.
 
-## Error
+
-**Soft limits**  
+## Troubleshooting
-Error message: `ERROR: Motor position outside soft limits`  
+### **Soft Limits Error**
-Problem is a soft limit on either the device Motor X or Y is blocking the scan motion
+#### **Error Message:**
-1. Select all from drop down menu for motor X and motor Y of PBPS GUI (shown below)  
+`ERROR: Motor position outside soft limits`
-2. Change motor soft limits to 1 and -1 for both motors  
+
-3. Retry calibration  
+#### **Cause:**
+- The PBPS **Motor X or Y** has hit a **soft limit**, preventing the scan.
+
+#### **Solution:**
+1. **Open the PBPS GUI** and locate the motor settings.
+2. **Modify the soft limits**:
+   - Set **Motor X soft limits** to `-1` and `1`
+   - Set **Motor Y soft limits** to `-1` and `1`
+3. **Retry Calibration**.
 <img src="https://docs.google.com/drawings/d/e/2PACX-1vSga-Zluo4b0isNs92C5MXfawMueNVk3ideRRDA_ZGQmD05Jn4noTS_pOl0OHiOyjS31OhLTAelFkYn/pub?w=728&amp;h=686">
+### **Additional Debugging Tips**
+- Ensure the **PBPS device is correctly selected**.
+- Verify that the **target is installed properly**.
+- Try manually moving the motor **in small steps** to check functionality.
+- If the issue persists, check for **elog messages** indicating motor faults.
+
+---
+
+## FAQ
+**Q: How do I know if my calibration was successful?**  
+A: If the diode response fits a straight line and the y-axis range is a few percent, your calibration is good!
+
+**Q: What happens if I push bad calibration results?**  
+A: The **old calibration** will be overwritten, which may cause **incorrect beam position data**. Make sure to verify results before pushing.
+
+**Q: Why does calibration fail even after adjusting soft limits?**  
+A: The device may be in a fault state. Try **resetting the motor controller** or checking the motor motion is completing by checking the motor GUI.
+
+---
+
+## 🎭 **Do Say / Don't Say**
+
+✅ **Do Say:**  
+- *"I just calibrated PBPS like a ninja!"*  
+- *"Let’s push these results to elog!"*  
+
+❌ **Don't Say:**  
+- *"What’s a soft limit?"*  
+- *"Do I really need to calibrate this thing?"*  
+
+---