9.2 Internal Software Interfaces

9.2.1 SC to Wavefront Controller Subsystem (WFC)

This interface is defined by:

The command interaction between the two subsystems and their formats. Commands are categorized in functional groups.

: Each of these functional commands is implemented with a set of channel access variables.

The telemetry data that continuously flows from WFC to SC during normal operation,
The diagnostic data that flows from WFC through disk to the UI,
A set of control signals, corresponding to asynchronous events.
An RS-170 video signal from the GTRI camera.
A set of configuration files resident on the WFC disk.

9.2.1.1 Wavefront Controller commands and State variables

9.2.1.1.1 WFC System State

: k2:ao:wcState
: off | Idle | active | ???

9.2.1.1.2 DM Loop State

: k2:ao:wc:dmState

9.2.1.1.3 TT Loop State

: k2:ao:wc:ttState

9.2.1.1.4 Telemetry State

: k2:ao:wc:telemState

9.2.1.1.5 Diagnostic State

: k2:ao:wc:diagState

9.2.1.1.6 Current DM Control Block

: k2:ao:wc:dm:cbNumState

9.2.1.1.7 Current DM Flat File

: k2:ao:wc:dm:flatState

9.2.1.1.8 Current DM Sharp File

: k2:ao:wc:dm:sharpState

9.2.1.1.9 Current TT Sensor ID

: k2:ao:wc:tt:sensorState

9.2.1.1.10 TT autogain State

: k2:ao:wc:tt:gainModeState
: 1234567890123456789012345678

9.2.1.1.11 TT Filter State

: k2:ao:wc:tt:filterState

9.2.1.1.12 Abort

k2:ao:wc:dm:abort

This command returns the system to its open loop states with mirrors in known positions from any other states. This gives us a three-level hierarchy of ways to open the loop:

- e-stop command opens loops, sends mirrors to home or flat, and disables power to mirrors
- abort command opens loops and sends mirrors to home and flat positions
- open loop commands open the respective loop leaving the mirror in its last position

The other principal function of abort is to get out of lengthy operations like a system matrix measurement if there is a problem. That's the one that caused LLNL to put it in at Lick and it is used a lot.

9.2.1.1.13 Emergency stop.

: Opens all loops (DM and TT) and returns mirrors to flat and home positions.

9.2.1.2 Wavefront sensor commands

9.2.1.2.1 Start / Stop WFS camera.

: k2:ao:wc:ws:start (written by SC)
: k2:ao:wc:ws:stop (written by SC)
: k2:ao:wc:ws:timeout (read by SC)
: k2:ao:wc:ws:active (read by SC)
: k2:ao:wc:ws:state (read by SC)
: k2:ao:wc:ws:status (read by SC)
: k2:ao:wc:ws:errstr (read by SC)
: Starts or Stops WFS camera operations, data transfer to WFC computer system, and centroid calculation process. If the WFC is unable to successfully start the camera process, it will return a status value and an associated error string. The value of k2:ao:wc:ws:timeout will indicate how many seconds the UISC should wait on an unresponsive device before concluding that there is a problem.

9.2.1.2.2 Set WFS camera timing sequence number

: k2:ao:wc:ws:timseq (written by SC)
: Determines control file to be used for the GTRI camera. The files are kept on the GTRI PC. Through the remote RS232 interface to the WFC, the WFC will be able to select 1 control file out of a set of 10. This command will allow the UISC to request that the WFC load the desired GTRI camera control file into the GTRI PC.

9.2.1.2.3 Set WFS camera gain

: k2:ao:wc:ws:gain (written by SC)
: gain prior to digitizing.

9.2.1.2.4 Get Average of N raw centroid vectors.

: k2:ao:wc:ws:centOffsetGet (written by SC)
: k2:ao:wc:ws:centOffsetX (vector read by SC)
: k2:ao:wc:ws:centOffsetY (vector read by SC)
: Computes average of last N gradient vectors. By setting the variable k2:ao:wc:ws:centOffsetGet to the value N, the WFC will be notified of the change in value, and will act on the request accordingly. At the end of the process the WFC should put a zero back into the variable k2:ao:wc:ws:centOffsetGet to indicate that the request has been filled.
: Is there any possibility that this command fails? Do we need a status/errstr/timeout structure?
: The vector is either returned in the same variables that normally hold the telemetry centroid vector, or a separate mirrored variable will be provided. (TBD)

9.2.1.2.5 Record WFS camera background image.

: k2:ao:wc:ws:backFmake (written by SC)
: k2:ao:wc:ws:backFname (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: The UISC will set the backFname value first, and then setting backFmake to TRUE should cause the action to occur.
: Used to capture and save current image as background field.

9.2.1.2.6 Load WFS camera background image from disk

: k2:ao:wc:ws:backFload (written by SC)
: k2:ao:wc:ws:backFname (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: This sets the current background image.
: The file name must be passed in as a parameter. This file will be on the WFC disk.

9.2.1.2.7 Record WFS flat field image

: k2:ao:wc:ws:flatFmake (written by SC)
: k2:ao:wc:ws:flatFname (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: The UISC will set the flatFname value first, and then setting backFmake to TRUE should cause the action to occur.
: Used to capture and save current image as a flat field reference. The file will be on the WFC disk.

9.2.1.2.8 Load WFS flat field image

: k2:ao:wc:ws:flatFload (written by SC)
: k2:ao:wc:ws:flatFname (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: This sets the current flat field image.
: The file name is passed in as flatFname. The destination control block must be identified, and finally the flatFload channel set to TRUE. The WFC will then load the indicated file into the system control block identified. This file will be on the WFC disk.

9.2.1.2.9 Set centroider threshold level

: k2:ao:wc:ws:centThresh (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: The units of this parameter are the GTRI camera digital numbers. This indicates a threshold intensity on pixels to determine whether or not they contribute to the centroiding algorithm.

9.2.1.2.10 Load WFS mapping table

: k2:ao:wc:ws:mapFname (written by SC)
: k2:ao:wc:ws:mapFload (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: An ascii file indicating which pixels correspond to which Shack Hartmann spot centroids, and which spots are to be used by the wavefront controller. The file contains x, y location and x, y width in pixels for each active subaperture. Created and maintained by the UISC. The file format is detailed in F.3.3, "Wavefront Sensor Mapping table".

9.2.1.2.11 Set low light warning level

: k2:ao:wc:ws:lowLight (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: Threshold for an individual sub-aperture light level warning. Exception should report which subaperture. The thresh is relative to the GRTI camera range, in GTRI camera digital numbers.

9.2.1.2.12 Load centroid origin vector

: k2:ao:wc:ws:centOrgFload (written by SC)
: k2:ao:wc:ws:centOrgFname (vector written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: Pass a vector into this command to set it for use in the WFC.

9.2.1.2.13 Load centroid offset vector from file.

: k2:ao:wc:ws:centOffFload (written by SC)
: k2:ao:wc:ws:centOffFname (vector written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: Allows a specified vector to be set as the control system reference.

9.2.1.2.14 Load centroid offset vector, immediate

: Pass a vector into the current DM control block.

9.2.1.2.15 Get Average of N subaperture intensity vectors.

: k2:ao:wc:ws:subapIntGet (written by SC)
: Computes average of last N subaperture intensity vectors. By setting the variable k2:ao:wc:ws:subapIntGet to the value N, the WFC will be notified of the change in value, and will act on the request accordingly. At the end of the process the WFC should put a zero back into the variable k2:ao:wc:ws:subapIntGet to indicate that the request has been filled.
: Is there any possibility that this command fails? Do we need a status/errstr/timeout structure?
: The vector is either returned in the same variables that normally hold the telemetry centroid vector, or a mirrored variable will be provided. (TBD)

9.2.1.2.16 Get WFS camera status

: k2:ao:wc:ws:temp
: k2:ao:wc:ws:XXXXX
: The returned data might include things like dewar temperature, or any other physical camera condition or feedback available from the camera. This will probably map into several direct channel access variables (TBD), which will be updated whenever this command is issued.

9.2.1.3 DM control commands

9.2.1.3.1 Open / Close DM loop

: k2:ao:wc:dm:open
: k2:ao:wc:dm:close
: k2:ao:wc:dm:state
: k2:ao:wc:dm:status
: k2:ao:wc:dm:errstr

9.2.1.3.2 Set DM Control Block

: k2:ao:wc:dm:setCBNum
: Set the control block to any 1 of N copies available.

9.2.1.3.3 Load DM Control Block

: k2:ao:wc:dm:CBnum
: k2:ao:wc:dm:CBFload
: k2:ao:wc:dm:CBFname
: Load a DM control block from a file.

9.2.1.3.4 Load reconstruction matrix

: k2:ao:wc:dm:reconFname
: k2:ao:wc:dm:reconFload
: The file naming convention is TBD.

9.2.1.3.5 Set DM gain

: k2:ao:wc:dm:gain (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: A scalar value stored in a file and managed as necessary by the UISC.

9.2.1.3.6 Set DM integrator weight

: k2:ao:wc:dm:intWt (written by SC)
: k2:ao:wc:CBnum (written by SC)
: This is a scalar value stored in a file and managed as necessary by the UISC.

9.2.1.3.7 Set DM compensator weights

: k2:ao:wc:dm:compWt1
: k2:ao:wc:dm:compWt2
: k2:ao:wc:CBnum (written by SC)
: This is two values stored in a file and managed as necessary by the UISC.

9.2.1.3.8 Load DM mapping table

: k2:ao:wc:dm:mapFname
: k2:ao:wc:dm:mapFLoad
: k2:ao:wc:cntrlBlockNum (written by SC)
: Load a DM mapping table from the WFC disk to the real-time buffer in the WFC. This new table becomes immediately active. Created with an editor. Which actuators are active and which are slaved.

9.2.1.3.9 Set DM Soft Limits

: This command sets a DM actuator limit vector, which if exceded will cause a warning to the UISC.
: Note: how can we do this to be compatible with EPICS warning levels? Whatever we do should be consistent with the exception handling scheme in general.

9.2.1.3.10 Move DM FLAT

: k2:ao:wc:dm:flatMove

9.2.1.3.11 Record this DM position as FLAT

: k2:ao:wc:dm:flatFmake
: k2:ao:wc:dm:flatFname

9.2.1.3.12 Load DM Flat setting from file

: k2:ao:wc:dm:flatFload
: ke:ao:wc:dm:flatFname

9.2.1.3.13 Move DM SHARP

: k2:ao:wc:dm:sharpMove
: Move the DM into the position associated with the name SHARP.

9.2.1.3.14 Record this DM position as SHARP

: k2:ao:wc:dm:sharpFmake
: k2:ao:wc:dm:sharpFname
: Save the current DM position as the named position SHARP. The SC will likely maintain multiple DM vectors that correspond to the sharpened DM state for each possible science instrument.
: How do we LOAD the sharpened DM settings?.

9.2.1.3.15 Load DM Sharp setting from file

: k2:ao:wc:dm:sharpFload
: k2:ao:wc:dm:sharpFname

9.2.1.3.16 Set DM positions (by actuator vector)

: k2:ao:wc:dm:actMove
: k2:ao:wc:dm:act (the actuator value array)
: Moves DM actuators to specified set of positions. The input required is an array of actuator positions. Note that the format of this array is the same as the format of 9.2.1.7.5, "DM signal Vector".

9.2.1.3.17 Set DM positions (by Zernike vector)

: k2:ao:wc:dm:zernMove (written by SC)
: k2:ao:wc:dm:zern (the zernike coef. array)
: Moves DM actuators to positions specified by a vector of Zernike Coefficients. The input required is an array of Zernike coefficients, that describe the overall shape of the DM. Note that the format of this array is the same as the format of 9.2.1.7.8, "Zernike modes from DM vectors"

9.2.1.3.18 Measure system Matrix

: k2:ao:wc:dm:sysTranFname
: k2:ao:wc:dm:sysTranFmake
: Moves DM actuators through pre-specified patterns to get estimate system transfer matrix. Stored in WFC system Matrix directory.
: Generates influence functions, gains, hysteresis, etc. of the DM.

9.2.1.3.19 Compute Least Squares Reconstruction matrix

: k2:ao:wc:dm:reconCompl
: k2:ao:wc:dm:reconFname
: Depends on system matrix and weight vector. Uses weighted least-squares approach.

9.2.1.3.20 Compute Optimal Reconstruction matrix

: k2:ao:wc:dm:reconCompo
: k2:ao:wc:dm:reconFname
: Depends on some atmospheric parameters (covariance matrix) as well as the system matrix and weight vector.

9.2.1.4 Tip-tilt control commands

9.2.1.4.1 Start / Stop Tip/Tilt control.

: k2:ao:wc:tt:start (written by SC)
: k2:ao:wc:tt:stop (written by SC)
: k2:ao:wc:tt:timeout (read by SC)
: k2:ao:wc:tt:active (read by SC)
: k2:ao:wc:tt:status (read by SC)
: k2:ao:wc:tt:errstr (read by SC)
: Starts or Stops tip/tilt operations, data transfer to WFC computer system, and centroid calculation process. If the WFC is unable to successfully start the TT process, it will return a status value and an associated error string. The value of k2:ao:wc:tt:timeout will indicate how many seconds the UISC should wait on an unresponsive device before concluding that there is a problem.

9.2.1.4.2 Open / Close TT loop

: k2:ao:wc:tt:open
: k2:ao:wc:tt:close
: k2:ao:wc:tt:state
: k2:ao:wc:tt:status
: k2:ao:wc:tt:errstr

9.2.1.4.3 Get Average of N T/FS data sets

: k2:ao:wc:tt:dataGet
: k2:ao:wc:tt:data
: Pass N in as a parameter. The data returned will include the four raw quadrant intensities, derived slopes and total intensity.

9.2.1.4.4 Set T/FS loop gain

: k2:ao:wc:tt:lgain
: This is the loop gain,.

9.2.1.4.5 Set T/FS Integration Time

: k2:ao:wc:tt:intTime

9.2.1.4.6 Set T/FS control offset

: k2:ao:wc:tt:ctrlOffsetX
: k2:ao:wc:tt:ctrlOffsetY

9.2.1.4.7 Set T/FS low light warning level

: k2:ao:wc:tt:lowLight (written by SC)
: k2:ao:wc:cntrlBlockNum (written by SC)
: Threshold for an individual sub-aperture (quadrant) light level warning. Exception should report which subaperture. The threshold units are APD digital levels.
: If a signal level on the APDs falls below this level, and exception is generated.

9.2.1.4.8 Record this TTM position as HOME

: k2:ao:wc:tt:homeFmake
: k2:ao:wc:tt:homeFname
: Records the current TTM position as HOME and saves this value in a file in the WFC file library.

9.2.1.4.9 Load TTM HOME position from file

: k2:ao:wc:tt:homeFload
: k2:ao:wc:tt:homeFname
: Loads a recorded home position from a file in the WFC file library.

9.2.1.4.10 Move TTM to home position

: k2:ao:wc:tt:homeMove
: Move the TTM to the currently defined HOME position.

9.2.1.4.11 Move TTM to a specified position.

: k2:ao:wc:tt:ttmMove
: k2:ao:wc:tt:ttmDesiredPos
: Moves TTM to specified position

9.2.1.4.12 Set TT signal source

: k2:ao:wc:tt:sensor
: One of two values will be entered here to indicate which sensor should be used to supply the tip / tilt information, the T/FS or the WFS. The choice of sensors is really implied by whether or not the LGS is being used.

9.2.1.4.13 Record T/FS background vector

: k2:ao:wc:tt:backFname
: k2:ao:wc:tt:backFmake
: k2:ao:wc:tt:backStatus
: k2:ao:wc:tt:backErrstr
: This records the T/FS background vector from the APDs and move it to the real time buffer and the library of files on the WFC disk.

9.2.1.4.14 Load T/FS background vector

: k2:ao:wc:tt:backFname
: k2:ao:wc:tt:backFload
: k2:ao:wc:tt:backStatus
: k2:ao:wc:tt:backErrstr

9.2.1.4.15 Set T/FS Filter Wheel Control Mode

: k2:ao:wc:tt:filterMode
: Set to AUTO, HOLD, MIN.

9.2.1.4.16 Set T/FS Filter Wheel to position N

: k2:ao:wc:tt:filter

9.2.1.4.17 Set T/FS Auto Gain Control on/off

: k2:ao:wc:tt:gainMode
: Auto gain mode enabled/disabled. (i.e. adaptive control or normal control)

9.2.1.4.18 Set TT soft limits

: This sets a soft limit on TTM travel. If the TTM is commanded to move beyond this limit, a warning will be generated to the UISC.
: NOTE: Handle this in a way that is consistent with EPICS exeption handling scheme.

9.2.1.5 WFC diagnostics commands

9.2.1.5.1 Run system self-test

: k2:ao:wc:dg:selfTest

9.2.1.5.2 Set DM integrator vector.

: Allows initialization of control state for transient response tests.

9.2.1.5.3 Start / Stop DM/WFS registration test

: A parameter indicates which action (Start or Stop) is desired.

9.2.1.5.4 Start / Stop TT Registration Test

: k2:ao:wc:tt:testStart
: k2:ao:wc:tt:testStop
: k2:ao:wc:tt:testState
: k2:ao:wc:tt:testStatus
: k2:ao:wc:tt:testerrstr
: This command causes the TT mirror to move through a preset series of positions. How we set up the position sequences is TBD. In the Lick system we use a function generator to move the TTM for tests of TTS and WFS responses, etc.

9.2.1.5.5 Set diagnostic mode.

: Determines which data are saved when diagnostics are triggered.

9.2.1.5.6 Set diagnostic trigger mode.

: Determines conditions for saving diagnostic data: command, data condition

9.2.1.5.7 Trigger diagnostics.

: Causes diagnostics to be recorded.

9.2.1.6 Telemetry commands

9.2.1.6.1 Set telemetry mode.

: Determines which data are included in telemetry data stream. The strategy here is TBD. Be sure to account for 'TT telemetry mode'. i.e. which of the two schemes of TT telemetry is desired.

9.2.1.6.2 Set telemetry on / off

9.2.1.6.3 Set WFC camera display gain

: This is the gain for the RS-170 output of the GTRI camera. May/may not be available as a feature on the GTRI camera. TBD

9.2.1.7 Telemetry data

9.2.1.7.1 Raw Centroid Vector

: Representing the location of the Shack-Hartmann spots. We will use a 1 dimensional vector of 349 (TBD) elements. Each element will be 2 real numbers corresponding to X, Y centroid of a spot.
: There is an open issue here regarding exactly how to map the centroids into the data structure. The issue is that as the pupil rotates, some subapertures around the edges appear and disappear. Should we have a static mapping of subaperture to data structure and mark some elements as unused for any given pupil rotation?

9.2.1.7.2 Corrected Centroid Vector

: Representing the location of the Shack-Hartmann spots AFTER adding the centroid offset vector. We will use a 1 dimensional vector of 349 (TBD) elements. Each element will be 2 real numbers corresponding to X, Y centroid of a spot.

9.2.1.7.3 Subaperture intensity Vector

: Representing a measure of Shack-Hartmann spot intensity. Like the centroid vector, this will be a 1 dimensional vector of 349 (TBD) elements. Each element in the matrix will be a single real number (integer?) metric, quantifying intensity of the corresponding spot.

9.2.1.7.4 Wavefront Reconstructor Output Vector

9.2.1.7.5 DM signal Vector

: This is a matrix of 349 DM actuator values. Each element is a single real number. This vector does NOT include the results of slaved actuator calculations.

9.2.1.7.6 DM Actuator Vector

: This is a matrix of 349 DM actuator values. Each element is a single real number. This vector does include the results of slaved actuator calculations.

9.2.1.7.7 Zernike error modes from wavefront reconstructor

When the WFS-DM control loop is open this data describes the aberrations in the uncorrected wavefront.

When the WFS-DM control loop is closed, this data will describe the aberrations (residual error) detected in the corrected wavefront.

The data format will likely be an array of at least 9 Zernike coefficients (real numbers), corresponding to the first 2 orders. Specifically:

Piston
1st Order X-Tilt
1st Order Y-Tilt
1st Order Focus
3rd Order Astigmatism (45 degrees)
3rd Order Astigmatism (0 degrees)
3rd Order Coma (x)
3rd Order Coma (y)
3rd Order Spherical

9.2.1.7.8 Zernike modes from DM vectors

: Same data format as Zernike error modes from the Reconstructor. The difference is that these correspond to the current shape of the DM. These are only available while the control loop is closed.

9.2.1.7.9 Wavefront rms error

9.2.1.7.10 Wavefront tilt rms error

9.2.1.7.11 Tilt/Focus Sensor (T/FS) values (slopes and intensity)

: This data consists of x-slope, y-slope, total intensity and the four quadrant intensities.

9.2.1.7.12 Tip/Tilt Mirror (TTM) Positions

: The position of the tip/tilt mirror (aka fast steering mirror) will be reported in two real numbers corresponding to angles about the X and Y axis.

9.2.1.7.13 Centroid display

: This display is computer generated from the centroid vector.
: A formatted picture of the subaperture layout. The last N centroid positions are plotted as dots within the corresponding subaperture.

9.2.1.7.14 DM display

: Formatted picture of the actuator layout. Color of the actuator corresponds to average position over the last N iterations of the DM control loop.

9.2.1.7.15 Tilt / Focus Sensor (T/FS) display

: Description TBD
: X-Y plot of the last N slope values similar to a single subaperture on the centroid display.
: TBD This could be combined with the Centroid display.

9.2.1.7.16 TTM position display

: X-Y or color display of the TT mirror position.
: TBD This could also be combined with other displays. Should it be?

9.2.1.7.17 WFS Camera RS-170 video output

9.2.1.8 Diagnostic data

: High Bandwidth Diagnostic data acquisition. All data available in telemetry is available here also, with the addition of raw and corrected pixels.
: There will be a collection of commands required to coordinate the capture, and retrieval of this diagnostic data using the 9Gig hard drive as the transfer mechanism.

9.2.1.9 Data Structure Libraries

: There will be a set of files maintained on the WFC. each library will be stored in a specified directory with a table of contents which will contain additional information on each file. (creation date, reference source used, ...) The libraries include...