WFCAM Control & DHS Overview



|Document Title |WFLIC - the WFCAM Local Instrument Controller |

|Document Number | |

|Issue |1.0 |

|Date |2004-Jul-21 |

|Document Prepared By: |Alan Pickup |Signature and Date | |

|Document Approved By: | |Signature and Date | |

|Document Released By: | |Signature and Date | |

CHANGE RECORD

|Issue |Date |Section affected |Change Description |

|1.0 |2004-Jul-21 |all |First full issue |

| | | | |

| | | | |

| | | | |

| | | | |

| | | | |

| | | | |

| | | | |

| | | | |

| | | | |

APPLICABLE DOCUMENTS

|Reference |Document Title |Document Number |Issue & Date |

| | | | |

| | | | |

| | | | |

| | | | |

| | | | |

Table of contents

1. Introduction 6

2. Description of WFLIC operations 8

2.1 WFLIC initialisation 8

2.2 Configuration 8

2.3 Observes 9

2.4 Data export 9

3. List of actions 10

4. Description of actions 11

4.1 checkWaiting 11

4.2 configure 11

4.3 confirmObs 12

4.4 countdown 12

4.5 exit 12

4.6 export 12

4.7 initialise 13

4.8 observe 13

4.9 powerOff 13

4.10 powerOn 14

4.11 setSim 14

4.12 test 14

5. WFLIC function descriptions 15

5.1 Exit 15

5.2 MJDate 15

5.3 buildDataset 16

5.4 checkWaiting 16

5.5 configure 17

5.6 configure2 18

5.7 configureCamera 18

5.8 confirmObs 19

5.9 countdown 20

5.10 export 21

5.11 export2 21

5.12 fifoCallback 22

5.13 fsIdle 23

5.14 getCamera 24

5.15 goCamera 24

5.16 initCamera 25

5.17 initialise 26

5.18 initialise2 27

5.19 initialise3 28

5.20 initialise4 28

5.21 initialise5 29

5.22 main 30

5.23 observe 31

5.24 observe2 32

5.25 observe3 32

5.26 poffCamera 33

5.27 ponCamera 34

5.28 postCamera 34

5.29 putMessage 35

5.30 rstCamera 36

5.31 setDitsTime 36

5.32 setSim 37

5.33 test 37

5.34 timeH 38

5.35 timeUTdate 38

5.36 ucState 39

5.37 waitIdle 40

5.38 wflicAbort 40

5.39 yyyymmdd 41

Introduction

This document describes the WFCAM WFLIC task and should be read in conjunction with Reference [##], the WFCAM Control and Data Handling System. Figure 1, reproduced from that latter, shows the location of WFLIC in the system design.

WFLIC is a DRAMA task that runs in each of WFCAM’s camera data acquisition computers and provides the interface to the camera and filesave servers. The full WFCAM system involves four copies of the WFLIC task, one for each camera. They receive action demands from the higher level control task, WFIS, and they control data acquisition (via the observe command) and the task, UCDEMUX, that performs the demultiplexing and export of data from the camera to a data handling task, DHSPOOL.

Description of WFLIC operations

1 WFLIC initialisation

The WFLIC task is initialised via the initialise action which takes an SDS structure that contains a number of configuration items. These are listed in the arguments for the action given in the section on Description of Actions, below. In practice, the SDS structure is constructed in the controlling WFIS task which invokes the initialise command.

The initialise action performs the following operations:

• Extracts the configuration items from the supplied SDS structure;

• Opens and reads the camera modes lookup table which lists the recognised readModes and supplies additional information about them;

• Initialises the connections to the camera and filesave servers;

• Gets and posts to the camera and filesave servers the applications that specify the attributes for the telescope and the camera;

• Obtains a DRAMA path to the demultiplexing task;

• Commands the demultiplexing task to obtain a path to the data handling system (DHSPOOL) task to which it will export the data.

The initialisation action may be invoked more than once, but the operations concerned with connecting to the servers and running the initial telescope and camera applications are not repeated.

2 Configuration

The camera are configured for data acquisition via the configure action. The associated configuration items for this action are given in the section on Description of Actions, below. These items arrive in an SDS structure from the higher-level WFIS control task when the latter executes its set action.

The configure action performs the following operations:

• Extracts the configuration items from the supplied SDS structure;

• Finds the entry in the already-read camera modes lookup table that relates to the requested readMode (returning an error if the readMode is not recognised);

• Gets the corresponding application and modifies its parameters in line with the requested readMode, coadds and exposure time. Also calculates the corresponding actual (as opposed to requested) exposure time and the expected time to complete the observe.

The application is retained in memory to will be posted to the camera and filesave servers when an observe is invoked. This means there is no need to call the configure action again when a further observe is to be executed with the same setup.

3 Observes

An observe is executed by the observe action which is invoked with the data label and the number of the frame in the observation, normally 1. The action procedes by posting the application that has been defined by the configure action to both the camera and filesave servers and waiting for them to complete. The action is woken up by a message from its callback function, fifoCallback, after the filesave server writes the name of the resulting raw data file into a FIFO buffer.

A basic SDS data structure is constructed when the observe begins. This contains many of the configuration items received by this task when it was initialised. It also contains a small dummy data array that will be replaced by the real data only after the latter has been demultiplexed in the demultiplexing task, UCDEMUX. When (and if) the observe completes successfully, the end time of the observe is added to this SDS. When (and if) advised via the confirmObs action, the SDS structure is placed on a queue of structures (exportQ) for export via the export action to the demultiplexing task. Alternatively, the failure of another camera in WFCAM may mean that confirmObs is run with its option to discard the data just taken, in which case the SDS is deleted and no data is placed on the queue or exported.

In most cases, an observe is synonymous with an observation and only a single data frame is written by the data handling system into the HDS container file for the observation. During a focus observation, however, several observes may be acquired in a single observation and the HDS container will contain a number of separate data frames. WFLIC cares little either way – it works only in terms of observes and the issue of how many frames go into a single HDS is a configuration one at the higher level between the WFIS control task and the DHS. However, during a focus observation, the current focus index position and offset are passed to the WFLIC as arguments 3 and 4 of the observe action, so that they are correct in the SDS structure it constructs; if these arguments are absent the corresponding values default to zero.

4 Data export

The transfer of new data from the cameras to the UKIRT DHS system is controlled by WFLIC’s export action. This is a continuously-running action which is started when WFLIC is loaded and which reschedules periodically to check for new datasets to appear in the exportQ array. These datasets are SDS structures containing status information about the observation together with the name of the raw data file written by the filesave application. When export finds a new dataset, it sends it to the UCDemux task with an invocation of the latter’s exportObs action. In turn, UCDemux demultiplexes the data in the raw data file, constructs a single image frame for export and builds a new SDS structure around it, including the status information from the original SDS. It then exports this new SDS to the DHS system, specifically the DHSPOOL task for the camera concerned.

Note that data export happens asynchronously with data acquisition via the observe action. The data export queue (exportQ) allows for a maximum of 10 datasets although it rarely contains more than one or two. If all the slots in the exportQ were to be filled, the observe action delays the acquisition of new data until a new slot becomes available. In practice, data acquisition will have been throttled back at a high level (at the issuing of new data labels by the DHS) before this becomes necessary.

List of actions

The following is a list of the DRAMA actions implemented by the WFLIC task.

|Action name |Purpose |

|checkWaiting |Wait until camera is ready to receive data |

|configure |Configure for a new observation |

|confirmObs |Confirm that data for latest observe should or should not be exported. |

|countdown |Continuous action to update countdown parameter with number of seconds remaining in current |

| |observe. |

|exit |Exit this task |

|EXIT |Synonym for exit |

|export |Continuous action to export confirmed data from this camera via the demultiplexing task. |

|initialise |Initialise this task |

|observe |Take an observation |

|powerOff |Disable power to the camera |

|powerOn |Enable power to the camera |

|setSim |Set the simulation level in the task |

|test |Test action for software development |

Description of actions

1 checkWaiting

|Action name |Principal function |Arguments |

|checkWaiting |checkWaiting() |None |

Once called, this action simply reschedules until the ifWaitingForData flag is set, and then completes. The latter flag becomes set once the camera has been triggered by the observe action to acquire a new set of data.

The checkWaiting action is used by the controlling WFIS task to synchronise the operation of the master and slave cameras in WFCAM. The observe and checkWaiting actions are invoked in the slave cameras first. Only when all the checkWaiting actions complete is the observe action invoked in the master camera. This ensures that the observe action in the master camera is the last one to be called so that the hardware trigger than it generates is picked up by the slaves.

2 configure

|Action name |Principal function |Arguments |

|configure |configure() |Arg 1 - observation type (eg OBJECT) |

| | |Arg 2 - readMode for the observation |

| | |Arg 3 - number of exposures to be coadded in camera before export |

| | |Arg 4 – the requested exposure time (seconds) |

| | |Arg 5 – optimisation value. |

This configures the camera for the next observe. The readMode given in input arguments is used as the key to a lookup table which, among other things, specifies the XML application to be run in the camera. This is fetched and its attributes (eg dwell time, number of reads) are modified in the light of the requested exposure time and number of exposures. The resulting modified application is not posted to the camera and filesave servers at this point. Rather, it is retained in memory and only posted when the observe is invoked. If more than one observe is required, it is not necessary to invoke configure again unless the configuration has changed.

Note that the exposure time supplied in the input arguments is only a requested one. An actual exposure time is computed in the configure after allowing for the quantisation of the time to an integer number of milliseconds, and considering that the time taken to read the array may set a lower limit on the exposure for certain readout types. It is this actual exposure time that is propagated with the data into the FITS headers of the data stored by the DHS.

3 confirmObs

|Action name |Principal function |Arguments |

|confirmObs |confirmObs() |Arg 1 – confirmation flag: 1 to accept and export the latest data; 0 to |

| | |discard the latest data. |

This action is invoked by the controlling WFIS task to inform WFLIC that the data it has just taken is to be accepted or discarded. If it is accepted, the SDS structure containing the status information for the observe is placed on the queue (exportQ) of data waiting to be demultiplexed and forwarded to the DHS by the UCDemux task.

4 countdown

|Action name |Principal function |Arguments |

|abort |countdown() |None |

This action runs continuously to update a DRAMA parameter, countdown, with the number of seconds remaining in the current observe. It is signalled to begin a new countdown sequence when the ifCountdown flag is switched to 1 in the observe action, which also sets the duration of the countdown to be the time calculated to acquire the data.

5 exit

|Action name |Principal function |Arguments |

|exit |Exit() |None |

This may be called to cause the WFLIC task to close down cleanly.

6 export

|Action name |Principal function |Arguments |

|export |export() |None |

This action runs continuously. At each reschedule, it checks for a new dataset to appear in the exportQ array of SDS structures. Each dataset contains configuration and status information about a new observe, including the name of the raw data file that holds the pixel data for the observe. If export finds a dataset, it invokes the exportObs action in the UCDemux task, passing it the SDS. The latter task then demultiplexes the raw data and exports the resulting single frame of data to the DHS.

7 initialise

|Action name |Principal function |Arguments |

|init |init() |cameraLUT – name of camera lookup table file |

| | |CRPIX1, CRPIX2, CD1_1, CD1_2, CD2_1, CD2_2, PV2_1, PV2_2, PV2_3 – WCS values |

| | |node – nodename of this computer. |

| | |camNum – number of this camera (1…4) |

| | |detectorID – serial number of detector array |

| | |sdsuID – serial number of SDSU controller |

| | |demuxTask – name of task for data demultiplexing and export |

| | |DHSTask – name for camera’s DHS task |

| | |role – camera’s role (master or slave) |

| | |simLevel – simulation level (0 for no simulation) |

| | |synchro – synchronisation (sync or nosync |

| | |camBase – base URL of camera server |

| | |flsBase – base URL of filesave server |

| | |proxy – NULL (usually) or base URL of proxy |

This action is called to initialise the WFLIC task and the camera under its control. An earlier section of this document (Description of WFLIC operations) outlines its role.

8 observe

|Action name |Principal function |Arguments |

|observe |observe() |Arg1 - Data label (char) |

| | |Arg2 – Frame number |

| | |Arg3 – (optional) focus index |

| | |Arg4 – (optional) focus offset |

An earlier section of this document (Description of WFLIC operations - Observes) outlines the role of this action.

9 powerOff

|Action name |Principal function |Arguments |

|powerOff |powerOff() |none |

This runs an application in the camera server to disable the power to the array.

10 powerOn

|Action name |Principal function |Arguments |

|powerOn |powerOn() |none |

This runs an application in the camera server to enable the power to the array.

11 setSim

|Action name |Principal function |Arguments |

|setSim |setSim() |Arg1 – Simulation level (0 for no simulation; 1 to simulate) |

This sets the simulation level of the camera. When simulation is enabled:

• There is no communication with the camera or filesave servers;

• The duration of requested exposures is not simulated;

• A single pre-existing raw dataset is identified as the raw data from every observe – it is this that is subsequently demultiplexed and exported.

Note that this action provides only a backup method of defining the simulation level. The usual way of setting this is via an argument of the init action.

12 test

|Action name |Principal function |Arguments |

|test |test() |As required for test |

This is a stub action provided for engineering purposes during WFLIC development but not intended for use during normal operation.

WFLIC function descriptions

1 Exit

Function:

Cause this task to exit

Description:

Calls DITSPUTREQUEST with DITS_REQ_EXIT.

Language:

C

Prototype declaration:

DPRIVATE DVOID Exit(StatusType * status);

Parameters:(“>” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input, “!” modified, “W” workspace, “” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“) char * app_name - Name of the application

(!) StatusType * status - Drama status

Function value:

void

Author:

Alan Pickup,ROE(dap@roe.ac.uk)

Version Date:

2004-Jun-30

15 goCamera

Function:

Send a GO to the camera and the filesave for the

current application

Description:

Return immediately if the status is bad on entry.

Initialise the localStatus to 0.

Call fsIdle() to wait for the fileave task to become idle.

Post the current application to the camera and filesave

servers.

If not in simulation, send a GO to the filesave server.

If not in simulation, send a GO to the camera server. If this

completed OK, set ifGoCamera to 1 to indicate that the

camera is active.

Language:

C

Prototype declaration:

static void goCamera (StatusType * status);

Parameters:(“>” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input, “!” modified, “W” workspace, “” input,“!” modified,“W” workspace,“” input, “!” modified, “W” workspace, “” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“” input,“!” modified,“W” workspace,“) double seconds - seconds of time

(” input, “!” modified, “W” workspace, “” input,“!” modified,“W” workspace,“” input, “!” modified, “W” workspace, “” input, “!” modified, “W” workspace, “ ................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download