Launch the PyDM Engineering Setup UI
1. Login to lcls-dev3 server
$ ssh lcls-dev3
2. Launch the top-level PyDM display
a. Find the name of IOC or CPU if you know either of them
ex) Soft IOC: sioc-b15-rf02, CPU: cpu-b15-rf03, shelf manager: shm-b15-rf03-1
[ktkim@lcls-dev3 ~]$ grep sioc-b15-rf02 $IOC/screeniocs # Find the line which has sioc-b084-rf54 in the $IOC/screeniocs file. When you don't know the CPU name, but IOC name sioc-b15-rf02 cpu-b15-rf03 laci # XTCAV/LLRF B15 Test Stand (HXR NC) [ktkim@lcls-dev3 ~]$ grep cpu-b15-rf03 $IOC/screeniocs # When you don't know the IOC names, but the CPU name cpu-b15-rf03 ts-b15-nw03 2014 lcls-dev1 # # IOCs that will be hosted by cpu-b15-rf03 (running linuxRT) sioc-b15-rf02 cpu-b15-rf03 laci # XTCAV/LLRF B15 Test Stand (HXR NC) sioc-b15-rf03 cpu-b15-rf03 laci # XTCAV/LLRF B15 Test Stand (SXR NC) sioc-b15-rf05 cpu-b15-rf03 laci # XTCAV/LLRF B15 Test Stand (HXR SC) sioc-b15-rf06 cpu-b15-rf03 laci # XTCAV/LLRF B15 Test Stand (SXR SC)
- $IOC=/afs/slac/g/lcls/epics/iocCommon
- All the IOC instances are located in this directory.
- sreeniocs: a script that has all IOCs and CPU information.
- To learn more about screeniocs and PyDM launch, click the link below:
atcaLLRF_UI.bash - launch the PyDM GUI for the LLRF IOCs
b. Useful information
$ cd $IOC # Where all the IOC instance information is located. $ pwd /afs/slac/g/lcls/epics/iocCommon [ktkim@lcls-dev3 iocCommon]$ cd sioc-b15-rf02 # Check one of the IOC information. [ktkim@lcls-dev3 sioc-b15-rf02]$ ls -l total 5 lrwxr-xr-x 1 ernesto cd 26 Aug 3 23:18 iocSpecificRelease -> iocSpecificRelease.ernesto/ lrwxr-xr-x 1 ernesto cd 75 Aug 3 16:14 iocSpecificRelease.egumtow -> /afs/slac/g/controls/development/users/egumtow/llrf_hls/R3.0.1_XTCAV.branch/ lrwxr-xr-x 1 ernesto cd 83 Aug 3 16:14 iocSpecificRelease.ernesto -> /afs/slac/g/controls/development/users/ernesto/sandbox/llrf_hls/R3.0.1_XTCAV.branch/ lrwxr-xr-x 1 ernesto cd 81 Aug 3 16:14 iocSpecificRelease.ktkim -> /afs/slac/g/controls/development/users/ktkim/sandbox/llrf_hls/R3.0.1_XTCAV.branch/ -rwxrwxr-x 1 ernesto cd 304 Aug 3 16:15 startup.cmd* $ env |grep EPICS_IOC_TOP # Where all the SLAC EPICS IOCs are located. EPICS_IOC_TOP=/afs/slac/g/lcls/epics/iocTop $ cd /afs/slac/g/lcls/epics/iocTop $ ls $ cd llrf_hls/ # Move to llrf_hls directory. $ ls R0.6.0/ R2.6.4/ R2.7.1/ R2.7.3/ R2.7.5/ R3.0.0/ R3.0.1-br/ llrf_hls-git/ master/ ued_support_v2/ R2.6.3/ R2.7.0/ R2.7.2/ R2.7.4/ R2.7.6/ R3.0.1/ llrf_hls-BsaCore_test/ llrf_hls-git_khkim/ ued_support/ $ cd R3.0.1-br/ # Move to specific branch you would like to go to. $ cd iocBoot/ # Where IOC instances are located $ ls Makefile common/ sioc-as01-ky01/ sioc-as01-ky03/ sioc-b084-rf52/ sioc-b084-rf53/ sioc-b084-rf54/ sioc-b084-rf60/ sioc-b34-rf13/
c. Launch the PyDM display
ex) iocName ==> sioc-b15-rf02
- The PV Name for the above IOC would be actually: SIOC:B15:RF02
- Launch the script: $ atcaLLRF_UI.bash
- BLD:<building #> → 15
- RF:<RF #> → 02
- INST:<Instantiation #> → 0
- INST is used to indicate the number of ATCA Carrier instances per IOC.
- Currently, there is only one IOC per LLRF ATCA board; so INST = 0
- However, one could have one EPICS IOC contain and run 2 LLRF ATCA cards.
- Then you would need to assign INST =0 for the first board and then INST =1 for the 2nd board.
$ atcaLLRF_UI.bash BLD: 15 RF: 02 INST: 0 [2022-07-20 23:06:21,294] [INFO ] - Using PyDM via SSH. Reverting to Software Rendering. PyDM 1.16.3
This is the main screen for the selected IOC. Check Buildstamp and Git hash (1) if the IOC uses the correct firmware.
Setup procedure
1. Setup Timing and Triggers
On the main screen, click the Timing button to bring up the timing related display. You will see this screen:
Verify that the RX Link Status is Link Up (1). This value tells you if the system is locked to the timing system.
If the status is not Link Up, verify that the Mode Selection is set to NC(Normal Conducting, LCLS1) (2), and under that the Timing Crossbar Switches, the FPGA output is set to RTM_IN0 (LCLS1) (3).
Timing crossbar switch for carrier without RTM
This instruction describes an AMC board that receives timing through the RTM (which are all the control stations). However, if the board doesn't have an RTM, and it receives the timing signal through the backplane, the FPGA output under the Timing Crossbar Switches in (3) must be set to BP.
You should also set up the master timing delay (TREF) in the LCLS1 master delay (4). The value of this delay depends on fiber length and needs to be tuned for each station. Make sure the Application Clock Speed (MHz) for LCLS1 is set to 119 and the Application Clock Speed (MHz) for LCLS2 is set to 185.714287 (5).
Then, click on the High Level Triggers (6) button to set up the triggers. You will see this screen:
Verify that Trigger Mode is set to ACCEL or STDBY or ACCEL_STDBY (1) and Enable/Disable is set to Enable (2).
Here make sure to select the appropriate event code, delays, and width parameters for all the triggers. For more information about how the different delay work, take a look at this document: TREF and Delay Setup.
DAQMUX triggers
The DAQMUX triggers in this screen are used to trigger the DaqMux firmware module which is used to display the raw waveforms on the main screen. As these signals are used only for debugging purposes, you should use a slow trigger, for example, a 1 Hz event code, which is:
- For FACET: event code 225
- For LCLS: event code 45
2. Setup PLLs
On the main screen, click the PLLs button to bring up the PLL-related display. You will see this screen:
First, check the reference channels. Check that the LO PLL Reference Demod Channel Select (1) on PLL-Control settings corresponds to the front panel channel where the RF phase reference is connected (DwnCnv:RF_IN_1 is usually used for the reference). For the CLK PLL, the Reference Demod Channel Select (2) must be set to UpCnv:TRIG_MON. The firmware engineers already found the optimal values of Kp and Ki of LO PLL and CLK PLL, Amplitude Loss Threshold, and Phase Lock Threshold. Thus, we don't have to adjust or care about them.
Check the reference signals' normalized amplitude (3). They must be between 0.5 and 0.9. Do not make saturation with too large amplitude > 0.9 or do not make it too small < 0.2. The LO PLL reference signal normalized amplitude can be adjusted using the corresponding attenuator (available on the main screen as below) to be in this range. The amplitude of the CLK PLL reference signal is internal and cannot be adjusted.
Check that both LO PLL DAC and CLK PLL DAC Control Muxes are set to PLL-Control (4).
Finally, you should see that for both LO PLL and CLK PLL, the Loss Signal Status is Presence, and the PLL Lock Status is Locked (5).
3. Setup the RTM inputs engineering unit scale factors
On the main screen, click the RF Interlock RTM button to bring up the RTM-related display. You will see this screen:
In this screen you can set scale factors for the three input signals: Beam Current, Beam Voltage, and Reflected Power. The scale factors will apply to the Fast ADC waveforms and peak values readings (2), the trip thresholds (3), and the fault history buffers waveforms (4).
To change the scale factors, click on the Scale Factors button (1). This will open this related display:
Here you can set the different thresholds for each input. For more details on how the scale factor works, please take a look here: FACET-II LLRF: RTM Analog Input Scale Factors
4. Setup the RF Output
On the main screen, click the RF DAC Out button to bring up the RF Output-related display. You will see this screen:
First, select the Reference Demod Channel Select channels for both Reference 0 and Reference 1 (1). These 2 references must be set to be the same as the channel corresponding to the front panel channel where the RF phase reference is connected. This should be the same channel that you used for LO PLL reference in 2-(1). We use RF_IN_1 as the RF phase reference.
Under RF Out Settings, verify that RF Output Enable is set to Enable (2) and that Mode Select is set to IQ Table (3).
Under Digital Filter Settings, verify that LO Select is set to Phase Corrected DUC (4).
Finally, you should set your Baseband IQ LLRF driver waveforms, by clicking the See/Change Baseband I/Q LLRF Driver Waveforms button (5). That will open this related display:
Caution
See/Change Baseband I/Q LLRF Driver Waveforms doesn't work for now. This is now updated to See/Change Baseband P/A LLRF Driver Waveforms in section 5-(c).
Phase Corrected DUC (Digital UpConverter) - 1
We have a digital PLL-based phase error correction in the UpConverter. The button, Phase Corrected DUC (4) activates the phase error correction. The digital PLL and phase correction work with the reference. Thus, we should set the Reference Demod Channel Select (1) in the UpConverter screen also. There are two reference channel settings, since, we only have one reference channel, we need to set up both of them to the single reference channel (RF_IN_1 in our case). As you can see, we have a flat line of phases as below. We are not sure how it behaves if we have two different reference channels. It may take an average between two channels, but we need to double-check to confirm.
Phase Corrected DUC (Digital UpConverter) - 2
If we activate the phase error correction without a proper setup of the reference channel, the digital PLL and phase error correction will malfunction, and it could make the phase drift. As you can see in the following two photos, when one of the reference signals is incorrect (1) and selects Phase Corrected DUC (2), the phase has a slope.
5. Setup the Feedback parameters
On the main screen, click the LLRF Feedback Setup button to bring the feedback setup-related display. You will see this screen:
Verify that Trigger Mode is set to ACCEL or STDBY or ACCEL_STDBY (1)
a. Set input signal labels
For each input channel, there is a user-customizable string PV which can be used as a label for the signal connected to them. These labels are shown under the column Signal name (1). In these displays, the PVs are read-only, so in order to modify them, you need to run a caput command from a terminal. The values are kept in autosave, so they won't be lost if the IOC is rebooted. You can get the PV name by middle-clicking the widget on the PyDM screen, which has the format $(DEV):DMOD_LABEL$(CH), where $(CH) is the channel number, starting at zero.
b. Select your reference and feedback signals
When you select which channels to use
When feeding back, we suggest that the channel you are feeding back on should be on the same ADC as the reference input. So, for example, if you are using RFIN2 as the reference, you should put your feedback channel onto RFIN1. Or, if using RFIN4 as a reference you should feedback on RFIN3. The pairs are 1/2, 3/4, and 5,6.
First, you need to select which channels correspond to your reference and feedback signals. Both the reference and the feedback signals can be a weighted combination of multiple channels, however, in our case, we will use only 1 channel for each of these.
The column Reference Weight (1) lets you set weights for each input channel used as a reference signal. In our case we have the reference signal from only 1 channel, so set to 1.0 as the weight corresponding to the front panel channel where the RF phase reference is connected. This should be the same channel that you used for the LO PLL reference, as well as for the DAC output reference such as 2-(1) and 4-(1). We usually use RF_IN_1 as a reference signal.
The column Feedback Weight (2) lets you set the weights for each input channel used as a feedback signal. In our case we have the feedback signal in only 1 channel, so set to 1.0 as the weight corresponding to the front panel channel or internal channel where the signal used as feedback is connected. We usually use RF_IN_2 as a feedback signal.
c. Setup the Baseband P/A LLRF driver waveforms
You should set your Baseband Phase and Amplitude LLRF driver waveforms, by clicking on the See/Change Baseband P/A LLRF Driver Waveforms button (1). That will open this related display:
Here you will see the Amplitude and Phase waveform PVs in the plot area. If you want to modify the waveforms, select the input signal (1) and go to Define new waveforms. This will allow you to define rectangular windows for both amplitude and phase.
First, enter the start and stop time (us) for the amplitude and phase windows in (2). You can define only one component (for example, only define the amplitude component) by leaving the other window's start and end time empty.
Then click the Write PV buttons (3). This will effectively write the waveforms into the real PVs (you will see the waveform PVs being updated in the plot).
Defining arbitrary window functions
This PyDM display, at the moment, supports only defining rectangular window functions. You can, however, define any arbitrary window function by writing the corresponding waveform values to the waveform PVs, from a python or Matlab script for example. You can get the PVs from the plot on the previous related display, which are: amplitude waveform PV = $(DEV):ABL_RBV, phase waveform PV = $(DEV):PBL_RBV.
d. Setup the feedback measurement windows
Now you need to define your average windows used for feedback. Under Average Window 0 for Feedback, click on See/Change Complex Window (1). This will open this related display:
Here you will see the current Amplitude and Phase waveform PVs for the average window in the plot area. If you want to modify the waveforms, select the input signal (1) and go to Define new waveforms. This will allow you to define rectangular windows for both amplitude and phase.
First, enter the start and stop time (us) for the amplitude and phase windows in (2). You can define only one component (for example, only define the amplitude component) by leaving the other window's start and end time empty.
Then click the Write PV buttons (3). This will effectively write the waveforms into the real PVs (you will see the waveform PVs being updated in the previous related display, in the Feedback Complex Window plot).
e. Setup the AMC input signal engineering unit scale factors
First, click the Scale Factors buttons (1).
Phase values
Phase values
The scale factors described here apply only to the signal amplitude and power readings. The signal phase readings are always expressed in degrees.
Amplitude values
Calibration order
During calibration, you must first calibrate the amplitude, and then the power readings. The relationship between the signal's amplitude and power is: Power = (Power Scale) * (Amplitude)2.
For each input channel, you can set a scale factor to convert the reading value, under the Scaled amplitude column (2), to engineering units. The scale factors for each input are available in the column Amplitude scale factor (1).
To figure out the scale factor follow this procedure:
- Start by setting the Amplitude scale factor (1) to 1.0,
- Apply a known signal to the input channels, and read the value from the Scaled amplitude column (2),
- Compute the scale factor as Scale = Applied signal level (engineering units) / read amplitude,
- Finally, set this calculated scale in the Amplitude scale factor (1) column for that channel.
You should now read the value in engineering units in the Scaled amplitude (2) column for that channel. Repeat this procedure for all the input channels.
Power values
Calibration order
During calibration, you must first calibrate the amplitude, and then the power readings. The relationship between the signal's amplitude and power is: Power = (Power Scale) * (Amplitude)2.
For each input channel, you can set a scale factor to convert the reading value, under the Scaled power column (4), to engineering units. The scale factors for each input are available in the column Power scale factor (3).
To figure out the scale factor follow this procedure:
- Start by setting the Power scale factor (3) to 1.0,
- Apply a known signal to the input channels, and read the value from the Scaled power column (4),
- Compute the scale factor as Scale = Applied signal level (engineering units) / read power.
- Finally, set this calculated scale in the Power scale factor (3) column for that channel.
You should now read the value in engineering units in the Scaled power (4) column for that channel. Repeat this procedure for all the input channels.
The relationship between the signal's amplitude and power is: Power = (Power Scale) * (Amplitude)2.
f. Setup the feedback engineer unit scale factors
Phase values
The scale factors described here apply only to amplitude values. The phase values are always expressed in degrees.
Time slot
The amplitude and phase feedback loop algorithms support 6 time slots, so on the screen, you will see values for all these time slots (rows TS 1 to TS 6). However, TCAV operates on only 1 time slot, TS 4. That is why the example above only highlights the values for this time slot.
A scale factor is available to scale all the feedback-related values. This will let you choose how to express the amplitude feedback-related values. You can work on normalized units ([0,1]), percentage ([0,100%]), or any arbitrary engineering units ([0,75kV]).
To set the scale factor:
- Disable the feedback loops by setting the Phase Feedback and Amplitude Feedback values to Disable (1).
- Click the Expert Settings (2). You will see the screen as below:
- Apply the scale factor to the Amplitude Drive (scaled) upper and lower limits (3). This value should be the maximum and minimum amplitude driver limits which represent in engineering units in your feedback signal.
- Then, go back to the LLRF Feedback Setup screen and click the Scale Factors button (4). That will open this related display:
- Set the Amplitude Normalization Factor (5). This factor should be the maximum DAC output value that is represented in engineering units in your feedback signal. For example:
- If you want to work in kV units, and the maximum DAC output corresponds to 75kV in your feedback signal, then set this factor to 75.0.
- If you want to work in percentage units, then set this factor to 100.0.
- If you want to work in normalized units, then set this factor to 1.0.
- Now, set AREQ (Amplitude Required) (6) to some amplitude value, and read the value from the Amplitude column (7) as below (Remember that AREQ is now expressed in the engineering units you selected above).
- Compute the amplitude scale factor as Scale = AREQ / read amplitude.
- Set this calculated scale in the Amplitude scale factor (8) column for that channel. You can see Amplitude column (7) is now the same as AREQ (6).
- You can now calibrate the power reading as well:
- Measure the actual power in the system.
- Set the Power scale factor (9) to 1.0.
- Read the value from the Power column (10),
- Compute the power scale factor as Scale = Measured power/read power.
- Finally, set this calculated scale in the Power scale factor (9) column for the feedback channel.
- Now, re-enable the feedback loops by setting the Phase Feedback and Amplitude Feedback values to Enable (1) on the LLRF Feedback Setup display.
Now, the amplitude set points (11), feedback signal amplitude, mean and jitter (12), and amplitude feedback loop parameters (13) will be expressed in engineering units. Also, your power measurement (10) will be expressed in engineering units
g. Setup the Beam Voltage scale factor
A scale factor is available to convert the Beam Voltage reading (1) to kV.
The scale factor is available in the Amplitude scale factor (2) under Beam Volts InputVOLT Conversion after clicking Scale Factors and it is expressed as kV/Count. The Beam voltage raw readings are 16-bit numbers, so they go from 0 to 65535.
How to operate the system
Once the system is properly configured as described in the previous section, you can use the system from the LLRF Feedback Setup screen:
On this screen you can:
- Setup the phase set point in PREQ (1), read the feedback signal phase under Phase (deg), Phase column, for the channel where the feedback signal is connected (2), and see the phase feedback loop parameters in (3).
- Setup the amplitude set point in AREQ (4), read the feedback signal amplitude under Amplitude (scaled), Amplitude column, for the channel where the feedback signal is connected (5), and see the phase feedback loop parameters in (6).
- You can also enable and disable either the phase and amplitude feedback loops independently in (7).
Time slot
The amplitude and phase feedback loop algorithms support 6 time slots, so on the screen, you will see values for all these time slots (rows TS 1 to TS 6). However, TCAV operates on only 1 time slot, TS 4. That is why the example above only highlights the values for this time slot.
The fault sequencer, which automatically handles and tries to recover faults, is described here: FACET-II LLRF: Fault Sequencer.
References
1. FACET-II LLRF: Checkout Instructions using PyDM
2. atcaLLRF_UI.bash - launch the PyDM GUI for the LLRF IOCs
3. LLRF Gen2 Up Converter Functional Test: Functional Test
Overview
Content Tools