Simple Instructions for Running the GCS Subsystem for Off-Axis Guiding and Wavefront Sensing

Background information for the GCS Subsystem

GCS Config Files Locations

GCS has a configuration file scheme that splits AGw configuration files up in a publicly accessible file containing settings that can be easily changed (i.e. hotspots, rotational offsets, etc.) by staff astronomers and a private file that contains hardware-related settings (IP addresses, port addresses, focal station assignments) that are not often modified.
The public files are in /home/telescope/TCS/Configuration/GCS/ (on CentOS obs workstations) and are owned by user telescope. On the tcs machines the public config files are in /lbt/data/config/tcs/GCS/.
The private files are in the config file directory /lbt/tcs/current/gcs/configuration/GCS/ on the tcs machines, and are not typically modified. The private files are distributed with each TCS Build. The section about configuration files below provides the details of the configuration files.

GCS Command Line Tools

In the absence of the fully functional GCSGUI, certain command line tools are available to control GCS. These are in the PATH. They are for engineering use and can confuse the TCS. Using them during science operations can result in bad or lost data.
Note: Every GCS command line program requires the function name as the first parameter and the side as the second parameter, which has to be 'left' or 'right'. 'left' indicates that the command should be processed by GCSL whereas 'right' indicates that GCSR should handle the request.

gcsclient selectAGW [left|right] public_AGW_config_file_name

Selects the AIP AGW unit for GCS, bypassing any side or focal station definition restrictions by specifying the public AGW config file name directly. This should not be done during science operation as it can confuse the TCS. There still has to be a matching entry that then specifies the private AGW config filename that goes with the public name in order to successfully select a new AGW. This can be used to force GCS to reread the configuration file. You can specify a public AGW configuration file to use which has to be in ~telescope/TCS/Configuration/GCS/ in order to be usable.

• gcsclient selectAGW left MODS_L.cfg for MODS1 at Left Direct Gregorian
• gcsclient selectAGW left LUCI_IRTC_DG_L.cfg for IRTC and AGW4 at Left Direct Gregorian
• gcsclient selectAGW left LUCI_IRTC_L.cfg for IRTC and AGW1 at Left Front Bent Gregorian
• gcsclient selectAGW right LUCI_IRTC_R.cfg for IRTC and AGW2 at Right Front Bent Gregorian
• gcsclient selectAGW left LUCI_L.cfg for LUCIFER and AGW1 at Left Front Bent Gregorian
• gcsclient selectAGW right LUCI_R.cfg for LUCIFER and AGW2 at Right Front Bent Gregorian

(Note that the details of exactly which .cfg file to use can vary. An agw might be moved from one focal station to another, config parameters changed, etc. There are many different files to choose from. The above is to be taken as a general guide. Look in the public configuration directory described above to see what is the current best file to use.)

NOTE: As of build 2015B (Patch 3.3c - 22 May 2015), the GCSGUI indicates on the main guiding panel which AGW is currently selected. If the AGW is not the one designated for the authorized instrument on that side, the information is displayed in yellow (indicating a warning). It is only a warning because once a Preset is issued, the GCS will check that the proper AGW is in use ("selected") for the known authorized instrument. If there is a mis-match detected, the GCS will pro-actively select the proper AGW for use. (MDD 03 June 2015)

For new focal station / instrument / agw combinations, make sure the configuration file has the right settings before issuing this command.

gcsclient setNewInstrument [left|right] {instrument} {focal station}

This command is used to select an AGW unit based on the given instrument name and focal station. Both parameters must be provided as for instrument authorization, they are not case sensitive though. The command can also be used to bypass a previous selection or to force the use of a specific AGW unit. This should not be done during science operation as it can confuse the TCS. If the GCS is restarted it reads the previously selected instrument and focal station and automatically tries to select the associated AGW unit.
The matrix that defines which configuration file is used for the instrument/focal station combination is /lbt/tcs/current/gcs/configuration/GCS/Instrument2AGW.cfg With every new Authorize command to the telescope this function is triggered internally by IIF to request an AGW selection.

• gcsclient setNewInstrument right irtc bentgregorianfront selects the AGW for use with IRTC in BGF position (AGW #2)
• gcsclient setNewInstrument left irtc bentgregorianfront selects the AGW for use with IRTC in BGF position (AGW #1)
• gcsclient setNewInstrument left lucifer bentgregorianfront selects the AGW for use with LUCIFER (AGW #1)
• gcsclient setNewInstrument left irtc directgregorian selects the AGW for use with IRTC in DG position (AGW #3)
• gcsclient setNewInstrument left pepsipfu bentgregorianrearfiberfeed selects the AGW for use with PEPSIPFU (AGW #7)

gcsclient setGS [left|right] -x [ra] -y [dec]

Set the guidestar coord to RA/DEC and move probe to position. This needs the help of PCS to determine where in the focal plane this RA/DEC position would be.

gcsclient setExpTime [left|right] [ttttt]

Sets the exposure time in milliseconds for guide camera. The minimum and maximum limits as defined in the instrument configuration file are enforced.

gcsclient setFilter [left|right] [f]

Selects a filter 1-5 on the AGW unit. Warning: GCS numbers the filters starting at 1, while oaccontrol starts numbering at 0. To decide which filter to use, look at the active configuration file which contains descriptions and wavelengths for each filter number.

Filter locations for AGW1 are (/lbt/tcs/current/gcs/configuration/GCS/LUCI_L.cfg) are: 1=B 2=V 3=r' 4=empty 5=empty.

gcsclient setFocus [left|right] [mm.m]

Sets focus (z-axis) position of the AGW probe 0.0 to 46.0 mm.

gcsclient setGSsfp [left|right] -x [xx.x] -y [yy.y]

Sets guidestar to given SFP coordinates in mm and moves probe. This commands bypasses the RA/DEC conversion through PCS and directly specifies a SFP position. Omitting the arguments will send the probe to the on-axis position. THIS DOES NOT MOVE THE MODS GUIDER STAGE - see the MODS utility programs for that (modsAGW 2 setxy 0 0).

gcsclient startGuiding is not a command ----> see closeLoop

gcsclient stopGuiding [left|right]

Stops guiding.

gcsclient offsetProbe [left|right] -x xOffs.KFP -y yOffs.KFP

This allows the probe to perform a relative move from its current position. Provide x and y offsets in KFP coordinates. Check resulting position with getStatus command. Make sure that the guide loop is paused before issuing this command. This command has been introduced with GCS V2.6.4 B1 as of build 2012C.

gcsclient pauseGuiding [left|right]

Pauses guiding (in a state that can be resumed)

gcsclient resumeGuiding [left|right]

Resumes guiding (if it was paused)

gcsclient closeLoop [left|right]

Tries to close guide loop at present probe position. This command wants you to specify the coordinates of the guide star in advance by using setGS or setGSsfp.

gcsclient getStatus [left|right]

Shows much relevant GCS information

gcsclient setHotspot [left|right] -x [xxx] -y [yyy] (reinstated Sep 2011)

Set the hotspot for guiding in absolute CCD pixel coordinates. This can be used during guiding, but take care to make small moves so as not to push the star out of the small guide box. The guider can handle steps of 10 pixels.

To center the star on the wavefront sensor pinhole manually (an obsolete talent):

• use getHotspot to learn the current hotspot command
• iteratively apply the setHotspot command changing x and y by not more than 10 steps per iteration
• continue until you reach the WFS hotspot of -x 292 -y 255

gcsclient getHotspot [left|right]

Return the absolute CCD pixel coordinates of the guiding hotspot.

gcsclient readGuideCam [left|right] -e [ttttt] [N]

This is the command formerly known as "sim". This takes N guide camera images with the specified exposure time in millisec. The files are stored in a "shared" directory /lbt/data/share/tcs named by username and date. The command will refuse to function if GCS is using the guide camera because of a closed guide loop or if it is in the continuous full CCD read out mode. The command sets the exposure time to the specified value before taking the image and returns it to the prior value after the image. Note this function has an expanded range for the allowed exposure time of [10:200000] milliseconds as compared to the limits imposed by the instrument configuration files.

If there's no error message and you don't find the image in the specified directory the most likely reason is that GCS was not allowed to write to the directory.

For example, as user telescope on obs3 :

[telescope@obs3 ~]$ gcsclient readGuideCam left -e 100
readGuideCam: acquiring full guider image ...
GCS side: left
exposureTime = 100 ms
new image (1/1) received in 1.85462secs : /lbt/data/share/tcs/telescope.20150910/left_guider000001.fits
seconds needed for 1 images: 1.85467
this is 1.85467 seconds per image

The filenames will be [left|right]_guider000001.fits and higher for the readguideCam program and for the readWFSCam it will be [left|right]_wfsc000001.fits and higher.

All image acquisitions with this and the readWFSCam command are channeled through GCS, so the subsystem has to be up and running in order for these client commands to function.

gcsclient getGuideCamSubWindow [left|right]

Reads guide camera readout area, where the first pair of output parameters define a lower left corner of the camera readout area pixel coordinate, and the second pair of the output parameters defines width and height of the camera readout area in pixels.

gcsclient setGuideCamSubWindow [left|right] -x [pix] -y [pix] -w [pix] -h [pix]

Sets guide camera readout area, where -x and -y define a lower left corner of the camera readout area pixel coordinate, and -w -h define width and height of the camera readout area in pixels. GCS restart is not required.

gcsclient readWFSCam [left|right] -e [ttttt] [N]

This is the command formerly known as "wfssim". This takes N WFS camera images with the specified time in milliseconds. The files are stored in a "shared" directory /lbt/data/share/tcs named by username and date. The command will refuse to function if the GCS is already in closed WFS loop. The command sets the exposure time to the specified value before taking the image and returns it to the prior value after the image. Note this function has an expanded range for the allowed exposure time of [10:200000] milliseconds as compared to the limits imposed by the instrument configuration files.

For example:

[telescope@obs3 ~]$ gcsclient readWFSCam left -e 100
readWFSCam: acquiring full wfsc image ...
GCS side: left
exposureTime = 100 ms
new image (1/1) received: /lbt/data/share/tcs/telescope.20150910/left_wfsc000001.fits 

The filenames will be [left|right]_wfsc000001.fits and higher.

All image acquisitions with this and the readGuideCam command are channeled through GCS, so the subsystem has to be up and running in order for these client commands to function.

gcsclient setWFSExpTime [left|right] [ttttt]

Sets the exposure time in milliseconds for WFS camera. The minimum and maximum limits as defined in the instrument configuration file are enforced.

gcsclient sendCentroidsToPCS [left|right] [0 or 1]

This controls whether GCS sends guiding Centroids to PCS after it analyzes the guider image. Parameter "0" means don't send, parameter "1" means send.

gcsclient sendZernikesToPSF [left|right] [0 or 1]

This controls whether GCS sends Zernikes to PSF after it analyzes the WFS image. Parameter "0" means don't send, parameter "1" means send.

gcsclient startAcquire [left|right]

Start acquire mode with full-frame movie mode on GCS GUI. There are a couple of preconditions that have to be met for the command to succeed:

• GCS must not be guiding
• an AGW unit must have been selected (check with getStatus if unsure)
• as the startAcquire command also moves the AGW probe to a defined position a guide star must have been provided. (you can do that on the command line by calling "setGSsfp", no parameters will drive it to on-axis position or use "-x mmSFP -y mmSFP" for anything else.)
• GCS must not already be in ACQUIRE mode
• the AGW probe position must be reachable and the move must succeed

gcsclient stopAcquire [left|right]

Stop acquire mode.

gcsclient startWFS [left|right]

Start the wavefront sensing loop, taking WFS images and analyzing them. (IIF thinks WFSing is paused when you run it this way.) Guiding must be running.

gcsclient stopWFS [left|right]

End the wavefront sensing loop.

gcsclient triggerWFS [left|right]

Requests GCS to take a single WFS image and analyze it. (Guiding must be running.)

gcsclient processWFSImage [left|right] [path/filename]

This command was implemented in a patch to Build 2018B on 20180906 to make it simpler for GCS to process an offline image. The associated .info file will be overwritten. Take care that the path is one that can be seen (with write permission) by GCS from the tcs machines (e.g. /lbt/data/share/tcs/user.date). Operational parameters such as rotator angle and probe position come from the FITS header while configuration parameters come from the config file (e.g. LUCI_L.cfg).

GCS Configuration (Private)

Parameters in /lbt/tcs/current/gcs/etc/gcs.conf

Note: All parameters are sided! They have to start with 'GCSL.' or 'GCSR.' in order to indicate which side the settings refer to. In the following example we just list the parameters for GCSL.

GCSL.wfsInterval (seconds)

default WFS interval if nothing is selected explicitly. This is the guide rate equivalent for the WFS track. If set to less than the minimum WFS exposure time the loop will always run as fast as possible. If set to something greater than the loop needs to acquire and process an image, the loop will be delayed to match the set interval time. The current default is 5 seconds.

GCSL.guideRate (Hz)

default guide rate if nothing is selected explicitly. The default is 0.2 Hz. Set it so something higher than the possible acquisition rate of the camera and the loop runs as fast a possible. Only evaluated at GCS start.

GCSL.debug

engineering use only. This will add very detailed log messages in some critical places of the current version at the time of GCS.. Defaults to false. Only evaluated at GCS start.

GCSL.profiling

defines if profiling messages should be added to SysLog. Defaults to true. Only evaluated at GCS start.

GCSL.noAGW

Disables the access to the probe if set to true. Good for downtown testing without having real hardware. Only evaluated at GCS start. Defaults to false on the mountain.

GCSL.noTCS

Eliminates communication with other TCS entities such as PSF or PCS if set to true. Good for standalone testing. Only evaluated at GCS start. Defaults to false on the mountain.

GCSL.noAzCam

Does not talk to the AzCams and simulates guide images (and loads prepared WFS images if put in /tmp for simulation in the WFS track). Only evaluated at GCS start. Defaults to false on the mountain.

GCSL.starOverlay

This overlays an artifical guide star on images read from the AzCam server. Be careful to not set this to true while noAzCam is set to true as well, as this will create double stars. This flag is useful when all you can do is get dark images from the guide camera (closed dome testing) but you want to close the guide loop for full communication and process testing. Only evaluated during GCS start. Defaults to false on the mountain.

GCSL.delayVerification

This defines if the star verification after acquisition and offsets should match the guide rate (and delay image acquisition) or if it should as fast as possible without any delays in between images. This defaults to false on the mountain. Beware that in test modes such as noAzCam = true image acquisition is extremely fast and you might want to delay star verification when in this mode.

GCSL . DDupdateDelay (milliseconds)

This defines the delay in GCS between updating GCS DD variables Default is 250ms and should be not less than this as the DD cannot be updating faster than with 4 Hz.

GCSL.secondsOfBadGS (seconds)

When the guide star is lost, this defines after how many seconds of not having detected a guide star the GCS should enter a warning state and throw an event, etc.

GCSL.cyclesUntilStable (iterations)

This defines after how many good guide images (star within maximum allowed distance from hotspot) the star verification is deemed to be successful.

GCSL.cycleLimit (iterations)

Defines the maximum number of iterations within the star verification has to succeed before it will fail

GCSL.internalCentroiding

When set to true the external centroiding program (currently Sextractor) will not be invoked and only internal centroiding routines will be used. When set to false, the external program will be called first - should it fail to detect a star, the internal algorithm will kick in as a backup algorithm. This procedure is repeated with every image analysis, the external program will be called first if this flag is set to false.

GCSL.sextractorFlags

Sextractor returns flags for each star detected. For the GCS to accept a specific result as a valid star the flags for the star have to be less or equal to this value. Defaults to 28. Range is 0 to 255.

GCSL.maxAGWerrors

limit of error reading AGW sensors before unit is deemed to have lost power and is deselected (0 = don't worry about these errors)

GCSL.sextractorClass

for a star in the sextractor output to be accepted by GCSL the star class value has to be greater or equal to this configuration value (range is 0.0..1.0)

GCSL.maxEllipticity

defines the maximum allowed ellipticity that will not trigger a warning during times of low WFS RMS values (as defined in AGW config files under WFS_rmsLimit - default is 400.0nm)

GCSL.readTemperatures

enables the code that updates dewar temperatures of selected AGW unit in DD (might interfere with closed loop operation, so there is a flag to switch it off)

GCSL.oacontrol_IP_AIP

IP/DNS name for the agw-control machine that runs the oacontrol service for the AIP AGW stage movements

GCSL.oacontrol_IP_OSU

IP/DNS name of the oacontrol-equivalent the MODS AGW stage movement

WFSgridIterations

how many iterations to try to minimize the tip/tilt in the grid positioning, 0 disables the iteration, 6 is the default if value is absent from gcs.conf

GCSL.maxFWHM

upper limit for FWHM of any source accepted in Source Extractor output in arcsecs

GCSL.driftingHotspot

temporary sanity flag to disable a new feature that allows for a drifting hotspot in the closed guide loop, setting this to false puts the previous static hotspot code back in action. This has to be enabled for non-sidereal guiding to work

GCSL.weightSourcesFlag

temporary sanity flag to enable a new feature that uses a weighting scheme to choose the proper guide star in the acquisition field. Setting this variable to a value of false re-activates the function which simply chooses the brightest "star" found and assumes this is the guide star.

AGW selection

When an instrument is authorized for access to the telescope the IIF sends the instrument name and focal station to the GCS responsible to serve the selected side. GCS looks up the AGW unit in the file Instrument2AGW.cfg in its configuration directory and looks for the matrix of side, instrument name and focal station. If there is a definition for this combination it uses the specified AGW configuration file to identify IP addresses and all related settings. When you are testing different things and you're bypassing the usual authorization process you can mimic the IIF activity by using the command setNewInstrument or the deprecated selectAGW.

Instrument2AGW.cfg

The format of this file is this:

#
# which AGw unit to use with which authorized instrument
#
L_LUCIFER_BENTGREGORIANFRONT    LUCI_L.cfg      string
LUCI_L.cfg      AGW3.cfg        string
#
L_IRTC_BENTGREGORIANFRONT       LUCI_IRTC_L.cfg string
LUCI_IRTC_L.cfg AGW3.cfg        string
#
L_MODS_DIRECTGREGORIAN  MODS_L.cfg      string
MODS_L.cfg      MODS1.cfg       string
#
etc.

A hash sign (#) indicates a comment and everything after the hash sign will be ignored. The first column is the key which consists of the concatenated strings for SIDE, INSTRUMENT and FOCALSTATION as they will be found in the DD. To ensure that there are no problems with lower or upper case, the whole string is converted to upper case.
The second column defines which public AGW configuration file used with this key. Make sure the file exists and has valid contents. Case does matter with the file name so ensure that it is right.
The last column has to be set to "string" for the Configuration class to detect the file name properly.

The file name for the public AGW configuration is not just used to load the configuration parameters but also to determine the file name containing the Zernike scale factors. So, if you add additional AGW configuration files you must not forget to also create a matching Zernike scale factor file in place as well as GCS won't be able to complete the AGW selection if you fail to do so.
In addition to a public file containing the astronomically relevant configuration for this AGW, there is also a private file that contains hardware specific settings for the AGW and determines which physical to use. This is specified in the second line following the the definition for the focal station. It starts with the AGW public config file name as the key and then specifies the private AGW config file name in the second column. While the public AGW config file resides in ~telescope/TCS/Configuration/GCS and can be easily changed by astronomers and the TO, the private file is in a GCS system directory and ought not be changed. There is one additional public files (in addition to the actual public AGW config file) that has to be there for an AGW selection to succeed. As they are all derived from the AGW config file name I will use a placeholder for this part of the name:

John's note from IT 7252: Here's a nasty little trap in how GCS reads the Instrument2AGW.cfg file. It took about 40 minutes to figure this out while trying to get GCSL to talk to AGW3 instead of AGW1. Success was at 02:16 UT on 20180602 with various failed selectAGW commands in the hour before that.

gcsclient selectAGW left LUCI_L.cfg

Instrument2AGW.cfg is layed out as follows (only a fraction of the total file) with my initial change in place. Note that there are two lines of text per focal station.

L_LUCIFER_BENTGREGORIANFRONT LUCI_L.cfg string
LUCI_L.cfg AGW3.cfg string
#
L_LUCIFER_BENTGREGORIANARGOS LUCI_L.cfg string
LUCI_L.cfg AGW1.cfg string
#
L_RETROREF_BENTGREGORIANFRONT LUCI_L.cfg string
LUCI_L.cfg AGW1.cfg string
#
L_RETROREF_BENTGREGORIANARGOS LUCI_L.cfg string
LUCI_L.cfg AGW1.cfg string

It turns out that GCS only saves one "AGW" per config file (LUCI_L) regardless of how many focal stations use that config file. So GCS won't use AGW3 until you change the last such entry after RETROREF.

L_RETROREF_BENTGREGORIANARGOS LUCI_L.cfg string
LUCI_L.cfg AGW3.cfg string

A vastly better scheme would be to have 3 entries per line:

L_LUCIFER_BENTGREGORIANFRONT LUCI_L.cfg AGW1.cfg string

Failing that coded improvement, we should recast the Instrument2AGW.cfg file like this to make it more obvious how it works: (I've not tested this.)

L_LUCIFER_BENTGREGORIANFRONT LUCI_L.cfg string
L_LUCIFER_BENTGREGORIANARGOS LUCI_L.cfg string
L_RETROREF_BENTGREGORIANFRONT LUCI_L.cfg string
L_RETROREF_BENTGREGORIANARGOS LUCI_L.cfg string
#
LUCI_L.cfg AGW1.cfg string

{AGW_config_file_name}_RM_sub11.cfg

An example for an actually existing file for this one is: LUCI_L_RM_sub11.cfg
This defines the the scale factors and or offsets for every Zernike mode depending on the used RM and the WFS sensor. So if we had different Reconstruction Matrices and WFS sensor sizes, the file name could vary even in the suffix part. Fortunately, we don't have that yet which will keep this description a bit more simple.
The format of the file is like this:

scale_Z4        -1.50   double
scale_Z5        1.70    double
scale_Z6        -1.60   double
.
.
.
scale_Z21       0.0     double
scale_Z22       -1.60   double
offset_Z4       0.0     double
offset_Z5       0.0     double
offset_Z6       0.0     double
.
.
.
offset_Z21      0.0     double
offset_Z22      0.0     double

Where the order is not important but you have to ensure that there is a definition for scale_* and offset_* for every mode from Z4 to Z22.

GCS / AGW Configuration Parameters (Public)

See the newer description of the parameters in https://wiki.lbto.org/Software/GCSConfiguration

I will focus on changes that might have to be done to get AGW #4 working in the Direct Gregorian position for now:

I tried to determine from AIP ahead of time if the filter configuration for unit #4 will be the same as it is for #3 but couldn't get an answer, so you might want to change the filter defintions in the AGW config file:

filter_1_name           B               string  # human readable filtername for presentation in the GUI
filter_2_name           V               string  # human readable filtername for presentation in the GUI
filter_3_name           r'              string  # human readable filtername for presentation in the GUI
filter_4_name           empty           string  # human readable filtername for presentation in the GUI
filter_5_name           empty           string  # human readable filtername for presentation in the GUI
filter_1_wl             440             int     # center wavelength of filter position
filter_2_wl             520             int     # center wavelength of filter position
filter_3_wl             630             int     # center wavelength of filter position
filter_4_wl             0               int     # center wavelength of filter position
filter_5_wl             0               int     # center wavelength of filter position
defaultFilter           3               int     # which one should be used in absence of a GS WL?

Important here is to set the correct default filter as this will be set during first selection of the unit. Note that GCS filter 3 is AGW filter 2 as GCS is one-based wheras AIP's oacontrol is zero-based.

You will definitely have to change the hotspots for the guide camera and WFS camera (the latter defines the center of the array of spots on the CCD) and maybe some of the related values:

guidecam_hotspot_x      289.0           double  # ccd x coordinate of pixel that represents center of light in WFS pupil
guidecam_hotspot_y      252.0           double  # ccd y coordinate of pixel that represents center of light in WFS pupil
guidecam_center_x       255.0           double  # center of guidecam to use for inital GS acquisition with MODS, this is also the spot used as the reference to build a pointing model!
guidecam_center_y       169.0           double  # center of guidecam to use for inital GS acquisition with MODS, this is also the spot used as the reference to build a pointing model!

The guidecam hotspot coordinates are specified in physical detector space on the CCD, so they do not need to be changed as a function of ROI or binning. They will need to be changed if the guider camera is remounted in the AGW unit.

WFScam_hotspot_x        380.9           double  # ccd x coordinate of pixel that represents x-center of WFS spots (20210903 JMH)
WFScam_hotspot_y        244.6           double  # ccd y coordinate of pixel that represents y-center of WFS spots (20210903 JMH)

WFScam_hotspot_x,y is the position of the center of the pupil on the S-H wfs camera when the guide probe is on-axis. This value can change when the AGw optics are realigned. (Yes, we know that multiple uses of the word "hotspot" was a terrible idea. "pupil center" would have been a better name.) Because the AGw optics are NOT telecentric, the position of the pupil on the wfs camera varies with position of the guide probe in the field. This variation is handled by WFS_r_ro_pupil_shift and related variables below.

WFScam_hotspot_sext_x        401.7           double  # ccd x coordinate of pixel that represents x-center of WFS spots
WFScam_hotspot_setx_y        220.9           double  # ccd y coordinate of pixel that represents y-center of WFS spots
WFScam_spacing_x        13.3            float   # distance of spots in pixels on x axis
WFScam_spacing_y        13.3            float   # distance of spots in pixels on y axis

WFScam_hotspot_sext_x,y specify the lower left corner of the lenslet grid. Since the lenslet array is glued to the wfs CCD, this number only changes when a different wfs camera is installed. (Ignore the misleading comment in the config files.)

More basic settings to address the correct cameras, probe positioning and rotator information are in the private file and should not be touched.

Now here are two new values that might have to be tweaked because the direct Gregorian focus has one less mirror in the optical path than bent Gregorian. When the Zernikes are rotated to be applied to the static Primary Mirror coordinate system, the following values will define how the rotation should be done:

WFS_ZrotatorDirection  1.0             float   # multiplication factor for rotator angle (to change direction use -1.0)
WFS_probeRotationFactor 1.0             float   # used to change how the probe rotation is added to the rotator angle (use -1.0 to subtract it from rotator, 0.0 for MODS)

In BG the values are +1.0 and +1.0. If the rotator angle for the Z rotation should turn the opposite way, use -1.0 for WFS_ZrotatorDirection. If the small compensation for the camera rotation due to the Phi-stage should be applied in the opposite direction set WFS_probeRotationFactor to -1.0.

WFS_xy_transpose        true            bool    # define if the pupil shift correction should be transposed (MODS)
WFS_pupil_shift_x       -1.0            float   # pupil shift factor in x
WFS_pupil_shift_y       1.0             float   # pupil shift factor in y
WFS_pupil_dir_x              -1              int     # which direction will the pupil shift? Default is +1 (see IT 8472)
WFS_pupil_dir_y              1               int     # which direction will the pupil shift? Default is +1
WFS_r_to_pupil_shift    0.16    float   # radius to pupil shift relation (change from 0.124 to 0.16 20180910 UT JMH)
WFS_pupil_rotoffset     5.0             double  # angle (degrees) between x.y stage motion and x,y pupil motion

Note that when WFS_xy_transpose is true (MODS), IDL and GCS use a value of WFS_pupil_rotoffset with the OPPOSITE SIGN. (JMH 20210202)

Note that WSF_pupil_shift_x,y and WFS_pupil_dir_x,y have seemingly redundant names and descriptions. (JMH 20210920)

Note: the configuration values are being read before every image processing

Now follows an older but somewhat still current description of how to optimize the automatic exposure time settings and centroiding sensitivity.

Optimizing centroiding sensitivity and automatic exposure time setting (as of October 2008)

There is one vital configuration file for GCS. On the mountain it's located in /lbt/tcs/current/etc/GCS/AIP_L.cfg. Leave those values alone if you don't know what you're doing would be a good advice to follow.

guidecam_exposureTime   2000            int     # ms of exposure time that's set by default and this is the start value for the acquisition image
guidecam_minExposure    500             int     # minimum ms of exposure time for auto adjustment to avoid correcting atmospheric dispersions

The maximum exposure time for the guide cam will be determined by the guide rate, so it's dynamic and not configurable.

WFScam_exposureTime     30000           int     # ms of exposure time that's set by default
WFScam_minExposure      15000           int     # minimum ms of exposure time for auto adjustment to avoid correcting atmospheric dispersions
WFScam_maxExposure      45000           int     # maximum ms of exposure time before failing because star is too dim

guidecam_saturation     65000           int     # beyond this number of counts the image is considered to be saturated or suffer from the effect
guidecam_lowCounts      1000             int     # low water mark for counts above background that cause adjustment of exposure time after full CCD readout
guidecam_highCounts     45000           int     # high water mark for counts above background that cause adjustment of exposure time after
full CCD readout

WFScam_saturation       30000           int     # beyond this number of counts the image is considered to be saturated or suffer from the effect

(This value 0f 30000 is caused by a peculiarity of this particular WFS camera. Normally it is 65000.)

WFScam_lowCounts        1000             int     # low water mark for counts above background that will cause auto exposure time adjustment
WFScam_highCounts       25000           int     # high water mark for counts above background until auto exposure time adjustment will be triggered
WFS_lostGSlimit         25.0            float   # how many percent of the exposure time can the GS be lost until the WFS image becomes worthless
countThreshold           100             int     # number of counts a star has to be above background level to be recognized as a valid guide star

This is what they should look like. If you have the feeling the GCS should acquire a guide star but it says it can't find one where you think it is, that is very likely to be an issue of a too dim guide star. If you start tweaking these values, it might lock on the star but it will introduce other problems that affect the proper functionality of guiding and particularly WFS.

If you tweak it anyway, please obey the following rules:

- NEVER set WFScam_minExposure time below 15 seconds, you will try to do adaptive optics instead of active optics and mirror will be less well collimated than better. If this seems necessary, the guide star is simply too bright.

- It is OK to set WFScam_maxExposure to 30000 ms which is the same as the default

- NEVER set guidecam_minExposure to less than 500 ms as this will not correct for tracking errors but atmospheric dispersions (a job for adaptive optics again).

- NEVER set countThreshold to a value below 100. It defines the peak value above background noise to accept a star as a valid star. If your star is too dim or the seeing is bad or the mirror is not collimated yet, setting it to something lower might cause the value to be within one standard deviation of the background noise and the guide loop might actually close. But if active mode was requested, it will also start the WFS exposure and it relies on the guiding part to positively identify a guide star. If the loop lock was accidental and there is an extremely dim something being identified as a star the WFS will rather run the mirror out of collimation than into it. You're not doing yourself a favor trying that.

If you want to tweak the automatic exposure time adjustments, here is how it goes:

for guidecam or WFScam, change the lowCounts and highCounts values. If the peak value of a star (or WFS spot) is below the lowCounts limit, the system tries to enhance the exposure time to get it within the limits if the maximum exposure time definition (or the guide rate) allow it. If the peak value exceeds the highCounts limit, the system tries to lower the exposure time to avoid saturation effects, if the minimum exposure time settings allow for it. Therefore, if you want to disable the adjustment at all, set the lowCounts to 0 and the highCounts to 65535 or eliminate just one adjustment by setting it to the physical limit. If you want to ensure the exposure time is never being reduced, set highCounts to 65535. If you want to ensure the exposure time is never being prolonged set lowCounts to 0. Don't mix up high and low counts as there's no sanity check in GCS yet that would recognize that.

Finally, if you experience problems with the WFS being strange on a cloudy day, it might be because the guide star was lost during the WFS exposure due to clouds. WFS_lostGSlimit defines in percent of the WFS cam exposure time, how much of that time the guide star is allowed to be invisible before the current WFS exposure will be considered to be failed and the image will not be thrown away. If this value is too high, it could cause incorrect corrections being sent to PSF in such a case. If you're conservative, set it to a smaller value.

When you change WFS related settings in AIP_L.cfg you don't have to do anything for the changes to become effective as these values are being reloaded each time a new WFS image is coming in.

-- TorstenLeibold - 09 Nov 2011