INS-CCD-5

Interfaces to the
science CCD server

Daniel Matthews

1.1; 20 November 1996

Isaac Newton Group, RGO,
Aptdo 368,
Santa Cruz de La Palma, TF38780 Spain

Telephone (int+) 34 22 405500
Fax (int+) 34 33 405646
Internet drm@ing.iac.es

1 Introduction

1.1 Context

The science CCD server is a program for the `Solaris' operating-environment that controls the science CCD controller. The detailed design of the server is described in INS-CCD***. The original user-requirements driving the design of the server are listed in INT-PF-1 and INT-DAS-1; a technical analysis of INT-PF-1 is presented in INT-PF-4. This document defines the interfaces by which other systems and programs can use the server.

This is a specification of the interface. It is valid for software writers to claim conformity with a specific issue of this document. If the implementation of the SCCD server does not match this document, then the software is at fault.

1.2 Overview of interfaces

Much of the detailed behaviour is described in INS-CCD***, reference [4], but these details are liable to change. The aspects of the behaviour that can be relied upon are described in sections 5 and 6.

The overall architecture of the server is outlined in section 2.

Communication with the science CCD controller is via an RS232 serial link, operating the "Utility Network" protocol, as described in reference [5] The specific messages used when communicating with a CCD controller are described in reference [6]. Section 3 defines the DRAMA interface for the utility network facility

The server runs under the supervision of the general observing system. The interfaces by which the server talks to its parent system are described in sections 5 and 6.

The server requires certain environment variables to find files, and homes for generated files. These are described in section 7.

1.3 References

[1] User Requirements for the INT DAS
RGO/ING document INT-DAS-1 by Guy Rixon and Daniel Matthews.

[2] Controls for the INT PFC: User Requirements
RGO/ING document INT-PF-1 by Guy Rixon.

[3] Controls for the INT PFC: System Requirements
RGO/ING document INT-PF-4 by Guy Rixon.

[4] Detailed design of the Science CCD server ING/RGO document INS-CCD***, by Daniel Matthews

[5] Utility net protocol
RGO/ING document ER412

[6] WHT CCD controller Network Messages
RGO/ING document WHT-CCD-1 by J F Maclean.

[7] Interfaces to the INT IDS server
ING/RGO document INS-IDS-1 by Daniel Matthews

[8] Science CCD server detailed design
ING/RGO document INS-CCD-x by Daniel Matthews

[9] Dialogues with the user: General Principles ING/RGO document OBS-TALK-1 by Guy Rixon

[10] Server services ING/RGO document ?????, by Guy Rixon

[11] Interfaces to the DAS server ING/RGO document ????,

2 Architecture

2.1 System Context

Figure 1. is the context diagram for the SCCD server. The primary data and control source is the CCD controller itself.



The system is responsive to all kinds of DRAMA transactions. The interface for incoming transactions are defined in the Command interface section 5. The interface to the talker is defined in reference [9].

The the parameter database (SCCD_parameters) is described in the Parameter Interface section 6. The archive action causes a FITs packet to be written to disk. This is described in reference [10]. The environment variables and command line arguments provided by the parent process are outlined in reference [7] and section 7. The low level communications is via the utility network protocol defined in reference [5], with the specific messages used defined in reference [6]. When the SCCD_INIT action is invoked, the server will attach to the CCD controller, and initialise its configuration by using the CCD_Profile file. The format of this is described in section 8.

2.2 Communications

The communication to and from the CCD controller is via one entry point. The utility network server described in section 3 is part of the "communications" task shown below. There is an interface task between the utility network layer and the update actions, that distributes the messages to the correct update task.



For each action (Action-N) there is an update (Update-N). When a low level message arrives from the controller the message is interpreted into a UNET_mechmsg_T (as defined in unet.h) message and forwarded to the appropriate Update task. This updates the Parameter system and sends a DRAMA Signal (Signal-transaction) to the task. If the task is not active, this message will be ignored. The status of the received mechanism is often given as an argument to the signal.

2.3 Actions

The Science CCD (SCCD) server has initialisation code, and 15 actions. The detail of the actions is described in section 5. Most actions correspond to a message or set of messages to the CCD controller. The exceptions are the PING and EXIT actions, provided by the srv facility (reference [10]), the ARCHIVE action, described in reference [7].

2.4 Clients

The clients are split into 9 groups of related functionality. Each group is implemented as one executable with softlinks to allow different invocation names. All clients have the ability to talk to SCCD servers with different DITs names. This is via the the "-C nnn/XXX" command line option. The "nnn" is ignored, while the XXXX is the name of the server required. This defaults to SCCDa, but when there are multiple CCDs, this can be used to differentiate between them.

The simplest clients carry out one function, and only communicate with the SCCD server. These are CLEAR, to clear the CCD, RESET, to reset the CCD controller, SHUTTER, for controlling the shutter, and SYNC_RTC. This final one is used to synchronise the CCD controller with the UTC on the Sparc. This implements the synchronisation protocol outlined in reference [6]. This can take up to a minute to complete. The system computer clearly has to have accurate time. NTP can be used to ensure this.

The PROMOTE client does not actually communicate with the SCCD server at all, but instructs the DAS server to create a run file from a scratch or glance file. This is outlined in reference [11].

The SETTINGS client provides a way of modifying the CCD controller settings. These are, the readout speed, the clear speed, the preflash time, the exposure time, the binning factor and the windows. If the required client causes the readout format to change, then the DAS server is also notified to ensure it will expect the correct number of pixels, and be able to interpret them correctly.

The SETUP client implements the SCCD_INIT action that causes the CCD profile file to be loaded and all the settings (above) to be initialised. The DAS server is also notified of the final format. It will also ensure the DAS server knows which headers to expect with any run.

The RUN client is the most complex and carries out the tasks required for creating an image file on disk. This requires coordination between the SCCD server and the DAS server. This client is used to generate the scratch, glance and science runs. It will also ensure the FITs headers are collected.

The RUNKICK client is used to modify the sequence of a RUN (see above). It implements the pause, continue, abort, finish and newtime functions.

The MULTRUN client causes a sequence of runs to be made. All runs will have the same exposure time and object name/comment.

2.5 Mimic

A simple user interface is provided to outline the state the CCD controller to the user. This shows any windows set up, the current readout and clear speeds and the state of any run being carried out, including the shutter position.

3 Utility Network Layer

The CCD controller communicates down the serial port using the utility network protocol. This interface is defined in reference [5], and the messages specific to the CCD controller in reference [6]. The Utility network has been implemented in DRAMA using a suite of functions, defined below. This facility is defined in detail in reference [8].

When the facility is first initialised, the XON/OFF transmission is started and remains active in the background. Every half second it will wake and send the XOFF character, as is required by the utility network protocol.

All utility net messages received or transmitted are logged using "msgLog" provided by the INS facility.

When the host server requests the transmission of a message, it gets assembled into a message string and sent down the serial port. The message also gets put into a transmit table. If the message gets acknowledged, it is removed from the transmit table. If, however, an acknowledge is not received after a certain period, it will get resent up to 4 times. In order not to overload the target instrument, messages are queued in the transmit table and only sent one at a time. Only when an acknowledgement is received for a message is it removed from the transmit table and the next message sent.

When a message is received, it is parsed to verify the type and conformity to the utility network protocol. If it is detected as an acknowledgement type message, the corresponding message in the transmit table is removed. Otherwise the message number is logged in the receive table and the message is forwarded to the server. If a subsequent message is received with the same message number as one that has previously arrived, the message is not forwarded to the server. Either way, the message is acknowledged.

3.1 Function interface

The Utility network facility requires the server to provide the following function:

void unetProcessMsg( UNET_mechmsg_T *umsg, StatusType *status)

umsg is the arrived utility network message

status is the inherited status

This is the mechanism by which the Utility network facility forwards the messages to the server, using the UNET_mechmsg_T structure type defined in unet.h

The Utility Network facility provides the following function to the observer:

void unetTransmit(UNET_mechmsg_T *umsg, StatusType *status )

umsg defines the message to be sent

status is the inherited status

This is the mechanism by which the server should send the utility network message. Firstly assemble the message into a UNET_MECHMSG_T structure, and then call this function to allow the message to enter the utility network facility.

The Utility Network facility provides the following functions to the INS server (defined in reference [7]):

portInit

portRead

3.2 Parameter Interface

The Utility network facility adds the following parameters to those declared by the host server:

SHORTMSG - counts the number of messages that have arrived too short

LONGMSG - counts the number of messages that have arrived too long

RESEND - counts the number of times a message has had to be resent

These parameters can be monitored to determine the state of the link. If there are repeated resends, this can imply that the serial ports are either not connected or are unreliable.

4 Behaviour of the science CCD server

This section defines those aspects of the server's behaviour that affect the interfacing. It describes the more complex actions in more detail.

The telescope may have more than one CCD in use at any time, so the server has been designed to allow multiple copies to be running simultaneously. Each SCCD server is associated with one serial port, and the part must be provided as an argument when the server is first started. It is not possible to change which port is served by any particular incarnation of the server, and the port name is used when the task registers with DRAMA, and must be known by any tasks requesting to communicate with the server. Sending a PING message (see section 4), or using 'ps' could indicate which servers are currently available. The command "cleanup -l" can also be used, but very carefully, as without the "-l" option all the DRAMA tasks will be killed.

Only when the server is initialised, by the INIT message, is the utility network name of the remote controller known. So until this is done, no utility network messages can be sent to the controller, and hence no other actions will succeed. The contents of the initialisation file is described in section 6.

The CCD controller is put into 'monitor mode' when initialised, so messages could arrive spontaneously from the controller with no action having requested them. A mechanism must be available for spontaneous messages to be displayed to the user. The "talker" (see reference [9]) is used for this.

The protocol used to communicate with the CCD controller is the "Utility Net Protocol" as described in reference [5]). The Utility Network Facility, section 3, is used to implement this.

The server is required to provide FITs descriptors for inclusion in the FITs header. These are generated using the INS Facility described in reference [7].

The server is used to set the time on the CCD controller. In order for this to be accurate, the time on the system computer should be accurate. This can be ensured by running the Network Time Protocol (NTP).

Some of the actions that can be started can take some time to complete - notably readout, run, clear and synchronise. If these actions are obviously going to fail and the user no longer wishes to wait for them to complete, they can be kicked (DRAMA Kick message sent to the action), with no arguments to cause them to terminate. This will not affect the CCD controller, which may continue to readout, clear or synchronise, without any action from the server. Therefore it is recommended that this feature be used sparingly and with caution.

5 Command interface

The science CCD (SCCD) server is a DRAMA task and its commands are implemented as DRAMA actions, invoked through OBEY messages in the normal way. These actions can be used by DRAMA tasks running on the science CCD server computer or on computers elsewhere on the Internet. There is a separate science CCD server for all CCDs at a given telescope.

The SCCD server registers with the DRAMA message-system as `SCCDn'; where the character 'n' is used to allow more than one copy of the server to run. Note also that case is significant when invoking this program by name. If the host computers for the INT and JKT are, say, lpss10 and lpss12 respectively, then the SCCD servers on those telescopes might be addressed as SCCDa@lpss10.ing.iac.es and SCCDa@lpss12.ing.iac.es: these are the fully-qualified task names that would be passed to functions of the DRAMA libraries when connecting to the servers.

The server's actions send one status message when they end and do not send `trigger' messages. Each completion message reports the final status of the action to which it applies but does not describe the state of the sub-system; e.g., a completion message might say that a format-change action failed, but it would not say what format was current at the end of the action. The sub-system state is reported by DRAMA parameters, as described in section 6. Action names are all in upper case: this make it possible to access the actions from an ADAM system. The argument names listed, including the mixed case, should be reproduced exactly in the argument structure passed with the action.

SCCD_INIT initialises the server. It is required that this action is executed once when the server starts and completes when this has been done It can be used subsequently to return the server and controller to the initial state. This action loads the CCD profile file, of the form EEV9.dat, and sets the CCD controller to these initial values. See section 6 for details of the CCD profile file. Most of the parameters listed in section 5 will be modified. SCCD_INIT requires one parameter as follows:

Argument1 (character string) is the name of the CCD in use.

SCCD_SETFORMAT set readout format of the detector to the format requested. If any values in the requested format are invalid, they will be ignored and the current values assumed as those required. That is: use 0 to retain current binning factors and INVALID for unused windows. This will complete once the controller has confirmed that the values have been set. SCCD_SETFORMAT requires one parameter as follows:

Argument1 (structure) is a structure describing the format; the argument is formed by exporting (using SdsPut()) a C structure of type SCCD_format_T - see below.

SCCD_SETRSPEED set the readout speed of the CCD controller. If the speed is invalid the action is rejected. The action will complete when the controller confirms the change in speed. SCCD_SETRSPEED requires one parameter as follows:

Argument1 (integer) specifies the readout speed, and can be interpreted using the SCCD_rspeed_t enumerated type, found in sccd.h.

SCCD_SETCSPEED set the clear speed on CCD controller. If the speed is invalid the action is rejected. The action will complete when the controller confirms the change in speed. SCCD_SETCSPEED requires one parameter as follows:

Argument1 (integer) specifies the clear speed, and can be interpreted using the SCCD_cspeed_t enumerated type, found in sccd.h.

SCCD_SETPFLASH sets the preflash time to that requested, and returns when the controller has confirmed the new preflash time. If the requested time is 0, there will be no preflash with subsequent exposures, otherwise, packaged runs (see SCCD_DORUN below) will have a preflash after the clear and before the exposure. SCCD_SETPFLASH requires arguments as follows:

Argument1 (float) is the preflash time in seconds.

SCCD_SETEXPTIME sets the exposure time, and returns when the controller has confirmed the new exposure time. The current exposure time can be read from the EXPOSURE_TIME element of the RUNSTAT parameter described below. If the requested time is 0, the shutter will not open in subsequent runs. If the server is already carrying out a RUN, this is interpreted as a modification to the exposure time, and an error will be reported if the new exposure time is less than that already complete, or the CCD has already started reading out. It requires the following parameter:

Argument1 (float) is the exposure time in seconds.

SCCD_DOSHUTTER moves the shutter mechanism. The action will complete when the movement is complete. SCCD_DOSHUTTER accepts one argument.

Argument1 (integer) is the action requested, from the SCCD_shutter_cmd_t, and can take the following values SHUTTER_OPEN (0), SHUTTER_CLOSED (1) or SHUTTER_UNJAM (2)

SCCD_DOCLEAR carries out a clear of the detector. This will be rejected if the controller is not in IDLE (see SCCD_runstat_T). This will complete when the controller confirms that the clear has finished. SCCD_DOCLEAR requires no arguments.

Sending a kick message to SCCD_DOCLEAR aborts the action. This kick requires no arguments. This will not stop the clear on the CCD controller, if it were in progress.

SCCD_DOREADOUT requests the CCD controller to readout the detector. This will be rejected if the controller is not in IDLE (see SCCD_runstat_T). This will complete when the controller confirms that the readout has finished. SCCD_DOREADOUT requires no arguments.

Sending a kick message to SCCD_DOREADOUT aborts the action. This kick requires no arguments. This will not stop the readout however.

SCCD_DORUN carries out a packaged run , that is a run that includes a clear, preflash (if requested with SCCD_SETPFLASH above), exposure and a readout. This action will be rejected if the CCD controller is not in the IDLE state. This action will return when the controller informs the server that the action is complete. If a dark exposure is requested, the shutter will not open. SCCD_DORUN requires 1 argument:

Argument1 (integer) is the type of packaged run requested. From the enumerated type SCCD_pkgrun_t SCCD_RUN_DARK is 1, and SCCD_RUN_PIC is 0 for a normal run.

Sending a kick message to SCCD_DORUN can modify the action. The kick has one or two optional arguments, if no argument is provided the action will abort, although the CCD controller will continue the run. The second argument is only needed for a PAUSE or NEWTIME kick message:

Argument1 (integer) is the optional kick type taken from the enumerated type SCCD_pkgrun_kick_t and takes the following values:

SCCD_DOABORT to attempt to abort the run before it starts reading out.

SCCD_DOFINISH to close the shutter and readout out the image now.

SCCD_DOPAUSE to pause or continue a run.

Argument2 in the case of a PAUSE kick(integer) TRUE (!0) to pause a run, FALSE (0) to continue a paused run.

The exposure time should have been set up previously with the SCCD_SETEXPTIME action. During an exposure the exposure time can also be changed with SCCD_SETEXPTIME.

SCCD_DOSYNC synchronised the real time clock on the CCD controller. This is important as it is this time used to time-stamp the opening of the shutter. This action will complete when the CCD controller acknowledges that the synchronisation has finished, which could be up to 70 seconds. No arguments are required.

Sending a kick message to SCCD_DOSYNC aborts the action. The kick requires no arguments. The synchronisation process will continue and the status held in the parameter UTCSYNC (see section 6).

SCCD_DORESET sends a reset message to the controller. This will cause the controller to reset, and will inform the server that the controller it is no longer initialised. An SCCD_INIT will be required after this action. This action completes immediately, however the controller takes some time to reset. SCCD_DORESET requires no arguments.

EXIT causes the server to exit cleanly. It is recommended that this be the only method of terminating the server. This is the standard action from the srv package.

PING does nothing, simply terminates immediately. It can be used as a method of verifying the server is alive. This is the standard action from the srv package.

ARCHIVE writes the FITs header packet relating to the SCCD to the named fits file. This is the standard action from the srv package, with the INS archive facility.

6 Parameter interface

The state of science CCD controller, the state of the server and several data values regarding the detector in use are all reported through DRAMA parameters. These parameters are updated and accessed independently of actions on the science CCD server.

The parameters may be monitored or polled by any DRAMA task that wishes to watch events in the server; monitoring is preferred to polling as it involves fewer messages and gives a more timely notification of changes. A task that monitors a parameter will not be told the parameter's value at the time that monitoring begins: the task should do one explicit GET of the parameter when monitoring starts.

Some additional parameters are maintained in the server by the Utility Network facility. See section 3.2.

INIT (unsigned short integer) is TRUE (!0) if the server has been successfully initialised with the SCCD_INIT action, or is FALSE (0) otherwise.

FORMAT (`format' structure - see below ) is the readout format currently set. This will be updated on an initialisation and whenever the readout format changes, such as when the SCCD_SETFORMAT action is executed.

RSPEED (unsigned short integer) is the current readout speed. The value can be interpreted from the SCCD_rspeed_t enumerated type in sccd.h. The speed defined by this value also corresponds to that defined in WHT-CCD-1 as follows:

RSPEED_STANDARD 0

RSPEED_QUICK 1

RSPEED_TURBO 2

RSPEED_NONASTRO 3

RSPEED_SLOW 4

CSPEED (unsigned short integer) is the current clear speed. The value can be interpreted from the SCCD_cspeed_t enumerated type in sccd.h. The speed defined by this value also corresponds to that defined in WHT-CCD-1 as follows:

CSPEED_STANDARD 0

CSPEED_QUICK 1

PFLASH (float) is the current preflash time in seconds, in the range 0 <= PFLASH <= 1600. A time of 0 (or less than 0.0001) indicates that there will be no preflash.

SHUTTERPOS (unsigned short integer) is the current position of the shutter. The value can be taken from the enumerated type SCCD_shutter_posn_t as defined in sccd.h. It can take the following values:

SHUTTER_OPENED 0

SHUTTER_CLOSED 1

SHUTTEROK (unsigned short integer) indicates the shutter status, and takes the value 0, or FALSE if the shutter is jammed, and !0 or TRUE otherwise.

RUNSTAT ('runstat' structure - see below ) describes the status of the current run as reported by the controller.

READTEMP (unsigned short integer) is the current temperature (in Kelvin) that the controller last reported the CCD. If this is seen to increase above SETTEMP, liquid nitrogen may have run out and the user should be informed.

SETTEMP (unsigned short integer) is the temperature (in Kelvin) that the controller has been set to servo the CCD to.

UTCSYNC (unsigned short integer) is TRUE (!0) if the CCD controller is synchronised to the time on the host computer, or FALSE (0) otherwise.

DAS_CHANNEL (unsigned short integer) is the channel on the DAS used by the this detector. This is usually fixed for an instrument setup.

HEADNO (unsigned short integer) is the head number of the detector on the controller. This will usually be 1.

HEADCODE (unsigned short integer) is the number appended, by the fibre driver card in the CCD controller, to the start of each pixel. This is fixed for a particular CCD.

DETCOUNT (unsigned short integer) is the number of separate CCD detectors are connected to the controller.. This will be 1 for most applications, but 4 for the INT PFC. It can be used when accessing the readout_noise and gain arrays below.

PIXXSIZE (float) is the size, in meters, in the X direction, of the detector pixels.

PIXYSIZE (float) is the size, in meters, in the Y direction, of the detector pixels.

XUNDER (unsigned short integer) is the size, in pixels, of the underscan region in X.

YUNDER (unsigned short integer) is the size, in pixels, of the underscan region in Y.

XSILSIZE (unsigned short integer) is the size in pixels of the imaging (silicon) area of the detector, in the X direction.

YSILSIZE (unsigned short integer) is the size in pixels of the imaging (silicon) area of the detector, in the Y direction.

GAIN (array float) is the approximate readout gain, in electrons/ADU, for the detector. This is an array, indexed by the readout speed.

CURRENT-GAIN (float) is the gain for the detector with the current readout speed

NOISE (array float) is the approximate readout noise, in electrons. This is a two dimensional array and can be indexed in the same way as GAIN above.

CURRENT-NOISE (float) is the current readout noise, in electrons, for the detector in the current readout speed.

CCDTYPE (string) defines the type of detector, eg "TEK1024AR"

CCDNAME (string) is the name that the detector is commonly known as, eg "TEK4"

UNET_REMOTE (string) is name used by the CCD controller when communicating on the utility network. This will usually be of the form "CCDn" where 'n' is '1' to '9'.

UNET_LOCAL (string) is the name used by the host computer when communicating on the utility network. This will usually be of the form "SYS.CCDn" where "CCDn" is UNET_REMOTE above.

The xy_T structure type used in the 'format' structure is defined in sccd.h. It has the following elements:

X (unsigned short integer)

Y (unsigned short integer)

The SCCD_win_T structure type used in the 'format' structure is defined in sccd.h and has the following elements:

VALID (unsigned short integer) TRUE (!0) if this hold a valid window definition.

WIN_SIZE (structure xy_T) defines the (x,y) size of the window.

WIN_START (structure xy_T) defines the (x,y) position of the first pixel in this window.

The `format' structure used for FORMAT may be read by SdsGet() into a C structure of type SCCD_format_T as defined in sccd.h. This is the same type used as an argument of the action SCCD_SETFORMAT. The elements of the structure are as follows:

SCCD_SIZE (structure type xy_T) is the default full frame readout size.

WIN (array of structure type SCCD_win_T) defines the windows current windows defined

WINP(array of structure type SCCD_win_T) is not used by the science CCD server. Its use is defined in INS-DAS-9.

WINDOWS_ENABLED (unsigned short integer) is FALSE (0) when windows are not in use, and TRUE (!0) otherwise.

BIN_FACTOR (structure xy_T) defines the x and y binning factors, which are set to (1,1) when binning is disabled.

TRANSFORM (array[8] of type char) is not used by the science CCD server. Its use is defined in INS-DAS-9.

IMAGE_SIZE (structure xy_T) is not used by the science CCD server.

The 'runstate' structure used for the parameter RUNSTAT may be read by SdsGet() into a C structure of type SCCD_runstat_T as defined in sccd.h. The SDS elements of this structure are as follows:

STATE (unsigned short integer) is the state that the controller is currently in, and takes a value from the enumerated type SCCD_runstate_t as defined in the file sccd.h. It can take the following values:

RSTATE_IDLE

RSTATE_CLEARING

RSTATE_PFLASHING

RSTATE_EXPOSING

RSTATE_READINGOUT

RSTATE_PAUSED

RSTATE_ABORTING

EXPOSED_TIME (float) is the time, in seconds, that the shutter has so far been open.

EXPOSURE_TIME (float) is the total exposure time, in seconds, requested.

ELAPSED_TIME (float) is the total time, in seconds, since this run started.

START_TIME (unsigned long integer) is the time, in the decimal form UTC hhmmss, that the shutter opened.

7 System interface

The sccd server requires the executable sccd to be in the search path (environment variable PATH). It is started by executing the command sccd with one argument defining the serial port to be used for this server. The name used to register with DRAMA should be given as a second parameter.. If executed on the command line or in a shell script, the server will probably want to run in the background. For example typing:

sccd /dev/term/a SCCDa &

will start the server, using serial port /dev/term/a, and operate in the background. The server will register with DRAMA as "SCCDa". There can only be one DRAMA task registered with a particular name at a time.

The following environment variables are used by the SCCD server:

LOGS defines the location for the log file produced by this server, "dramaname"_log - where dramaname is the second command line parameter. If this environment variable is undefined, the file will be deposited in the current directory.

LOGDATE defines the date to be used for the log file suffix produced by this server, SCCDn_yymmdd.log. If it is undefined, the log file will be called SCCDn_NULL.log

HDR_TEMPLATES defined the location of the FITs header template files. These are named sccdTemplate.BEGIN and sccdTemplate.END

OBSSYS defines the root of the current observing system in use. This is used for storage of the archive packets and the location of the persistence files containing the exchangeable optics databases.

SCCD_PROFILE defines the location for the detector profile files, as described in section 6. If this is not defined, the current directory will be searched for the appropriate file, if it still can't be located, the initialisation (DRAMA action SCCD_INIT) will fail.

The utility network layer is provided by the Utility Network Facility as described in section 3.

The following files are required by the SCCD server:

sccdHdr.BEGIN defines the header packets to be collected at the start of an observation. See reference [7] for details of the format. This file should be stored in the location indicated by HDR_TEMPLATES above.

sccdHdr.END defines the header packets to be collected at the end of an observation. See reference [7] for details of the format. This file should be stored in the location indicated by HDR_TEMPLATES above.

8 The CCD profile file

When an SCCD_DOINIT action is requested, the server searches the path indicated by SCCD_PROFILE for a file of the name CCCC.dat, where CCCC is the detector name supplied as "Argument1" to the action routine. For example, if TEK3 is in use, file TEK3.dat will be loaded.

The file format is:

Plain ASCII text, of the UNIX stream format, with records separated by '\n'.

Any line not starting with an upper case character (A-Z) is ignored, and may be used for comments.

The first item on a non comment line is the parameter name, as defined in section 4, followed by a white space separator, followed by the value, or in the case of arrays or structures, the complete set of values.

The values must be numeric, unless the parameter is a string. eg readout speed should be 0 for RSPEED_STANDARD. (See section 4)

There should be no '\n' (CRLF) until the definition of the parameter is complete.

Parameter names that are not expected, will be ignored, and no parameter will be generated or set.

The FORMAT structure is not defined directly. Instead the three parts that can be initialised, are set individually. Any windows that are to be defined initially should be defined with a parameter name WIN, with subsequent parameters "n xsize ysize xstart ystart" where n is the window number between 1 and WINDOWS_PER_HEAD (4). If no windows are defined, windows will not be enabled, otherwise they will, with undefined windows set to invalid. Binning factors should be defined using the parameter name BIN with 2 subsequent arguments, X and Y. If this is not included. the BIN factors will default to (1,1), ie unbinned. The default full frame readout size MUST be setup, using the keyword SCCD_SIZE, with 2 subsequent arguments X and Y. No other elements in the FORMAT structure can be initialised.

The following parameters must be defined in the file:

SCCD_SIZE Full frame readout size (x,y)

UNET_REMOTE Network name of CCD controller, of form CCDn

GAIN Gain in e/ADU for each readout speed, these should be in the order Standard, Quick, Turbo, Nonastrom Slow

NOISE Noise in e/ADU for each readout speed - in the same order as GAIN above

DAS_CHANNEL Channel of the FOX card to be used by this detector

HEADNO Head that the CCD is connected to, always 1

HEADCODE Code prefixed to each pixel by the fibre card of the CCD controller. This is usually set to be 16 times the UNET_REMOTE number. ie 32 for CCD2

PIXXSIZE pixel size in metres in the X direction

PIXYSIZE Pixel size in metres in the Y direction

XUNDER Number of pixels in the X underscan

YUNDER Number of pixels in the Y underscan

XSILSIZE Size of the imaging area in pixels in the X direction

YSILSIZE Size of the imaging area in pixels in the Y direction

CCDTYPE Text string describing the CCD type

CCDNAME Name commonly used for this detector

The following are also accepted but if not present default to the value shown:

TRANSFORM image transform (none)

BSCALE Scaling of digital number (1.0)

BZERO Value assumed for 32767 (32767)

BITPIX Number of bits per pixel (16)

WIN any default windows (Wno XSize YSize Xstart YStart) (no windows)

BIN Binning - Xbin Ybin (1,1)

PFLASH Preflash time (0.0)

RSPEED Readout speed (standard)

CSPEED Clear speed (quick)

DETCOUNT Number of detectors (1)

The meaning of these parameters can be determined by reference to section 6. An example can be found in appendix A.

9 Compile-time interfaces

The science CCD server sub-system provides some include files defining SCCD-specific constants and data types for the use of other software.

sccd.h defines data types used in the parameter and command interfaces.

unet.h defines data types and constants for programs intending to access the utility network layer directly.

ins.h defines data types and constants used in the general instrument facilities.

sccdErr_msg.h Error messages corresponding to error numbers produced in the server

sccdErr.h Error numbers returned by actions in this server.

insErr_msg.h Error messages corresponding to error numbers produced by the general instrument facilities

insErr.h Error numbers for the above.

Appendix A. Example CCD profile (TEK1.dat)

#===============================================================#
# #
# Issac Newton Group of Telescopes #
# Roque de los Muchachos Observatory #
# La Palma #
# #
#===============================================================#
#
#
# FILE:
# TEK1.dat
#
# TYPE:
# CCD definition file
#
# PURPOSE:
# Defines the initialised state of TEK1
#
# REFERENCES:
# "Interfacing with the science CCD server"
# RGO/ING document INS-CCD-5
#
#
# HISTORY
# v1.1 30/04/96 DRM First formal release
# v1.2 11/11/96 DRM Removed fixed window
#
#===============================================================#
# Version
# @(#) BOM TEK1.dat 1.2
#===============================================================#
#===============================================================#
# Following are ALL essential:
#
UNET_REMOTE CCD2
HEADNO 1
RSPEED 0
CSPEED 1
PFLASH 0.0
DETCOUNT 1
PIXXSIZE 24E-6
PIXYSIZE 24E-6
XUNDER 50
YUNDER 0
XSILSIZE 1024
YSILSIZE 1024
SCCD_SIZE 1124 1124
CCDTYPE TEK1024AR
CCDNAME TEK1
TRANSFORM +-
BSCALE 1.0
BZERO 32767
BITPIX 16
DAS_CHANNEL 1
HEADCODE 32
#
# Gain and readout noise table :
# Std Quick Turbo Nonast Slow
GAIN 1.28 1.74 2.73 4.77 1.16
NOISE 5.24 5.73 8.38 23.56 5.02
#===============================================================#
#===============================================================#
# Add any non-essential ones below this line
#

Appendix B. Document History

Issue 1.1 16.11.96 First formal release