Template for Design Description

EUROPEAN SOUTHERN OBSERVATORY

Organisation Européenne pour des Recherches Astronomiques dans l'Hémisphère Austral

Europäische Organisation für astronomische Forschung in der südlichen Hemisphäre

VLT PROGRAMME

VERY LARGE TELESCOPE

VLT Software

---

VLT Instrumentation Software

Template for Design Description

Doc. No.: VLT-SPE-ESO-17240-3223

Issue: 1

Date: 30/09/2005

Prepared: A.Longinotti 30/09/2005

Name Date Signature

Approved: K.Wirenstrand

Name Date Signature

Released: M.Cullum

Name Date Signature

VLT PROGRAMME * TELEPHONE: (089) 3 20 06-0 * FAX: (089) 3 20 06 514

CHANGE RECORD

ISSUE	DATE	SECTION/PAGE AFFECTED	REASON/INITIATION DOCUMENTS/REMARKS
1/draft 1	31/08/2005	All	First draft for review
1	30/09/2005	All	First issue after incorporating reviewers comments

TABLE OF CONTENTS 3

1 INTRODUCTION 6

1.1 Purpose 6

1.2 Scope 6

1.3 Applicable Documents 6

1.4 Reference Documents 6

1.5 Abbreviations and Acronyms 7

1.6 Glossary 8

1.7 Stylistic Conventions 9

1.8 Naming Conventions 9

1.9 Problem Reporting/Change Request 9

1.10 Graphical notation 9

2 OVERVIEW 11

3 ARCHITECTURE 12

3.1 Instrument ID and prefix 12

3.2 Hardware architecture 12

3.2.1 Instrument LAN 12

3.3 Software architecture 13

3.3.1 INS environments 14

3.3.2 INS users 14

4 INSTRUMENT CONTROL SOFTWARE (ICS) 16

4.1 Devices 16

4.1.1 Special devices 18

4.1.2 Cryogenics 18

4.1.3 Backlash compensation 18

4.1.4 Interlocks 18

4.1.5 Parallelism 18

4.1.6 States 18

4.2 ICS LCU part 18

4.2.1 Architecture 18

4.2.2 Lakeshore special device 19

4.3 ICS WS part 20

4.3.1 Architecture 20

4.3.2 Special classes 20

4.3.3 Assemblies 21

4.3.4 Interfaces 21

4.3.5 Alarms 21

4.4 Configuration 21

4.5 Dictionaries 22

4.6 Test Software 22

4.7 Standards 22

4.8 Modules 22

5 DETECTOR CONTROL SOFTWARE (DCS) 24

5.1 Architecture 24

5.1.1 States 24

5.1.2 Logging 24

5.1.3 Failure Mode Operation 24

5.1.4 Simulation 24

5.2 Interfaces 24

5.3 Data 25

5.3.1 Acquisition 25

5.3.2 Processing 25

5.3.3 FITS file 25

5.3.4 Display 25

5.4 Configuration 25

5.5 Test Software 25

5.6 Standards 25

5.7 Modules 25

6 OBSERVATION SOFTWARE (OS) 26

6.1 Architecture 26

6.2 Processes 27

6.2.1 OS Server 27

6.2.2 OS Archiver 31

6.2.3 Slit viewer server 31

6.3 Configuration 33

6.4 Dictionaries 33

6.5 Dictionaries 33

6.6 Templates 33

6.6.1 Templates library 34

6.6.2 Instrument package 34

6.7 Test Software 34

6.8 Standards 34

6.9 Modules 34

7 MAINTENANCE SOFTWARE (MS) 35

7.1 Configuration 35

7.2 Templates 35

7.2.1 Instrument technical package 36

7.3 Test Software 36

7.4 Standards 36

7.5 Modules 36

8 OBSERVER SUPPORT SOFTWARE (OSS) 37

8.1 Standards 37

8.2 Modules 37

9 SYSTEM ATTRIBUTES 38

9.1 Installation 38

9.2 Startup/Shutdown 38

9.3 Performance 38

9.3.1 Initialization and setup 38

9.3.2 Data rates 38

9.3.3 Data processing 38

9.3.4 Real-Time Display 38

9.3.5 DCS Synchronization 38

9.3.6 Exposure life cycle 39

9.4 User Station 39

9.5 Security 39

9.6 Availability 39

9.7 Maintainability 39

9.8 Documentation 39

9.9 Adaptability and enhancement potential 39

9.10 Training 40

10 DEVELOPMENT AND TEST FACTORS 41

10.1 Project Control 41

10.2 Test 41

11 REFERENCE 42

11.1 ICS 42

11.1.1 Lakeshore special device server 42

11.1.2 Lakeshore special device monitoring task 42

11.1.3 Lakeshore special device operational logs 42

11.1.4 ICS WS Server 42

11.1.5 ICS WS special classes 42

11.1.6 Assemblies 42

11.1.7 Alarms 42

11.1.8 FITS header 42

11.1.9 Configuration 43

11.2 DCS 43

11.2.1 DCS Server 43

11.2.2 DCS keywords 43

11.2.3 On-line database 43

11.2.4 FITS header 43

11.3 OS 43

11.3.1 OS Server special classes 43

11.3.2 OS Secondary Guiding Server 43

11.3.3 Modes 43

11.4 MS 44

11.5 OSS 44

12 Traceability matrix 45

1 INTRODUCTION

This document aims to provide Instrument Software Engineers with a template of the Instrument Software Design Description (ISDD) document. Instrument specific ISDD documents should be based on this template. They should contain at least the structure and information described herein (whenever applicable), and possibly add instrument specific parts.

In the present document, XXXX is used to indicate the name of a generic instrument. Its characteristics (devices, detectors, performances etc) are used just as example and do not correspond to any existing or planned VLT/VLTI Instrument

Examples appearing in this document are taken from existing ISDD documents.

Paragraphs in italics should be removed or adapted to the specific instrument.

1.1 Purpose

The purpose of this document is to describe the design of the XXXX Control Software. They are the result of the Instrument Software Detailed Design study.

This document logically follows the Instrument Software Functional Specification (ISFS, see [AD 12]) and shall be applicable to the implementation of the Software.

In order to trace more easily all design solutions, all major points described here have a numbered tag: [ISDDnn].

This document shall be reviewed at the Final Design Review (FDR). It shall be part of the FDR data package. In case of exceptional changes to the requirements after PDR, once the change request has been approved by ESO, the ISURS, ISFS and this document shall be updated accordingly.

1.2 Scope

This document is supposed to be used as template for the ISDD of any instrument based on the VLT common sw. It is therefore applicable also to VLTI Instruments..

This document defines the detailed Design Description of the XXXX Control Software only. The design of other parts of the VLT data flow, such as the pipeline, is outside its scope.

1.3 Applicable Documents

The following documents, of the exact issue shown, form a part of this document to the extent specified herein. In the event of conflict between the documents referenced herein and the contents of this document, the contents of this document shall be considered as a superseding requirement.

Reference	Document Number	Issue	Date	Title
[AD 01]	VLT-SPE-ESO-xxxxx-xxxx	1	xx/xx/xxxx	XXXX Technical Specification
[AD 02]	VLT-SPE-ESO-17212-0001	4	13/01/2005	Instrumentation Software Specification
[AD 03]	VLT-SPE-ESO-17240-0385	4	13/01/2005	INS Common Software Specification
[AD 04]	VLT-SPE-ESO-10000-2723	1	18/03/2005	VLT Requirements for Scientific Instruments
[AD 05]	VLT-PRO-ESO-10000-0228	1.0	10/03/1993	VLT Software Programming Standards
[AD 06]	VLT-SPE-ESO-xxxxx-xxxx	1	xx/xx/xxxx	XXXX Control Electronics Specification
[AD 07]	VLT-ICD-ESO-17240-19200	1.3	07/06/2000	ICD between VCS and OH
[AD 08]	VLT-ICD-ESO-17240-19400	2.6	17/11/1997	ICD between VCS and Archive
[AD 09]	VLT-PLA-ESO-10000-0441	1.0	01/05/1995	VLT Science Operation Plan
[AD 10]	GEN-SPE-ESO-19400-0794	3	01/02/2005	Data Interface Control Document
[AD 11]	VLT-SPE-ESO-xxxx-xxxx	1	xx/xx/xxxx	XXXX Control Software User Requirements
[AD 12]	VLT-SPE-ESO-xxxx-xxxx	1	xx/xx/xxxx	XXXX Control Software Functional Specification

1.4 Reference Documents

The following documents are referenced in this document.

Reference	Document Number	Issue	Date	Title
[RD 01]	VLT-MAN-ESO-17200-0888	1.0	17/08/1995	VLT Common Software Overview
[RD 02]	VLT-MAN-ESO-17200-0642	4	29/04/2004	VLT Common Software Installation Manual
[RD 03]	VLT-MAN-ESO-17230-0942	2	22/03/2002	TCS User Manual
[RD 04]	VLT-PLA-ESO-17240-2266	5	13/01/2005	INS Acceptance Test Plan Template Document
[RD 05]	VLT-MAN-ESO-17200-0981	2	16/10/1998	VLT Problem Report Change request User Man.
[RD 06]	G. Booch, I. Jacobson, J. Rumbaugh		10/1998	The Unified Modelling Language User Guide
[RD 07]	VLT-MAN-ESO-17240-0934	5	31/03/2004	INS Common sw - Base ICS User Manual
[RD 08]	VLT-MAN-ESO-17240-2240	4	31/03/2004	INS Common sw for Templates User Manual
[RD 09]	VLT-MAN-ESO-13640-1388	3	31/03/2004	FIERA Control Software User Manual
[RD 10]	VLT-MAN-ESO-17240-2265	4	05/04/2004	INS Common sw - Base OS Stub User Manual
[RD 11]	VLT-MAN-ESO-17220-1332	4	19/04/2004	HOS/Broker for Observation Blocks User Manual
[RD 12]	VLT-MAN-ESO-17240-1973	5	13/01/2005	Template Instrument User and Maint.Manual
[RD 13]	VLT-PLA-ESO-xxxx-xxxx	1	xx/xx/xxxx	XXXX Software Management Plan
[RD 14]	VLT-MAN-ESO-17210-0619	2.4	31/03/2004	Central Control Software User Manual
[RD 15]	VLT-MAN-ESO-14100-1878	1.4	01/12/2003	IRACE-DCS User Manual

1.5 Abbreviations and Acronyms

The contents of this section must be adapted to contain only the abbreviations and acronyms actually used within the document.

This document employs several abbreviations and acronyms to refer concisely to an item, after it has been introduced. The following list is aimed to help the reader in recalling the extended meaning of each short expression:

ADC	Analogue to Digital Converter
AIV	Assembly, Integration and Verification
API	Application Programmatic Interface
ATM	Asynchronous Transfer Mode
ATP	Acceptance Test Plan
BOB	Broker for Observation Blocks
CCD	Charge Coupled Device
CCS	Central Control Software
CDT	Commands Definition Table
CPU	Central Processing Unit
DCS	Detector Control Software
DFE	Detector Front-End Electronics
DICB	ESO Data Interface Control Board
DMA	Direct Memory Access
DRS	Data Reduction Software
DSP	Digital Signal Processor
FDR	Final Design Review
FITS	Flexible Image Transport Format
FWHM	Full Width Half Maximum
GUI	Graphical User Interface
HW	Hardware
HOS	High Level Operating Software
ICS	Instrument Control Software
IEE	Institution of Electrical Engineers (UK)
IEEE	Institute of Electrical and Electronics Engineers (USA)
INS	Instrumentation Software
I/O	Input/output
IR	Infra-Red
ISDD	Instrument Software Design Description
ISFS	Instrument Software Functional Specification
ISURS	Instrument Software User Requirements Specification
ISUMM	Instrument Software User and Maintenance Manual
IWS	Instrument Workstation
KRPM	Kilo (i.e. Thousand) Revolutions Per Minute
LAN	Local Area Network
LCC	LCU Common Software
LCU	Local Control Unit
MIDAS	ESO-Munich Image Data Analysis System, ESO-MIDAS ^TM
MS	Maintenance Software
MTBF	Mean Time Between Failures
MTBS	Mean Time Between Service
N/A	Not Applicable
OB	Observation Block
OBD	Observation Block descriptor
OLAS	On-Line Archive Subsystem
OLDB	On-Line DataBase
OMT	Object Modeling Technique
OO	Object Oriented
OS	Observation Software
OSS	Observer Support Software
PAE	Preliminary Acceptance Europe
PAF	Parameters File
PDR	Preliminary Design Review
QE	Quantum Efficiency
RAM	Random Access Memory
SNR	Signal to Noise Ratio
SOS	Supervisory Observation Software
STRAP	System for Tip-tilt Removal with Avalanche Photodiodes
SW	Software
TBC	To Be Clarified
TBD	To Be Defined
TCCD	Technical CCD
TCS	Telescope Control Software
TIM	Time Interface Module
TRS	Time Reference System
TSF	Template Signature File
UIF	(Portable) User Interface (Toolkit)
UNIX	Trademark of Bell Laboratories (operating system)
UV	Ultra-Violet
VCSOLAC	VLT Control Software On-Line Archive Client
VLT	Very Large Telescope
VME	Versa Module Eurocard
VOLAC	VLT On-Line Archive Client
WS	Workstation

1.6 Glossary

The following is defined in [AD 02]:

Ø Exposure

Ø Integration

Ø Instrument Mode

Ø Instrument Workstation

The following is defined in [AD 07]:

Ø Observation Block

Ø Template

Ø Template Signature File

The following is defined in [AD 03]:

Ø Setup file

Ø Short Hierarchical Format

The following is defined in [AD 11]:

Ø User

The following is defined in [RD 07]:

Ø Assembly

1.7 Stylistic Conventions

The following styles are used:

bold

in the text, for commands, filenames, pre/suffixes as they have to be typed.

italic

in the text, for parts that have to be substituted with the real content before typing.

teletype

for examples.

<name>

in the examples, for parts that have to be substituted with the real content before typing.

bold and italic are also used to highlight words.

1.8 Naming Conventions

This implementation follows the naming conventions as outlined in [AD 03].

1.9 Problem Reporting/Change Request

The form described in [RD 05] shall be used.

1.10 Graphical notation

The contents of this section must be adapted to contain the notation actually used within the ISDD document.

The following graphical notation is used (see [RD 06]):

Asynchronous message

A form of communication in which a producer task sends a message to a consumer task and does not wait for a response; a message queue could potentially build up between the tasks. Also referred to as “loosely coupled message communication”.

Dependency

Show which component and/or package communicates and/or depends with/on another one.

Package

A group of modelling elements.

Component

An active self-contained object with a well-defined interface.

Interface

The external specification of a class, task or component.

Actor

Shows an outside user or related set of users who interact with the system.

Node

In a distributed environment, each node consist of one or more processors with shared memory.

Object

An instance of a class that contains both hidden data and operations on that data.

Use Case Realization

A use case realization is a graphic sequence of events, also referred to as a scenario or an instance of a use case. These realizations or scenarios are depicted in either a sequence or collaboration diagram.

2 OVERVIEW

This document tries to associate, whenever possible, every design aspect to one of the standard instrumentation modules (ICS, DCS, OS, OSS and MS). This approach is a consequence of the fact that in most of the instrumentation projects the software part is developed at several sites, and the repartition of responsibility among partners is based on the instrumentation modules (e.g. partner A is responsible for ICS, B for DCS, C for OS, OSS and MS). The risk of such approach however is that system and integration aspects do not get the necessary attention. For this reason, separate chapters are dedicated to system aspects and to the overall project organization.

Chapter 3 describes the instrument hardware and software architecture

Chapter 4 describes the design of the ICS module

Chapter 5 describes the design of the DCS module

Chapter 6 describes the design of the OS module

Chapter 7 describes the design of the MS module

Chapter 8 describes the design of the OSS module

Chapter 9 describes aspects related to the design of the whole instrument

Chapter 10 describes aspects about the project organization

3 ARCHITECTURE

3.1 Instrument ID and prefix

The instrument ID will be XXXX. The instrument prefix will be xx. [ISDD01]

3.2 Hardware architecture

Figure 1 gives an overview of the instrument hardware architecture.

Following the VLT standard system architecture, the instrument hardware will be located in the Telescope Area.

As from [AD 06], the instrument devices will be controlled from two LCUs.

The two scientific detectors are controlled by two dedicated Detector LCUs (Ultra-Sparc Workstations).

Note: in future projects the Detector LCU will probably consist of a Linux box.

Control and data information is transferred over the Instrument LAN between the Instrument Workstation and the Instrument and Detectors LCUs.

The Instrument Workstation (IWS) is located in the Computer Room in the Control Building. The typical amount of data produced and stored on disk during an observing night is xx GB and the maximum amount is xx GB. The IWS will be equipped with two hard disks of xx GB working at 7,2 Krpm, one reserved for the acquired data (INS_ROOT) and one for the rest (operating system, VLTROOT, INTROOT, VLTDATA etc.) [ISDD46].

Only the LCU controlling the image derotator device will be equipped with a TIM board and connected to the Time Reference System. The other LCUs have no time critical synchronization requirements and will therefore not be equipped with a TIM board. [ISDD02]

The two screens of the User Station console will be used: one for control and status display and the other one for real-time image display (see 9.3).

3.2.1 Instrument LAN

The Instrument LCUs have a normal Ethernet connection to the Instrument LAN.

The two scientific detectors LCUs, as well as the Instrument WS, have a large bandwidth ATM connection to the Instrument LAN.

Note: in future projects the large bandwidth connection will be probably based on Gigabit Ethernet.

The name of the nodes will be [ISDD03]:

wxxxx for the Instrument Workstation
lxxics1 for the first instrument LCU
lxxics2 for the second instrument LCU
wxxdir for the infra-red science detector LCU
wxxduv for the ultra-violet science detector LCU

Figure 1 Hardware architecture

3.3 Software architecture

Figure 2 shows the architecture of the instrument software and the data flow between its components [ISDD64].

The instrumentation software is subdivided in the standard INS modules (see [AD 02]) ICS, DCS, OS, MS, OSS [ISDD04].

Observation Blocks (OBs) are normally prepared by the observing team at the home institute well before the observing night, using the Phase 2 Proposal Preparation (P2PP) Tool.

During visitor observing runs, the next OB to be executed is loaded in the P2PP Tool on the Observation Handling WS[1]. It is then retrieved by the Broker for Observation Blocks (BOB) Tool on the Instrument WS.

BOB reads the contents of the OB and executes one by one the templates specified in there. Each template consists in general of a sequence of commands to be sent to the Observation Software (OS) Server. OS Server translates the incoming commands into further commands to be sent to the Detector Control Software (DCS), Instrument Control Software (ICS) and Telescope Control Software (TCS). DCS, ICS and TCS then take care of instructing the respective LCUs of all actions they should take with the connected hardware.

A typical science OB consists of one acquisition template and one or more science templates. In the acquisition template, the instrument and telescope are setup to acquire the object to be observed. Especially for spectrographs, which normally require the object to be centered in a slit, interactions with the Real Time Display (RTD) play an important role. A simple science template consists of one or more science exposures on the acquired object. The typical simple sequence of commands sent to OS by science observation templates to execute an exposure is:

SETUP (one or more)
START (exposure)
WAIT (till exposure finished)

As a result of an exposure, the related DCS generates detector data, displays them on the Real Time Display (RTD) GUI and saves them in a FITS file. The OS process responsible for archiving data takes care of merging into that file the information, coming from the other sub-systems (TCS and ICS), related to the same exposure. It then informs the standard VLT On-Line Archive (VOLAC) process that a new file is ready to be archived. In turn, VOLAC passes this information to the standard VCSOLAC process, which finally transfers the file to the On-Line Archive Subsystem (OLAS) on the Data Handling Server (DHS).

3.3.1 INS environments

The environments used by the instrumentation software are [ISDD06]:

wxxxx on the Instrument Workstation. Type CCS-lite
lxxics1 on the first instrument LCU
lxxics2 on the second instrument LCU
wxxduv on the UV science detector LCU. Type CCS-lite

The IR science detector LCU Software runs under no-CCS and therefore does not need any CCS environment.

3.3.2 INS users

Two UNIX users will be dedicated to this instrument [ISDD07]:

xxxxmgr, responsible for building and installing the Software
xxxx, responsible for starting/stopping and running the INS environments and the INS Software

Figure 2 Software architecture

4 INSTRUMENT CONTROL SOFTWARE (ICS)

This Chapter describes the design of the ICS package. Depending on its size, or for any other reasons, it might be convenient to place it in a separate dedicated document. In such case, this chapter is replaced by a simple reference to the separate document.

Some instruments may have multiple ICS, e.g. one normal ICS and one or more special ones, e.g. STRAP or AO RTC. In such cases, there will be one chapter (or document) for each ICS.

One single ICS controls all devices, except the detectors [ISDD13].

It consists of one part, which runs on LCU(s) and one part, which runs on the IWS.

The LCU part is responsible for the interface to the devices hardware and the low-level control. No real-time functionality is required.

The WS part is responsible for the coordination between LCUs and for the API to OS.

Both WS and LCU part will be based on the VLT standard icb package [ISDD28].

ICS provides also engineering GUI(s) based on the VLT standard icbpan package.

4.1 Devices

The following tables describes the devices seen by the control electronics and related software, i.e. those devices that are to be controlled or sensors whose output is to be monitored. See also [AD 06].

The contents of file xxmcfgINS.cfg reflect what described in these tables.

Table 1Total number of ICS devices

TYPE	SYMBOL	Total
Lamps	LAM	4
Shutters	SHU	1
Servo driven rotational motion, no limit switches	ROT	6
Servo driven linear motion (slide), limit switches	LIN	2
Servo driven rotational motion, no limit switches, used to generate a linear motion, requiring position lookup table	EXC	2
All types of sensors, simple or complex; PMT's, temperature sensors, LN2 level detectors, vacuum sensors, contacts. Analogue or logical values (in digital form).	SEN	2
		17

Table 2 ICS Devices [ISDD14]

#	Device	NAME	TYPE	FITS KEYS	VALUES	LCU	REMARKS
1	Calibration mirror slide	CALS	LIN icbMOT_MIRROR	INS.MIRR1.NAME	TELESCOPE SPHERE THAR1 THAR2	1	Slide with 4 positions
2	ThAr lamp 1	TAL1	LAM icbLAMP	INS.LAMP1.ST	T/F	1	T=On F=Off Special power level in standby state [ISDD22]
3	ThAr lamp 2	TAL2	LAM icbLAMP	INS.LAMP2.ST	T/F	1	T=On F=Off Special power level in standby state
4	ThAr shutter	TSH	SHU icbSHUTTER	INS.SHUT1.ST	T/F	1	T=Open F=Close
5	FF lamp 1	FFL1	LAM icbLAMP	INS.LAMP3.ST	T/F	1	T=On F=Off On sphere
6	FF lamp 2	FFL2	LAM icbLAMP	INS.LAMP4.ST	T/F	1	T=On F=Off On sphere
7	Image derotator	DROT	ROT icbMOT_DROT	INS.DROT.MODE INS.DROT.POSANG INS.DROT.RA INS.DROT.DEC	SKY ELEV STAT [0.0 – 360.0]	1	It has three modes [ISDD21]: 1) derotate sky (fixed position angle of slit on the sky). Position angle selectable by observer. Default: N/S 2) derotate elevation direction (align the elongation direction of the stellar image with the slit) to eliminate need for ADC 3) stationary, used with image slicer
8	Preslit filter wheel	PFIL	ROT icbMOT_FILTER	INS.FILT1.NAME	B U … FREE	1	Wheel with 16 positions
9	Mode selector	MODE	LIN icbMOT_MIRROR	INS.MIRR2.NAME	IR UV DICHROIC	1	Slide with 3 positions
10	UV slit	UVSS	EXC icbMOT_SLIT2_WID	INS.SLIT1.WID	[0.01 – 10.00]	2	Width in arcsec. Backlash
11	UV filter wheel	UVFIL	ROT icbMOT_FILTER	INS.FILT2.NAME	B U … FREE	2	Wheel with 24 positions
12	UV cross disperser	UVCD	ROT icbMOT_GRATING2	INS.GRAT1.NAME INS.GRAT1.WLEN	GRAT1 GRAT2 [9000 –11000] [8000 –10000]	2	User specifies grating and order number [ISDD24]. Two gratings back to back.
13	IR slit	IRSS	EXC icbMOT_SLIT2_WID	INS.SLIT2.WID	[0.01 – 10.00]	2	Width in arcsec. Backlash
14	IR filter wheel	IRFIL	ROT icbMOT_FILTER	INS.FILT3.NAME	B U … FREE	2	Wheel with 24 positions
15	IR cross disperser	IRCD	ROT icbMOT_GRATING2	INS.GRAT2.NAME INS.GRAT2.WLEN	GRAT3 GRAT4 FREE [12000-15000] [11000-14000]	2	User specifies grating and order number. Two gratings back to back.
16	UV camera temperature monitoring	TUVC	SEN (CRY) xxiLAKE (special)	INS.TEMP1.VAL		2	Value in deg C Sampling period 60 sec [ISDD25]
17	IR camera temperature monitoring	TIRC	SEN (CRY) xxiLAKE (special)	INS.TEMP2.VAL		2	Value in deg C Sampling period 60 sec

4.1.1 Special devices

For every special device, a justification why none of the icb standard devices can be used must be given.

The only special devices are the two camera temperature monitoring sensors (TUVC and TIRC). None of the temperature sensor standard devices supported by icb fulfills the requirements in terms of accuracy and operability in a cryogenic environment. For these reasons, a Lakeshore xyz device, not supported by icb, has been chosen [ISDD27].

4.1.2 Cryogenics

Information about devices in a cryogenic environment should be placed in the Control Electronics Design document. A reference to that document is enough.

Details on cryogenics devices are described in [AD 06]. [ISDD26]

4.1.3 Backlash compensation

Due to mechanical backlash, the target position for the two slit devices (UVSS and IRSS) shall always be approached in the direction of increasing encoder steps. This will be achieved by using the two-steps motion feature provided by the standard VLT motor library [ISDD23]. The size of last step will be 100 encoder steps.

4.1.4 Interlocks

Information about hardware interlocks should be placed in the Control Electronics Design document. A reference to that document is enough.

Details on hardware interlocks are described in [AD 06]. [ISDD62].

Software alarms will be implemented to warn the user that the environmental conditions (e.g. temperature) are approaching the values which trigger interlocks.

4.1.5 Parallelism

Actions on all devices (initialization, setup) will be done in parallel, as they are fully independent from each other [ISDD48]. This functionality is embedded in the icb architecture.

4.1.6 States

The standard instrument states and related commands to change state are described in [AD 03]. All scenarios have to fit into that scheme, because the whole common Software relies on it.

The instrument states are the standard ones specified in [AD 03], namely: [ISDD29]

OFF: part of the Software is not running and part of the LCUs and devices can be powered off.
LOADED: the whole hardware is powered on, the whole Software is running, but the interfaces to the hardware are not initialized.
STANDBY: the interfaces are initialized, but the hardware may not.

Sphere lamps are off. ThAr lamps are in a special standby power status.
Shutters are closed
Encoders are on
Motors current is off.
Sensors monitoring is active.

ONLINE: all software and hardware is loaded, initialized and active. This is the normal state during operations.

4.2 ICS LCU part

The design should be based on the UML notation.

Use cases should describe the most important or critical operations. For each Use Case a description of the actors involved, performance requirements, basic course, exception course is mandatory; a Use Case Diagram is recommended. Depending on the type of device and its characteristics, other diagrams may be used. Typically Sequence Diagrams and State Chart Diagrams should be used in the design of ICS LCU special devices.

This section describes the design of the LCU part of ICS. Because the core is built from icb, this section will not repeat the design of standard devices, already available as plug&play components from icb. It will instead concentrate on the design of the special devices, which is the only part to be coded.

4.2.1 Architecture

A Component Diagram is recommended if special devices have to be integrated in the icb architecture.

The Component Diagram in Figure TBD shows the processes running on the LCU and their relationship

4.2.2 Lakeshore special device

The Lakeshore special device functionality will be implemented in two dedicated LCU processes (see Figure TBD):

xxilakServer (see 11.1.1), which receives commands from the standard ic0lcuServer task, executes the corresponding actions and returns the reply.
xxilakMonitor (see 11.1.2), which periodically monitors the status of the hardware associated to the device

The Hardware interface is represented by the VME ISER12 board.

The Software interfaces are:

ISER12 driver and specific serial communication protocol for the Lakeshore device.
Command Interface to the process ic0lcuServer (see below)
OLDB attributes, scanned to the IWS (see below)

The short FITS prefix for device TUVC is INS.SENS1 and for TIRC is INS.SENS2.

The commands for the Lakeshore device server are the standard ones defined in the ic0devServer*.icdt files [ISDD30].

For devices with setup keywords, the foreseen list should be given with accepted values. It should be reminded that:

The syntax and value of Setup keywords must be checked for validity before taking any action.
The value of Setup parameters must be stored in the LCU and/or WS on-line database in dedicated attributes, different from the attribute containing the corresponding status parameter.
The value of Setup parameters in the on-line database shall not be changed until a new SETUP command is executed.
Setup keywords must be registered in the dictionary XXXX_ICS

No setup keyword is foreseen for these devices.

The following status keywords are registered in the dictionary XXXX_ICS: [ISDD66]

Device TUVC: INS.SENSOR1.SWSIM INS.TEMP1.VAL

The reply to the STATUS –header command will contain (format required by icb, in particular ic0lcuServer):

INS.SENSOR1.ID “tuvc”,

INS.SENSOR1.NAME “UV camera”,

INS.TEMP1.ID “uvc”,

INS.TEMP1.NAME “Temp. UV camera”,

INS.TEMP1.VAL 123.4567

Device TIRC: INS.SENSOR2.SWSIM INS.TEMP2.VAL

The reply to the STATUS –header command will contain (format required by icb, in particular ic0lcuServer):

INS.SENSOR2.ID “tirc”,

INS.SENSOR2.NAME “IR camera”,

INS.SENSOR2.SWSIM TRUE,

INS.TEMP2.ID “irc”,

INS.TEMP2.NAME “Temp. IR camera”,

INS.TEMP2.VAL 123.4567

The special device code will support hardware simulation in that calls to the ISER12 driver will be skipped and the most realistic reply will be simulated [ISDD37]. The keyword INS.SENSi.SWSIM TRUE will be returned in the reply to the command STATUS –header (see example above for device TIRC). [ISDD38]

The following OLDB attributes will be scanned to the IWS (extract of file xxi/config/lxxics1.scan): [ISDD33]

<alias>TUVC.state <alias>TUVC.state SRBX 2

<alias>TUVC.simulation <alias>TUVC.simulation SRBX 2

<alias>TUVC.last <alias>TUVC.last SRBX 2

<alias>TIRC.state <alias>TIRC.state SRBX 2

<alias>TIRC.simulation <alias>TIRC.simulation SRBX 2

<alias>TIRC.last <alias>TIRC.last SRBX 2

The following use cases describe the operations of the Lakeshore special device:

Monitor temperature

Description: The Lakeshore device is supposed to monitor the temperature value with a periodicity defined in the configuration file. The new value read from the hardware must be stored in the OLDB and logged. The monitoring must be started during the state transition from loaded to stand-by and stopped during the transition from stand-by (or online) to loaded.

Actors: ic0lcuServer, Lakeshore device hw

Performance: 3 sec. Accuracy 0,01 degree Celsius

Frequency: configurable (see Configuration below)

Configuration: INS.SENSORi.MONTIME defines the monitoring periodicity

Commands: STANDBY, STATUS, OFF

Preconditions: LCU is booted and OLDB is properly configured (see utility icbConfigSet)

Basic Course:

· Device server xxilakServer receives a STANDBY command

· Device server xxilakServer spawns the monitoring task xxilakMonitor

· The monitoring task xxilakMonitor reads from OLDB frequency and the ISER12 device name

· The monitoring task reads, with the defined periodicity, the temperature from the ISER12 device, writes the value in the OLDB attribute .last and issues an operational log containing the current value (see 11.1.3). [ISDD40]

· Device server xxilakServer receives a STATUS command

· Device server xxilakServer reads from the OLDB the value obtained from the last access to the hw and returns it in the reply (see above for the complete reply format)

· Device server xxilakServer receives a OFF command

· Device server xxilakServer terminates the monitoring task xxilakMonitor

Exception Course: read from ISER12 failed

· Try once more as recovery procedure

· If failure persists, issue an operational log of type UNFORESSEN and flag the failure by writing an illegal value (9999) in the OLDB

· Keep the same state and keep the monitoring task active

Diagrams: Use Case Diagram, Sequence Diagram, State Chart Diagram, Component Diagram

…..

4.3 ICS WS part

The design should be based on the UML notation.

Use cases should describe the most important or critical operations. For each Use Case a description of the actors involved, performance requirements, basic course, exception course is mandatory; a Use Case Diagram is recommended. Depending on the context, other diagrams may be used. Typically Class Diagrams and Sequence Diagrams should be used in the design of ICS WS special classes.

This section describes the design of the WS part of ICS. Because the core is built from icb, this section will not repeat the design of the icb standard WS classes. It will instead concentrate on the design of special classes and assemblies.

4.3.1 Architecture

A Component Diagram is recommended in case of a special ICS (e.g. AO RTC), which does not follow the standard icb architecture.

The architecture of the ICS WS part is the standard one coming from icb and consists of two processes:

ICS Server xxiControl. It provides the API to OS and takes care of forwarding commands to the LCUs
ICS LCU simulation process xxiSimControl. It simulates the behavior of the LCUs in test/development environments where they are not available.

4.3.2 Special classes

The following special classes will be developed for the ICS WS part (see 11.1.5):

xxiINS_LAMP. This is a subclass of ic0INS_LAMP and aims to compute statistics on the time the lamp was on and do predictions on the lamp lifetime.
….

The relationship between classes is described in the Class Diagram shown in Figure TBD.

All the above classes will use the standard tool ctoo to access the value of configuration keywords. [ISDD51]

The following Use Cases describe the most common/critical circumstances where the classes above are used:

Lamp On/Off cycle

Description: In order to have an estimate of the remaining lamp lifetime, the total time the lamp was on as well as the last period of time the lamp was on must be stored.

Actors: ICS WS server, ICS LCU server

Performance: N/A

Frequency: N/A

Configuration: N/A

Commands: SETUP

Preconditions: ICS is ONLINE

Basic Course:

· ICS WS server receives a command SETUP –function INS.LAMP1.ST T

· ICS WS server triggers the DevTrigger method of xxiINS_LAMP

· xxiINS_LAMP stores the current time

· ICS WS server forwards the SETUP command to the LCUs

· ICS WS server receives the last reply from the LCUs and returns the last reply to the SETUP command

· ICS WS server waits for the next command

· ICS WS server receives a command SETUP –function INS.LAMP1.ST F

· ICS WS server triggers the DevTrigger method of xxiINS_LAMP

· xxiINS_LAMP calculates the time between the two SETUP commands and stores it in the lastTimeOn OLDB attribute. It adds this value to the contents of the totalTimeOn OLDB attribute and writes the new cumulated value to the OLDB

Exception Course: failed to write in the OLDB

· return FAILURE

Diagrams: Use Case Diagram, Sequence Diagram

…..

4.3.3 Assemblies

The following assemblies are defined: [ISDD36]

INS.LAMP. All calibration lamps are mutually exclusive, i.e. it does not make sense to have more than one turned on at one time. This assembly simplifies the interface to higher level Software (OS) in that it allows specifying with one single keyword which lamp is going to be used, if any.
……

See 11.1.3 for more details about the definition of assemblies in file xxmcfgINS.cfg

4.3.4 Interfaces

The programmatic interface of the ICS WS Server process xxiControl consists of:

Interface to the LCU part. It consists of the Command Definition Table for the standard icb LCU Server ic0lcuServer.
Interface to the OS Server. It consists of:

Command Definition Table for the xxiControl process (see 11.1.3).
FITS file containing the ICS header keywords as result of the command STATUS –header –dumpFits (see 11.1.8 [ISDD41])

The Graphical User Interface for stand-alone engineering operations consists of one ICS engineering GUI, based on the VLT standard package icbpan [ISDD39].

Figure 3 shows a mockup of such GUI (example taken from Omegacam)

4.3.5 Alarms

The following alarms will be defined in the OLDB using the standard classes provided by the CCS module alrm: [ISDD31]

UV camera temperature too high.

OLDB attribute: <alias>TUVC.alarm0 [ISDD84]

IR camera temperature too high

OLDB attribute: <alias>TIRC.alarm0

Alarms will be triggered only if the device is not hardware simulated and the monitoring is active. CCS OLDB calculation engine functionality will be used to achieve this (see 11.1.7). [ISDD83]

4.4 Configuration

Configuration parameters are stored in the file xxmcfgINS.cfg, belonging to module xxmcfg (see 7.1)

4.5 Dictionaries

All keywords used by ICS at runtime are registered in the dictionary XXXX_ICS.

The special configuration keywords, not registered in ICB_CFG, are registered in the dictionary XXXX_CFG (see 11.1.9).

All dictionaries are contained in module dicXXXX.

Figure 3 ICS stand-alone engineering GUI

4.6 Test Software

The ICS Test Software shall consist of [ISDD35]:

Low-level LCU test procedure for the Lakeshore special device. It will be implemented in file xxilak/test/xxilakTest.c
High-level WS test procedure for the Lakeshore special device. The inscSelfTestICS utility will be used for this purpose. The procedure will be defined through the keywords INS.SENSi.TEST* in file xxmcfgTEST.cfg
Self-test procedure. The inscSelfTestICS utility will be used for this purpose. The procedure will be defined through the keywords OCS.INS1.TEST* in file xxmcfgTEST.cfg
Alarms test procedure. The reaction of the Software to each alarms condition is tested. Whenever it is not possible or too risky to reproduce an alarm condition in hardware, it is simulated in software.

All test procedures will test also the most common or critical error cases.

4.7 Standards

ICS will be based on icb and icbpan.

4.8 Modules

The cmm modules belonging to ICS are [ISDD34]:

xxi. It is the main module and includes the ICS WS front-end and LCU simulator.
xxipan. It includes the ICS stand-alone GUI
xxilak. It includes the code for the Lakeshore special device

5 DETECTOR CONTROL SOFTWARE (DCS)

This Chapter describes the design of the DCS package. Depending on its size, or for any other reasons, it might be convenient to place it in a separate dedicated document. In such case, this chapter is replaced by a simple reference to the separate document.

In case of non standard DCS, or special extensions of the standard functionality, the design should be based on the UML notation.

The instrument is equipped with two science detector cameras [ISDD15].

Two DCSs will be in place, each controlling one of the two science cameras [ISDD16].

The DCS for the UV camera will be an instance of the standard FIERA package [ISDD17].

The UV CCD detector size will be 2028 x 2048 pixels, upgradeable to 4096 x 4096 [ISDD18].

The DCS for the IR camera will be an instance of the standard IRACE package [ISDD19].

The IR detector size will be 1024 x 1024 pixels [ISDD20].

5.1 Architecture