PFIS Detector Package Software Specification and Design Document 44

Southern Africa Large Telescope

Prime Focus Imaging Spectrograph

SAAO Detector Subsystem:

SALT-3199AS0001: Software Specification

And Design Document

SAAO PFIS Detector Subsystem Team:

Dave Carter

Luis Balona

Geoff Evans

Willie Koorts

James O’Connor

Darragh O’Donoghue

Faranah Osman

Hendrik Steyn

Issue 1.3

25 June 2003

Issue History

Number And File Name / Person / Issue / Date / Change History
SALT-3199AS0001 Software Issue 1.1.doc / 1.1 / 11 Feb 2003 / PFIS CDR version
SALT-3199AS0001 Software Issue 1.2.doc / 1.2 / 19 Mar 2003 / Post-PFIS CDR version from discussions at Wisconsin
SALT-3199AS0002 Software Specification and Design Issue 1.3.doc / 1.3 / 25 Jun 2003 / Design phase: split of CDR software doc into development plan document and software specification and design document. Both are designated to be Issue 1.3.

TABLE OF CONTENTS

1 Scope 5

2 Referenced Documents 6

3 Customer Furnished Equipment and Responsibilities 6

4 Software Specification 8

4.1 The Concept of Procedures 8

5 Functional Requirements: PDET CON 10

5.1 Procedure Initiation/Termination/Aborting 10

5.2 Image Display and Interaction 10

5.3 Data Storage 10

5.4 Peak-Up and Fabry-Perot Operation 10

5.5 Communication With Precision Time Source 10

5.6 Communication With PDET KER 10

5.7 Communication With PDET PCI 11

5.8 Communication With PDET SDSU 11

5.9 Communication With The Science Database 11

6 Functional Requirements: PDET KER 12

6.1 Communication With PDET MMI 12

6.2 Communication With PCONDI 12

6.3 Communication With The TCS 13

6.4 Communication With PDET CON 13

7 Functional Requirements: PDET MMI 15

8 Functional Requirements: PDET SDSU (including PCI and Subsystem Controller) 16

8.1 The SDSU-PCI : 16

8.2 The SDSU Controller: 16

8.3 The Subsystems Controller: 16

9 Technical Requirements 18

9.1 Software Architecture 18

9.2 Software Interfaces 18

9.3 Modes, States and Events 19

9.4 Software Capabilities 22

9.4.1 Communication 22

9.4.2 Initialisation 22

9.4.3 Command Interpretation and Generation 22

9.4.4 Status Reporting 22

9.5 Operating System 22

9.6 Resource Allocation 22

10 Generic Software Requirements 23

11 Software Testing 24

11.1 Verification cross-reference matrix 24

11.2 Detailed Test Requirements 25

11.2.1 Interface Test 25

11.2.2 Initialisation 25

11.2.3 Command Interpretation and Generation 25

11.2.4 Status Reporting 25

12 Software Design: PDET KER & PDET CON 26

12.1 Mode Command Vocabulary 26

12.2 Top Level Status 28

12.3 PROCEDURE Mode: Sub-Commands and Sub-Status 28

12.3.1 Activity On Entering PROCEDURE Mode 30

12.3.2 Activity On Starting An Exposure 30

12.3.3 Definition of Windows 32

12.3.4 Definition of Procedures 33

12.3.5 Target Information 36

12.3.6 PFIS Configuration Information 36

12.3.7 Pointing Information 37

12.3.8 Disk File Names 37

12.3.9 Status of Procedure Execution 37

12.4 READY Mode: Sub-Commands and Sub-Status 38

12.5 Detector Package Hardware Status 39

12.6 Sub-Commands and Sub-Status in INITIAL Mode 40

12.6.1 Initialization Operations: PDET CON: 40

12.6.2 Initialization Operations: PDET KER: 41

12.7 Image Interaction By PDET CON 41

12.7.1 Image Marks, Boxes, Slits, Overlays etc. 42

12.8 Code Structure of PDET KER: (SALTICAM VERSION) 45

12.9 Code Structure of PDET CON (SALTICAM VERSION) 46

12.10 Data Clusters/Structures, Software ICD 47

12.11 Named-Pipe Communications Between PDET KER and PDET CON 48

13 Software Design: PDET MMI 50

13.1 PDET MMI: Mode Commands and Status 50

13.2 PDET MMI: PROCEDURE/INITIAL Mode Sub-Commands and Sub-Status 50

13.3 PDET MMI: Front Panel 50

14 Software Design: PDET SDSU (SALTICAM Version) 52

14.1 Code Modules 52

14.2 SDSU-PCI: 52

14.3 SDSU Controller: 53

14.4 Code Structure 57

14.5 Subsystem Controller 57

15 Appendix A: List of FITS Keywords and Information (SALTICAM Version) 58

16 Appendix B: List of Error Messages 59

17 Appendix C: List of Descriptors For Named Pipe Communications (SALTICAM Version) 60


ACRONYMS AND ABBREVIATIONS

ATP / Acceptance Test Procedure
ATR / Acceptance Test Report
BITE / Built-in Test Equipment
CDR / Critical Design Review
COTS / Commercial off the shelf
ELS / Event Logger Software
HET / Hobby-Eberly Telescope
I/O / Input/Output (Device)
ICD / Interface Control Dossier
MMI / Man-Machine Interface
MTBF / Mean Time Between Failures
MTTR / Mean Time to Repair
OEM / Original Equipment Manufacturer
OPT / Operational Planning Tool
PC / Personal Computer
PDR / Preliminary Design Review
PFIS / Prime Focus Imaging Spectrograph
PI / Principal Investigator (Astronomer)
PIPT / PI Planning Tool
PLC / Proceduremable-Logic Controller
SA / SALT Astronomer
SALT / Southern African Large Telescope
SAMMI / SA Machine Interface
SC / Software Component (e.g. part of the TCSS)
SDB / Science Database
SD / Software Design
SDP / Software Development Plan
SI / Software Item (the TCSS is a Software Item) OR
SO / SALT Operator
SOMMI / SO Machine Interface
SRS / Software Requirement Specification
STARCAT / Object Catalogue
SW / Software
TBC / To Be Confirmed
TBD / To Be Determined
TCS / Telescope Control System
TCSS / TCS Server
VI / Virtual Instrument (Labview function) OR

1  Scope

The PFIS detector package is being supplied to the University of Wisconsin by the SAAO. This document specifies both the requirements and the design for the software for the detector package.

According to 3199AS0001 Software Development Plan Issue 1.3, the software to be developed comprises:

a.  PFIS Control PC (hereafter called PCON)

·  PCON Control Procedure Software.

·  PCON Detector Interface (designated PCONDI) Software. This is the main interface to the PDET.

·  Labview Data Socket (part of the standard Labview Application)

b.  PFIS Detector PC (hereafter called PDET)

·  PDET Kernel Software (designated PDET KER). This will interact with the PCONDI residing in the PCON machine. PDET KER will also interact with PDET MMI and PDET CON as described below.

·  PDET MMI Software (designated PDET MMI). This is the interface to PDET for development and maintenance via the PDET PC keyboard. It will be similar to PCONDI, the difference being that the former exerts control via an MMI, the latter through commands from the PCON computer.

·  PDET Control Software (designated PDET CON). This is software that will receive instructions from PDET KER, and control all the detector hardware.

·  PDET PCI Card Software (designated PDET PCI). This is software that is supplied by Astronomical Research Cameras with their SDSU II/III CCD controllers.

·  PDET SDSU II/III Control Software (designated PDET SDSU), including the software in the subsytem controller. This is software that is initially supplied by Astronomical Research Cameras with their SDSU II/III CCD controllers. The supplied software will be used as a prototype for an SAAO developed equivalent, tailored for the PDET application.

·  This machine will contain no other applications.

In addition, the PDET software will interact with these machines forming part of the SALT TCS. Their main applications software units are also indicated:

c.  Data Processor

·  Science database. This is the organised storage and retrieval of all instrument configuration, calibration, science and telescope data pertaining to science observations made.

d.  Data Reduction PC

·  PDET Data reduction pipeline (designated PDET DRED).

e.  TCS Server

·  SALT TCS Server application

·  Labview Data Socket (part of the standard Labview Application)

SAAO is therefore responsible for providing:

·  PDET KER

·  PDET MMI

·  PDET CON

·  PDET PCI

·  PDET SDSU

·  PDET DRED

U of Wisconsin at Madison is responsible for providing PCONDI.

2  Referenced Documents

The following documents are referenced in this specification and are applicable to the extent specified herein.

1000AA0030 / SALT Safety Analysis
1000AB0044 / SALT Labview Coding Standard
1000AD0005 / SALT Computer Architecture
1000AS0040 / SALT Operational Requirements
1700AS0001 / TCS Specification
1000AS0049 / SALT Data Interface Control Dossier
3199AS0001 / Software Development Plan

3  Customer Furnished Equipment and Responsibilities

N/A

Figure 1. PDET Modules From The Software Perspective

4  Software Specification

PDET will have its own fully functioning MMI, which may be used not only to enable the human operator to control the detector, but also for development and maintenance purposes. In normal operation, control shall be via PCONDI. PCONDI, which stands for PCON Detector Interface, is the component of the top level LabVIEW PFIS Control Software which interacts with the detector package. PCONDI is the responsibility of the University of Wisconsin.

The relationships of these software items to each other are shown in Fig. 1. The main purpose of the software suite is to:

·  Enable PCONDI/PDET MMI to control the PDET hardware to obtain images/spectra arriving at the PFIS focal plane.

·  Display the data on the PDET PC monitor near the SA. The software should provide control of this display, as well as interact with it (placement of markers etc.).

·  Manage the storage of science images on the PDET PC disc in FITS format.

·  Use the virtual mouse to execute simple algorithms to make quantitative measurements on the displayed image.

·  Interact with the TCSS to obtain telescope status information.

·  Monitor the safety of the detector, preventing unsafe or inappropriate operation.

4.1  The Concept of Procedures

The concept of a “Procedure” is an important one for control of the PFIS detector package. The name Procedure is used to distinguish it from the “Programs” used on SALTICAM instrument control; the concept is similar, but not identical, so distinct names are required.

PFIS is capable of imaging but it is also capable of spectroscopy in which data appears as one or more strips of light on the detector. Nevertheless, whatever the meaning of the data, the detector package records whatever the PFIS camera images. So for the purpose of this discussion, we shall refer to all PFIS data as images, even if the images are, in fact, spectra.

Images can only be obtained in “Procedure” mode. The sequence of operations to be carried out in the acquisition of images will be predefined in specific “Procedures”. Procedures will be subsets of, or associated with, PFIS scripts which control the entire instrument (all the mechanisms and not just the detector package). This discussion just focuses on Procedures.

·  As an example, a multi-object spectroscopy Procedure would entail imaging several spectra of several objects through a slit mask, resulting in one readout of the detector.

·  As another example, a sequence of images through 3 different filters with different exposure times etc. can be defined, resulting in multiple readouts.

·  Another example might involve a sequence of spectra of the same object taken at high time resolution. Such an image will require multiple, windowed readouts.

·  Another example involves polarimetry in which shuffling of the image up or down the columns of the CCD, along with movement of the polarimetric waveplates, is required.

·  A final example involves nod and shuffle, in which shuffling of the image up or down the columns of the CCD, along with movement of the telescope, is required.

Other “Procedures” could be defined for obtaining bias images, dark images, or other calibrations.

In this manner, flexibility of operation as well as ease of routine use are assured. This catering for “opposite ends of the operational spectrum” is sufficiently important that it assumes the position of a requirement of the software, as opposed to a design feature.

The Procedures will be managed by the controlling entity (either PDET MMI or PCONDI) and will be transmitted to the PFIS Detector Computer just before data acquisition begins.

A Procedure will comprise the following information:

  1. Whether or not the shutter should be open during the execution.
  2. Whether or not the acquired images should be written to disk.
  3. The row prebin factor.
  4. The column prebin factor.
  5. The readout speed.
  6. The gain used in conversion from measured electrons to analog to digital units (ADUs).
  7. The number of times to repeat the sequence.
  8. Whether or not shuffle operations are required
  9. The number of different exposures in a sequence of shuffles (1 if no shuffling is required).
  10. For each exposure in the shuffle sequence: the exposure time.
  11. For each shuffle in the shuffle sequence: the number of rows to shuffle up or down.
  12. The number of windows on the detector.
  13. For each window, a definition of the window position and size.
  14. Science Observation ID.
  15. Path to the data file storage on the Data Processor PC.

5  Functional Requirements: PDET CON

PDET CON will be the “central control room” of the detector package. For this reason, we consider its functional requirements first.

5.1  Procedure Initiation/Termination/Aborting

After receiving instructions from PDET KER to do so, PDET CON will initiate the start of the next Procedure or abort the currently executing Procedure.

5.2  Image Display and Interaction

PDET CON will display images obtained by the detector with adequate resolution on a large monitor in the SALT Control Room. This monitor will be the PDET PC Monitor (as indicated in Fig. 1). Control of brightness and contrast shall be part of the display algorithms.

PDET CON will also manage interaction with the displayed image to place marks/boxes/windows on the display, select objects on the display, overlay templates or wavelength scales on the display etc. The nature of what is displayed will be controlled by PCONDI. Status return is via the appearance of the display.

The following simple image processing algorithms are also required:

i.  Extraction of spectra.

ii.  A read out of pixel position, RA and Dec of a mouse-type pointer.

iii.  Fitting of Gaussian functions to point sources.

iv.  2-d line plots of image brightness in any direction across the image.

v.  Simple aperture photometry to estimate magnitudes of point source objects.

vi.  Simple image processing functions such as background subtraction, smoothing or median filtering.

Results of these operations will be reported either directly to PDET KER or via the PDET PC display.

The user input to the interaction with the image will take place using the PDET PC (virtual) mouse.

5.3  Data Storage

PDET CON will also control and manage data storage (in FITS format) on the PDET PC’s disk. (It is necessary that PDET CON carry out this task as opposed to PDET KER/PDET MMI/PCONDI as in very high speed mode, minimum latency is required).