INS-DAS-21

Server Interface for Shutter Control

Issue 2.1, written on 4th August 1999

Guy Rixon, UK ATC (gtr@mrao.cam.ac.uk )

Introduction

Purpose of this document

The DRAMA interface for control of shutters is described. The interface is a standard within the UltraDAS project and this document defines the standard.

Authors of UltraDAS software should construct their programmes to conform to the current issue of this document and should note the specific issue in the programme's documentation. If the programmes are found to differ from this document, then the programmes should be corrected.

Scope of the interface

Instructions from shutter control pass from client programmes on the system computer; then to server programmes on the DAS computer; then to programmes on the detector controller; finally to the shutter-control electronics. The interface discussed here is the first of these links, between the client and server programmes. Please see the main architecture document [1] for details of the other interfaces.

This interface applies to the camera servers of the UltraDAS and to any separate server programmes (e.g. the MCA programme for the INT wide-field camera) that control shutters which can time exposures. There is no need to apply this standard to non-timing shutters such as the grating shutter in the IDS.

The interface is a standard set of DRAMA actions and DRAMA parameters that allows the client
to

open and close the shutter;
do timed exposures;
measure the timing of exposures;
determine the shutter's state.

The standard part of the interface abstracts a simple shutter such as the Compur devices. A more-complex device, such as the disc shutter in the INT wide-field camera, must implement the standard interface but it may also extend the interface (e.g. to provide detailed feedback on the shutter's position) with additional actions and parameters.

Changes to this document

Issue 1.1, 1998-10-13:

Original document.

Issue 2.1, 1999-08-04:

The parameter interface was simplified to take account of the limited information available from the CCD controllers. The order of arguments in the INTEGRATE action was reversed to match the arguments already implemented for the WFC shutter. No particular error-codes are now specified.

Issue 2.2, 2000-03-08:

Updated and corrected links to other documents

References

Architecture for the UltraDAS

INS-DAS-19

User requirements for the UltraDAS data acquisition system

INS-DAS-16

Concepts

Each shutter is presumed to have a preferred "parking position". This is the position that the shutter is best left in between observations. For most shutters, the parking position is the closed position, but some may need to be parked open to allow ancilliary equipment to see the sky.

From the observer's point of view, an integration that has not run its full course can be "finished", which implies that the data will be read out and kept, or "aborted", which implies that the data will be discarded. This distinction does not hold in shutter control: the house-keeping operations at the end of the integration are so quick that there is no reason not to do them when an observation is aborted. Hence, there is only one action that stops an integration and it is called "FINISH".

The current user-requirements [2] do not ask for commands to pause and resume an integration. Those facilities are not included here.

Integration times are represented as floating-point numbers of seconds. Absolute times are expressed as timestamp strings in ISO8601 format:

   yyyy-mm-ddThh:mm:ss.sss

For example: 42 minutes, 58 seconds and 648 milliseconds past midnight on the 3rd of January 1999 is show as

   1999-01-03T00:42:58.648

The times are in UTC.

Some of the action descriptions talk of "sending an ERS report to the client". This means making a normal status-report through calls to the ERS library but deliberately not setting the broadcast flag in the report. In this way, the report goes to the log via the client and the client has the chance to supress it if the error can be recovered without user intervention.

Actions

Open the shutter

Name: OPEN

Arguments sent with command: none.

Arguments returned with status: none.

Sematics:
The shutter is moved to its fully-open position and left there. The action completes when the shutter is fully open.

If the shutter is already open, then the action completes immediately with good status.

If the shutter does not respond, or does not complete the movement correctly, the action aborts within five seconds of the command. In this case, the server returns the status SHUT-E-MOVEFAIL and sends an ERS report to the client.

Shut the shutter

Name: SHUT

Arguments sent with command: none.

Arguments returned with status: none.

Sematics:
The shutter is moved to its fully-closed position and left there. The action completes when the
shutter is fully closed.

If the shutter is already shut, then the action completes immediately with good status.

If the shutter does not respond, or does not complete the movement correctly, the action aborts within five seconds of the command. In this case, the server returns the bad status and may send an ERS report to the client.

Park the shutter

Name: PARK

Arguments sent with command: none.

Arguments returned with status: none.

Sematics:
The shutter is moved to its parking position and left there. The action completes when the
shutter is parked.

If the shutter is already at the parking position, then the action completes immediately with good status.

If the shutter does not respond, or does not complete the movement correctly, the action aborts within five seconds of the command. In this case, the server returns bad status and may send an ERS report to the client.

Time an integration

Name: INTEGRATE

Arguments sent with command:

Argument1

type of integration: "exposed" or "dark" (case is not significant).

Argument2

exposure time in seconds. This number must be zero or positive.

Arguments returned with status:

Argument1

exposed time in seconds.

Argument2

starting time of the integration in UTC as ISO8601 timestamp

Sematics:
In the normal case, Argument1 is set to "exposed". The exposure-timer is set to zero. The shutter is opened fully and the time of opening is recorded; the exposure-timer is started. At the end of the allotted time, the shutter is closed fully and the final length of the exposure is noted. The length of the exposure is returned to the client with the final status.

No check is made that the shutter is closed at the start of the action. If the shutter is fully open at the start, then the exposure timer starts immediately; the shutter is closed as normal at the end.

If Argument1 is set to "dark", then there are no shutter movements. The timer for the integration starts immediately at the start of the action and the action ends as soon as the alotted time has expired and the parameters have been updated.

The demanded exposure time may be less than the minimum time needed to move the shutter With Argument1 set to "expose", the shutter will make the shortest exposure that the mechanism can manage: this is not a bias frame. For a bias observation, set Argument2 to 0.0 seconds and Argument1 to "dark".

If an integration is terminated by the FINISH action, below, it ends immediately. The shutter is closed as normal and the final length of the integartion is recorded. Retiming the integration to a length less than that already exposed also has this effect.

If a negative number is given for Argument2, the action will end immediately with bad status. No ERS report will be made.

If the shutter does not respond, or does not complete a movement correctly, the action aborts within five seconds of the time of the failed movement. In this case, the server returns bad status and may send an ERS report to the client.

Retime an exposure

Name: RETIME

Arguments sent with command:

Argument1

Demanded exposure time in seconds.

Arguments returned with status: none.

Sematics:
The end point of the current integration is changed. The action returns immediately. The shutter is not moved by this action.

Retiming an integration to less than than the time integrated so far causes the integration to finish immediately: see the INTEGRATE action above.

If there is no integration, the action returns bad status immediately.

If a negative number is given for Argument1, the action returns bad status.

Curtail an integration

Name: FINISH

Arguments sent with command: none.

Arguments returned with status: none.

Sematics:
The integration is ended immediately. The effect is as if the demanded integration-time was exactly equal to the integration time so far, except that the demanded-time parameter is not updated. The action returns as soon as the integration has finished.

If there is no integration, the action returns bad status immediately.

Parameters

These DRAMA parameters may be read by clients at any time. The clients must not write to the parameters.

T_SET = number: is the demanded exposure time in seconds. This parameter is set at the start of the INTEGRATE action and during the RETIME action.
T_EXPOSED = number: is the time integrated so far in seconds. It is set to zero at the start of the INTEGRATE action and is updated at least once every five seconds during the integration. The parameter is updated once more when the integration ends naturally; when the integration is curtailed by FINISH; or when the integration is ended by RETIME. Although the parameter name refers to an exposure, the parameter also records the integrated time in dark integrations.
T_START = ISO8601 timestamp: is the timestamp of the start of the most-recent integration, in the ISO8601 format described above. The parameter is set only at the start of the INTEGRATE action. This means that the value for the last integration is shown between integrations.
T_STOP = ISO8601 timestamp: is the timestamp of the end of the most-recent integration, in the ISO8601 format described above. The parameter is set only at the end of an INTEGRATE action that has got as far as setting T_START. This means that the value for the last integration is shown between integrations.
SHUTTER_STATE = {"open" | "shut" | "not responding"}: is the shutter position. (Note that each keyword has a different first character; clients are invited to use this information to parse the keywords. Case is as shown.) Open and shut mean that the shutter has reached one of its normal stopping-positions and completed its move; anything else is shown as midway. The parking position for a shutter will be shown as one of the states above; "Parked" is not an allowed value for this parameter. The parameter is updated whenever the shutter moves, whether or not there is an action in progress. Spontaneous movements should be noted within five seconds; movements as part of an action should be noted within one second.