| |
|
|
|
6 INFRARED DCS
6.1 INFRARED ACQUISITION LIBRARY
The iracq-library contains a basic set of ANSI-C functions to control both the IRACE front end and the acquisition process. When using the server class libraries, these routines are fully transparent.
6.2 CONTROL SERVER BASE CLASS
On top of the infrared acquisition library a basic C++ server class (iracqSRV) has been built to provide control server functions, which are also compliant to VLT-NOCCS installations on the IRACE workstation. This is intended to be used as lab-interface to IRACE. The NOCCS acquisition server (iracqServerNoCss), that uses an instance of this class, can be operated under some restrictions (no logging, no database, no templates...) via the same graphical user interface as the higher level iracqServer (see section 6.9).
6.3 EVENT HANDLER CLASS
The infrared acquisition event handler class (iracqEVH) is derived from the control server base class (iracqSRV). Using the CCS/ECCS functionalities this class provides the high level interface to the infrared data acquisition. Application specific servers can be built by deriving new classes from iracqEVH (see section 6.6).
6.4 INFRARED ACQUISITION CONTROL SERVER
The infrared acquisition control server (iracqServer) is the interface process to the IRACE-DCS for the external world. Through this server all commands must pass. The server checks the validity of various commands and parameters according to the current state of DCS.
The <-inst> option allows to start several control servers within the same environment. This is necessary to interface to more than one IRACE controllers at the same time. The name to register with CCS will be `iracqServer_<instance>'. The database point for the iracq-module is then supposed to be `<alias>iracq_<instance>:'. Without the <-inst> option defined the server will register under his actual process name. The database point is then supposed to be `<alias>iracq:'.
The file iracqBranch.db contains the class definition for the Infrared Acquisition Module. This file has to be included in the DATABASE.db file of the environment. The following macros can be defined before each inclusion:
#define iracqINSTANCE iracq_myInstance
iracqINSTANCE becomes the alias of the database point for this instance. If not defined it defaults to "iracq". iracqROOT is the absolute path of the database root. If not defined it defaults to <iracqINSTANCE>.
The basic structure of the infrared acquisition database is as follows:
--o <alias>iracqINSTANCE --|--o irace (irace system parameters)
|--o exposure (exposure parameters)
|--o detector (detector specific values)
The server state is called "OFF" when no server process is running. Starting the server initializes the state to "LOADED". Then it is possible to send commands. If a default detector configuration was specified in the system configuration or the -det option was set, the detector configuration is loaded. The command "STANDBY" brings the server to the "STANDBY"-state. All sub-systems are up, but not yet configured. The IRACE command server (protocol converter) is running on the IRACE pre-processor workstation. The IRACE front-end is booted. The acquisition process is not yet running. The command "ONLINE" configures all sub-systems with the current detector configuration and also starts the acquisition process ("ONLINE"-state). It is possible to go directly from "LOADED"- to "ONLINE"-state and vice-versa (with the command "OFF"). When going from "ONLINE" to "STANDBY" the acquisition process terminates, the sequencer is stopped, the CLDC-boards are all disabled and the control server disconnects from IRACE command server and front-end. However the IRACE front-end remains in booted state unless the -haltIrace flag was set in the "STANDBY" command (i.e. "STANDBY -haltIrace"). The "OFF"-command will terminate all sub-processes and the IRACE front-end is no longer booted.
The data acquisition is started/stopped with the "SEQ -start/-stop" command. The command "MISC -rstcnt" sets a flag on the acquisition process to reset all loop counters.
If the DET.CON.AUTONLIN parameter is set to "T" in the system configuration, the server will automatically go to "ONLINE"-state after being started.
The IRACE front-end can be reset using the RESET-command. This is only valid in "ONLINE"- or "STANDBY"-state. Otherwise the command has no effect. If the state was "ONLINE" the server goes automatically to "STANDBY"-state afterwards.
iracqSTATE_LOADED (3) - "LOADED"
iracqSTATE_STANDBY (3) - "STANDBY"
iracqSTATE_ONLINE (4) - "ONLINE"
iracqSUBSTATE_IDLE (1) - "IDLE"
iracqSUBSTATE_BUSY (2) - "BUSY"
iracqSUBSTATE_ERROR (3) - "ERROR"
racqMODE_SIM (2) - "SIMULATION"
<alias>iracq:irace.state - current server state
<alias>iracq:irace.stateN - server state name
<alias>iracq:irace.subState - current server sub-state
<alias>iracq:irace.subStateN - server sub-state name
<alias>iracq:irace.opMode - operational mode
<alias>iracq:irace.opModeN - name of operational mode
6.4.1 INTEGRATION TIME
The integration time is set via the setup parameter DET.DIT. There is a minimum value (MINDIT) for the integration time, which depends on the currently used read-out technique. The actual value of MINDIT is defined in the Sequencer-Program file. If a the value of less than MINDIT is specified, DIT is automatically corrected.
- DET.DIT <alias>iracq:exposure.DIT
- DET.MINDIT <alias>iracq:exposure.MINDIT
- DET.DIT SETUP "-function DET.DIT <value in seconds>"
- DET.MINDIT STATUS "-function DET.MINDIT"
6.4.2 SETUP COMMAND
The syntax of the setup command is:
"SETUP -function <param1Name> <param1Value> <param2Name> <param2Value> ..."
All setup keywords specified in the ESO-VLT-DIC.IRD dictionary can be set using this command. The dynamic parameters of the acquisition process can also be set via the setup command. The database attribute <alias>iracq:irace.dynPars contains a table (fields: name, value) of all currently defined acquisition process parameters.
The dynamic parameters of the acquisition process can also be set via the setup command. The database attribute `<alias>iracq:irace.dynPars' contains a table [name (rtBYTES32), value (rtBYTES32)] of all currently defined dynamic parameters.
The parameter setup contains all dynamic parameters for a read-out mode. These can be parameters exported by the acquisition process or parameters used in the sequencer program or subpattern dispatcher files. All parameters which are not exported from the acquisition process have to be defined in the DSUP-file of the read-out mode. The acquisition process defines valid default values for all its exported parameters (these parameters can optionally be set in the DSUP-file)
6.4.3 READ-OUT MODES
The read-out modes for a detector are defined in the detector configuration file. Each read-out mode is assigned a unique name, which is used for selection via the control panel or the setup command "SETUP -function DET.NCORRS.NAME <name>". The setup parameter DET.NCORRS refers to the unique id (RM-index) of the mode and can be used alternatively.
DET.IRACE.RM2.NAME "Double"; # read-mode name
DET.IRACE.RM2.ACQ "sdmaAl2"; # acquisition process
DET.IRACE.RM2.SEQ "AladdinDblCor_seq"; # readout sequence
DET.IRACE.RM2.DSUP "AladdinDblCor.dsup"; # default parameters
The available read-out modes for the current detector setup can be retrieved with the command "STATUS -function DET.NCORRS.AVAIL". The format of the returned list is:
<NCORRS>:<read-out mode name>|...
The currently defined read-out modes are also stored as table (fields: name, ncorr) in the database attribute `<alias>iracq:irace.rmDef'.
6.4.4 WINDOW
The setup parameters DET.WIN.STARTX, DET.WIN.STARTY, DET.WIN.NX, DET.WIN.NY define the format and position of the data-frame within the chip. STARTX/Y refers to the lower left corner. If software windowing is used (default, "SETUP -function DET.WIN.TYPE 0"), the whole detector is read out and only the data transfer task is informed to request a window from the pre-processor. This is mainly used to save transfer/storage overheads.
If hardware windowing is selected ("SETUP -function DET.WIN.TYPE 1") the sequencer program is reloaded with the new window parameters and the acquisition process is restarted with the `-nx, -ny' command line options set accordingly. The DET.WIN.HW.SUP setup parameter can be used to disable hardware windowing. Generally this should be set in the default parameter setup file for read-out modes which do not support windowed read-out of the detector. If hardware windowing is switched on, the window setup parameters are automatically adjusted following several detector specific rules which are defined in the detector configuration:
The DET.CHIP.ADJUST parameter specifies the HW-window adjustment mode for the detector. Valid values are
CENTER - window is automatically centered
PART - window is adjusted to the next partition
specified by the DET.CHIP.PARTNX,PARTNY parameters
FREE - window is only adjusted to multiples of
the DET.CHIP.STEPX,STEPY parameters
The DET.CHIP.STEPX/Y parameters specify the adjustment step in x/y-direction for windowed readout. Adjustments are done in multiples of this value.
The DET.CHIP.PARTX/Y parameters specify the partition size in x/y-direction for windowed readout. Only relevant, if the DET.CHIP.ADJUST value is set to "PART".
6.4.5 EXPOSURE CONTROL
Normally, when an exposure is started both sequencer and acquisition are restarted. It is also possible to let the sequencer run continuously, when a START-command is issued. This is controlled via the SETUP keyword "DET.IRACE.SEQCONT T|F". In continuous mode just the acquisition process resets its buffers and starts building a new sum. This is useful to avoid that corrupted data is used for building the sum, like if for instance the telescope was moved and frames where taken during the movement. It is however possible to specify that the acquisition process should not reset the buffers/counters by using the flag "-noNcReset" together with the START-command. In this case the acquisition process continues to build the sum and the frame may be ready earlier than the actual exposure time. This feature can be used when it is important to minimize the overheads, but requires that there are no changes in the fields of view.
The exposure can be aborted using the ABORT-command. In this case no data file is generated unless the frame was already received on the WS as the command was issued.
The END-command makes the acquisition process terminate the exposure as soon as possible. In this case the data file generated may be just an intermediate result.
The WAIT-command can be used to wait for an exposure to complete. It returns the actual exposure state with the last reply.
The FITS-header is generated as specified in the ESO-VLT-DIC.IRACE dictionary. With the setup command "SETUP -function DET.FITSHDR.EXT.ST T|F" the extended FITS-header can be enabled or disabled. When the extended FITS-header is enabled also maintenance keywords like clock- and bias-voltages will be stored.
iracqEXP_UNDEFINED (0) UNDEFINED
iracqEXP_PENDING (2) `not implemented'
iracqEXP_INTEGRATING (4) INTEGRATING
iracqEXP_PAUSED (8) `not implemented'
iracqEXP_READING_OUT (16) `not implemented'
iracqEXP_PROCESSING (32) `not implemented'
iracqEXP_TRANSGFERRING (64) TRANSFERRING
iracqEXP_COMPL_SUCCESS (128) COMPLETED
iracqEXP_COMPL_FAILURE (256) FAILURE
iracqEXP_COMPL_ABORTED (512) ABORTED
<alias>iracq:exposure.expStatus - exposure status
<alias>iracq:exposure.expStatusN - exposure status name
<alias>iracq:exposure.expTime - exposure time
<alias>iracq:exposure.expCountDown - exposure countdown
<alias>iracq:exposure.expNo - exposure number
After starting the exposure state will be "INTEGRATING". When the header of the last file has been received by the data transfer task (i.e. the break-conditions for all frames have been reached) the exposure state goes to "TRANSFERRING". At this time all detector-data for the current exposure are taken. When the last file has been stored on disk the exposure state goes to "COMPLETED". If an error occurred during the exposure the state goes to "FAILURE". If the exposure was aborted the state goes to "ABORTED".
6.4.6 DETECTOR MODES
Setup macros for operating the detector in several pre-defined modes can be declared in the detector configuration file:
DET.MODEi.NAME "name of the mode";
DET.MODEi.SETUP "<keyword> <value>, <keyword> <value>, ...";
The mode can be selected with the command:
"SETUP -function DET.MODE.NAME <name>"
This will set all keywords given in the DET.MODE.SETUP of that mode. If the current setup matches all keywords of a mode, the DET.MODE.NAME keyword reflects the according mode-name and is also set in the FITS-header. If several modes match, the one with the most keywords is taken. The maximum number of modes for one detector configuration is 16. Each mode can contain up to 64 keywords. If the setup line length exceeds 256 characters, a file-name can be specified instead. The setup file must contain the keywords for the mode in SHORT-FITS format. Unless an absolute path-name is given, the file is searched in
$INS_ROOT/$INS_USER/MISC/IRACE/MSUP/
If no extension is given in the file-name, the extension ".msup" is assumed.
6.4.7 FRAME SELECTION
Usually an exposure is finished, when the INT-frame has been received on the WS. As it is required by some readout modes to store also other frames during one exposure, a more general exposure break condition has to be applied. Each frame generated by the acquisition process and selected to be stored can have a counter, that indicates the number of frames of that type, that must be stored during the exposure. The exposure is finished, when all these frames have reached their break condition. All that can be controlled via the command:
"FRAME -name <frame name> [-gen T|F] [-store T|F] [-break <counter>]"
A list of all available frames can be retrieved with the command:
"STATUS -function DET.NCORRS.FRAMES"
The format of the returned list is:
<frame name>: <gen (0|1)> <store (0|1)> <break counter>|...
The available frames are also stored as a table (fields: name, generate, store, disp, break) in the data base attribute `<alias>iracq:irace.frames'.
6.4.8 NAMING OF DATA FILES
There are three different naming-schemes for files produced during an exposure. Unless an absolute path name is specified as base-name for one of the below naming-schemes all files will be stored by default in the data-path $INS_ROOT/$INS_USER/DETDATA. In addition the data-path can be defined via the DET.IRACE.DTT.PATH parameter which can also be set in the system-configuration file.
The naming scheme can be adjusted:
- via the system configuration keyword "DET.CON.NAMING.TPYE <type>"
- via the command "SETUP -function DET.EXP.NAMING.TYPE <type>"
The <type> can take the values "Request-Naming" or "Sequence-Naming" or "Auto-Naming".
Two different naming schemes are supported:
1. Request Data File Naming: The Name must be given in before each exposure is started (START command given). The name is given in with the SETUP command (parameter "DET.EXP.NAME <name>"). The FITS-file will be named in the following way:
<requested-name>_<frame-no>_<frame-name>.fits
If only one INT frame is taken during the exposure the file name for this frame will be just <requested-name>.fits
2. Sequence Data File Naming: An index is added to a base name. The index is incremented after each exposure. Setting the base name is done with the SETUP command (parameter "DET.EXP.SEQ.NAME <name>"). The index can be set with the "DET.EXP.SEQ.NO <no>" parameter. The FITS-file will be named in the following way:
<seq-base-name><seq-no>_<frame-no>_<frame-name>.fits
If only one INT frame is taken during the exposure the file name for this frame will be just <seq-base-name><seq-no>.fits
3. Auto Data File Naming: An index is added to a base name. When a new base name is set (or the naming scheme changes) a start index is determined automatically by searching the data target directory for files starting with the base-name. Initially (i.e. when DET.EXP.SEQ.NO is set to zero) the returned index is the highest existing index plus one. If DET.EXP.SEQ.NO is larger than zero the returned index is the first not existing index which is larger than DET.EXP.SEQ.NO. Once the index is determined it is incremented by one (without further check) after each exposure until either the base-name or the naming scheme changes or a new (minimum-)sequence number is explicitly set via a setup command. This makes it necessary that if DET.EXP.SEQ.NO is set to a value larger than zero, then no file with the current base-name and an index larger than DET.EXP.SEQ.NO must exist in the data target directory.
To save the FITS-header and file generation overhead it is also possible to store the frames in data cubes. If the data cubes are enabled via the SETUP command "DET.FILE.CUBE.ST T|F", one data cube file is generated for each frame type that has been selected for storage. If the maximum size for one data-cube has been reached, the data transfer task will automatically create a new one for that frame type. The file naming is done in the same way as for normal FITS files.
The name of the last file saved to disk is stored in the database attribute `<alias>iracq:exposure.newDataFileName'.
6.4.9 FITS HEADER
The FITS-header is generated as specified in the ESO-VLT-DIC.IRACE dictionary. With the setup command "SETUP -function DET.FITSHDR.EXT.ST <T|F>" the extended FITS header can be enabled or disabled. When the extended FITS-header is enabled also maintenance keywords like clock- and bias-voltages are stored.
6.5 DATA TRANSFER BASE CLASS
The data transfer task (iracqDtt) is started, stopped and controlled via the control server (-> System Control). Generally the data transfer task runs on the same host as the control server. If the data transfer task should run on a different WS, the host name for the data transfer task can be specified in the system configuration file via the keyword "DET.IRACE.DATAHOST <hostname>". A base class (iracqDTT) is provided to allow also here application specific extensions. If the extension also wants to add callbacks or database access, the iracqDTT_EVH class has to be used as parent class instead of iracqDTT.
6.6 SERVER EXTENSIONS
To customize your own server, a new server class has to be derived from the public iracqEVH class. There it is possible to add new command callbacks. The standard vltMakefile should be used to build the server process. The following flags have to be set:
myServer_LIBS = iracqEvh iracqSrv iracqExt iracq \
slx misc evh eccs CCS fnd C++ c
A detailed example that is also contained in the test directory of the iracq-module can be found in section 11.1.
To customize your own data transfer task, a new class has to be derived from the public iracqDTT_EVH class. There it is possible to add new command callbacks. The standard vltMakefile should be used to build the server process. The following flags have to be set:
myDtt_LIBS = iracqData iracqDataEvh iracqExt iracq irl \
tcomSclInt tcom sdmaInt icmdSock icmd \
The customized data transfer task is selected via the "-dtt <data transfer task name>" command line argument of the acquisition server. A detailed example that is also contained in the test directory of the iracq-module can be found in section 11.2.
`virtual int ProcessFrame(sdmaFRAME_T *frame, char *erms)'
method, which is defined in the iracqDTT base class. This method can be overloaded by the application to add own frame post-processing. It is a callback function, which is called just after a data frame has been received from the acquisition process. A pointer to the received frame is passed via the sdmaFRAME_T structure. If the function returns iracqFAILURE, the string <erms> is sent as data error event to the control server and the exposure is discarded. If the `FrameHandled()' method is called within the call-back, no further action (scaling, post-processing, display, storage) is done with the current frame.
The sdmaFRAME_T structure is defined as follows:
Several functions have been made public to give access to internal frame information which might be needed for application specific frame handling (see also man-page of the `iracqDTT' class):
Returns current path, where data files will be stored.
Returns the proposed FITS-file name (without .fits extension)
depending on the selected naming scheme and the current
Returns the global null terminated FITS-buffer
filled by the control server. The number of FITS-lines
in the buffer is the length of the returned string
Returns the current exposure number.
Returns the current exposure status. Use the
iracqEXP_ISACTIVE(ExpStatus()) macro to see whether the
void GetFrameName(int ftype, char *fname);
Get the name associated with the specified frame
type. If fname returns an empty string no name has
been assigned to the type by the acquisition process.
Returns the exposure start time.
Returns the time when the header of a frame was received
int SendFileEvent(const char *fileName, char *erms);
Send a file-event to the control server;
Returns the current detector number/partition, which is
selected to be stored. If 0 is returned, all detectors
are selected. Only relevant if more than one detector
Returns the number/partition of the detector, which is
actually received. Only relevant if more than one detector
6.7 IMAGE POST-PROCESSING
The data transfer task provides a general mechanism to perform operations on the images received from the acquisition process before storing them to disk. The post-operations are selected via the IMGOP command. The "IMGOP -enable|disable" command enables/disables the currently specified operations. The "IMGOP -clear" command clears all operations (-> no post-processing is done before storing the image on disk). The operations on the image are performed in the same order as the IMGOP command is issued. The following features are supported (each operation has to be set with a separate command):
"IMGOP -rotate <angle>": The image is rotated by <angle>.
Valid values are 0, 90, 180, 270.
"IMGOP -fx": Flip image in x-direction.
"IMGOP -fy": Flip image in y-direction.
Note that all operations are memorized until an "IMGOP -clear" is sent. So the command sequence "IMGOP -rotate 90; IMGOP -rotate 90;" will have the same effect (and also same performance) as "IMGOP -rotate 180"
6.8 BURST MODE
In some cases it might be necessary to store larger amounts of raw data or to sample at a very high frame-rate. If the frame rate is too high (> 200 Hz) the DMA-interrupt latency becomes dominating and no CPU-power is left for pre-processing. Two kinds of "burst modes" have been introduced to cover these two cases.
6.8.1 RAW DATA MODE
The raw data mode is activated by sending the setup command
"SETUP -function DET.BURST.NUM <num>"
If <num> is greater than zero it indicates the number of [DET.WIN.NX, DET.WIN.NY]-dimension sample-frames to be stored in the burst buffer. If an exposure is started both sequencer and acquisition are restarted (the DET.IRACE.SEQCONT flag is ignored in that case) and the buffer is filled until <num> sample-frames (16 bit short integer) are stored. At the end of the exposure an INT-frame (containing only dummy data at the moment) is transferred. The transfer of the sample-frames starts immediately and runs in parallel to the data recording. A 3 X 2 MBytes input-ring buffer is used to ensure interrupt stability. This means that at least 2 MBytes of data have to be created to satisfy the DMA. The dynamic parameter DET.BURST.SKIP indicates the number of frames to be skipped before starting to transfer.
This mode can be activated regardless of the currently selected read-out mode. Setting DET.BURST.NUM to zero deactivates the burst-mode and restores the standard acquisition process for the current read-out mode.
6.8.2 INTERNAL BURST MODE
The internal burst is activated by sending the setup command
"SETUP -function DET.BURST.NUM <-num>"
The negative value indicates that an internal burst-buffer should be applied. In this case the DMA is enlarged by a factor of <num>. The data processing is not affected in this case as soft-interrupts are created for each sub-division. The calculation thread will wait for <num> buffers and will then process them within one step. This helps to workaround the 200Hz interrupt limitation, but depending on the actual processing it may slow down the acquisition performance as a whole (if for example least-square fit or standard deviation have to be solved within the <num> buffers).
Also in this case a value of zero for DET.BURST.NUM deactivates the burst-mode.
6.9 GRAPHICAL USER INTERFACE
In the control panel there is a notebook area, where an application can insert widgets to control functions, that do not belong to the general DCS. These widgets should be designed as standard user interface classes (uif-classes) with the panel editor. The application has to provide its own Tcl-library to communicate with its server extension callbacks. If the `-load <module name>' argument is set in the command line of iracqStart, the Tcl-library `lib<module name>.tcl' is dynamically loaded and all uif-classes, that are contained in that library, are added to the notebook area of the standard DCS control panel. If the Tcl-library contains a `<module name>Init' procedure, this is called during initialization. The instance of the uif-classes is the module name. So all global variables used in the Tcl-library are accessed via `gvar(<module name>_variableName)'. Each uif-class appears on an own notebook-page. The title of the page is derived from the filename. The uif-class with the name `<module name>MyClass_uifClass.tcl' will appear as page with the title `MyClass'.
6.10 START-UP
The startup/shutdown of the Infrared Data Acquisition is done via the iracqStart/Stop script:
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|
