Command-and-status interface to DRAMA clients for UltraDAS

Introduction

Purpose of this document

Scope of the interface

The first interface is between UI programmes of UltraDAS and the command-translator polymorph. This is both an internal interface, between UltraDAS' GUI programmes and polymorph, and a user interface, since UI may be a standard shell and the user may give these user commands directly or from a script.

The second interface is between polymorph and the client programmes themselves.  This is an internal interface of UltraDAS and users are not expected to type these client commands at the terminal.

There are a few clients whose client commands are issued directly by the UI programmes without translation by polymorph.

The context of client operations is described in more detail in the architecture document for UltraDAS [1].
 

Revisions to the document

References

1. Architecture for UltraDAS

ING document INS-DAS-23 by Guy Rixon.

2. Server interface for shutter control

ING document INS-DAS-21 by Guy Rixon.

3. Client-server interface for control of cameras

ING document INS-DAS-24 by Guy Rixon.
 

Camera names, instrument names, and the CIA's environment variables

• OBSSYS must contain the path to the top of the observing system. E.g. /int/s8-1.
• TELESCOPE must contain the name of the telescope in upper case. E.g. INT.
• INSTRUMENT must contain the formal name of the instrument, or a space-separated list of such names. E.g. IDS or "blue red" (the latter case for the two arms of ISIS).
• CAMERA must contain the formal name of the camera or a space-separated list of such names.  E.g. WFC or "TEK2 EEV13".
• The number and order of names in CAMERA must match the number and order of names in INSTRUMENT. That is, the first-named detector must be the one mounted on the first-named instrument, etc,  and an instrument that carries more than one camera (like ISIS) must have a distinct name to go with each camera.

An instrument's formal name is a name known to both the DAS and the CIA. In UltraDAS, the CIA passes the instrument's
formal name to the DAS as an argument when asking for a run to be archived: this allows the DAS to determine which FITS-header packets to include.  Typical names are IDS, WFC, Musicos, blue and red: the last two refer to the arms of ISIS.  The formal name of the instrument is often the name by which the instrument's server programme logged into the DRAMA message-net, but this is not always the case.  For example, ISIS needs a separate formal name for the blue and red arms, but only has one name in the message net. Case is significant in these names.

Formal names appear both in UltraDAS' configuration files and in the observing-system's start-up scripts and configuration menus. The names must be agreed between the parties maintaining these packages.

The user commands described below each have a camera-choice argument. This indicates which camera and instrument are involved with the command where more than one camera is configured. The camera-choice must match the formal name of the camera or the formal name of the corresponding instrument, but case is not significant in this matching. That is, for a configuration of

INSTRUMENT = "blue red"
CAMERA     = "TEK2 EEV13"

run blue 10
run BLUE 10
run tek2 10
run TEK2 10

run 10

The environment variables are used by polymorph to convert the user commands to client commands according to the list of translations below. The transient-client programmes that implement the client commands do not need to see the environment variables; instead, polymorph feeds the configuration data to the clients on their commands lines.

The datum in TELESCOPE defines the directory in which UltraDAS programmes look for configuration files. The datum in OBSSYS is copied by udas_run into the FITS-header packet observation.
 

User commands, grouped by function

Common features

• All user commands can be run as foreground or background background processes of a shell. Normal rules for Unix processes apply.
• Clients do not prompt for input from the terminal.
• Clients do not write to the command terminal except in two cases:
• Clients write one line of notification to standard error if they exit with bad status.
• A few clients write data to standard output, and this is noted in their descriptions. These clients are intended to be run with their standard output piped into another application.
• Clients return zero in their exit status to indicate success and non-zero to indicate failure. At present, there are no specific codes for types of failures. This may change in the future.
• Command translation and matching of camera names applies as describe above.
• The detailed semantics of the commands are not given in this section. See the definition of the client-command interface, below for the details.

Data-disposal commands

promote [camera-choice] scratch-file-no
translates to
udas_promote camera-name scratch-file-no
and promotes a scratch run to an archivable run.

Readout-format commands

bin [camera-choice] bin-factor bin-factor
translates to
udas_format camera-name "bin" bin-factor bin-factor
and sets the binning factors in x and y.

rspeed [camera-choice] ro-speed
translates to
udas_format camera-name "rspeed" ro-speed
and selects a readout speed.

window [camera-choice] win-no image-section [frame-no]
translates to
udas_format camera-name  "win-set" win-no image-section [frame-no]
and sets one window.

enable_win [camera-choice]
translates to
udas_format camera-name "win-enable"
and enables previously-set windows.

disable_win [camera-choice]
translates to
udas_format camera-name "win-enable"
and disables previously-set windows.

Run commands

arc [camera-choice] exp-time [title]
translates to
udas_run camera-name instrument telescope obssys "1" "arc"  "0" exp-time [title]

bias [camera-choice] [title]
translates to
udas_run camera-name instrument telescope obssys "1" "bias" "0" "0.0" [title]

dark [camera-choice] exp-time [title]
translates to
udas_run camera-name instrument telescope obssys "1" "dark"  "0" exp-time [title]

flash [camera-choice] exp-time [title]
translates to
udas_run camera-name instrument telescope obssys "1" "flash" "0" exp-time [title]

flat [camera-choice] exp-time [title]
translates to
udas_run camera-name instrument telescope obssys "1" "flat" "0" exp-time [title]

run [camera-choice] exp-time [title]
translates to
udas_run camera-name instrument telescope obssys "1" "run"  "0" exp-time [title]

sky [camera-choice] exp-time [title]
translates to
udas_run camera-name instrument telescope obssys "1" "sky" "0" exp-time [title]
 

This is the command to take one observation and save it to a scratch file:

scratch [camera-choice] scratch-file-no exp-time [title]
translates to
udas_run camera-name instrument telescope obssys "1" "scratch" scratch-file-no exp-time [title]
 

This is the command to take and display a glance observation without saving it:

glance [camera-choice] exp-time
translates to
udas_run camera-name instrument telescope obssys "1" "glance"  "0" exp-time
 

These commands do sequences of the basic observation types above:

multarc [camera-choice] n-obs exp-time [title]
translates to
udas_run camera-name instrument telescope obssys n-obs "arc" "0" exp-time [title]

multbias [camera-choice] n-obs [title]
translates to
udas_run camera-name instrument telescope obssys n-obs "bias" "0" "0.0" [title]

multdark [camera-choice] n-obs exp-time [title]
translates to
udas_run camera-name instrument telescope obssys n-obs "dark" "0" "exp-time [title]

multflash [camera-name] n-obs exp-time [title]
translates to
udas_run camera-name instrument telescope obssys n-obs "flash" "0" exp-time [title]

multflat [camera-choice] n-obs exp-time [title]
translates to
udas_run camera-name instrument telescope obssys n-obs "flat" "0" exp-time [title]

multrun [camera-choice] n-obs exp-time [title]
translates to
udas_run camera-name instrument telescope obssys n-obs "run" "0" exp-time [title]

multsky [camera-choice] n-obs exp-time [title]
translates to
udas_run camera-name instrument telescope obssys n-obs "sky" "0" exp-time [title]

multscratch [camera-choice] n-obs scratch-file-no exp-time [title]
translates to
udas_run camera-name instrument telescope obssys n-obs "scratch" scratch-file-no exp-time [title]

multglance [camera-choice] n-obs exp-time [title]
translates to
udas_run camera-name instrument telescope obssys n-obs "glance" "0" exp-time [title]

See the description of udas_run, below, to find the effect of the commands.

Please note that the prefix for the multiple-exposure commands is "mult" with no "i".

Intervention commands

abort [camera-choice]
translates to
udas_intervene camera-name "abort"
and ends the current observation, discarding the data.

finish [camera-choice]
translates to
udas_intervene camera-name "finish"
and ends the current integration, saving the data.

newtime [camera-choice] exp-time
translates to
udas_intervene  camera-choice  "newtime" exp-time
and changes the length of the current integration.

killmult [camera-choice]
translates to
udas_intervene camera-name  "killmult"
and cancels observations in a sequence that have not yet started.

Shutter commands

shutter  [camera-choice] shutter-pos
translates to
udas_shutter camera-name shutter-pos

Monitoring commands

Data definitions

Client commands

udas_detect_obs

Semantics:
Every time the camera releases a FITS file, the client writes the name of the file to standard output. The client does not write out the names of files already released when it starts up.

This client is intended to be run as a sub-process of a data-consuming programme such as a logger or the head of data-reduction pipeline. The output from the client would be piped into the parent programme.

The file-names are those seen by the server programme on the DAS computer. If the computer where the client programme is running has different mount-points for the data disc then the names may not be intelligable.

Output syntax:
For each FITS file released, the client writes one line of output containing only the fully-qualified name of the file.

udas_format

Semantics:
All forms of the command adjust the current readout format on the named camera.

• "bin" sets the x and y binning factors (x comes before y in the command).
• "rspeed" selects one of two named readout speeds. Selecting the speed also sets the gain of the detectors.
• "win-enable" turns on all windows previously set with "win-set".
• "win-disable" turns off all windows; the camera remembers where they were and the windows can be turned back on later.
• "win-set" sets the size and position of one window and enables all windows.

The command only works when the camera is idle. If the camera is doing a run, format commands are rejected without prejudicing that run. When a format command is accepted, it completes "immediately" and the new format applies to all subsequent observations.
 

udas_intervene

Semantics:
All forms of the command affect the course of the current observation or sequence of observations.

• "abort" stops the observation "immediately" (within five seconds), whatever the camera is doing. The current run is lost: its data are thrown away and the run number is never reused. Aborting a sequence of observations cancels the observations that haven't started yet.
• "finish" changes the demanded integration time to the time already integrated such that the integration finishes immediately. The run reads out and is saved normally. If a sequence of observations is underway, the sequence continues from the start of the next observation.
• "killmult"cancels observations in a sequence that haven't started yet. It has no effect on the current observation.
• "newtime" changes the demanded integration-time of the current observation; it does not change the time of other observations in a sequence. If an integration is retimed to a shorter time than has already been integrated, then it ends immediately. The observation reads out and is saved normally.

udas_monitor

Semantics:
This command sets up a monitor on one or more DRAMA parameters of a camera server. The current values of the parameters, and the new value each time a parameter changes, are written to standard output. If the parameter is an array or structure, each scalar element of the array is written out as one line of output. If the array or structure members are not scalars, they are decomposed in the same way.

The command is normally run as a sub-process of a mimic programme with the mimic reading the client's output through a pipe.

Output syntax:
Each line has the format:
set parameter-name parameter-value

That is, udas_monitor writes out Tcl! The parameter name for a structure element is the structure name and the element name joined by an underscore. For example: Filter_details_waveband. The parameter name for an array element is the array name and the indices joined by underscores. For example: Transformation_matrix_0_1.
 

udas_keep

Semantics:
The command promotes the last observation from a glance to an archived run and saves it to disc with the given title. If the scratch-file number is positive, the command promotes the scratch file to an archived run; in this case the title is not used because the scratch run already has a title.

Keeping a glance fails if the camera is not idle at the time of the command. Keeping an observation that was not a glance saves an extra copy of the observation to disc as an archivable run. The command completes when the data have been sent to disc, which make take up to 30 seconds for a large camera.

udas_promote

Semantics:
The command promotes the scratch file with the given number to an archived run.

Scratch files can be promoted while the camera is busy with another run. Promotion should complete within one second.

Promoting a scratch file is allowed while another observation is in progress. This form of the command completes immdiately.

udas_run

Semantics:
N-obs observations are made in sequence with the same parameters.

The handling of the integration varies according to the observation type and the demanded integration-time.

• If the observation type is given as "bias", the camera does a zero-second dark frame without preflash.
• If the observation type is given as "flash", the camera does a zero-second dark frame with preflash.
• If the observation type is given as "dark", the camera does a timed dark-frame with preflash.
• If the observation type is something else, but exp-time is less than 10^-6s, the camera behaves as if the observation type has been "bias". (This allows for the traditional usage of "run 0" to get a bias frame.)
• Otherwise, the camera does a timed exposure with preflash.

If the observation type is "glance", the camera reads the observation into memory but does not release it in a FITS file. Otherwise, the camera releases the observation in an archiveable FITS file.

The command fails if it is given when the camera is not idle.

For most cameras, the run commands complete only after the data have been saved to disk (excepting glance runs). For some very large cameras, the data-saving time would be excessive: for these cameras, the data are saved to disk as a background process in parallel with the next observation.
 

udas_shutter

Semantics:
The shutter is moved to the named position and left there.

This command fails if given when the camera is not idle. In particular, it cannot be used during an run. If the command is accepted, it returns when the shutter has completed its movement.