VERY LARGE TELESCOPE · -MAN ESO 17240 1973 1.6 Reference Documents The following documents are referenced in this document: Ref Title Document Number [RD1] CCS User Manual VLT -MAN

ESO, Karl-Schwarzschild-Str. 2, 85748 Garching bei München, Germany

VERY LARGE TELESCOPE

Instrument Control Software Laboratory Exercise

Doc. No.: VLT-MAN-ESO-17240-4618

Issue: 1

Date: 2009-09-01

Prepared: M.Kiekebusch J.Knudstrup D.Popovic Name Date Signature

Approved: G.Chiozzi Name Date Signature

Released: M. Peron Name Date Signature

European Organisation for Astronomical Research in the Southern Hemisphere

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

Instrument Control Software

Laboratory Exercise

Doc:

Issue

Date

Page

VLT-MAN-ESO-17240-4618

1

2009-09-01

2 of 51


CHANGE RECORD

ISSUE DATE SECTIONS

AFFECTED Who

REASON/INITIATION

DOCUMENTS/REMARKS

0.23 2008-10-04 All INS Team First issue.

1.0 2009-09-01 All JKN Major overhaul. Removed Special

Device and CLIP session from the

document. Fixed issues in the

remaining sessions and simplified a bit.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

3 of 51


TABLE OF CONTENTS 1 Introduction ..................................................................................................................................... 6

1.1 Purpose .................................................................................................................................. 6 1.2 Acknowledgments .................................................................................................................. 6 1.3 Scope ..................................................................................................................................... 6 1.4 List of Abbreviations & Acronyms .......................................................................................... 6 1.5 List of Applicable Documents ................................................................................................. 7 1.6 Reference Documents ........................................................................................................... 7 1.7 Guidelines for Reading this Document .................................................................................. 8

2 Overview ....................................................................................................................................... 10 2.1 The Instrument ..................................................................................................................... 10 2.2 Hardware Architecture ......................................................................................................... 10

2.2.1 Devices ........................................................................................................................ 10 2.2.2 Computers and Hardware ........................................................................................... 10

2.3 Software Architecture ........................................................................................................... 12 2.4 Environment Configuration................................................................................................... 13

2.4.1 User Accounts/Environments ...................................................................................... 13 2.4.2 CCS/LCC Environments .............................................................................................. 14

3 Exercise #1: Getting Started ......................................................................................................... 15 3.1 Purpose ................................................................................................................................ 15 3.2 Implementation Details ......................................................................................................... 15 3.3 Exercise Steps ..................................................................................................................... 15

3.3.1 Preparing the XXXX Modules for the Basic Adaptation .............................................. 15 3.3.1.1 Checking and Adapting the Environment .............................................................. 15 3.3.1.2 Retrieve the XXXX Base Module ........................................................................... 15 3.3.1.3 Initial Adaptation of the Integration Module ........................................................... 16 3.3.1.4 Retrieving the XXXX Modules ............................................................................... 16

3.3.2 Adapting the Template Instrument to the Exercise Instrument ................................... 16 3.3.2.1 Creating the Exercise Instrument Software ........................................................... 16 3.3.2.2 Adapting the Installation Configuration File ........................................................... 17 3.3.2.3 Adapting the TCS Simulator Configuration ........................................................... 17 3.3.2.4 Adapt the Instrument Configuration ....................................................................... 18 3.3.2.5 Adapt the Start-up Configuration ........................................................................... 19 3.3.2.6 Build the SW for the Exercise Instrument .............................................................. 19 3.3.2.7 Start the Instrument ............................................................................................... 19

3.4 Session Summary ................................................................................................................ 20 4 Exercise #2: Instrument Control Software - ICS ........................................................................... 21

4.1 Purpose ................................................................................................................................ 21 4.2 Implementation Details ......................................................................................................... 21

4.2.1 Devices ........................................................................................................................ 21 4.2.2 Location of Relevant Configuration Files .................................................................... 21

4.3 Exercise Steps ..................................................................................................................... 21 4.3.1 Adapting the Instrument Configuration ........................................................................ 21 4.3.2 Adjusting Instrument DB .............................................................................................. 24

4.3.2.1 Adjusting the DB Definition “iniEnv.db”.................................................................. 24 4.3.3 Configuring Scan Links ............................................................................................... 25 4.3.4 Setting Default LCU DB Configuration ........................................................................ 26 4.3.5 Adjusting Instrument WS Simulation DB ..................................................................... 26 4.3.6 Adjusting Instrument Dictionary ................................................................................... 27 4.3.7 Setting Simulation Level .............................................................................................. 27 4.3.8 Adapt the “pkgin” configuration file .............................................................................. 27 4.3.9 Build and Install Updated Modules .............................................................................. 27 4.3.10 Re-building the SW...................................................................................................... 27 4.3.11 Starting ICS ................................................................................................................. 27

4.4 Session Summary ................................................................................................................ 28


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

4 of 51


5 Exercise #3: Interfacing with Detector Control Systems............................................................... 29 5.1 Purpose ................................................................................................................................ 29 5.2 Exercise Steps ..................................................................................................................... 29

5.2.1 Adapt the Instrument Configuration for RTD Start-Up ................................................ 29 5.2.2 Adapting the NGC IR Detector Configuration ............................................................. 29

5.2.2.1 Updating the High Level NGC IR Configuration .................................................... 29 5.2.2.2 Update the NGC System and Detector Configuration ........................................... 30 5.2.2.3 NGC IR Verification ............................................................................................... 31

5.2.3 Update the TCCD Configuration ................................................................................. 34 5.2.4 Update ICB Installation Configuration for the TCCD ................................................... 35 5.2.5 TCCD Verification ........................................................................................................ 35

5.3 Session Summary ................................................................................................................ 37 6 Exercise #4: Observation Software – OS ..................................................................................... 38

6.1 Purpose ................................................................................................................................ 38 6.2 Implementation Details ......................................................................................................... 38 6.3 Exercise Steps ..................................................................................................................... 38

6.3.1 Configure OS Subsystems .......................................................................................... 38 6.3.2 Update the Start-Up Configuration .............................................................................. 39 6.3.3 OS Database Configuration ........................................................................................ 39 6.3.4 OS Verification ............................................................................................................. 40 6.3.5 Optional: Update the OS Control Panel ...................................................................... 42

7 Exercise #5: Templates ................................................................................................................ 43 7.1 Purpose ................................................................................................................................ 43 7.2 Additional Information .......................................................................................................... 43 7.3 Implementation Details ......................................................................................................... 43 7.4 Exercise Steps ..................................................................................................................... 44

7.4.1 Optional: Create Snapshot .......................................................................................... 44 7.4.2 Prepare Science TSF Files ......................................................................................... 44 7.4.3 Prepare the Sequencer Files ....................................................................................... 46 7.4.4 Prepare Technical TSF Files (module: “inmtsf”) ......................................................... 49 7.4.5 Prepare Technical Sequence Files ............................................................................. 50

7.5 Session Summary ................................................................................................................ 51


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

5 of 51



Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

6 of 51


1 Introduction This document contains the course material for a laboratory exercise (for short, “lab ex”)developed to train SW engineers working for the VLT control SW, in particular in the context of instrument control SW. The lab ex has been developed so that it can be executed as a self-study course. In case of problems, the course participant is invited to contact the ESO INS Team for assistance. The exercise in its present version, is targeted for the VLT2009; but it should also work with future releases. The lab ex will be verified on new releases and this document updated accordingly regularly.

1.1 Purpose

The purpose of the document is to provide a step by step set of instructions to implement the control SW for a fictitious instrument that should be built in the course of the laboratory exercise. The document is aimed to become a guideline for how to approach the development of the control SW for a particular instrument complementing the INS SW documentation set and providing a practical example that can be used by developers to understand better the process of customizing the INS Template Instrument. Note however, that it is not the intention of the exercise to show the way for implementing the control SW for an instrument, but rather to show one way with the purpose of giving the course participant a fairly thorough walk-through of many of the aspects of the development process.

1.2 Acknowledgments

The authors would like to thank M.Comin, M.Pruemm and G.Chiozzi (all three SDD/CIS) for their help and useful feedback in connection with the preparation of this document.

1.3 Scope

The intended audience are developers of instrument control SW from the consortia working in collaboration with ESO. In addition people coding and maintaining instrument SW at the observatory sites and whoever is using the INS SW framework of the VLT SW Package. This document covers only the control part of the fictitious instrument SW. Pipelines development and other dataflow related aspects are out of the scope of this exercise.

1.4 List of Abbreviations & Acronyms

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:

CCS Central Control Software DCS Detector Control Software DFS Data Flow System GUI Graphical User Interface HW Hardware HDU Header/Data Unit (FITS) ICS Instrument Control Software INS Instrumentation Software Package I/O Input/output ISF Instrument Summary File IWS Instrument Workstation LCC LCU Common Software LCU Local Control Unit MS Maintenance Software N/A Not Applicable


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

7 of 51


PAE Preliminary Acceptance Europe PAF Parameter File P2PP Phase 2 Proposal Preparation RTAP Real-Time Application Platform SW Software TBC To Be Clarified TBD To Be Defined TCS Telescope Control Software TIM Time Interface Module TRS Time Reference System TSF Template Signature File VLT Very Large Telescope WS Workstation

1.5 List of Applicable Documents

This document is based on the following documents:

Ref Title Document Number

[AD1] Data Interface Control Document GEN-SPE-ESO-19400-0794

[AD2] VLT Software Programming Standards VLT-PRO-ESO-10000-0228

[AD3] VLT Instrument Software Specification VLT-SPE-ESO-17212-0001

[AD4] INS Common Software Specification VLT-SPE-ESO-17240-0385

[AD5] Template Instrument Software – User and Maintenance Manual


1.6 Reference Documents

The following documents are referenced in this document:

Ref Title Document Number

[RD1] CCS User Manual VLT-MAN-ESO-17210-0619

[RD2] HOS/Sequencer - User Manual VLT-MAN-ESO-17220-0737

[RD3] VLT Software Real Time Display, User Manual VLT-MAN-ESO-17240-0866

[RD4] IRACE-DCS - Real-Time Display application, UM VLT-MAN-ESO-14100-2108

[RD5] NGC Optical DCS – User Manual VLT-MAN-ESO-13660-4086

[RD6] NGC Infrared DCS – User Manual VLT-MAN-ESO-13660-4085

[RD7] CCS Engineering Interface And Graphical Tools VLT-MAN-ESO-17210-3816

[RD8] Linux Installation Manual VLT-MAN-ESO-17200-2009

[RD9] Installation Tool for VLTSW Packages – Maintenance and User Manual


[RD10] I INS/Base ICS User Manual GEN-SPE-ESO-19400-0794

[RD11] Base Observation Software Stub VLT-MAN-ESO-17240-2265

[RD12] INS Startup Tool – User Manual VLT-MAN-ESO-17240-2153

[RD13] VLT SW Environments – Common Configuration VLT-MAN-ESO-17210-0855

[RD14] INS Common SW for Templates – User Manual VLT-MAN-ESO-17240-2240

[RD15] HOS / Broker for Observation Blocks – User Manual VLT-MAN-ESO-17220-1332

[RD16] VLT SW Installation Manual VLT-MAN-ESO-17200-0642


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

8 of 51


1.7 Guidelines for Reading this Document

Since the course is based on using the SW completely in simulation mode on the IWS and/or on the LCU, it is possible to use the course notes as a self-tutorial/training session. All what is needed to do this, is the availability of the latest VLT SW release and a suitable Linux box with the proper Linux version installed and a VxWorks based LCU. Additional background information is provided in the exercise instructions in info boxes as shown here:

Information

These boxes can in principle be skipped while carrying out the exercise, but they provide important/useful information that will help the course participant achieving more in-depth information about the VLT SW and the environment as such, and should help to provide a better overview of the system. It would be good to go through this at some point in time … In the different parts of the exercise, the steps to carry out is shown like this: Steps:

1. <step 1>

2. <step 2>

3. … Text examples from the configuration files, is shown in courier font/black like this, e.g.:

4. Rename “TSH” to “SHUT” by replacing the following for “SHUT1”:

INS.SHUT1.DEVNAME "shut"

INS.SHUT1.DEVDESC "Entrance shutter"

INS.SHUT1.ID "SHUT"

INS.SHUT1.NAME "Entr_Shutter"

If no ICS LCU is available for the exercise, it is possible to executue in WS simulation. The places where to deviate from the normal track, if this is desired, is indicated as follows:

NO-LCU: <action> It goes without saying, that carrying out the exercise with an ICS LCU is the best option. Note also, that working without an LCU, the DB attributes of the devices are only updated partially. I.e., the simulation provided by IC0 is fairly simple, and serves normally, merely to make it possible to work with the higher level systems without any HW at all. The steps to carry out during the exercise are admittedly somewhat „mechanical‟. The course parcipant is therefore encouraged to study closely and try to understand the action performed during each step. This implies also analysing carefully the contents of configuration information involved in each step. Disclaimer: While preparing this document, we have tried to make the descriptions as accurate as possible. Nevertheless, the document contains many details and thereby there are many possibilities for mistakes. If a mistake/type/error is found in the document, whilst for instance applying this document for a self-study tutorial, we kindly request that this discrepancy is reported to the authors, to enable us to keep the document as correct as possible.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

9 of 51


The exercise is based on the “xxins” module version 5.57 and it might also be that due to changes, e.g. in the configuration of the Template Instrument, that details in the document could become obsolete over time. We will try to keep the contents up to date and as compatible as possible with the current VLTSW Release. Note also that due to time constraints, it is only possible to cover a part of the INS Common Framework.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

10 of 51


2 Overview This chapter contains an overview of the fictitious instrument (Exercise Instrument) that will be built during this exercise. In addition information about the VLTSW development environment is given, i.e. the details to set up a running environment are explained.

2.1 The Instrument

The Exercise Instrument is a near-infrared imager, equipped with a narrow-band filter and a mosaic of 2 Hawaii RG detectors with a size of 512x512 pixels and a physical gap of 20µ. The light passes through a filter wheel before reaching the detector. It has a calibration unit composed by a technical detector, one sodium lamp, one halogen lamp with intensity control and one dichroic mirror. The cryogenic variables (temperatures, vacuum, etc) are monitored by a Yokogawa controller. There is an entrance shutter to protect the instrument optical components from dust. This instrument is intended for the VLT at the Cassegrain focus.

2.2 Hardware Architecture

2.2.1 Devices

The Exercise Instrument is composed of the following components:

6 devices, controlled by the ICS on 1 LCU:

2 motors.

1 entrance shutter.

1 sodium lamp.

1 DAQ unit (Yokogawa).

1 halogen lamp (special device).

1 scientific detector:

1 NGC controller (infrared SW).

1 technical detector:

1 NGTCCD.

2.2.2 Computers and Hardware

The Exercise Instrument is using the following computers and HW1:

Instrument WS (could be running in a virtual machine). Environment name: “winsx”.

ICS LCU 1. Environment name: “linics1”. Installed boards:

1 Motorola MVME-6100 PowerPC CPU.

1 MEN VME carrier board A201S.

1 ESD CAN 04.

1 MACCON MAC4-INC.

1 Servo Amplifier Board VME4SA.

NO-LCU: If no ICS LCU is available, it will still be possible to configure the various devices and operate the instrument (with reduced functionality).

1 Although this equipment was used while developing the exercise, it is possible to carry out the exercise with only

an IWS (could be a virtual machine) or an IWS together with an LCU of the current standard.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

11 of 51


Figure 1: Devices of the Exercise Instrument.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

12 of 51


2.3 Software Architecture

The SW architecture that will be built when going through this exercise is depicted in Figure 2.

Figure 2: The Exercise Instrument SW Architecture.

The instrument ID is “INSX” and its prefix “in”. The starting point for the development is the Template Instrument [AD5]. The Template Instrument is provided by the VLTSW Package, within the scope of the Instrument Common SW (INSCSW), as an example/demo instrument, which can be used as starting point for developing new instrument control SW. The “Template Instrument” and the “Exercise Instrument” have the following configuration:

Instrument Name Template Instrument Exercise Instrument

Instrument ID XXXX INSX

Prefix xx in

Instrument User xxxx insx

Instrument Manager

xxxxmgr insxmgr

WS Environments wxxxx, wxxtcs winsx, wintcs

ICS LCU Environments

lxxics1, lxxics2 linics1

Detector Systems IRACE, TCCD, FIERA, NGC/IR NGC/IR, TCCD

Detector LCUs lxxtccd None (LCU Simulation)

Note that the Template Instrument comes with many devices, more or less, all possible devices and detector systems supported by the ICB. During this exercise, all of configuration information related to the devices not existent in the Exercise Instrument will be removed from the various configuration files. The mapping of environments used by XXXX and INSX is shown in the following table:


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

13 of 51


Environment Number

Template Instrument Exercise Instrument

1 wxxxx winsx

2 lxxics1 linics1

3 lxxics2 -

4 lxxtccd -

2.4 Environment Configuration

This section describes the configuration of the IWS. Apart from some definitions of the environment variables in PECS files, e.g. RTAPENV and TCS_ENVNAME, that have to be set by the instrument SW developer, all the remaining configuration should be done by the user “vltmgr” during the installation of the VLT SW. The configuration given below is just a check-list in case that there are some fundamental problems on the IWS.

2.4.1 User Accounts/Environments

The Instrument User Accounts should be declared as usual on the WS (Linux based). The entry in “/etc/passwd” should be something like this:

insx:x:4929:300:(c/a vltmgr):/home/insx:/bin/bash

insxmgr:x:4932:300:(c/a vltmgr):/home/insxmgr:/bin/bash

For each instrument there is a deployment user under which the SW is running and a manager account, under which the SW is being developed, built and installed [AD3]. These account should be named according to the instrument, e.g. in the case of the exercise instrument, “insx” and “insxmgr” [AD3]

For the Instrument Manager Account, “insxmgr”, the following environment variables should be defined in PECS (e.g. “/home/insxmgr/.pecs/apps-all.env”), e.g.:

export INTROOT=/vlt/INSX/INTROOT

export PATH=$INTROOT/bin:$PATH

export LD_LIBRARY_PATH=$INTROOT/lib:$GNU_ROOT/lib:\

$CPL_HOME/lib/:/usr/local/lib:$LD_LIBRARY_PATH

export INS_ROOT=/data/INSX/INS_ROOT

export INS_USER=SYSTEM

export TARGET=LAB_EX

export RTAPENV=winsx

export DHS_DATA=$INS_ROOT/SYSTEM/DETDATA

export TCS_ENVNAME=wintcs

To simplify the configuration of the deployment user, here “insx”, a link is normally created, which points to the definition for the Manager Account, e.g.:

/home/insx/.pecs/apps-all.env -> /home/insxmgr/.pecs/apps-all.env

The VLTSW building tool (“pkgin”) is depending on having the Instrument Manager Account user executing remote shell commands as the Instrument User. It is therefore necessary to add entries in the “~insx/.rhosts” definition of the Instrument User to allow this, e.g.:

te77.hq.eso.org insx

te77.hq.eso.org insxmgr

The global user account on the VxWorks based LCUs, is called “vx”. It is important to add an entry in the “~vx/.rhosts” definition to make it possible for the “vx” user on the LCU to access and boot the VxWorks kernel, e.g.:

linics1 vx

linics1.hq.eso.org vx

lintccd vx


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

14 of 51


licics1.hq.eso.org vx

2.4.2 CCS/LCC Environments

The basic configuring is described in this section. A CCS environment (or RTAP Environment), must have an entry in “/etc/services”, reserving a unique port number for the command channel, e.g.:

winsx 2302/tcp

wintcs 2303/tcp

Also, for the VxWorks based LCUs, there should be an entry per environment:

linics1 2160/tcp

lintccd 2160/tcp

Note that LCU‟s always have the same port defined (2160). In order to register properly the environments in the CCS framework, the environments must be defined in the ACC DB. The ACC DB is managed by the “vltmgr” account.

Access and Configuration Control (ACC) DB is relational SQL-based database containing a centralized configuration for the nodes, CCS and LCU environments in the control network and the relation between them. This configuration data can be queried at run-time by the engineering interfaces and VLT applications [RD13].

This is done by inserting the following lines in the SQL script, “/vltdata/msql/accData.sql”:

…

INSERT INTO prog_environment VALUES ('winsx','','QSEMU',2302,'te77','','','',0)\g

INSERT INTO prog_environment VALUES ('wintcs','','QSEMU',2303,'te77','','','',0)\g

…

INSERT INTO station VALUES

('linics1','','vltsoft','134.171.24.75','','AH','VLT','','','ppc','PPC604','mv6100',0)\g

…

INSERT INTO prog_environment VALUES('linics1','','LCU',2160,'linics1','','','',0 ) \g

…

# linics1 boots from winsx.

INSERT INTO lcu_progenv VALUES ('linics1' ,'winsx' ) \g

…

Note, this is only part of the ACC configuration, necessary to run a VLTSW „network‟ with several hosts and CCS environments. For a complete description of how to configure and install a properly functioning VLTSW host, please refer to the “VLT SW Installation Manual” ([RD16]). The ACC SQL script must be loaded into the ACC RDBMS by invoking the command “accLoadData” as user “vltmgr”.

The “vltmgr” account is defined on all VLT machines and it has special privileges to install and configure VLTSW and configuration files which are write protected for the other users. Among other things, this manager account can, for instance, modify the ACC DB and update the VLTSW installation.

After having loaded the ACC DB definition, it is possible to cross-check if the environments have been properly defined by means of the “vccEnv” Tool.

VLT Common Configuration Environment (VCC) is a family of engineering tools intended to create, delete, query and control the VLT environments in a uniform way. In particular, vccEnv is an interactive engineering panel which, among other things, interact with the ACC server to retrieve the information about the CCS and LCU environments.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

15 of 51


3 Exercise #1: Getting Started

3.1 Purpose

The purpose of this session is to initiate the implementation of the instrument SW. This involves allocating various names and ID‟s for the instrument, preparing the environment and building of the base SW package. After having carried out this session the course participant should be capable of initiating the development of an instrument him/her-self. The developer should have a good overview of the basic environment and insight into the functioning of the building process and the various configuration files involved.

3.2 Implementation Details

During this session, an initial adaptation of the Template Instrument will be done. The adaptation is not complete but rather, should be seen as the first iteration to obtain an initial, rough version of the new instrument. Note, all actions described below and in the subsequent sessions involving the implementation/building of the SW must be done as the manager user “insxmgr”. All actions involving starting and operating the instrument control SW, should be done as the deployment user “insx”.

3.3 Exercise Steps

3.3.1 Preparing the XXXX Modules for the Basic Adaptation

During this part of the exercise we will be setting up the development and the run-time environment and create the base structure used as a starting point for the actual development of the instrument SW.

3.3.1.1 Checking and Adapting the Environment

The purpose of this step is to verify and correct, if necessary, the environment, adapting it to the specific instrument.

Steps: 1. According to the description of the environment in section 2.4, verify that all parameters etc.

described are set appropriately.

3.3.1.2 Retrieve the XXXX Base Module

The purpose of this step is to retrieve the base module (Instrument Integration Module) of the Template Instrument, to be able to retrieve and build the complete instrument SW, by means of the “pkginBuild” Tool.

The Template Instrument Package, also referred to as “XXXX” is provided as an example of an instrument. It can be used as the starting point for every new instrument control SW development [AD5] .

The “pkginBuild” tool is the general VLTSW tool to build and install VLT SW packages [RD10]. The build and installation process is carried out in two main phases: build and install. The pkgin tool gets its input from configuration files (ASCII files using the PAF format), the configuration defines what SW modules and environments to be build including the setting of the scan links. The tool can be executed such that it carries out various phases or single steps of the building and installation procedure. Consult the man-page for further information (man pkginBuild).


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

16 of 51


Steps: 1. Create the instrument software root directory:

cd

mkdir XXXX

2. Check out the Integration Module of the Template Instrument:

cd ~/XXXX

cmmCopy xxins

3. Change permission on the files in the Integration Module to be able to adapt them:

chmod -R +w xxins

By convention the main source directory for the instrument SW is named “<instrument ID>. This directory should contain all the different modules which are part of the instrument SW. Modules will be retrieved from the CMM archive by the pkgin tool as part of the building process.

Every instrument must have an Instrument Integration Module, named “<prefix>ins”. This is the module for the deployment at the telescope site and contains the pkgin configuration required to build and install the instrument control SW. In addition to that, there might be several other such Integration Modules for different development sites, extending and overriding the definitions in the main Instrument Integration Module in order to reflect the configuration at the site, e.g. Telescope not present, some hardware not present, etc.

The retrieved XXXX files are read only. Therefore, write permissions have to be added in order to modify files (see Step 4 above).

3.3.1.3 Initial Adaptation of the Integration Module

The purpose of this step is to adapt the Instrument Installation Configuration to match the exercise instrument.

Steps: 5. Open a text editor on the file “~/XXXX/xxins/config/xxinsINSTALL.cfg”.

6. Adjust the user names of the Instrument User and Instrument Manager accounts to “insx” and

“insxmgr” (keywords: “INSTALL.LOGINNAME.USER/USERMGR”).

3.3.1.4 Retrieving the XXXX Modules

The purpose of this step is to retrieve all modules pertinent to the Template Instrument to be able to make the initial adaptation of the rest of the package.

Steps: 1. pkginBuild xxins -tostep RETRIEVE

3.3.2 Adapting the Template Instrument to the Exercise Instrument

During this part of the session, we will be creating a first, rough version of our target instrument. After a successful completion of this part, we will have an initial, simple version, running in simulation, with which various operations can be done, like producing data and displaying this in the Real-Time Display (RTD). The output of this exercise is the actual starting point for the instrument SW. During the following exercises we will be modifying it in order to obtain the final configuration.

3.3.2.1 Creating the Exercise Instrument Software

The purpose of this step is to generate the source files and modules from the Template Instrument. The adaptation itself is done automatically by a tool called “inscCreateNewInstrument”, which converts modules and files written for the Template instrument in files for the new instrument by doing mainly


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

17 of 51


renaming and replacing of the instrument ID and prefix. This step saves quite a lot of time for the developer.

Steps: 1. Create copy of the Template Instrument instrument root directory while adapting the names to

match the Exercise Instrument:

cd ~/XXXX

inscCreateNewInstrument INSX in

2. Enter the instrument root directory created for the Exercise Instrument:

cd ../INSX

3.3.2.2 Adapting the Installation Configuration File

The purpose of this step is to adapt the Instrument Installation Configuration what concerns the CCS Environments, LCC Environment and the CCS Scan System. In addition the detector systems provided by the system are defined.

For further information about CCS services consult the CCS User Manual.

Steps: 1. Open the “~/INSX/inins/config/ininsINSTALL.cfg” configuration file in a text editor. 2. Remove MC68040 from “INSTALL.MODULE.CPU” since we are not using this board.

3. We will work only with the “winsx”, “linics1” and “wintcs” environments. Add line:

INSTALL.ENVS.AVAIL "winsx linics1 wintcs"

below the “INSTALL.LCUENV3.*” block, to signal which environments to build and use. NO-LCU: To run without the ICS LCU, leave out “linics1”.

4. Remove IRACE and FIERA detectors from the system. Comment out the entries for “INSTALL.DET1” and “INSTALL.DET3” (“DET1” will become the NGC/IR detector system in the exercise instrument).

5. Remove the module “indirdcs” from the list of modules to install. Comment out the keywords

“INSTALL.MODULE35.*”.

6. Set keyword “INSTALL.SCAN5.REMOTEENV” to “wintcs”.

7. Add this line at the top of the installation configuration after the existing “APPEND” keyword to have the TCS Simulator included in the configuration:

INSTALL.APPEND2.FILE "ininsINSTALL_TCSSIM.cfg";

3.3.2.3 Adapting the TCS Simulator Configuration

The purpose of this step is to configure the TCS Simulator to make it ready for usage in connection with the exercise instrument. The TCS Simulator will be running on the same WS as the instrument SW.

Steps: 1. Open the TCS Simulation Configuration File,

“~/INSX/inins/config/ininsINSTALL_TCSSIM.cfg”, with a text editor.

2. Replace the contents with the following configuration:

# NOTE: RTAPENV1 - winsx

INSTALL.RTAPENV2.NAME "wintcs";


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

18 of 51


INSTALL.RTAPENV2.TPLSRC "inins/ENVIRONMENTS/wintcs";

# Installation Hook for the TCS Simulation Package.

INSTALL.HOOK2.NAME "AFTER_CREATE_SCAN";

INSTALL.HOOK2.PLUGIN "tcssimInstall.sh";

3.3.2.4 Adapt the Instrument Configuration

The purpose of this step is to carry out the basic (initial) adaptation of the Instrument Configuration File in order to make it possible to build our instrument. The end result is only a minor step towards the final solution. i.e., further adaptation will have to be done at a later stage.

The INS framework provides the skeleton of the instrumentation SW that can be customized by an instrument developer through configuration files.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

19 of 51


Steps: 1. Open the Instrument Configuration File, “~/INSX/MS/inmcfg/config/inmcfgINS.cfg”, in a text

editor.

2. Locate the keyword “INS.CON.LCUENV2” and add this line:

INS.CON.LCUAV2 F; # LCU 2 not available

Normally this configuration file should be cleaned up completely, i.e. all unused devices removed, and the documentation in the source file updated, e.g. the table showing the devices, etc. Due to time constraints we will refrain from doing a complete update at this point. During the next session we will continue the adaptation of the Instrument Configuration File.

3.3.2.5 Adapt the Start-up Configuration

The purpose of this step is to adapt the Instrument Start-Up Configuration to make it possible to start our first, rough version of INSX.

The Instrument Start-Up Configuration defines how to start-up and initialize the various components constituting the instrument.

Steps: 1. Open the Start-up Configuration, “~/INSX/MS/inmcfg/config/inmcfgSTART.cfg”, in a text

editor.

2. Put “OCS.DET1.ACCESS”, “OCS.DET3.ACCESS” and “OCS.DET5.ACCESS” to “IGNORE”, as we don‟t want to start up the IRACE, FIERA and NGC/OPT detector systems.

3. NO-LCU: To operate without an ICS LCU set the key “OCS.INS1.SWSIM” to “LCU_SIM”.

3.3.2.6 Build the SW for the Exercise Instrument

The purpose of this step is to actually build and generate all the bits and pieces of object files and libraries, DB configuration files, etc. which make up the first version of INSX. Furthermore, the various CCS and LCU Environments involved are created and initialized.

Steps: 1. Invoke the PKGIN Build Tool:

cd ~/INSX

pkginBuild inins

The above step will take a while.

3.3.2.7 Start the Instrument

The purpose of this step is to start-up the initial instrument and to verify that the environment and the SW components etc. involved seem to be correctly generated from the configurations.

Steps: 1. Login in to the IWS as user “insx”.

2. Start the instrument SW:

ininsStart

3. In the INSX Control Panel appearing, start the INSX Engineering Panel (Engineering -> GUI) and bring the following subsystems ONLINE: TCCD DCS, NGC/IR and ICS.

4. Shut down the instrument by invoking the shut-down tool, “ininsStop”.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

20 of 51


Scripts “ininsStart” and “ininsStop” are start up tools encapsulating a generic tool based on the “osb” and “stoo” packages.

The basic GUIs provided at this stage, should merely be seen as simple implementations of the actual GUIs, which will have to be implemented for the real deployment of the instrument at the telescope.

3.4 Session Summary

During this exercise we have made the very basic preparations to start building the Exercise Instrument. We have set up the environment, retrieved the Instrument Integration Module of the Template Instrument Package and adapted the very basic parameters. Then we retrieved the rest of the modules, pertinent to the Template Instrument from CMM, and did all necessary renaming using the provided tools. Finally, we rebuilt the SW and executed the very first start up and shutdown procedures. Note, normally at this stage in the project, we should create the CMM modules belonging to the INSX Instrument in CMM. Due to the logistics handling of this, we will refrain from doing this in connection with this exercise. What we have now is an intermediate version of the instrument. It is possible to start the instrument and do various basic actions, everything in simulation. In the next sessions we will be looking into implementing more specific details of the instrument.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

21 of 51


4 Exercise #2: Instrument Control Software - ICS

4.1 Purpose

The purpose of this session is to implement the Instrument Control SW, ICS, of the instrument. The device configuration of XXXX, which we modified slightly during the first session, will be adapted to reflect the exact configuration of INSX. During this session the course participant will get a walk-through the details related to the ICS. It will provide an overview of configuration parameters for various devices and how these are mapped into the running ICS. At the end of the session, the ICS of the instrument should be obtained, running in simulation on the ICS LCU. It should be possible to connect the real devices and let it run in the normal mode at a later stage.


4.2.1 Devices

The exercise instrument supports the following standard devices:

# Name FITS Prefix ICB Class LCU Details Comments

1 FILT FILT1 icbMOT_FILTER 1 Filters: H, J, Y - Filter Wheel 1

2 MIRR MIRR1 icbMOT_MIRROR 1 Positions: In, Out - Mirror 1

3 LAMP1 LAMP1 icbLAMP 1 On/off. - Lamp 1

4 SHUT SHUT1 icbSHUTTER 1 Open/closed. - Shutter 1

5 YOKO SENSOR1 icbSEN_DX200 1 - - Yokogawa DAQ Station 1

A “Standard Device” is a hardware device for which a driver is provided by the VLTSW and no coding is needed to incorporate it into an instrument. The term “Special Device” is used to describe an application that has to be developed in order to control hardware that is not supported by the VLTSW.

4.2.2 Location of Relevant Configuration Files

To add/remove a device to/from a VLT instrument the following configuration files should be adjusted:

1. Device configuration; file “inmcfgINS.cfg”.

2. Instrument DB; files “iniEnv1.db” and “iniEnv.db”.

3. Scan links; file “linics1.scan”.

4. LCU default DB configuration; file “iniConfigLib.tcl”.

5. WS simulation DB; file “iniSIM_CONTROL.class”.

6. Instrument Dictionary; files “dicINSX*.txt”.

4.3 Exercise Steps

4.3.1 Adapting the Instrument Configuration

During this step we will update the device configuration of the instrument to reflect the actual configuration. We will leave only four existing devices in the system: “FILT”, “MIRR”, “LAMP1” and


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

22 of 51


“TSH” (to be renamed into “SHUT”). Then we will add the fifth device (“YOKO”) so the total number of devices for this session is five.

Steps: 7. Open the Instrument Configuration, "~/INSX/MS/inmcfg/config/inmcfgINS.cfg", in a text editor.

8. Locate the device summary list (keywords of type: "INS.CON.DEVICE*"). Set the number of

devices to 5 ("INS.CON.DEVNUM=5”).

9. Remove all the irrelevant devices from the configuration file. Leave only devices with FITS prefix “LAMP1”, “SHUT1”, “FILT1”, “MIRR1” and “SENSOR1”. Both the "INS.CON.DEVICE*" and the specific definitions of each device should be removed (keywords of the type e.g. "INS.ADC1.DEVNAME" and "INS.SENSOR2". Last device: "INS.MIRR2").

10. Rename “TSH” to “SHUT” by replacing the following for “SHUT1”:

INS.SHUT1.DEVNAME "shut"

INS.SHUT1.DEVDESC "Entrance shutter"

INS.SHUT1.ID "SHUT"

INS.SHUT1.NAME "Entr_Shutter"

11. Device “MIRR1” has two named positions, “In” and “Out”. Define them as the follows:

INS.MIRR1.POSNUM 2

INS.MIRR1.POSID1 "Out"

INS.MIRR1.POSID2 "In"

INS.MIRR1.ID1 "Out"

INS.MIRR1.NAME1 "Out"

INS.MIRR1.ID2 "In"

INS.MIRR1.NAME2 "In"

12. Define the positions for the filter wheel, the definition should look like this:

INS.FILT1.DEVNAME "filt"

INS.FILT1.DEVDESC "Filter wheel"

INS.FILT1.LCUID 1

INS.FILT1.SWSIM T

INS.FILT1.POSNUM 3

INS.FILT1.POSID1 "H"

INS.FILT1.POSID2 "J"

INS.FILT1.POSID3 "Y"

INS.FILT1.ID1 "H"

INS.FILT1.NAME1 "H"

INS.FILT1.ID2 "J"

INS.FILT1.NAME2 "J"

INS.FILT1.ID3 "Y"

INS.FILT1.NAME3 "Y"


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

23 of 51


13. Add the Yokogawa configuration below the “INS.MIRR1” block of keywords (ensure the existing definition for “INS.SENSOR1.*” has been removed):

#

# Sample YOKOGAWA DX200 DAQ Station

#

INS.SENSOR1.DEVNAME "yoko"; # Name of the ICS device

INS.SENSOR1.DEVDESC "YOKOGAWA DX200 DAQ"; # Description of the device

INS.SENSOR1.DEVTYPE "DX200"; # Device type

INS.SENSOR1.LCUID 1; # Id. of the LCU managing device

INS.SENSOR1.SWSIM T; # If T, function is SW simulated

INS.SENSOR1.PORT "/tyCo/3"; # Hardware device

INS.SENSOR1.NUM 3; # Number of managed sensor values

INS.SENSOR1.NAME1 "CH1"; # Sensor value name

INS.SENSOR1.DESC1 "Temp 1"; # Sensor value description

INS.SENSOR1.HEADER1 F; # If T, report sensor value in header

INS.SENSOR1.FITS1 "INS.SENS1.VAL"; # Sensor value FITS keyword

INS.SENSOR1.SENUNIT1 "C"; # Sensor value unit

INS.SENSOR1.SENADDR1 01; # Sensor value hardware address

INS.SENSOR1.LOG1 T; # If T, function is SW simulated



INS.SENSOR1.HEADER2 F; # If T, report value in FITS header







INS.SENSOR1.HEADER3 F; # If T, report value in image header





14. Re-number the devices in the device summary list (keywords of type: "INS.CON.DEVICE*"), according to the table listing all devices above. There should be five of them as it is shown below:

INS.CON.DEVNUM 5; # Number of ICS devices

INS.CON.DEVICE1 "INS.LAMP1"; # Device FITS prefix used in the config file

INS.CON.DEVICE2 "INS.SHUT1"; # Device FITS prefix used in the config file

INS.CON.DEVICE3 "INS.FILT1"; # Device FITS prefix used in the config file

INS.CON.DEVICE4 "INS.MIRR1"; # Device FITS prefix used in the config file

INS.CON.DEVICE5 "INS.SENSOR1"; #Device FITS prefix used in the config file

15. Set all “LCUID” keywords equal to “1”, i.e. we reassign all the devices to LCU #1.

16. Leave only the assembly that contains the word “INS.MODE” and set its index to 1. Remove all other assemblies. If needed, they will be defined at a later stage:

#

# 2.2 ICS Assemblies

#

# INS.MODE:

# Accept any value of INS.MODE and do not forward this key to the LCUs.

INS.ASSEMBLY1 "INS.MODE";

INS.ASSEMBLY1.KEY1 "*"

INS.ASSEMBLY1.VAL1 ""

17. Comment out all lines containing “OCS.MODE*” keywords. These define observation modes, which will be defined during the OS session (Session 5).


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

24 of 51


18. The ICS GUI is a generic panel that is dynamically created from the instrument configuration file. Our ICS GUI will have two notebooks; the first one showing motors (tab #1) and lamps and shutters (tab #2), and the other one showing the Yokogawa widget. To configure the layout of the widgets on the ICS Engineering GUI search for word UIF and adjust the GUI definition to the following:

INS.UIF.NBOOKS 2

INS.UIF1.TABS 2

INS.UIF2.TABS 1

INS.UIF1.LABEL1 "Motors"

INS.UIF1.LABEL2 "Lamps/shutters"

INS.UIF2.LABEL1 "YOKO"

INS.LAMP1.UIFNB 1

INS.LAMP1.UIFTB 2

INS.SHUT1.UIFNB 1

INS.SHUT1.UIFTB 2

INS.SENSOR1.UIFNB 2

INS.SENSOR1.UIFTB 1

19. Build and install the configuration:

cd ~/INSX/MS/inmcfg/src

make clean all install

By installing the ICB Instrument Configuration directly from the “inmcfg” time is saved compared to installing it through “pkginBuild”. This is in particular important when working on the adaption of the configuration iteratively.

4.3.2 Adjusting Instrument DB

The Instrument DB definition can be found in the module “ini”, under the “dbl” directory. The top level file is called “iniEnv.db”. It essentially includes the DB definitions of all existing LCU‟s. In our case we have only one LCU and therefore the inclusion of LCU2 should be removed.

4.3.2.1 Adjusting the DB Definition “iniEnv.db”

Steps: 1. Open the DB Configuration file "~/INSX/ICS/ini/dbl/iniEnv.db", in a text editor.

2. Since LCU2 does not exist, comment out the line “#include "iniEnv2.db"“.

3. Comment also the line adding the historian tables which are not going to be used during this

exercise (“#include “iniHISTORIAN.db”).

4. Open file "~/INSX/ICS/ini/src/Makefile", in a text editor.

5. Remove reference to “iniEnv2(.db)” and “iniHISTORIAN(.db)”.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

25 of 51


5.3.2.2 Adjusting LCU DB Configuration “iniEnv1.db” NO-LCU: This part may be skipped if no LCU is used. During this step we will modify the LCU DB definition file. This means, defining DB points for the devices of our instrument. Currently the DB definition is spread over two files, one for each LCU. We will move all needed devices into the file “iniEnv1.db” and remove the rest, including the file “iniEnv2.db”. Yokogawa DB will also have to be added.

Steps: 1. Open the two environment DB Configuration files "~/INSX/ICS/ini/dbl/iniEnv1.db" and

"~/INSX/ICS/ini/dbl/iniEnv2.db” from the same directory, with a text editor.

2. In file "iniEnv1.db" remove all devices but “FILT” and “MIRR”.

3. From file "iniEnv2.db" copy definitions for “LAMP” and “TSH” into file "iniEnv1.db".

4. Remove file "iniEnv2.db".

5. In file "iniEnv1.db" rename “TSH” to “SHUT” and “tsh” to “shut”.

6. In the same file set “lcuId” to 1 for all devices.

7. Add a DB point for the Yokogawa device “iniEnv1.db”:

//************************************************************************

// Device YOKO

//

POINT icbSEN_DX200 :Appl_data:INSX:ICS:DEVICES:YOKO

BEGIN

ALIAS YOKO

ATTRIBUTE bytes20 device "yoko"

ATTRIBUTE bytes16 prefix "INS.YOKO"

ATTRIBUTE int32 lcuId 1

END

4.3.3 Configuring Scan Links

NO-LCU: This part may be skipped if no LCU is used. During this part of the exercise, we will define the scan link set-up between the environments involved in our instrument. Again, we have to group all relevant definitions into a single file “linics1.scan” and remove the other file “linics2.scan”.

Steps: 1. Open the scan links configuration file "~/INSX/ICS/ini/config/linics1.scan", with a text editor.

2. Leave only the entries for devices “FILT” and “MIRR”. Remove the rest.

3. Open the scan links configuration file "~/INSX/ICS/ini/config/linics2.scan", with a text editor.

4. Copy entries for “LAMP”, “TSH” and “FCS” to “linics1.scan”.

5. Remove file “linics2.scan”.

6. In file “linics1.scan” rename “TSH” to “SHUT” and “FCS” to “YOKO”.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

26 of 51


7. DB attribute “<alias>MIRR:MOTOR:STATUS.posEnc” is used to verify scan links when starting the instrument. The verification attribute should always be the last entry in the scan configuration file. Move “MIRR” block of lines to the end of the file.

If the ICS LCU is not used, i.e., not in the list contained in the keyword “INSTALL.ENVS.AVAIL” in the Installation Configuration, it will not be attempted to create scan links.

Having the attribute to verify scan links as the last entry in the scan configuration will ensure that others attributes are correct in case verification is successful.

4.3.4 Setting Default LCU DB Configuration

NO-LCU: This part may be skipped if no LCU is used. Every time an LCU is rebooted, the DB configuration file “$VLTDATA/config/<LCU name>.dbcfg” (e.g. “linics1.dbcfg” in this case) is loaded into the LCU DB. The input for the creation of this file is taken from the configuration defined in the file “inmcfgINS.cfg”. The DB configuration file can be manually created by entering at command line:

> icbConfigSet INSX

It could also be manually changed and re-loaded into the LCU with following:

> dbRestore -f /vltdata/config/linics1.dbcfg

During the build process, “pkginBuild” does this automatically through the defined plug-in:

INSTALL.HOOK1.PLUGIN "icbInstallHook INSX";

How the file is created (the mapping between the keywords and the corresponding DB attributes) is defined in script “iniConfigSet.tcl”, which is known to the system through the keyword “INS.CON.CONFIGSET”, defined in the Instrument Configuration, “MS/inmcfg/config/inmcfgINS.cfg”. It is important to note that for standard devices the user does not have to do anything since this is automatically handled by the system. Changes are only required when special devices are added to or removed from the instrument. Handling of special device keywords are done in file “iniConfigLib.tcl” that is internally called by “iniConfigSet.tcl”. In our case we have to remove the entry for device “INS.MIRR2” which does not exist in INSX.

Steps: 1. Open the file "~/INSX/ICS/ini/src/iniConfigLib.tcl", with a text editor.

2. Comment out the line:

set specialDevices { "INS.MIRR2" };

4.3.5 Adjusting Instrument WS Simulation DB

The WS simulation DB is used to handle SETUP and STATUS commands in WS simulation. It maps keywords and corresponding DB attributes. When a SETUP command is sent, the value of the keyword is written into the DB. The STATUS command returns values saved in the DB.

Steps: 1. Open the file "~/INSX/ICS/ini/dbl/iniSIM_CONTROL.class", with a text editor.

2. Leave only the entries for “LAMP1”, “SHUT1” (“TSH”), “FILT1”, “MIRR1” and “SENSOR1”.

Remove the rest.

3. Rename “TSH” to “SHUT” and “FCS” to “YOKO”.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

27 of 51


4.3.6 Adjusting Instrument Dictionary

Instrument dictionary is necessary to be updated when new keywords are added to the instrument. For the time being we do not have to change anything.

4.3.7 Setting Simulation Level

If the ICS LCU “linics1” is available still no hardware is connected. Therefore, the access to the LCU is “NORMAL” (key: “INS.CON.OPMODE”) but “SWSIM” for each device is set to “T” in the Instrument Configuration, “~/INSX/MS/inmcfg/config/inmcfgINS.cfg”. If no ICS LCU is available, set “INS.CON.OPMODE” to “LCU_SIM”.

Steps: 1. Open the file "~/INSX/MS/inmcfg/config/inmcfgSTART.cfg", with a text editor.

2. Set keyword “INS.CON.OPMODE” to “NORMAL”. NO-LCU: If no ICS LCU is available, set the

value to “LCU_SIM”.

4.3.8 Adapt the “pkgin” configuration file

The purpose is to correct the verification of the scanning according to the real instrument devices.

1. Open the file "~/INSX/inins/config/ininsINSTALL.cfg", with a text editor.

2. Change “TILT” to “MIRR” in scanning source attribute in “INSTALL.SCAN1.SRCATTR”.

4.3.9 Build and Install Updated Modules

Steps: 1. Enter the ICS module and build and install it:

cd ~/INSX/ICS/ini/src


2. Enter the ICS Configuration Module and build and install it:



Note, we install only the configuration files (selectively) that were changed during the previous steps. Invoking “pkginBuild inins –step INSTALL_FILES” would have the same effect but the approach above is more efficient.

4.3.10 Re-building the SW

The configuration is ready for a complete rebuild. At the end, the ICS LCU will be rebooted. Execute the following lines as user “insxmgr”:

Steps: 1. Build the entire instrument package, starting from the CCS/LC environments:

cd ~/INSX

pkginBuild inins –fromstep BUILD_ENV

4.3.11 Starting ICS

We will start the ICS and bring it ONLINE. Execute the following lines as user “insx”:

Steps: 1. Start the ICS daemon processes:


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

28 of 51


ininsStart -proc ICS

2. Start the ICS Control Panel:

ininsStart -panel ICS

3. On the ICS Control GUI select ONLINE from the ICS pull-down menu to bring the ICS ONLINE.

4. Test the SETUP command with motors, lamps and shutters.

A start-up tool (here “ininsStart”) is automatically generated for an instrument, when the new instrument SW code base is derived from the Template Instrument. Also a tool to shut down the system, or parts of it, is generated (“ininsStop”). By using the start-up utility with the “-proc” and “-panel” options, it is possible to start specific parts of the system. For a list of all possible options for an instrument, invoke the tool like this, e.g.: “ininsStart –proc x”.

Figure 3: ICS Control Panel.

NO-LCU: If no ICS LCU is used, the DB attributes of the devices are only partially updated and the output fields in the ICS Control Panel, will have different values than shown above.

4.4 Session Summary

In this session we learned the necessary steps to configure the instrument ICS, including the GUI, starting from the existing ICS configuration of the Template Instrument. At the end of the session we were able to run the ICS in HW simulation.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

29 of 51


5 Exercise #3: Interfacing with Detector Control Systems

5.1 Purpose

The purpose of this session is to define the configuration of the detector systems which are part of the Exercise Instrument. The goal is to be able to take exposures with the scientific and technical DCS in standalone mode and verify that the images are properly generated and can be displayed with the corresponding RTD applications. The intention with this session is not to provide a detailed insight into the NGC/IR and TCCD SW packages. The main purpose is to make the course participants acquainted with these packages and to demonstrate how to integrate/adapt them into the instrument SW.

5.2 Exercise Steps

5.2.1 Adapt the Instrument Configuration for RTD Start-Up

Here only one keyword is adapted. This is done because it is required by the start up tool (“stoo”) to start properly the NGC IR Real Time Display. The other detector configuration keywords will be adapted in the OS session. Steps:

1. Open instrument configuration file “~/INSX/MS/inmcfg/config/inmcfgINS.cfg” and change the contents of keyword “OCS.DET4.SDMAHOST” to the Exercise Instrument WS as it is shown below:

OCS.DET4.SDMAHOST "winsx"

2. Build and install the new configuration:



5.2.2 Adapting the NGC IR Detector Configuration

The NGC/IR configuration can be separated in two main parts: High Level configuration and System and Detector configuration. The High Level configuration is the first configuration level for the NGC/IR SW and is used at the process start-up. It is important to point out that is compliant with the INS Configuration Tool (“ctoo”) and does the mapping between the NGC IR and its System configuration. The System and Detector configuration covers low level details about the controller electronics and detector.

5.2.2.1 Updating the High Level NGC IR Configuration

The purpose of this step is to edit the default ctoo configuration defining the configuration sets and the right NGC system configuration name. The configuration file “innngcirNGCIR1.cfg” will be reused for the Exercise Instrument.

Steps: 3. Go to the NGC configuration directory:

cd ~/INSX/DCS/inngcir/config/

4. Remove default configuration files which are not needed for the Exercise Instrument:

rm inngcirNGCIR2.cfg

5. Open the “ctoo” configuration file, “~/INSX/DCS/inngcir/config/inngcirCONFIG.cfg, and remove the second configuration set (all keywords starting with “CONFIG.SET2*”) as this is not used.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

30 of 51


5.2.2.2 Update the NGC System and Detector Configuration

The purpose of this step is to edit the default NGC configuration according to the specifics characteristics of the scientific detector of the Exercise Instrument.

The configuration shall be done under the following assumptions about the scientific detector:

Mosaic with 2 virtual chips along axis X.

Each chip size is 512x512 pixels.

Physical mosaic gap is 20µm.

2 Readout modes: “Uncor” and “Double”.

Acquisition Process: “ngciracqH2RG1”.

For simplicity, clock pattern definition, voltages and sequencer program will not be configured and we will use the same definition from the Template Instrument.

An Acquisition Process is a multi-threaded process running in the NGC LCU doing the data acquisition and pre-processing.

Steps: 1. Go to the NGC configuration directory:

cd ~/INSX/DCS/inngcir/config/NGCIRSW

2. Remove default Detector Configuration Files which are not needed for the Exercise Instrument:

rm inngcirDetNGCIR2.dcf inngcirSysNGCIR2.cfg

3. Update the detector configuration:

a. Open the Detector Configuration File: “~/INSX/DCS/inngcir/config/NGCIRSW/inngcirDetNGCIR1.dcf” and change the number of detector outputs to 64 (keyword: “DET.OUTPUTS”). The new setting should looks like the following:

DET.OUTPUTS 64; # total number of outputs

b. Remove the index of the all chip keywords replacing “DET.CHIP1” by “DET.CHIP”. The new settings should look like the following, e.g.:

DET.CHIP.NAME "myChipName"; # chip name

DET.CHIP.ID "myChipId"; # chip id

…

DET.CHIP.ACQIDX 0; # map to acquisition module

c. Change the detector size to 1024x512 pixels (keywords: “DET.CHIP.NX” and “DET.CHIP.NY”. The new settings should looks like the following:

DET.CHIP.NX 1024; # number of pixels along x

DET.CHIP.NY 512; # number of pixels along y

d. Define the physical detector gap adding only the gap along axis X (keywords: “DET.CHIP.XGAP” and “DET.CHIP.YGAP”). The new settings should looks like the following:

DET.CHIP.XGAP 20; # gap between chips along x

DET.CHIP.YGAP 0; # gap between chips along y


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

31 of 51


e. Split virtual chip into a mosaic defining properly the split keywords to define two extensions along axis X (keywords: “DET.ACQ1.SPLITX” and “DET.ACQ1.SPLITY”). The new settings should look like the following:

DET.ACQ1.SPLITX 2;

DET.ACQ1.SPLITY 1;

f. Add the specific configuration for the two virtual chips as follows:

DET.CHIP1.ID "chipId1";

DET.CHIP1.TYPE "IR";

DET.CHIP1.INDEX 1;

DET.CHIP1.X 1;

DET.CHIP1.Y 1;

DET.CHIP2.ID "chipId2";

DET.CHIP2.TYPE "IR";

DET.CHIP2.INDEX 2;

DET.CHIP2.X 2;

DET.CHIP2.Y 1;

g. Set the acquisition processes for the two read-out modes: Uncor and Double (keywords: “DET.READ1.ACQ1” and “DET.READ2.ACQ1”). The new settings should look like the following:

..

DET.READ1.ACQ1 "ngciracqH2RG1 -map 2"; # acquisition process

..

DET.READ2.ACQ1 "ngciracqH2RG1 -map 2"; # acquisition process

..

4. Go to the NGC configuration source directory and install the updated configuration:

cd ~/INSX/DCS/inngcir/src


The next step is to verify that NGC infrared SW is working properly after to have carried out all the above steps.

5.2.2.3 NGC IR Verification

The purpose of this step is to verify that NGC infrared detector SW is working in standalone mode. Check that the images are properly generated and they fulfil the specification of the Exercise Instrument detector (number of extensions, chip size, physical gap, etc.). A few remarks:

All the verifications steps should be done as user “insx”.

The RTD configuration is based in what was defined for the Template Instrument and therefore will not be modified.

Steps: 1. Start the logMonitor if is not already running. 2. Start the NGC Infrared SW:

ininsStart -proc NGCIR1

If everything goes well, the following logs should appear:

> ininsStart -proc NGCIR1

-> INIT : Reading INSX configuration.

INSX> START: Thu Aug 27 13:53:55 UTC 2009

INSX> ARGS : -proc NGCIR1.

INSX> START: Starting INSX DCS NGCIR1 (WS SIMULATION) . . .

INSX> Process INSX DCS NGCIR1 process ngcircon_NGCIR1: started.

INSX> INSX DCS NGCIR1 started.

INSX> END : Start end.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

32 of 51


3. Verify that processes are running:

psg ngcir

You should see the following process:

ngcircon –db ngircon –ins NGCIR1 –cfg NGCIRSW/inngcirSysNGCIR1.cfg …

4. Verify that no errors are reported at the process start-up looking at the logMonitor. 5. Start the NGC Infrared standalone panel using the “stoo” tool:

ininsStart -panel NGCIR1

6. Put the system to ONLINE state and verify that the main server is online and the simulation mode is well defined as shown in Figure 4.

Figure 4: NGCIR Standalone panel – state, mode and exposure name.

7. Specify the name for the image to be generated, e.g. “firstImage”. Enter value in “Name:” input field and press return.

8. Define the detector integration (DIT), e.g. 2 seconds as is shown in Figure 5 (enter value and press return).

Figure 5: NGCIR standalone panel – DIT specification.

9. Start the exposure by pressing “Start” button shown in Figure 4. Wait until the image is produced. The final exposure status should be “success”.

10. VLT instruments save the images in the directory: “$INS_ROOT/SYSTEM/DETDATA”, go there and verify that image just taken is completed using the standard RTD application (“rtd”)

2.

When you start RTD giving as parameter the name of the file (see below), you will see the image displayed and a pop-up window with the FITS HDU specification as is shown in Figure

2 The standard RTD application is used only to verify that contents of the image are correctly defined loading the

FITS file from disk. For real time display, NGC Infrared RTD shall be used.

NGC IR Server state NGC IR Server

simulation mode

File name specification

Detector Integration (DIT) specification


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

33 of 51


6. If you press “Display as one Image” button you will see the mosaic of two detectors along axis X as is shown in Figure 7:

cd $INS_ROOT/SYSTEM/DETDATA

rtd firstImage.fits3

Figure 6: RTD FITS HDU pop-up window.

Figure 7: RTD displaying the output image of the NGCIR detector of the Exercise Instrument.

11. Check the contents of the main image header and extensions by selecting the option “Fits

header...” from the “View” menu as is shown in Figure 8.

3 Put here the name of the image that you have chosen.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

34 of 51


Figure 8: RTD displaying the image header information.

12. Start the NGC Real Time Display. The DIT frames should appear in the display as is shown in Figure 9:

ininsStart -panel NGCIR1_RTD

Figure 9: NGC Infrared Real Time Display.

5.2.3 Update the TCCD Configuration

The purpose is to define the right CCD chip configuration. In case of the Exercise Instrument, the chip configuration is the one already available in the VLTSW release but not the same defined for the Template Instrument so it needs to be changed. Steps:

1. Open instrument configuration file “~/INSX/MS/inmcfg/config/inmcfgINS.cfg” and change the contents of keyword “OCS.DET2.DBFILE” to the Exercise Instrument WS as it is shown below:

Main image header and two extension headers.

Chip size.

Detector physical gap information.

The “green spot” is an indication that image events are being received.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

35 of 51


OCS.DET2.DBFILE "ccdTecE2V47.dbcfg";

2. Change the default simulation level adding keyword “OCS.DET2.SWSIM” in the configuration:

OCS.DET2.SWSIM "LCU_SIM";

3. Build an install the new configuration:



5.2.4 Update ICB Installation Configuration for the TCCD

Steps: 1. Open file “~/INSX/inins/config/ininsINSTALL.cfg” and change the contents of keyword

“INSTALL.DET2.DBFILE” as it is shown below:

INSTALL.DET2.DBFILE "ccdTecE2V47.dbcfg";

2. Update the TCCD configuration file in the INS_ROOT directory with “pkginBuild”:

pkginBuild inins -step INSTALL_CCD TCCD

“pkginBuild -step INSTALL_CCD” will copy the detector configuration files from the VLTROOT in the instrument directory (INS_ROOT). The CCD SW will load the configuration from there at the process start-up.


=============================================================================

pkginBuild started at Wed Sep 24 07:58:15 UTC 2008

Arguments = 'inins -step INSTALL_CCD TCCD'

Host = 'Linux winsx 2.6.9-prep #1 Tue Oct 2 08:10:51 UTC 2007 i686 i686 i386

GNU/Linux'

PWD = '/home/insxmgr/MKI/Session2/INSX'

VXROOT = '/vlt/VLT2008/vw5.5/target'

VLTROOT = '/vlt/VLT2008/CCSLite'

INTROOT = '/vlt/INSX/INTROOT'

INS_ROOT = '/data/INSX/INS_ROOT'

-----------------------------------------------------------------------------

For error and status messages please refer to the files:

/home/insxmgr/MKI/Session2/INSX/INSTALL/pkginBuild.log

/home/insxmgr/MKI/Session2/INSX/INSTALL/pkginBuild.err

=============================================================================

INIT : Reading inins configuration.

Skipped ininsINSTALL_VLTSW.VLT2008.cfg (not found).

Reading ininsINSTALL_TCSSIM.cfg.

-----------------------------------------------------------------------------

START: Installing detectors:

Detector TCCD: ACE tccd in lintccd ... OK.

START: OK.

-----------------------------------------------------------------------------

pkginBuild ended at Wed Sep 24 07:58:24 UTC 2008 (00:00:09)

=============================================================================

5.2.5 TCCD Verification

The purpose of this step is to verify that TCCD SW is working in standalone mode and the images are displayed.

CCD SW in LCU_SIMULATION mode save images with a fixed filename “ccdImageLcuSim.fits”.

Steps:

1. Start the logMonitor if is not already running. 2. Start the TCCD SW:


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

36 of 51


ininsStart -proc TCCD


-> INIT : Reading INSX configuration.

INSX> START: Tue Sep 23 13:57:07 UTC 2008

INSX> ARGS : -proc TCCD.

INSX> START: Starting INSX DCS TCCD (WS SIMULATION) . . .

INSX> INSX DCS TCCD started.

INSX> END : Start end.

INSX> END : Tue Sep 23 13:57:11 UTC 2008

3. Verify that processes are running:

psg ccd

You should see the following processes:

insx 12141 1 0 13:57 pts/3 00:00:00 ccdconCI tccd

insx 12142 1 0 13:57 pts/3 00:00:00 ccditWs tccd

4. Verify that no errors are reported at the process start-up looking at the logMonitor. 5. Start the TCCD standalone panel:

ininsStart -panel TCCD

6. Place the TCCD SW online sending the command to the front-end process and verifying that configuration is correct and the state is reached as is shown in Figure 10:

msgSend "" ccdconCI_tccd ONLINE ""

Figure 10: CCD Standalone panel (top part).

7. Start the RTD Display and attach to the camera (use the “Start Display” button at the bottom of the CCD standalone panel). Take an image of 1 second and wait until status is finish. You should see the image displayed in the RTD as is shown in Figure 11.

Camera Name

Chip ID Simulation Level

SW state


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

37 of 51


Figure 11: TCCD image (LCU simulation).

5.3 Session Summary

This session involved the configuration of the detector systems for the Exercise Instrument and their verification in standalone mode. The course participant should have have gained some insight into the process of preparing the different configuration files associated with the NGC infrared and technical CCD SW.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

38 of 51


6 Exercise #4: Observation Software – OS

6.1 Purpose

The purpose of this session is to configure all the OS subsystems and the supported observation modes of the Exercise Instrument.


The observation modes foreseen for the Exercise Instrument are the followings:

IMAGING: Direct imaging using the two detectors.

CALIBRATION: Special mode for the technical detector intended for calibrations.

The behaviour of OS is defined via configuration keywords. This covers all the basic information about the each subsystem that will be coordinated by the OS [RD11]. OS configuration keywords have the following format: OCS.<CAT>.i.NAME. Where <CAT> can be one of the following categories: DET, INS, OS and TEL [RD11].

6.3 Exercise Steps

6.3.1 Configure OS Subsystems

Steps: 1. Open the configuration file “~/INSX/MS/inmcfg/config/inmcfgINS.cfg”. 2. Update the telescope environment name (keyword “OCS.TEL.ENVNAME”) as is shown below

so that the OS server knows how to contact the TCS:

OCS.TEL.ENVNAME "wintcs”

3. Remove the IRACE (IRDCS) subsystem from the OS part of the instrument configuration i.e. all keywords starting with “OCS.DET1”. These keywords are left over from the Template Instrument. They are intended for an IRACE system, which is not part of the Exercise Instrument.

4. Remove the FIERA subsystem from the OS configuration. i.e. all keywords starting with

“OCS.DET3”. 5. Update the index of the remaining detector subsystems. Changing all keywords starting from

“OCS.DET4” to “OCS.DET1” (belonging to NGCIR1).

6. Remove all keywords for the optical NGC instance, contained in the Template Instrument but not used for the Exercise Instrument (keywords: “OCS.DET5.*”).

After step 4 - 6 the OS detector configuration should look like the following:

# Subsystem: DET1 - NGCIR1

# --------------------------------------------------------------------------

OCS.DET1.NAME "NGCIR1";

OCS.DET1.DICT "NGCDCS";

OCS.DET1.ENVNAME "winsx";

OCS.DET1.PROCNAME "ngcircon_NGCIR1";

OCS.DET1.KEYWFILT "DET1.*.*.*.*.*.*";

OCS.DET1.TIMEOUT 20;

OCS.DET1.TYPE "NGCIR";

OCS.DET1.CFGSET "NGCIR1";

OCS.DET1.DBROOT "<alias>ngcircon_NGCIR1";


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

39 of 51


OCS.DET1.SDMAHOST "winsx"

OCS.DET1.RTDPORT "7001"

# Subsystem: DET2 TCCD

# ------------------------------------------------------------------------

OCS.DET2.NAME "TCCD";

OCS.DET2.DICT1 "CCDDCS";

OCS.DET2.ENVNAME "winsx";

OCS.DET2.PROCNAME "ccdconCI_tccd";

OCS.DET2.KEYWFILT "DET2.*.*.*.*.*.*,DET.*.*.*.*.*.*";

OCS.DET2.TIMEOUT 20;

OCS.DET2.DBROOT "<alias>tccd";

OCS.DET2.TYPE "ACE";

OCS.DET2.CCDNAME "tccd";

OCS.DET2.CCDLENV "lintccd";

OCS.DET2.DBFILE "ccdTecE2V47.dbcfg";

OCS.DET2.SWSIM "LCU_SIM";

7. Update the number of detectors systems accordingly (keyword “OCS.DET.NUM”):

OCS.DET.NUM 2;

8. Update the observation modes according to the request for the Exercise Instrument (keyword “OCS.MODEi”). The final setting should looks like the following:

#

# 5.5 Instrument modes

#

OCS.MODE1.NAME "CALIBRATION";

OCS.MODE1.SETUP "-function INS.MIRR1.NAME In";

OCS.MODE1.SUBSYST "TCCD ICS UT1";

OCS.MODE1.PATH "TCCD";

OCS.MODE2.NAME "IMAGING";

OCS.MODE2.SETUP "-function INS.MIRR1.NAME Out";

OCS.MODE2.SUBSYST "NGCIR1 TCCD ICS UT1";

OCS.MODE2.PATH "INFRARED";

6.3.2 Update the Start-Up Configuration

Steps: 1. Open the configuration file “~/INSX/MS/inmcfg/config/inmcfgSTART.cfg”. 2. Update the access definition for the detector systems “DET1/2” to “NORMAL”:

OCS.DET1.ACCESS "NORMAL";

...

OCS.DET2.ACCESS "NORMAL";

...

3. Remove keywords in the Start-Up Configuration for the dectector systems, which are not used (“OCS.DET3”, “OCS.DET4” and “OCS.DET5”).

4. Build and Install the module “inmcfg”:



6.3.3 OS Database Configuration

Steps: 1. Update the subsystem list in the main OS server database class (file

“~/INSX/OS/ino/dbl/inoSERVER.class”) and remove the detector subsystems which are not used. Final configuration should be as is shown below:

CLASS bossINTERFACE_LIST inodbSUB_SYSTEMS

BEGIN


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

40 of 51


ATTRIBUTE bossINTERFACE_TCCD tccd

ATTRIBUTE bossINTERFACE_NGCIR ngcir1

ATTRIBUTE bossINTERFACE_ICS ics

ATTRIBUTE bossINTERFACE_TCS tcs

END

2. Build and Install the module “ino”:

cd ~/INSX/OS/ino/src


3. Rebuild the WS environment database:

cd ~/INSX/

pkginBuild inins -fromstep BUILD_ENV -env winsx wintcs

6.3.4 OS Verification

This part should be carried out as user “insx”. Steps:

1. Open a new xterm in order to load the new pecs configuration. 2. Start-up the whole instrument SW. Make sure that start-up settings are as shown in Figure 12:

ininsStartup

If processes are already running they will be restarted by the instrument start up tool.

Figure 12: Instrument SW Start-Up Panel.

3. Press “Start” button and wait until start up is finished. You should see two panels (BOB and

OS Control) and all processes in “STANDBY” state. 4. Check the logMonitor to monitor possible errors.

Note that some errors will be reported by the OS Control panel. This is due to the systems that were removed from the database. Panel should be updated in order to fix this problem; this is described in the exercise below in section 6.3.5 (optional). The errors as such, should not affect the normal operation of this panel.

5. Put the system ONLINE from the “OS_CONTROL” panel (menu “Instrument” option ONLINE). 6. Check that all subsystems are in ONLINE state. The above should exclude system removed

from the configuration like FIERA, IRACE and NGC/OPT detector systems. 7. Verify that all subsystems defined to have „normal access‟ in the ICB Start-Up Configuration,

are accessed by OS as expected:


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

41 of 51


msgSend "" inoControl ACCESS "-info"

The reply should be something like the following:

MESSAGEBUFFER:

UT1 IGNORE

ICS NORMAL

NGCIR1 NORMAL

TCCD NORMAL

8. Open the OS Engineering panel and start-up the TCS Simulation package. This operation can take several minutes:

ininsStart -panel OS_ENGINEERING

9. Enable the OS access to the TCS subsystem using the ACCESS command as is shown below. This can be also done from menu “Telescope” of the OS Engineering panel.

msgSend "" inoControl ACCESS "-subsystem UT1 -mode NORMAL"

10. Check again the access of all the subsystems

msgSend "" inoControl ACCESS "-info"

The reply should be like the following:

MESSAGEBUFFER:

UT1 NORMAL

ICS NORMAL

NGCIR1 NORMAL

TCCD NORMAL

11. Open the TCS Simulation User Panel and preset the telescope to Zenith:

tcssimUser &

12. Verify that telescope coordinates have been updated in the OS control panel:

ininsStart -panel OS_CONTROL

13. Take an exposure with the infrared detector:

msgSend "" inoControl SETUP "-expoId 0 -function INS.MODE IMAGING OCS.DET.IMGNAME

myFirstFile"

msgSend "" inoControl START "-detId NGCIR1"

msgSend "" inoControl WAIT ""

The reply should be like the following:

MESSAGEBUFFER:

Telescope preset to a named position (zenith)


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

42 of 51


Observation status: INTEGRATING

MESSAGEBUFFER:

Exposure status: FINISHED

14. Verify that a FITS file has been generated that contains all the subsystem keywords (“DET”, “INS” and “TEL”):

cd $INS_ROOT/SYSTEM/DETDATA

slxCatFits myFirstFile<day of year>_<number>.fits

6.3.5 Optional: Update the OS Control Panel

As mentioned previously, when starting up the instrument SW, the following error messages are written on stderr, e.g.:

> ininsStartup

inslab1 insx:/data/INSX/INS_ROOT/SYSTEM/DETDATA 1133 > USER DEBUG> DB EVENT ATTACH FAIL for

@winsx<alias>ino:subsystems:fiera.access

Reason : cannot attach event to "@winsx<alias>ino:subsystems:fiera.access"

Invalid DB attribute or filter : VECTORS and TABLES use 'w' filter only

USER DEBUG> DB EVENT ATTACH FAIL for @winsx<alias>ino:subsystems:irdcs.access

Reason : cannot attach event to "@winsx<alias>ino:subsystems:irdcs.access"

Invalid DB attribute or filter : VECTORS and TABLES use 'w' filter only

The reason for these error messages is that the OS Control Panel from the Tamplate Instrument, contains widgets for sub-systems, which are not available for the Exercise Instrument. To fix this, we need to edit the OS Control Panel with the CCS Panel Editor. This is done as follows: Steps:

1. Enter the source directory containing the OS panel Tcl code: “~/INSX/OS/inopan/src”. 2. Start the panel editor (“panelEditor”). 3. Open the source code for the OS Control Panel (“inopanControl.pan”). 4. Edit the panel, remove the widgets for the “IR DCS”, “FIERA” and “NGC/OPT” detector

systems. 5. Save the updated panel. 6. Build and install the updated panel code:

cd ~/INSX/OS/inopan/src


7. Re-start the OS Control Panel:

ininsStart -panel OS_CONTROL

8. Verify that the panel comes up and that the errors no longer appear on the terminal window.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

43 of 51


7 Exercise #5: Templates

7.1 Purpose

The purpose of this session is to implement the Science and Technical Templates and the generation of the Instrument Package (IP) for the Exercise Instrument. Preparation of Observation Blocks using the P2PP tool is out of the scope of this Laboratory Exercise. After having carried out this session the course participant should be able to execute the Observation Blocks automatically generated by the template modules.

7.2 Additional Information

Figure 13: Instrument Templates

An Instrument Template is the basic unit of an observation block and deals with the setup and execution of one or more exposures of a particular type. Each template is made of two parts: a template signature file and a sequencer script. The Template Signature File (TSF) is the definition of all parameters that can be used within the template. The sequencer script (file with extension .seq) implements the behaviour of the template including the execution of one or more SETUP commands. Setup parameters can be defaulted using reference files.

The Instrument Package IP contains all the TSF files needed by the Astronomers to create scientific Observation Blocks for a particular instrument. The IP is used by The Phase 2 Preparation (P2PP) tool to produce and manage the observations.

An Observation Block is the smallest schedulable observational unit for the VLT. It contains all the information necessary to execute sequentially a set of related exposures including one Telescope acquisition. A telescope acquisition is used to specify how a target will be acquired by the telescope. The Observation Block Description (OBD) is the PAF file used to specify an Observation Block


The list of science templates for the Exercise Instrument is based on the assumption of the following request:

1 Normal Acquisition Template ("INSX_img_acq").


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

44 of 51


1 Observation Template for the Imaging Mode ("INSX_img_obs_exp").

The list of technical templates for the Exercise Instrument is based on the assumption of the following request:

1 Bias Template ("INSX_gen_tec_bias").

7.4 Exercise Steps

7.4.1 Optional: Create Snapshot

At this point in the exercise, it might make sense to make a snapshot of the (hopefully) fully functioning Exercise Instrument to be able to roll back if needed. Follow the steps below to do this: Steps:

1. Go to the instrument SW root directory:

cd ~/INSX/

2. Clean up the various modules:

pkginBuild inins -step CLEAN

3. Create the back-up copy of the instrument SW root, e.g.:

cp –r ../INSX ../INSX_backup_<tag>

4. Rebuild the entire SW:

pkginBuild inins

7.4.2 Prepare Science TSF Files

Steps: 1. Go to the scientific TSF module:

cd ~/INSX/OS/inotsf/

2. Remove unnecessary files:

rm src/INSX_opt* src/INSX*spec* src/INSX_irimg_obs*

3. Update the Instrument Summary File (ISF): a. Open the file “~/INSX/OS/inotsf/config/INSX.isf” b. Update observation modes to the ones defined for the Exercise Instrument (keyword:

“MODES”). This should looks like the following:

MODES "IMAGING CALIBRATION"

c. Delete all the lines below comment “OTHER TAGS”. d. Update the CCD window size to the detector characteristics of the Exercise

Instrument (keyword "CCD.WINDOW"). The setting should looks like the following:

CCD.WINDOW "1 1 1024 512"

e. Add the setting for the filters and default parameter values:

FILTERS "H J Y"

IR.NDIT.RANGE "1 1000"

INS.FILT1.NAME.VALUE "H"

DET1.SEQ.DIT.TEST.VALUE "1"

DET2.SEQ.UIT.TEST.VALUE "5"


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

45 of 51


The Instrument Summary File (ISF) contains a summary of the instrument elements which are addressable from the observation preparation tool (P2PP). A template is the basic unit of an Observation Block.

4. Adapt the Acquisition Template Signature File:

a. Go to the sources:

cd ~/INSX/OS/inotsf/src/

b. Rename file “INSX_irimg_acq.tsfx” following the naming convention for templates:

mv INSX_irimg_acq.tsfx INSX_img_acq.tsfx

c. Rename all instances of “irimg_acq” to “img_acq” inside the file:

tooReplace irimg_acq img_acq INSX_img_acq.tsfx

d. Rename file “INSX_ngcirimg_acq_MoveToSlit.tsfx” following the naming convention for templates:

mv INSX_ngcirimg_acq_MoveToSlit.tsfx INSX_img_acq_MoveToSlit.tsfx

e. Rename all instances of “irimg_acq” to “img_acq” inside the file:

tooReplace ngcirimg_acq img_acq INSX_img_acq_MoveToSlit.tsfx

f. Adapt detector index in the include file:

cd ~/INSX/OS/inotsf/include

tooReplace DET4 DET1 inotsfNGCIR_DET_DIT.tsfx

g. Open the TSFX file “~/INSX/OS/inotsf/src/INSX_img_acq.tsfx” and change the associated reference setup file and the sequence script (keywords “TPL.REFSUP” and “TPL.PRESEQ”). The new setting should looks like the following:

TPL.REFSUP "INSX_img_acq.ref"

TPL.PRESEQ "INSX_img_acq.seq"

h. Change the instrument mode (keyword “INS.MODE.VALUE”) as is shown below:

INS.MODE.VALUE "IMAGING"

i. Add the telescope conditional preset keyword by including file “inotsfSEQ_PRESET.tsfx”. We should also include the TSFX file, defining the Instrument Mode. The include entries should looks like the following:

PAF.INCLUDE "inotsfTEL.tsfx"

PAF.INCLUDE "inotsfSEQ_PRESET.tsfx"

PAF.INCLUDE "inotsfINS_MODE.tsfx"

j. Open the file “~/INSX/OS/inotsf/src/INSX_img_acq_MoveToSlit.tsfx” and change the associated reference setup file and the sequence script (keywords “TPL.REFSUP” and “TPL.PRESEQ”). The new setting should looks like the following:

TPL.REFSUP "INSX_img_acq.ref"

TPL.PRESEQ "INSX_img_acq_MoveToSlit.seq"

k. Change the default TPL mode (keyword “TPL.MODE”) as is shown below:

TPL.MODE "IMAGING"

l. Add the telescope conditional preset keyword by including file “inotsfSEQ_PRESET.tsfx”. The include entries should looks like the following:


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

46 of 51


PAF.INCLUDE "inotsfTEL.tsfx"

PAF.INCLUDE "inotsfSEQ_ACQ.tsfx"

PAF.INCLUDE "inotsfNGCIR_DET.tsfx"

PAF.INCLUDE "inotsfSEQ_PRESET.tsfx"

The “SEQ.PRESET” is a keyword used to prevent the telescope preset. This is used to save time when the acquisition template must be repeated and the telescope is already in position. The default value is always true and can only be modified by the Instrument Operator.

5. Adapt the Observation Template Signature File

a. Rename file “INSX_ngcirimg_obs_exp.tsfx” following the naming convention for templates:

cd ~/INSX/OS/inotsf/src/

mv INSX_ngcirimg_obs_exp.tsfx INSX_img_obs_exp.tsfx

b. Rename all instances of “irimg_acq” to “img_acq” inside the file:

tooReplace ngcirimg_obs_exp img_obs_exp INSX_img_obs_exp.tsfx

c. Open file “INSX_img_obs_exp.tsfx” and setup the set “TPL.MODE” to “IMAGING” as is shown below:

TPL.MODE "IMAGING"

6. Build and Install the TSF module: a. Update the “Makefile” file removing the special setting in the make rule “all”. This

setting was only need for the Template Instrument. The rule should looks like the following:

all: do_all

@echo " . . . 'all' done"

b. Generate the TSF files and the Exercise Instrument IP:

cd ~/INSX/OS/inotsf/src

make all

c. Verify that no errors are reported and TSF files are generated in the config directory. d. Install the TSF files:

make install

e. Check that files are installed in the INS_ROOT directory:

ls $INS_ROOT/SYSTEM/COMMON/TEMPLATES/TSF/INSX_img*.tsf

/data/INSX/INS_ROOT/SYSTEM/COMMON/TEMPLATES/TSF/INSX_img_acq.tsf

/data/INSX/INS_ROOT/SYSTEM/COMMON/TEMPLATES/TSF/INSX_img_acq_MoveToSlit.tsf

/data/INSX/INS_ROOT/SYSTEM/COMMON/TEMPLATES/TSF/INSX_img_obs_exp.tsf

7.4.3 Prepare the Sequencer Files

Steps: 1. Go to the scientific template script module:

cd ~/INSX/OS/inoseq/src

2. Remove unnecessary files:

rm INSX_irimg* INSX_optimg* INSX*spec* inoseqGenTecSelfTest.txt_with_midas

3. Rename sequencer files:


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

47 of 51


mv INSX_acq.seq INSX_img_acq.seq

mv INSX_ngcirimg_acq_MoveToSlit.seq INSX_img_acq_MoveToSlit.seq

mv INSX_ngcirimg_obs_exp.seq INSX_img_obs_exp.seq

mv INSX_ngcirimg_obs_exp.obdv INSX_img_obs_exp.obdv

4. Replace the names inside the files:

tooReplace INSX_acq INSX_img_acq *

tooReplace INSX_ngcirimg_acq INSX_img_acq *

tooReplace INSX_ngcirimg_obs_exp INSX_img_obs_exp *

5. Go to the scientific template configuration directory and update the Reference Set-up File for the IMAGING Instrument Mode:

cd ~/INSX/OS/inoseq/config

tooReplace DET4 DET1 INSX_ngcirimg_obs_exp.ref

6. Update Telescope Focus ID in the acquisition sequencer file. Open file “~/INSX/OS/inoseq/src/INSX_img_acq.seq” and change the line where the “tplTCS” object is created. The ID of Cassegrain focus is “CA”. The new line should looks like the following:

tplTCS tcs TCS ino tcs CA INSX

7. Do the same as step 5 with file “INSX_img_acq_MoveToSlit.seq”. 8. Update the detector index in the imaging observation sequencer file. Open file

“INSX_img_obs_exp.seq” and change the line where the “tplNGCIR” object is created. The index of the scientific detector is 1. The new line should looks like the following:

set dcsFullName [namespace current]::[tplNGCIR dcs ngcircon_NGCIR1 NGCIR1 1]

9. Repeat step 7 for file “INSX_img_acq_MoveToSlit.seq”.

10. Update the OBDV file for the imaging observation template. Open file “INSX_img_obs_exp.obdv” and update the integration time and the index of the detector. New setting should be like the following:

DET1.SEQ.DIT "2";

The OBD Value files (OBDV) are used by the tool “tpltooObdBuild” to provide a way to overwrite the definition of the keyword values in the TSF at the generation of the test OBD files.

11. Create a new OBDV file, “INSX_img_acq.obdv”, to overwrite the telescope coordinates. The contents of the new file should looks like the following:

PAF.HDR.START;

PAF.TYPE "Template";

PAF.ID "$Id$";

PAF.NAME "INSX_img_acq";

PAF.DESC "Imaging Acquisition";

PAF.CRTE.NAME "";

PAF.CRTE.DAYTIM "";

PAF.LCHG.NAME "";

PAF.LCHG.DAYTIM "";

PAF.CHCK.NAME "";

PAF.CHCK.DAYTIM "";

PAF.CHCK.CHECKSUM "";

PAF.HDR.END

TEL.TARG.ALPHA "000000.";

TEL.TARG.DELTA "-850000.";

12. Make a copy of the previously created OBDV file and name it “INSX_img_acq_MoveToSlit.obdv”:


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

48 of 51


cd ~/INSX/OS/inoseq/src/

cp INSX_img_acq.obdv INSX_img_acq_MoveToSlit.obdv

13. Update the OBDV file “INSX_img_acq_MoveToSlit.obdv” adding the default setting for the NGC detector integration time (keyword “DET1.SEQ.DIT”):

DET1.SEQ.DIT "2";

14. Update reference files: a. Remove unnecessary files:

cd ~/INSX/OS/inoseq/config

rm –f *.obd INSX_optimg* INSX_*spec*

b. Rename reference files:

mv INSX_acq.ref INSX_img_acq.ref

mv INSX_irimg_obs_exp.ref INSX_img_obs_exp.ref

c. Replace the names inside the files:

tooReplace INSX_acq INSX_img_acq *

tooReplace INSX_ngcirimg_obs_exp INSX_img_obs_exp *

d. Adapt the file “~/INSX/OS/inoseq/config/INSX_img_obs_exp.ref” according the functions of the Exercise Instrument:

INS.MODE "IMAGING"

DET1.SEQ.DIT 1.0

DET1.SEQ.EXPTIME 5.0

INS.LAMP1.ST "F"

INS.SHUT1.ST "F"

INS.MIRR1.NAME "Out"

15. Update file “~/INSX/OS/inoseq/src/inoseqTsfList.txt” removing all TSF files which are not part of the Exercise Instrument. The final list should looks like the following:

INSX_img_acq.tsf

INSX_img_acq_MoveToSlit.tsf

INSX_img_obs_exp.tsf

The purpose of the TSF list file is to define the list of template signature files (TSF) to be processed by tool “tpltooObdBuild” in order to generate individuals test OBD files. This happen during the building of the module (make all) and the generated OBD files are located under the config directory. These OBD files are used to test the instrument templates in an interactive and programmatic way.

16. Copy file “inoseqTsfList.txt” to file “inoseqGenTecSelfTest.txt”:


cp inoseqTsfList.txt inoseqGenTecSelfTest.txt

The purpose of the Self Test list file is to define the list of template signature files (TSF) to be processed by tool “tpltooObdBuild” in order to generate one OBD file containing all templates included in the list. This happen during the “make” of the module (make all) and the generated OBD file is located under the “config” directory. This OBD file is normally used to carry out the self test of the instrument templates.

17. Build and Install the module “inoseq”:



18. Verify the execution of the templates (as user “insx”). a. Start the instrument SW if is not already running. Follow the instructions given in the

OS session (section 6.3.4).


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

49 of 51


b. Load the Self Test OBD from BOB tool (“INSX_gen_tec_SelfTest.obd”). This OBD file should contain three templates: “INSX_img_acq”, “INSX_img_acq_MoveToSlit” and “INSX_img_obs_exp”). If the optional template was implemented during the exercise, there will be four templates.

Figure 14: Loading an OBD file from BOB tool.

c. Press “Start” button and make sure the OBD execution terminates without errors.

Broker for Observation Blocks (BOB) is the high-level interface toward the Instrument Control SW. Its main task is to break the OBD files down to units of individual exposures, sending sequences of commands to the Observation SW (OS) and informing their execution status to the users [RD15].

7.4.4 Prepare Technical TSF Files (module: “inmtsf”)

Steps: 9. Go to the technical TSF module:

cd ~/INSX/MS/inmtsf/

10. Update the Instrument Summary File (ISF): a. Copy the ISF file from Science Templates:

cp ../../OS/inotsf/config/INSX.isf config

11. Add the Bias TSF: b. Go to the source directory:

cd src

c. Rename file “INSX_optimg_tec_parasitic.tsfx”:

mv INSX_optimg_tec_parasitic.tsfx INSX_gen_tec_bias.tsfx

d. Rename all instances of “optimg_tec_parasitic” to “img_gen_tec_bias” inside the file:

tooReplace optimg_tec_parasitic gen_tec_bias *

e. Open file “~/INSX/MS/inmtsf/src/INSX_gen_tec_bias.tsfx” and change the keyword “TPL.MODE” as is shown below:

TPL.MODE "CALIBRATION"

f. Update the sequence script changing the keyword “TPL.PRESEQ” as is shown below:

TPL.PRESEQ "INSX_gen_tec_bias.seq"

g. Replace the last part of the file with the following:

PAF.INCLUDE "inotsfSEQ.tsfx"

PAF.INCLUDE "inotsfTCCD_DIT.tsfx"

12. Build and Install the module “inmtsf”.


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

50 of 51



7.4.5 Prepare Technical Sequence Files

Steps: 1. Go to the technical sequencer module:

cd ~/INSX/MS/inmseq/

2. Add the Bias Sequencer File: h. Go to the sources directory:

cd src

i. Rename file “INSX_optimg_tec_parasitic.seq”:

mv INSX_optimg_tec_parasitic.obdv INSX_gen_tec_bias.obdv

j. Rename all instances of “optimg_tec_parasitic” to “img_gen_tec_bias” inside the file:


k. Update the file “~/INSX/MS/inmseq/src/INSX_gen_tec_bias.obdv” changing to the right detector index (TCCD) as is shown below:

DET2.WIN1.UIT1 "10";

l. Create file “INSX_gen_tec_bias.seq” with the following contents:

proc INSX_gen_tec_bias { parArrays obsInfo } {

seeBobVars

catch { delete object obs }

catch { delete object tccd }

tplOBS obs ino

set tccdFullName [namespace current]::[tplACE tccd tccd TCCD 2]

set TPL(NEXP) $SEQ(NEXPO)

obs ExposeDark $TPL(ID) $tccdFullName $TPL(REFSUP) $SEQ(NEXPO)

tplLog "Template $TPL(ID) finished."

return {}

}

3. Update reference files: a. Remove unnecessary files:

cd ~/INSX/MS/inmseq/config

rm *.obd

b. Rename reference files:

mv INSX_optimg_tec_parasitic.ref INSX_gen_tec_bias.ref

c. Replace the names inside the files:


d. Adapt the file “INSX_gen_tec_bias.ref” to the correct detector index replacing “DET3” by “DET2”.

e. Update default Instrument Mode to “CALIBRATION” changing keyword “INS.MODE”.

4. Build and Install the module “inmseq”: a. Update “Makefile” to add the installation of the sequencer files. The new setting

should be as follows:

#


Laboratory Exercise

Doc:

Issue

Date

Page


1

2009-09-01

51 of 51


# INS_ROOT files to be installed

#-------------------------------

INS_ROOT_FILES = ../config/*.ref ../config/*.obd *.seq

b. Install the files:

cd ~/INSX/MS/inmseq/src


5. Verify the execution of the templates (as user “insx”) a. Load the self test OBD from BOB tool (“INSX_gen_tec_MSTest.obd”) assuming that

Exercise Instrument SW is ONLINE and BOB tool is running. b. Press “Start” button and make sure the OBD execution terminates without errors.

7.5 Session Summary

During this session the course participant has learnt how to adapt the scientific and technical modules from the Template Instrument to specifics requirements. Due to the time constraints, the examples are limited and quite simple nevertheless they outline the process that a developer would have to face when implementing the templates for an instrument.