EUROPEAN SOUTHERN OBSERVATORY - ESO · Web viewRemove MC68040 from “INSTALL.MODULE.CPU” since we are not using this board. We will work only with the “winsx”, “linics1”

VERY LARGE TELESCOPE

Instrument Control SoftwareLaboratory Exercise

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

Issue: 0.23

Date: 04.10.2008

Prepared: M.KiekebuschJ.KnudstrupD.PopovicName Date Signature

Approved: G.ChiozziName Date Signature

Released: M. PeronName Date Signature

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

European Organisationfor AstronomicalResearch in theSouthern Hemisphere

Organisation Européennepour des RecherchesAstronomiquesdans l’Hémisphère Austral

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


Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.20082 of 78

CHANGE RECORD

ISSUE DATE SECTION/PARA.AFFECTED

REASON/INITIATIONDOCUMENTS/REMARKS

0.23 2008-10-04 All First issue.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.20083 of 78

TABLE OF CONTENTS

1 Introduction.................................................................................................................................... 71.1 Purpose................................................................................................................................. 71.2 Acknowledgments.................................................................................................................71.3 Scope.................................................................................................................................... 71.4 List of Abbreviations & Acronyms..........................................................................................71.5 List of Applicable and Referenced Documents......................................................................81.6 Reference Documents...........................................................................................................81.7 Guidelines for Reading this Document..................................................................................9

2 Overview...................................................................................................................................... 102.1 The Instrument.................................................................................................................... 102.2 Hardware Architecture.........................................................................................................10

2.2.1 Devices....................................................................................................................... 102.2.2 Computers and Hardware...........................................................................................10

2.3 Software Architecture..........................................................................................................122.4 Environment Configuration..................................................................................................13

2.4.1 User Accounts/Environments......................................................................................132.4.2 CCS/LCC Environments.............................................................................................14

3 Exercise #1: Getting Started........................................................................................................153.1 Purpose............................................................................................................................... 153.2 Implementation Details........................................................................................................153.3 Exercise Steps.................................................................................................................... 15

3.3.1 Preparing the XXXX Modules for the Basic Adaptation..............................................153.3.1.1 Checking and Adapting the Environment..............................................................153.3.1.2 Retrieve the XXXX Base Module..........................................................................153.3.1.3 Initial Adaptation of the Integration Module...........................................................163.3.1.4 Retrieving the XXXX Modules...............................................................................16

3.3.2 Adapting the Template Instrument to the Exercise Instrument...................................163.3.2.1 Create the Exercise Instrument Software..............................................................163.3.2.2 Adapt the Installation Configuration File................................................................173.3.2.3 Adapting the TCS Simulator Configuration...........................................................173.3.2.4 Adapt the Instrument Configuration.......................................................................183.3.2.5 Adapt the Start-up Configuration...........................................................................183.3.2.6 Build the SW for the Exercise Instrument..............................................................183.3.2.7 Start the Instrument...............................................................................................18

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

4.1 Purpose............................................................................................................................... 204.2 Implementation Details........................................................................................................20

4.2.1 Devices....................................................................................................................... 204.2.2 Location of Relevant Configuration Files....................................................................20

4.3 Exercise Steps.................................................................................................................... 214.3.1 Adapting the Instrument Configuration........................................................................214.3.2 Adjusting Instrument DB.............................................................................................23

4.3.2.1 Adjusting the DB Definition “iniEnv.db”.................................................................234.3.3 Configuring Scan Links...............................................................................................244.3.4 Setting Default LCU DB Configuration........................................................................254.3.5 Adjusting Instrument WS Simulation DB.....................................................................254.3.6 Adjusting Instrument Dictionary..................................................................................254.3.7 Setting Simulation Level.............................................................................................254.3.8 Adapt the “pkgin” configuration file.............................................................................264.3.9 Build and Install Updated Modules.............................................................................264.3.10 Re-building the SW.....................................................................................................264.3.11 Starting ICS................................................................................................................26

4.4 Session Summary...............................................................................................................27



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.20084 of 78

5 Exercise #3: Implementing a Special Device...............................................................................285.1 Purpose............................................................................................................................... 285.2 Implementation Details........................................................................................................28

5.2.1 Device Description......................................................................................................285.2.2 Integration of the special device with the existing instrument.....................................29

5.3 Exercise Steps.................................................................................................................... 295.3.1 Retrieving the inilamp module:....................................................................................295.3.2 Inclusion of the inilamp module in the integration module inins..................................295.3.3 Update of the “bootScript” for the environment “linics1”..............................................295.3.4 Update of the instrument dictionary............................................................................305.3.5 Device configuration:..................................................................................................305.3.6 Update of the instrument DB.......................................................................................315.3.7 Update of scan links:..................................................................................................315.3.8 Update of the simulation DB:......................................................................................315.3.9 Automatic creation of default LCU DB configuration...................................................325.3.10 Build and Install Updated Modules.............................................................................325.3.11 Verification - Rebuilding and restarting the instrument software.................................33

5.4 Code walk-through - Optional..............................................................................................335.4.1 Device DB, file inilamp/dbl/inilampLAMP2.db:................................................335.4.2 Definition of DB attributes literals and DB access macros..........................................355.4.3 Device Initialization.....................................................................................................365.4.4 State change to STANDBY.........................................................................................365.4.5 State change to ONLINE............................................................................................365.4.6 State change to OFF..................................................................................................375.4.7 Simulation ON.............................................................................................................375.4.8 Simulation OFF...........................................................................................................385.4.9 Device STATUS..........................................................................................................385.4.10 Device SETUP............................................................................................................385.4.11 Important files:............................................................................................................38

5.5 Creating WS Lamp Special Device.....................................................................................395.6 Session Summary...............................................................................................................42

6 Exercise #4: Interfacing with Detector Control Systems..............................................................436.1 Purpose............................................................................................................................... 436.2 Exercise Steps.................................................................................................................... 43

6.2.1 Adapt the Instrument Configuration for RTD Start-Up................................................436.2.2 Adapting the NGC IR Detector Configuration.............................................................43

6.2.2.1 Updating the High Level NGC IR Configuration....................................................436.2.2.2 Update the NGC System and Detector Configuration...........................................446.2.2.3 NGC IR Verification...............................................................................................45

6.2.3 Update the TCCD Configuration.................................................................................486.2.4 Update “pkgin” TCCD Configuration...........................................................................486.2.5 TCCD Verification.......................................................................................................49

6.3 Session Summary...............................................................................................................517 Exercise #5: Observation Software – OS.....................................................................................52

7.1 Purpose............................................................................................................................... 527.2 Implementation Details........................................................................................................527.3 Exercise Steps.................................................................................................................... 52

7.3.1 Configure OS Subsystems..........................................................................................527.3.2 OS Database Configuration........................................................................................537.3.3 OS Verification............................................................................................................54

8 Exercise #6: Templates...............................................................................................................578.1 Purpose............................................................................................................................... 578.2 Additional Information..........................................................................................................578.3 Implementation Details........................................................................................................578.4 Exercise Steps.................................................................................................................... 58

8.4.1 Prepare science TSF Files (module “inotsf”)...............................................................58



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.20085 of 78

8.4.2 Prepare the Sequencer Files (Module: “inoseq”)........................................................618.4.3 Prepare Technical TSF Files (module: “inmtsf”).........................................................668.4.4 Prepare Technical Sequence Files (module “inmseq”)...............................................66

8.5 Session Summary...............................................................................................................679 Exercise #7: Online Image Processing with CLIP........................................................................68

9.1 Exercise Steps.................................................................................................................... 689.1.1 Customize NGC IR Server..........................................................................................689.1.2 Create an RTD acquisition panel................................................................................749.1.3 Modify the Acquisition Template (MoveToSlit)............................................................76

9.2 Session Summary...............................................................................................................7710 Appendix A................................................................................................................................... 78



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.20086 of 78



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.20087 of 78

1 IntroductionThis document contains the course material for a laboratory exercise carried out in connection with the Instrument Control Software Workshop, held at the ESO premises in October 2008. The complete exercise is composed of 7 sessions that cover different parts of the instrumentation SW. Each session has a specific purpose and a number of steps that the participant should follow before continuing with the next session. After following all the instructions for each session, the final result of the lab exercise should be a fully working instrumentation SW.

Although the exercise has been developed for the workshop, it is intended to be used also for training in other contexts, e.g. for training new personnel (in this case, executed then as a self-study session).

1.1 PurposeThe 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 AcknowledgmentsThe 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 ScopeThe 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 & AcronymsThis 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 SoftwareDFS Data Flow SystemGUI Graphical User InterfaceHW HardwareHDU Header/Data Unit (FITS)ICS Instrument Control Software INS Instrumentation Software PackageI/O input/outputISF Instrument Summary FileIWS Instrument WorkstationLCC LCU Common SoftwareLCU Local Control UnitMS Maintenance SoftwareN/A Not Applicable



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.20088 of 78

PAE Preliminary Acceptance EuropeP2PP Phase 2 Proposal PreparationRTAP Real-Time Application PlatformSW SoftwareTBC To Be ClarifiedTBD To Be DefinedTCS Telescope Control SoftwareTIM Time Interface ModuleTRS Time Reference SystemTSF Template Signature FileVLT Very Large TelescopeWS Workstation

1.5 List of Applicable and Referenced DocumentsThis 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 VLT-MAN-ESO-17240-1973

1.6 Reference DocumentsThe 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 VLT-MAN-ESO-17240-1913

[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



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.20089 of 78

1.7 Guidelines for Reading this DocumentSince 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 VxWork 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 …

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.

The exercise is based on the “xxins” module version 5.46 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. This exercise will be using a patched version of VLT2008.

Note also that due to time constraints, it is only possible to cover a part of the INS Common Framework.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200810 of 78

2 OverviewThis 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 InstrumentThe 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 one 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 DevicesThe Exercise Instrument is composed of the following components:

6 devices, controlled by the ICS on 1 LCU: 2 motors. 1 entrance shutter. 2 lamps. 1 DAQ unit (Yokogawa).

1 scientific detector: 1 NGC controller (infrared SW).

1 technical detector: 1 NGTCCD.

2.2.2 Computers and HardwareThe Exercise Instrument is using the following computers and HW1:

Instrument WS (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.

1 Although this equipment was used during the INS SW Workshop 2008 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.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200811 of 78

Figure 1: Devices of the Exercise Instrument.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200812 of 78

2.3 Software ArchitectureThe 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 INSXPrefix xx inInstrument User xxxx insxInstrument Manager

xxxxmgr insxmgr

WS Environments wxxxx, wxxtcs winsx, wintcsICS LCU Environments

lxxics1, lxxics2 linics1

Detector Systems IRACE, TCCD, FIERA, NGC/IR NGC/IR, TCCDDetector 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.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200813 of 78

The mapping of environments used by XXXX and INSX is shown in the following table:

Environment Number

Template Instrument Exercise Instrument

1 wxxxx winsx2 lxxics1 linics13 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/EnvironmentsThe 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/bashinsxmgr: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/insamgr/.pecs/apps-all.env”), e.g.:

export INTROOT=/vlt/INSX/INTROOTexport PATH=$INTROOT/bin:$PATHexport LD_LIBRARY_PATH=$INTROOT/lib:$LD_LIBRARY_PATHexport INS_ROOT=/data/INSX/INS_ROOTexport INS_USER=SYSTEMexport TARGET=LAB_EXexport RTAPENV=winsxexport DHS_DATA=$INS_ROOT/SYSTEM/DETDATAexport 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 insxte77.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 vxlinics1.hq.eso.org vxlintccd vxlicics1.hq.eso.org vx



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200814 of 78

2.4.2 CCS/LCC EnvironmentsThe 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

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

linics1 2160/tcplintccd 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 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…

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.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200815 of 78

3 Exercise #1: Getting Started

3.1 PurposeThe purpose of this session is to initiate the implementation of the instrument SW. This involves the allocation of various names and ID’s for the instrument, preparation of 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 DetailsDuring 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 AdaptationDuring 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 EnvironmentThe 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 ModuleThe 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).



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200816 of 78

Steps:1. > mkdir XXXXSource2. > cd XXXXSource3. > cmmCopy xxins4. > chmod -R +w xxins

By convention the main source directory for the instrument SW is named “<instrument ID>Source. 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 ModuleThe purpose of this step is to adapt the Instrument Installation Configuration to match the exercise instrument.

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

2. 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 ModulesThe 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 InstrumentDuring 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.

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 Create the Exercise Instrument SoftwareThe 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 renaming and replacing of the instrument ID and prefix. This step saves quite a lot of time for the developer.

Steps:1. > inscCreateNewInstrument INSX in2. > cd ../INSXSource

The exercise instrument is supposed to control hardware that is not supported by the current VLTSW



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200817 of 78

release VLT2008, e.g. NGC detectors and Yokogawa DAQ Station. Also, there have been many improvements and bug fixes since the last official release that are needed for the exercise. For that reason, the latest SW has to be installed on top of the existing VLTROOT. The convention is to list the modules in file named “inins/config/ininsINSTALL_VLTSW.<VLTSWRelease>.cfg”. Since the current release is VLT2008, the file name is “ininsINSTALL_VLTSW.VLT2008.cfg”. This file is automatically searched for and, if exists, appended by the “pkginBuild” tool.

The NGC SW is not supported in VLT2008 release and it takes long time to compile it. In order to minimize the compilation time during the lab exercises, the latest NGC SW has already been installed in the VLTROOT.

3.3.2.2 Adapt the Installation Configuration FileThe 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 “~/INSXSource/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.

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 ConfigurationThe 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,

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

2. Add/Change the following lines to the file :# NOTE: RTAPENV1 - winsxINSTALL.RTAPENV2.NAME "wintcs";INSTALL.RTAPENV2.TPLSRC "inins/ENVIRONMENTS/wintcs";

# Installation Hook for the TCS Simulation Package.INSTALL.HOOK2.NAME "AFTER_CREATE_SCAN";



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200818 of 78

INSTALL.HOOK2.PLUGIN "tcssimInstall.sh";

3.3.2.4 Adapt the Instrument ConfigurationThe 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.

Steps:1. Open the Instrument Configuration File, “~/INSXSource/MS/inmcfg/config/inmcfgINS.cfg”, with

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, 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, “~/INSXSource/MS/inmcfg/config/inmcfgSTART.cfg”, in a

text editor.

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

3.3.2.6 Build the SW for the Exercise InstrumentThe 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. > cd ~/INSXSource

2. > pkginBuild inins

The above step will take a while, so please be patient.

3.3.2.7 Start the InstrumentThe 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. > ininsStart



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200819 of 78

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”.

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 SummaryDuring this exercise we have made the very basic preparations to start building the Exercise Instrument. We 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 pertinent 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.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200820 of 78

4 Exercise #2: Instrument Control Software - ICS

4.1 PurposeThe 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 Implementation Details

4.2.1 DevicesThe exercise instrument supports the following 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

6 LAMP2 LAMP2 N/A 1 Digital and Analog I/O control

Special device. Lamp with intensity control currently not supported by the lamp standard device.

Note, the Special Device, “LAMP2”, will not be implemented during this session.

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 FilesTo 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”.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200821 of 78

4.3 Exercise Steps

4.3.1 Adapting the Instrument ConfigurationDuring 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 “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. The Special device “LAMP2” will be added at a later stage.

Steps:1. Open the Instrument Configuration, "~/INSXSource/MS/inmcfg/config/inmcfgINS.cfg", with a

text editor.

2. Locate the device summary list (keywords of type: "INS.CON.DEVICE*"). Set the number of devices to 5 ("INS.CON.DEVNUM"=5). The special device (#6) will be added during the next session.

3. 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").

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";

5. 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";

6. 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";

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



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200822 of 78

## Sample YOKOGAWA DX200 DAQ Station#INS.SENSOR1.DEVNAME "yoko"; # Name of the ICS deviceINS.SENSOR1.DEVDESC "YOKOGAWA DX200 DAQ"; # Description of the deviceINS.SENSOR1.DEVTYPE "DX200"; # Device typeINS.SENSOR1.LCUID 1; # Id. of the LCU managing deviceINS.SENSOR1.SWSIM T; # If T, function is SW simulated

INS.SENSOR1.PORT "/tyCo/3"; # Hardware deviceINS.SENSOR1.NUM 3; # Number of managed sensor values

INS.SENSOR1.NAME1 "CH1"; # Sensor value nameINS.SENSOR1.DESC1 "Temp 1"; # Sensor value descriptionINS.SENSOR1.HEADER1 F; # If T, report sensor value in image headerINS.SENSOR1.FITS1 "INS.SENS1.VAL"; # Sensor value FITS keywordINS.SENSOR1.SENUNIT1 "C"; # Sensor value unitINS.SENSOR1.SENADDR1 01; # Sensor value hardware addressINS.SENSOR1.LOG1 T; # If T, function is SW simulated

INS.SENSOR1.NAME2 "CH2"; # Sensor value nameINS.SENSOR1.DESC2 "Temp 2"; # Sensor value descriptionINS.SENSOR1.HEADER2 F; # If T, report value in FITS headerINS.SENSOR1.FITS2 "INS.SENS2.VAL"; # Sensor value FITS keywordINS.SENSOR1.SENUNIT2 "C"; # Sensor value unitINS.SENSOR1.SENADDR2 02; # Sensor value hardware addressINS.SENSOR1.LOG2 T; # If T, function is SW simulated

INS.SENSOR1.NAME3 "CH3"; # Sensor value nameINS.SENSOR1.DESC3 "Temp 3"; # Sensor value descriptionINS.SENSOR1.HEADER3 F; # If T, report value in image headerINS.SENSOR1.FITS3 "INS.SENS3.VAL"; # Sensor value FITS keywordINS.SENSOR1.SENUNIT3 "C"; # Sensor value unitINS.SENSOR1.SENADDR3 03; # Sensor value hardware addressINS.SENSOR1.LOG3 T; # If T, function is SW simulated

8. 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 devicesINS.CON.DEVICE1 "INS.LAMP1"; # Device FITS prefix used in the config fileINS.CON.DEVICE2 "INS.SHUT1"; # Device FITS prefix used in the config fileINS.CON.DEVICE3 "INS.FILT1"; # Device FITS prefix used in the config fileINS.CON.DEVICE4 "INS.MIRR1"; # Device FITS prefix used in the config fileINS.CON.DEVICE5 "INS.SENSOR1"; #Device FITS prefix used in the config file

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

10. 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 ""

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



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200823 of 78

12. 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 2INS.UIF1.TABS 2INS.UIF2.TABS 1INS.UIF1.LABEL1 "Motors"INS.UIF1.LABEL2 "Lamps/shutters"INS.UIF2.LABEL1 "YOKO"INS.LAMP1.UIFNB 1INS.LAMP1.UIFTB 2INS.SHUT1.UIFNB 1INS.SHUT1.UIFTB 2INS.SENSOR1.UIFNB 2INS.SENSOR1.UIFTB 1

13. Build and Install the configuration

> cd ~/INSXSource/MS/inmcfg/src> make clean all install

4.3.2 Adjusting Instrument DBThe 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 "~/INSXSource/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 (“#include “iniHISTORIAN.db”).

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

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



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200824 of 78

5.3.2.2 Adjusting LCU DB Configuration “iniEnv1.db”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 "~/INSXSource/ICS/ini/dbl/iniEnv1.db" and

"~/INSXSource/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:YOKOBEGIN ALIAS YOKO ATTRIBUTE bytes20 device "yoko" ATTRIBUTE bytes16 prefix "INS.YOKO" ATTRIBUTE int32 lcuId 1END

4.3.3 Configuring Scan LinksDuring 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 "~/INSXSource/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 "~/INSXSource/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”.

7. DB attribute “<alias>MIRR:MOTOR:STATUS.posEnc” is used to verify scan links. 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.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200825 of 78

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 ConfigurationEvery time an LCU is rebooted, the DB configuration file “$VLTDATA/config/<LCU name>.dbcfg” (e.g. “linics1.dbcfg”) is loaded into the LCU DB. The input for the creation of this file is taken from the configuration defined in 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 "~/INSXSource/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 DBThe 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 "~/INSXSource/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”.

4.3.6 Adjusting Instrument DictionaryInstrument 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 LevelThe LCU “linics1” is available but the hardware is not connected. Therefore, the access to the LCU is “NORMAL” but “SWSIM” for each device is set to “T” in the Instrument Configuration, “MS/inmcfg/config/inmcfgINS.cfg”.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200826 of 78

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

2. Set keyword “INS.CON.OPMODE” to “NORMAL”.

4.3.8 Adapt the “pkgin” configuration fileThe purpose is to correct the verification of the scanning according to the real instrument devices.

1. Open the file "~/INSXSource/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 ModulesSteps:

1. > cd ~/INSXSource/ICS/ini/src

2. > make clean all install

3. > cd ~/INSXSource/MS/inmcfg/src


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

Steps:5. > cd ~/INSXSource

6. > pkginBuild inins –fromstep BUILD_ENV

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

Steps:1. > ininsStart -proc ICS

2. > 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.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200827 of 78

Figure 3: ICS Control Panel.

4.4 Session SummaryIn 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.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200828 of 78

5 Exercise #3: Implementing a Special Device

5.1 PurposeThe purpose of this session is to implement an LCU special device that controls a lamp with intensity control. The standard LAMP device does not support intensity control and for that reason a special device has to be implemented. In addition, a WS special device (dynamic assembly) will be implemented in order to simplify the interface with the corresponding LCU part.

It should be noted that the application created for this section does not represent the most optimal design and its sole purpose is to give a simple example how to create special devices on both LCU and WS.

Normally, the starting point for implementation of a special device would be the module xxidev which we have renamed into ixidev in Session 1. However, there are too many changes of the xxidev code required to implement our example special device. The available time for this session would not be enough for the participants of this course to complete the exercise. For that reason the complete module inilamp will be taken from the archive. The sample code supports a very basic functionally needed for the exercise, i.e. state change, setup and status.

During this session the course participant will get a walk-through the details related to the implementation of the special device and the way it is incorporated into the existing instrument.

At the end of the session, the complete instrument SW will be rebuilt from scratch and started. It should be possible to control the special device, in simulation, from the ICS Control panel or by sending messages. The device configuration given in this session is the one that is going to be used with the real hardware at the end of the course.

5.2 Implementation Details

5.2.1 Device DescriptionSwitching the lamp ON/OFF is controlled via a digital output while the intensity is controlled via an analog output. Feedback signals for both control signals are provided. All changes of the device status are logged.

HW Interface:

Signal IN / OUT Interface Channel ActiveON/OFF Control: digital OUT MEN “/men3” 0 LOWON/OFF Feedback: digital IN MEN “/men3” 9 HIGHIntensity Control: analog OUT, 0-10V CANBus“/canio0” 0 N/AIntensity Feedback: analog IN, 0-10V CANBus“/canio0” 0 N/A

Setup commands:

Function Keyword Range Units CommentON/OFF: INS.LAMP2.ST T or F Standard keyword. Every time the lamp is

switched OFF the intensity is set to 0. Switching it ON does not affect the intensity.

Intensity INS.LAMP2.INTENS 0-10 V Setting the intensity to zero will switch the lamp OFF.

Power INS.POWER.VAL 0-100 % Keyword used by the WS special device. Defines relative intensity, i.e. 100% = 10V. Setting power to a value other than zero switches the lamp ON as well.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200829 of 78

Note: Keywords INS.LAMPi.INTENS and INS.POWER.VAL do not exist in the ICB dictionary and therefore will have to be added to the instrument dictionary.

5.2.2 Integration of the special device with the existing instrumentThe module inilamp represents only the special device code. However, the device has still to be integrated into the instrument. The following steps have to be completed:

1. Retrieving the inilamp module.

2. Inclusion of the inilamp module in the integration module inins, file inins/config/ininsINSTALL.cfg.

3. Update of the bootScript for the environment linics1, file inins/ENVIRONMENTS/linics1/bootScript.

4. Update of the instrument dictionary, files dicINSX/src/dicINSX_CFG.txt and dicINSX_ICS.txt.

5. Device configuration including the GUI configuration, file inmcfg/config/inmcfgINS.cfg.

6. Update of the instrument DB, file ini/dbl/iniEnv1.db.

7. Update of the scan links, file ini/config/linics1.scan.

8. Update of the simulation DB, file ini/dbl/iniSIM_CONTROL.class.

9. Automatic creation of default LCU DB configuration, files ini/src/iniConfigLib.tcl and iniConfigSet.tcl.

5.3 Exercise StepsPlease note that unless explicitly stated, all steps should be executed as user insxmgr.

5.3.1 Retrieving the inilamp module:Execute the following lines as insxmgr:

Steps:1. > cd ~/INSXSource/ICS

2. > cmmCopy inilamp

NOTE: For real development cmmCopy would be replaced with: > inscRename xxidev inilamp YYYY LAMP2 xx in

5.3.2 Inclusion of the inilamp module in the integration module ininsSteps:

1. Open file inins/config/ininsINSTALL.cfg with text editor.

2. Change the configuration for MODULE41 (module inidev became inilamp). Comment out the line “INSTALL.MODULE41.VERSION …”:

INSTALL.MODULE41.NAME "inilamp";INSTALL.MODULE41.SUBPKG "ICS";#INSTALL.MODULE41.VERSION "1.22";

5.3.3 Update of the “bootScript” for the environment “linics1”

LCU boot script is automatically generated from the definitions given as comments starting with the ‘#’ character in file “inins/ENVIRONMENTS/linics1/bootScript”. The resulting file is installed in the directory “$VLTDATA/ENVIRONMENTS/linics1”.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200830 of 78

Steps:1. Open file inins/ENVIRONMENTS/linics1/bootScript with text editor.

2. Modify the following two lines as shown below. The lines define the drivers and modules that get installed during the boot process. Note that special device modules, in this case module inilamp, must be declared before module icb in vUsrmodlist.

# vSysmodlist: lcudrv lculog lqs mendrv canstack canstackLib canio canrmc ampl ikon iser mcon tim lcc cai scan # vUsrmodlist: inducer mcm inilamp icb

5.3.4 Update of the instrument dictionaryWe have introduced three new keywords: the configuration keyword INS.LAMPi.BITDEVi (will be described in the following section 5.3.5) and the setup keywords INSi.LAMPi.INTENS and INSi.POWER.VAL. They should be added to files dicINSX_CFG.txt and dicINSX_ICS.txt respectively.

Steps:1. Open file “dicINSX/src/dicINSX_CFG.txt” with text editor and add the following lines:

INSi.LAMPi.BITDEVi %15s Device used for corresponding SIGBIT (c).Device used for corresponding SIGBIT.Used to define device for each bit.Examples "/men3", "canio2".

2. Open file dicINSX/src/dicINSX_ICS.txt with text editor and add the following keyword definitions just below keyword INSi.LAMPi.ST:

INSi.LAMPi.INTENS %.2f Lamp intensity [V] (hs).Lamp intensity in Volts. Range 0-10V.

INSi.POWER.VAL %.2f Lamp power [%] (hs).Lamp power expressed as percentage of full power.Range 0-100%, corresponds to intensity 0-10V.

5.3.5 Device configuration:Steps:

1. Open file inmcfg/config/inmcfgINS.cfg with text editor.

2. Add the following lines just after LAMP1:

## Special lamp#INS.LAMP2.DEVNAME "lamp2"; # Name of the ICS deviceINS.LAMP2.DEVDESC "Special lamp"; # Description of the ICS deviceINS.LAMP2.DEVTYPE "S_LAMP"; # Device typeINS.LAMP2.PROCNAME "inilampServer"; # Name of the LCU server processINS.LAMP2.LCUID 1; # Id. of the LCU managing the deviceINS.LAMP2.SWSIM T; # If T, function is software simulated

INS.LAMP2.ID "LAMP2";INS.LAMP2.NAME "Special_Lamp";# A/D I/O interface setupINS.LAMP2.SIGBIT1 0; # on_OUT control signalINS.LAMP2.SIGBIT2 9; # on_IN feedback signalINS.LAMP2.SIGBIT3 0; # intens_OUT control signalINS.LAMP2.SIGBIT4 0; # intens_IN feedback signal



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200831 of 78

INS.LAMP2.BITDEV1 "/men3"; # MEN Controller Digital OUTINS.LAMP2.BITDEV2 "/men3"; # MEN Controller Digital ININS.LAMP2.BITDEV3 "/canio0"; # CANBus Controller Analog OUTINS.LAMP2.BITDEV4 "/canio0"; # CANBus Controller Analog IN

3. Add LAMP2 as DEVICE6 and increment the number of devices in the system:

INS.CON.DEVNUM 6; # Number of ICS devicesINS.CON.DEVICE6 "INS.LAMP2"; # Device FITS prefix used in the config file

4. Configure the ICS GUI:NOTE: Device LAMP2 has a dedicated ICS widget called inipanLamp. Other devices use the standard widgets provided by the icbpan module.Add the following lines just after INS.LAMP1.UIFTB:

INS.LAMP2.UIFNB 1INS.LAMP2.UIFTB 2INS.LAMP2.UIFCLASS "inipanLamp"

5.3.6 Update of the instrument DB Steps:

1. Open file ini/dbl/iniEnv1.db with text editor.2. Below the LAMP definition add the following lines:

//************************************************************************// Device LAMP2//#include "inilampLAMP2.db"

5.3.7 Update of scan links:Steps:

1. Open file ini/config/linics1.scan with text editor.2. Add the following lines just after LAMP.

Note: Attributes on the left belong to the WS DB while the ones on the right belong to the LCU DB. Scanning is always from LCU or WS to WS, never from WS to LCU.

## LAMP2#<alias>LAMP2.state <alias>LAMP2.state SRBX 2<alias>LAMP2.simulation <alias>LAMP2.simulation SRBX 2<alias>LAMP2.on <alias>LAMP2:on_IN.value SRBX 2<alias>LAMP2.intens <alias>LAMP2:intens_IN.value SRBX 2

5.3.8 Update of the simulation DB:

The simulation DB is used for WS simulation, i.e. when LCU’s are not available, and therefore there is no scan links between the LCU’s and the WS. The DB defines where the values of SETUP keywords are stored and where they are read from in reply to the STATUS command.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200832 of 78

Steps:1. Open file ini/dbl/iniSIM_CONTROL.class with text editor.2. Add the following lines just after LAMP1:

// // LAMP2: special lamp // ("INS.LAMP2.ST", "<alias>LAMP2.on", dbLOGICAL), ("INS.LAMP2.INTENS", "<alias>LAMP2.intens", dbFLOAT), ("INS.LAMP2.SWSIM", "<alias>LAMP2.simulation", dbLOGICAL),

5.3.9 Automatic creation of default LCU DB configuration

Files ”iniConfigLib.tc”l and “iniConfigSet.tc”l are scripts that read device configurations from file “inmcfgINS.cfg” and translate them into corresponding DB configuration that is stored in file “$VLTDATA/config/linics1.dbcfg”. This file is loaded after the LCU boot and also during the initialisation of standard devices. The DB is initialised that way in order to avoid hard-coding of the DB.

Steps:1. Open file ini/src/iniConfigLib.tcl with text editor:2. In proc ConfigGetSpecialDevices add line:

set specialDevices { "INS.LAMP2" }; 3. In proc ConfigSetSpecialDevice add code for LAMP2

"INS.LAMP2" {set devName [cfg Get [cconcat $device .DEVNAME]]cfg2db PutsPoint "<alias>[string toupper $devName]"cfg2db PutsScalar device $devNameset listDev [list on_OUT_dev on_IN_dev intens_OUT_dev intens_IN_dev]set listCh [list on_OUT_ch on_IN_ch intens_OUT_ch intens_IN_ch]loop i 0 4 {

set idx [expr {$i + 1}]set sigbit [cfg Get [cconcat $device .SIGBIT${idx}]]set bitdev [cfg Get [cconcat $device .BITDEV${idx}]]set dev [lindex $listDev $i]set ch [lindex $listCh $i]cfg2db PutsScalar $ch $sigbitcfg2db PutsScalar $dev $bitdev

}}

5.3.10 Build and Install Updated ModulesBefore building the SW, remember to stop the instrument SW.

Steps:1. > cd ~/INSXSource/dicINSX/src


3. > cd ~/INSXSource/ICS/ini/src


5. > cd ~/INSXSource/ICS/inilamp/src




Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200833 of 78

7. > cd ~/INSXSource/MS/inmcfg/src


9. > icbConfigSet INSX

5.3.11 Verification - Rebuilding and restarting the instrument softwareSteps:

1. As user insxmgr:> cd ~/INSXSource> pkginBuild inins –fromstep BUILD_ENV

2. As user insx:> ininsStart –proc ICS> ininsStart –panel ICS- Test LAMP2 device in simulation

Figure 4: Instrument Startup Panel and ICS Control Panel

Section 5.4 is optional, it contains explanations of the code for the special device for the LCU part. To skip to the next mandatory part, go to section 5.5.

5.4 Code walk-through - OptionalThe code is already provided in the module inilamp which has been copied from the archive. The following sections will focus only at the additional code in respect to the original one provided in the module xxidev. Only the most important details/changes will be discussed with the instructor. The new blocks of code are marked with “/* NEW */” – “/* END NEW */”. There is no need for the participants to do any coding during this part of the exercise.

5.4.1 Device DB, file inilamp/dbl/inilampLAMP2.db:Database definition:

POINT icbDEVICE_BASE :Appl_data:INSX:ICS:DEVICES:LAMP2BEGIN ALIAS LAMP2

// name and desc. of the device, // prefix of the FITS keywords // and LCU managing the device // ATTRIBUTE bytes20 device "lamp2" ATTRIBUTE bytes20 description "ICS device lamp2" ATTRIBUTE bytes16 prefix "INS.LAMP2" ATTRIBUTE int32 lcuId 1 ATTRIBUTE bytes32 devType "S_LAMP" ATTRIBUTE bytes32 server "inilampServer"

// status attr. (example) ATTRIBUTE double data1 10.0 ATTRIBUTE double data2 20.0

#ifdef MAKE_VXWORKS // Signal DB attributes can only be defined in LCU DB. // The corresponding attributes on WS are defined in the 'else' block. // LCU attributes will be scanned into WS attributes. ATTRIBUTE lccDIGITAL_SIGNAL on_OUT


“LAMP2” special device widget as it appears on the ICS control panel.


Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200834 of 78

ATTRIBUTE lccDIGITAL_SIGNAL on_IN ATTRIBUTE lccANALOG_SIGNAL intens_OUT ATTRIBUTE lccANALOG_SIGNAL intens_IN#else ATTRIBUTE LOGICAL on // corresponds to on_IN signal on LCU ATTRIBUTE float intens // corresponds to intens_IN signal on LCU#endif

// Devices are defined for each signal // This way we have a freedom of mixing available signals // from different controllers. ATTRIBUTE bytes16 on_OUT_dev "" ATTRIBUTE bytes16 on_IN_dev "" ATTRIBUTE bytes16 intens_OUT_dev "" ATTRIBUTE bytes16 intens_IN_dev ""

// I/O channels ATTRIBUTE int on_OUT_ch ATTRIBUTE int on_IN_ch ATTRIBUTE int intens_OUT_ch ATTRIBUTE int intens_IN_ch

// misc. attr. (do not delete) ATTRIBUTE int32 substate ATTRIBUTE int32 error

// port description. Used as example for icbConfigSet special behavior ATTRIBUTE BASE_CLASS communication BEGIN ATTRIBUTE bytes16 device ATTRIBUTE int32 fd ENDEND



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200835 of 78

5.4.2 Definition of DB attributes literals and DB access macrosFile inilampDeviceNewObj.c, addition of inilamp specific DB attributes to array attrNames[], just before NULL:

/* NEW */"on_OUT.value","on_IN.value","intens_OUT.value","intens_IN.value","on_OUT_dev","on_IN_dev","intens_OUT_dev","intens_IN_dev","on_OUT_ch","on_IN_ch","intens_OUT_ch","intens_IN_ch",/* END NEW */

File inilampDevice.h, addition of indices for the new DB attributes in the attrNames[] array:

/* NEW */#define inilampDEVICE_ATTR_ON_OUT_SIG 11#define inilampDEVICE_ATTR_ON_IN_SIG 12#define inilampDEVICE_ATTR_INTENS_OUT_SIG 13#define inilampDEVICE_ATTR_INTENS_IN_SIG 14#define inilampDEVICE_ATTR_ON_OUT_DEV 15#define inilampDEVICE_ATTR_ON_IN_DEV 16#define inilampDEVICE_ATTR_INTENS_OUT_DEV 17#define inilampDEVICE_ATTR_INTENS_IN_DEV 18#define inilampDEVICE_ATTR_ON_OUT_CH 19#define inilampDEVICE_ATTR_ON_IN_CH 20#define inilampDEVICE_ATTR_INTENS_OUT_CH 21#define inilampDEVICE_ATTR_INTENS_IN_CH 22/* END NEW */

File inilampDevice.h, addition of macros for accessing new DB attributes:

/* NEW *//* * LAMP2 specific attribute access functions */#define inilampDeviceRead_on_OUT_dev(obj,buf,error) \

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_ON_OUT_DEV,(buf),(error))#define inilampDeviceRead_on_IN_dev(obj,buf,error) \

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_ON_IN_DEV,(buf),(error))#define inilampDeviceRead_intens_OUT_dev(obj,buf,error) \

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_INTENS_OUT_DEV,(buf),(error))#define inilampDeviceRead_intens_IN_dev(obj,buf,error) \

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_INTENS_IN_DEV,(buf),(error))#define inilampDeviceRead_on_OUT_ch(obj,buf,error) \

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_ON_OUT_CH,(buf),(error))#define inilampDeviceRead_on_IN_ch(obj,buf,error) \

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_ON_IN_CH,(buf),(error))#define inilampDeviceRead_intens_OUT_ch(obj,buf,error) \

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_INTENS_OUT_CH,(buf),(error))#define inilampDeviceRead_intens_IN_ch(obj,buf,error) \

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_INTENS_IN_CH,(buf),(error))#define inilampDeviceRead_on_IN_sig(obj,buf,error) \



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200836 of 78

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_ON_IN_SIG,(buf),(error))#define inilampDeviceWrite_on_IN_sig(obj,buf,error) \

caiRWAttribute((obj)->attrs,1,inilampDEVICE_ATTR_ON_IN_SIG,(void*) (buf),(error))#define inilampDeviceRead_intens_IN_sig(obj,buf,error) \

caiRWAttribute((obj)->attrs,0,inilampDEVICE_ATTR_INTENS_IN_SIG,(buf),(error))#define inilampDeviceWrite_intens_IN_sig(obj,buf,error) \

caiRWAttribute((obj)->attrs,1,inilampDEVICE_ATTR_INTENS_IN_SIG,(void*) (buf),(error))/* END NEW */

5.4.3 Device InitializationFile inilamp/src/inilampDeviceCmds.c, function inilampDeviceInit().

The initialization code is not optimized on purpose in order to give explicit examples of how to initialize digital and analog signals as inputs and outputs.

Pseudocode:

DBREAD simulationIF simulation = T THEN

LOG SWSIM = TLOG ACTION LAMP2 INIT

ELSEINIT Analog and Digital signalsLOG ACTION LAMP2 INIT

ENDIFinitialised = TDBWRITE initialised

5.4.4 State change to STANDBYFile inilamp/src/inilampDeviceCmds.c, function inilampDeviceStandby().

Pseudocode:

DBREAD initialisedIF initialised != T THEN

INITENDIF

We could switch the lamp OFF when changing from ONLINE to STANDBY.

5.4.5 State change to ONLINEFile inilamp/src/inilampDeviceCmds.c, function inilampDeviceOnline().

Pseudocode:

DBREAD stateIF state < STANDBY THEN

STANDBYENDIFinitialised = Tstate = ONLINEDBWRITE initialisedDBWRITE state



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200837 of 78

5.4.6 State change to OFFFile inilamp/src/inilampDeviceCmds.c, function inilampDeviceOff().

The end state must be LOADED even if there are failures. Otherwise, the system would be in a deadlock if HW fails and it would not be possible to switch to simulation.

Pseudocode:

DBREAD simulationDBREAD initialisedIF initialised = T THEN

IF simulation = T THENUPDATE DBLOG INTENS = 0LOG ST = F

ELSEINTENS = 0ST = FLOG INTENS = 0LOG ST = F

ENDIFENDIFinitialised = Fstate = LOADEDDBWRITE initialisedDBWRITE state

5.4.7 Simulation ONFile inilamp/src/inilampDeviceCmds.c, function inilampDeviceSimulat().

After entering simulation, the device should be brought back to the state in which it was before.

Pseudocode:

DBREAD simulationIF simulation != T THEN

DBREAD stateIF state > LOADED THEN

OFFENDIFsimulation = TDBWRITE simulationIF state > LOADED THEN

SET STATE = stateENDIF

ENDIF



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200838 of 78

5.4.8 Simulation OFFFile inilamp/src/inilampDeviceCmds.c, function inilampDeviceStopSim().

When exiting simulation, the device should be brought to state LOADED.

Pseudocode:


OFFsimulation = FDBWRITE simulationLOG SWSIM = F

ENDIF

5.4.9 Device STATUSFile inilamp/src/inilampDeviceCmds.c, function inilampDeviceStatus().

Status is available in states STANDBY and ONLINE only.

Pseudocode:


DBREAD on_INDBREAD intens_IN

ELSEREAD_DIGITAL on_INREAD_ANALOG intens_IN

ENDIFRETURN status

5.4.10 Device SETUPFile inilamp/src/inilampDeviceCmds.c, function inilampDeviceSetup().

Setup is allowed in ONLINE state only.

Pseudocode:DBREAD simulationFOREACH (kw,val) IN setup_bufferBEGIN

PROCESS kwEND

5.4.11 Important files:$VLTDATA/config/linics1.dbcfg – created by the script iniConfigSet ($ icbConfigSet INSX)$VLTDATA/ENVIRONMENTS/linics1/bootScript – created by pkginBuild.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200839 of 78

5.5 Creating WS Lamp Special DeviceThe purpose is to implement an assembly class taking care of turning On/Off the LCU Special Lamp device and setting the intensity value using only one setup keyword. This will show how to use the ICB assemblies for more complex requirements which cannot be fulfilled using just the assembly configuration keywords.

Lamp Power: 0 – 100%Lamp Intensity: 0 - 10 [V]

The WS class will convert the power to the right intensity value.

Steps:1. Stop the ICS processes if they are already running (as user insx)

> ininsStop –proc ICS

2. Create the Lamp Class Declaration file (“iniLAMP_POWER.h”) a. Rename file “iniINS_TRAK.h”

> cd ~/INSXSource/ICS/ini/include> mv iniINS_TRAK.h iniLAMP_POWER.h> tooReplace iniINS_TRAK iniLAMP_POWER *

xxiINS_TRAK is an example of especial assembly class provided with the Template Instrument.

b. Review the contents of the new file. It should look like the following:

#ifndef iniLAMP_POWER_H#define iniLAMP_POWER_H

/* VLT file header excluded on purpose */

#ifndef __cplusplus#error This is a C++ include file and cannot be used from plain C#endif

/* * System Headers */

/* * VLT Headers */#include <fndDICTIONARY.h>#include "ic0INS_ASSEMBLY.h" // parent class

// Lamp deviceclass iniLAMP_POWER: public ic0INS_ASSEMBLY{ public:

iniLAMP_POWER(); fndStdObjectDef(iniLAMP_POWER, ic0INS_ASSEMBLY)

protected:

virtual ccsCOMPL_STAT DevTrigger(ic0KEYWORD &keyword, void*);



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200840 of 78

private:

}; /* end class iniLAMP_POWER */

#endif /*!iniLAMP_POWER_H*/

3. Create the Lamp Class Implementation File (“iniLAMP_POWER.C”)a. Rename file “iniINS_TRAK.C” to “iniLAMP_POWER.C”

> cd ../src> mv iniINS_TRAK.C iniLAMP_POWER.C> tooReplace iniINS_TRAK iniLAMP_POWER *

b. Clean up the constructor code. Remove all lines apart from the log statement.c. Replace the code for the method “DevTrigger” with the following code:

// Keyword TriggerccsCOMPL_STAT iniLAMP_POWER::DevTrigger(ic0KEYWORD &keyword, void *udata){ cout << "DevTrigger" << " command " << keyword.Command() << " keyword " << keyword.InsKeyword() << endl;

IC0_LOG4("iniLAMP_POWER: %s Called trigger for keyword %s Value %s", Name(), keyword.InsKeyword(), keyword.ValueString());

if (strcmp(keyword.Command(), ic0SETUP_CMD) == 0) {

SetupRunning(TRUE);

if (strcmp(keyword.Parameter(), "VAL") == 0) { vltINT32 power = atoi(keyword.ValueString()); IC0_LOG4("Keyword Parameter: %s Value: %d",

keyword.Parameter(),power); slxKEYW_LINE key_val; ic0KEYWORD_LIST keywordList; if (power > 0)

{ // If power is greater than zero means that lamp should be

// turned on and intensity should be set to the power value. // Keywords will be added to the keyword list and dis

strcpy(key_val,"INS.LAMP2.ST T"); keywordList.AddElement(key_val, keyword.Command()); // Convert % to Volts, 100%=10V sprintf(key_val,"INS.LAMP2.INTENS %.2f",

(10.0 * power / 100.0)); keywordList.AddElement(key_val, keyword.Command()); // dispatch keyword list if (keywordList.GetItemsInContainer() > 0) {

IC0_LOG4("Dispatch keywords: %s", keywordList.KeywordList()); return conf.handler->Dispatch(&keywordList); } }

else {

// If power is zero means that lamp should be turned off. // Keyword is added to the list and send

strcpy(key_val,"INS.LAMP2.ST F"); keywordList.AddElement(key_val, keyword.Command()); if (keywordList.GetItemsInContainer() > 0) { IC0_LOG4("Dispatch keywords: %s",

keywordList.KeywordList()); return conf.handler->Dispatch(&keywordList);



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200841 of 78

} }

} }

// SETUP error (VLTSW20040335) else if (strcmp(keyword.Command(), ic0SETUP_ERR) == 0) { if (SetupRunning()) { cout << "iniLAMP_POWER: " << Name () << " Setup error: reset values to undefined" << endl; IC0_LOG4("iniLAMP_POWER: %s Setup error: reset values to undefined", Name()); } } // SETUP OK (VLTSW20040335) else if (strcmp(keyword.Command(), ic0SETUP_OK) == 0) { if (SetupRunning()) { cout << "iniLAMP_POWER: " << Name () << " Setup completed " "successfully" << endl; IC0_LOG4("iniLAMP_POWER: %s Setup completed successfully", Name()); } } return SUCCESS;}

Method “DevTrigger” can be used to overload the keyword handling done by the ICS WS process before the setup buffer is forwarded to the LCU. In the same way it can be used to modify the reply sent by the LCU to the originator [RD10].

4. Make sure that new class is registered in file “iniControl.h”. Correct the following two lines:

#include "iniLAMP_POWER.h"RegisterStorable(POWER, iniLAMP_POWER)

5. Add assembly configuration to the configuration file “~/INSXSource/MS/inmcfg/config/inmcfgINS.cfg” including the following keywords:

INS.ASSEMBLY2 "INS.POWER"; # Assembly FITS nameINS.ASSEMBLY2.HEADER T; # Last setup value goes in the FITS headerINS.ASSEMBLY2.KEY1 "*"INS.ASSEMBLY2.VAL1 ""INS.ASSEMBLY2.FITSKEY1 "INS.POWER.VAL"

6. Rebuild ini and inmcfg modules:

> cd ~/INSXSource/ICS/ini/src> make clean all man install> cd ~/INSXSource/MS/inmcfg/src> make clean all man install> icbConfigSet INSX

7. Verify the assembly functionality sending the following commands. Check the results with the ICS control panel.

> ininsStart –proc ICS> ininsStart –panel ICS> msgSend "" iniControl ONLINE ""> msgSend "" iniControl SETUP "-function INS.POWER.VAL 0"

The above command should turn the lamp off and set the intensity to zero.

> msgSend "" iniControl SETUP "-function INS.POWER.VAL 100"



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200842 of 78

The above command should turn the lamp on and set the intensity to its maximum power.

5.6 Session SummaryIn this session we learned how to create special devices at LCU and WS levels and how to incorporate them into the existing instrument. It was also explained the need for special devices and their advantages and disadvantages compared with the existing standard devices supported by the VLTSW.

The code represents a very simple example which can be used as a sample code for more complex applications for real instruments.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200843 of 78

6 Exercise #4: Interfacing with Detector Control Systems

6.1 PurposeThe 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.

6.2 Exercise Steps

6.2.1 Adapt the Instrument Configuration for RTD Start-UpHere only one keyword is adapted. This is done because it is required by the startup 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. Go to the Instrument configuration:

> cd ~/INSXSource/MS/inmcfg/config/

2. Open instrument configuration file “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"

3. Build and install the new configuration

> cd ~/INSXSource/MS/inmcfg/src; make clean all install

6.2.2 Adapting the NGC IR Detector ConfigurationThe 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.

6.2.2.1 Updating the High Level NGC IR ConfigurationThe 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:4. Go to the NGC configuration file:

> cd ~/INSXSource/DCS/inngcir/config/

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

> rm inngcirNGCIR2.cfg

6. Open the “ctoo” configuration file, “inngcirCONFIG.cfg, and remove the second configuration set (all keywords starting with “CONFIG.SET2*”). Do not forget to save the file after you have finished.

The next step is to update the NGC system and detector configuration.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200844 of 78

6.2.2.2 Update the NGC System and Detector ConfigurationThe 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 chips along axis X.

Each chip size is 512x512 pixels.

Physical mosaic gap is 20µm.

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

Acquisition Processes: “ngciracqH2RG1” and “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-threading process running in the NGC LCU doing the data acquisition and pre-processing.

Steps:1. Go to the NGC configuration file:

> cd ~/INSXSource/DCS/inngcir/config/NGCIRSW

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

> rm inngcirDetNGCIR2.dcf inngcirSysNGCIR2.cfg

3. Update the detector configuration:

a. Open the file (“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:

DET.CHIP.NAME "myChipName"; # chip nameDET.CHIP.ID "myChipId"; # chip idDET.CHIP.ACQIDX 0; # mamp to acquisition module

TIP: from emacs use Shift-Alt-5 to do the string replacement.

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 xDET.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 xDET.CHIP.YGAP 0; # gap between chips along y

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;



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200845 of 78

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..

h. Finally, do not forget to save the detector configuration file (“inngcirNGCIR1.dcf”).

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

> cd ~/INSXSource/DCS/inngcir/src ; make clean all install

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

6.2.2.3 NGC IR VerificationThe 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:

INSX> START: Fri Aug 29 11:41:45 UTC 2008INSX> 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.

3. Verify that processes are running:> psg ngcir

You should see the following processes:



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200846 of 78

ngcircon –db ngircon –ins NGCIR1 –cfg NGCIRSW/inngcirSysNGCIR1.cfg …ngciracqH2RG1 –map 2 –im sim …

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. Verify that main server is online and the simulation mode is well defined as shown in Figure 5.

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

7. Specify the name for the image to be generated, e.g “firstImage”.8. Define the detector integration (DIT), e.g. 2 seconds as is shown in Figure 6.

Figure 6: NGCIR standalone panel – DIT specification.

9. Start the exposure by pressing “Start” button shown in Figure 5. 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. As soon 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 7. If you press “Display as one Image” button you will see the mosaic of two detectors along axis X as is shown in Figure 8.

> cd $INS_ROOT/SYSTEM/DETDATA> rtd firstImage.fits3

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. 3 Put here the name of the image that you have chosen.


NGC IR Server state NGC IR Server

simulation mode

File name specification

Detector Integration (DIT) specification


Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200847 of 78

Figure 7: RTD FITS HDU pop-up window.

Figure 8: 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 9.

Figure 9: 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 10:


Main image header and two extension headers.

Chip size.

Detector physical gap information.


Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200848 of 78

> ininsStart -panel NGCIR1_RTD

Figure 10: NGC Infrared Real Time Display.

6.2.3 Update the TCCD ConfigurationThe purpose is to define the right CCD chip configuration. In case of the Exercise Instrument, the chip configuration is one already available in the VLTSW release but not the same defined in the Template Instrument.

CCD CHIP configuration: “ccdTecE2V47.dbcfg”.

Steps:1. Go to the Instrument Configuration:

> cd ~/INSXSource/MS/inmcfg/config/

2. Open instrument configuration file “inmcfgINS.cfg” and change the contents of keyword “OCS.DET2.DBFILE” to the Exercise Instrument WS as it is shown below:

OCS.DET2.DBFILE "ccdTecE2V47.dbcfg";

3. Change the default simulation level adding keyword “OCS.DET.SWSIM” in the configuration:

OCS.DET2.SWSIM "LCU_SIM";

4. Build an install the new configuration:

> cd ~/INSXSource/MS/inmcfg/src; make clean all install

6.2.4 Update “pkgin” TCCD ConfigurationSteps:

1. Go to the integration module:

> cd ~/INSXSource/inins/config/

2. Open file “ininsINSTALL.cfg” and change the contents of keyword “INSTALL.DET2.DBFILE” as it is shown below:

INSTALL.DET2.DBFILE "ccdTecE2V47.dbcfg";


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


Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200849 of 78

3. 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). CCD sw will load the configuration from there at the process start-up.


pkginBuild inins -step INSTALL_CCD TCCD=============================================================================pkginBuild started at Wed Sep 24 07:58:15 UTC 2008Arguments = '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/INSXSource'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/INSXSource/INSTALL/pkginBuild.log/home/insxmgr/MKI/Session2/INSXSource/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)=============================================================================

6.2.5 TCCD VerificationThe 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:> ininsStart -proc TCCD


winsx insx:~ 16 > ininsStart -proc TCCD -> INIT : Reading INSX configuration.INSX> START: Tue Sep 23 13:57:07 UTC 2008INSX> 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:



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200850 of 78

insx 12141 1 0 13:57 pts/3 00:00:00 ccdconCI tccdinsx 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 the state is reached as is shown in Figure 11:

> msgSend "" ccdconCI_tccd ONLINE ""

Figure 11: 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 12.

Figure 12: TCCD image (LCU simulation)

6.3 Session SummaryThis session involved the configuration of the detector systems for the Exercise Instrument and their verification in standalone mode. The course participant should have experienced the process to prepare the different configuration files associated with the NGC infrared and technical CCD SW.


Camera Name

Chip ID Simulation Level

SW state


Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200851 of 78

7 Exercise #5: Observation Software – OS

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

7.2 Implementation DetailsThe observation modes foreseen for the fictitious 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]

7.3 Exercise Steps

7.3.1 Configure OS SubsystemsSteps:

1. Go to the Instrument configuration

> cd ~/INSXSource/MS/inmcfg/config

2. Open the configuration file “inmcfgINS.cfg”.

3. Update the telescope environment name (keyword “OCS.TEL.ENVNAME”) as is shown below:

OCS.TEL.ENVNAME “wintcs”;

4. 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.

5. Remove the FIERA subsystem from the OS configuration. i.e. all keywords starting with “OCS.DET3”.

6. Update the index of the remaining detector subsystems. Changing all keywords starting from “OCS.DET4” to “OCS.DET1” (belonging to NGCIR1).

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

# Subsystem: DET1 - NGCIR1# --------------------------------------------------------------------------OCS.DET1.NAME "NGCIR1";OCS.DET1.DICT "NGCDCS";OCS.DET1.ENVNAME "winsx";OCS.DET1.PROCNAME "inircon_NGCIR1";OCS.DET1.KEYWFILT "DET1.*.*.*.*.*.*";



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200852 of 78

OCS.DET1.TIMEOUT 20;OCS.DET1.TYPE "NGCIR";OCS.DET1.CFGSET "NGCIR1";OCS.DET1.DBROOT "<alias>ngcircon_NGCIR1";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";

9. Build and Install the module “inmcfg”:> cd ~/INSXSource/MS/inmcfg/src; make clean all install

7.3.2 OS Database ConfigurationSteps:

1. Go to the OS module:

> cd ~/INSXSource/OS/ino/

2. Update the subsystem list in the main OS server database class (file “dbl/inoSERVER.class”) and remove the detector subsystems which are not used. Final configuration should be as is shown below:

CLASS bossINTERFACE_LIST inodbSUB_SYSTEMSBEGIN ATTRIBUTE bossINTERFACE_TCCD tccd ATTRIBUTE bossINTERFACE_NGCIR ngcir1



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200853 of 78

ATTRIBUTE bossINTERFACE_ICS ics ATTRIBUTE bossINTERFACE_TCS tcsEND

3. Build and Install the module “ino”:> cd ~/INSXSource/OS/ino/src; make clean all install

4. Rebuild the WS environment database:

> cd ~/INSXSource/> pkginBuild inins -fromstep BUILD_ENV -env winsx wintcs

7.3.3 OS VerificationThis part should be carried out as user “insx”.

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

> ininsStartup

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

Figure 13: 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 fixed in order to fix this problem but this is outside the scope of this exercise. Nevertheless errors 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 and IRACE systems.7. Verify the access of all the subsystems using the ACCESS command:

> msgSend "" inoControl ACCESS "-info"



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200854 of 78

The reply should be something like the following:

MESSAGEBUFFER:

UT1 IGNOREICS NORMALNGCIR1 NORMALTCCD 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 NORMALICS NORMALNGCIR1 NORMALTCCD NORMAL

11. Open the TCS Simulation User Manual and preset the telescope to the 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 and verify that image is created and contains all the subsystem keywords (“DET”, “INS” and “TEL”):

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


Telescope preset to a named position (zenith)


Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200855 of 78

> msgSend "" inoControl START "-detId NGCIR1"> msgSend "" inoControl WAIT ""

The reply should be like the following:

MESSAGEBUFFER:Observation status: INTEGRATINGMESSAGEBUFFER:Exposure status: FINISHED

> cd $INS_ROOT/SYSTEM/DETDATA> slxCatFits myFirstFile<day of year>_<number>.fits



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200856 of 78

8 Exercise #6: Templates

8.1 PurposeThe 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.

8.2 Additional Information

Figure 14: 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

8.3 Implementation DetailsThe list of science templates for the Exercise Instrument is based on the assumption of the following request:

1 Normal Acquisition Template ("INSX_img_acq").



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200857 of 78

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

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").

8.4 Exercise Steps

8.4.1 Prepare science TSF Files (module “inotsf”)Steps:

1. Go to the scientific TSF module:

> cd ~/INSXSource/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 file “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.DIT.TEST.VALUE "1"DET2.UIT.TEST.VALUE "5"

f. Finally, do not forget to save the file “config/INSX.isf”.

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 ~/INSXSource/OS/inotsf/src/

b. Rename file “INSX_irimg_acq.tsfx” to follow 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” to follow the naming

> mv INSX_ngcirimg_acq_MoveToSlit.tsfx INSX_img_acq_MoveToSlit.tsfx



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200858 of 78

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 ~/INSXSource/OS/inotsf/include> tooReplace DET4 DET1 inotsfNGCIR_DET_DIT.tsfx

g. Open the file “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"; # Reference setup fileTPL.PRESEQ "INSX_img_acq.seq"; # Sequencer script

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”. The include entries should looks like the following:PAF.INCLUDE "inotsfTEL.tsfx"PAF.INCLUDE "inotsfSEQ_PRESET.tsfx"

j. Open the file “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"; # Reference setup fileTPL.PRESEQ "INSX_img_acq_MoveToSlit.seq"; # Sequencer script

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: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” to follow the naming convention for templates:> 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"



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200859 of 78

6. Add an AutoJitter observation (Optional):

a. Create the TSFX file “inotsfSEQ_NOFFSET.tsfx” with the following contents:#*********************************************************************# NAME# inotsfSEQ_NOFFSET - number of exposures# #---------------------------------------------------------------------#

TPL.PARAM "SEQ.NOFFSET";SEQ.NOFFSET.TYPE "integer";SEQ.NOFFSET.RANGE "1..1000";SEQ.NOFFSET.DEFAULT "NODEFAULT";SEQ.NOFFSET.LABEL "Number of offsets within a box";SEQ.NOFFSET.MINIHELP "Number of offsets within a box";

b. Create the TSFX file “inotsfSEQ_JITTER_WIDTH.tsfx” with the following contents:#*********************************************************************# NAME# inotsfSEQ_JITTER_WIDTH - keyword SEQ.JITTER.WIDTH# #---------------------------------------------------------------------#

TPL.PARAM "SEQ.JITTER.WIDTH";SEQ.JITTER.WIDTH.TYPE "number";SEQ.JITTER.WIDTH.RANGE "5..60";SEQ.JITTER.WIDTH.DEFAULT "NODEFAULT";SEQ.JITTER.WIDTH.LABEL "Jitter Box Width (arcsec)";SEQ.JITTER.WIDTH.MINIHELP "Jitter Box Width (arcsec)";

c. Create the TSFX file “inotsfSEQ_POISSON_IDIS.tsfx” with the following contents:#*********************************************************************# NAME# hkotsfSEQ_POISSON_IDIS – Poisson Index of Dispersion# #---------------------------------------------------------------------#

TPL.PARAM "SEQ.POISSON.IDIS";SEQ.POISSON.IDIS.TYPE "integer";SEQ.POISSON.IDIS.RANGE "1..100";SEQ.POISSON.IDIS.DEFAULT "10";SEQ.POISSON.IDIS.LABEL "Poisson index of dispersion";SEQ.POISSON.IDIS.MINIHELP "Poisson index of dispersion";SEQ.POISSON.IDIS.HIDE "OHS";

d. Create the TSFX file “INSX_img_obs_AutoJitter.tsfx” with the following contents:#*********************************************************************# NAME# INSX_img_obs_AutoJitter - Imaging with jitter # #---------------------------------------------------------------------#PAF.HDR.START;PAF.ID "$Id$"PAF.DESC "Imaging with jitter";PAF.CRTE.NAME "";PAF.CRTE.DAYTIM "";PAF.LCHG.NAME "";PAF.LCHG.DAYTIM "";



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200860 of 78

PAF.HDR.END;

TPL.INSTRUM "INSX";TPL.MODE "IMAGING";TPL.VERSION "$Revision: 1.16 $";TPL.REFSUP "";TPL.PRESEQ "INSX_img_obs_AutoJitter.seq";TPL.TYPE "science";

PAF.INCLUDE "inotsfSEQ.tsfx";PAF.INCLUDE "inotsfNGCIR_DET.tsfx";PAF.INCLUDE "inotsfINS_FILT.tsfx";PAF.INCLUDE "inotsfSEQ_NOFFSET.tsfx";PAF.INCLUDE "inotsfSEQ_JITTER_WIDTH.tsfx";PAF.INCLUDE "inotsfSEQ_POISSON_IDIS.tsfx";

7. 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:>

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

> cd inotsf/src> make install

e. Check that files are installed in the INS_ROOT directory:> cd $INS_ROOT/SYSTEM/COMMON/TEMPLATES/TSF

8.4.2 Prepare the Sequencer Files (Module: “inoseq”)Steps:

1. Go to the scientific template script module:> cd ~/INSXSource/OS/inoseq/src

2. Remove unnecessary files:> rm INSX_irimg* INSX_optimg* INSX*spec* inoseqGenTecSelfTest.txt_with_midas

3. Rename sequencer files:> 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. Update Telescope Focus ID in the acquisition sequencer file. Open file “INSX_img_acq.seq” and change the line where the “tplTCS” object is created. The ID of Cassagrain focus is “CA”. The new line should looks like the following:tplTCS tcs TCS ino tcs CA INSX

6. Do the same as step 5 with file “INSX_img_acq_MoveToSlit.seq”.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200861 of 78

7. 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]

8. Do the same as step 7 with file “INSX_img_acq_MoveToSlit.seq”.

9. 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.

10. 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.";

11. Copy the new OBDV file as “INSX_img_acq_MoveToSlit.obdv”:

> cp INSX_img_acq.obdv INSX_img_acq_MoveToSlit.obdv

12. 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";

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

> cd ~/INSXSource/OS/inoseq/config> rm *.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_img_obs_exp.ref” according the functions of the Exercise Instrument:



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200862 of 78

INS.MODE "IMAGING";DET1.SEQ.DIT 1.0; # integration timeDET1.SEQ.EXPTIME 5.0; # Exposure time

INS.LAMP1.ST "F"; # lamp on/offINS.LAMP2.ST "F"; # lamp on/offINS.SHUT1.ST "F"; # shutter on/offINS.MIRR1.NAME "Out"; # device named position

14. Add the AutoJitter Observation (Optional):

a. Create file “INSX_img_obs_AutoJitter.seq” with the following contents:#*********************************************************************# NAME# INSX_img_obs_AutoJitter - Imaging with jitter# # DESCRIPTION# This template offsets the telescope between exposures according# to a random pattern of offsets.##---------------------------------------------------------------------#proc INSX_img_obs_AutoJitter { } { seeBobVars

#----------------------------------------------------------------- # Object generation # catch {delete object obs} catch {delete object tcs} catch {delete object dcs} catch {delete object clip}

tplOBS obs ino tplTCS tcs TCS ino tcs CA INSX tplCLIP clip clipObj

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

set funcS " \ -file $TPL(REFSUP) \ -function INS.MODE $TPL(MODE) \ [dcs ExpTime] \ INS.FILT1.NAME $INS(FILT1.NAME)"

obs Setup $funcS

set nexpo $SEQ(NEXPO); set noffset $SEQ(NOFFSET)set TPL(NEXP) [expr {$nexpo*$noffset}];

#-------------------------------------------------------# Prepare exposure loop#set jwidth $SEQ(JITTER.WIDTH); set dispersion $SEQ(POISSON.IDIS);

# generate offset values

lassign [clip Poisson $jwidth $noffset $homog] offA offD;



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200863 of 78

tplLog "Offset list in Alpha: $offA"tplLog "Offset list in Delta: $offD"

set sumA 0 set sumD 0

#--------------------------------------------------------------# Run the exposures#loop i 0 $noffset { # Relative offsets set dA [expr {[lindex $offA $i] - $sumA}] set dD [expr {[lindex $offD $i] - $sumD}] # Offset the telescope tplLog "Offsetting A/D ...: [format %.3f $dA], \

[format %.3f $dD] (arcsec)" \ black 1 LightGreen

Set cmdId [tcs SendOffsadg $dA $dD] tcs Wait $cmdId set sumA [expr {$sumA + $dA}] set sumD [expr {$sumD + $dD}] loop j 0 $nexpo {

set buffer "-function INS.MODE $TPL(MODE)"obs Setup $buffer

obs Expose $TPL(ID) $dcsFullName $buffer {} 1 \ [obs ImgName]

}}

} { if { $errorResult != "" } {

tplLog "Template error: $errorResult"} obs Wait 0 "-all"

if {"$SEQ(RETURN)" == "T"} { set msg "Returning to initial position" tplLog $msg black 1 Yellow # get accumulated offsets and offset set cmdId [tcs SendOffadg $sumA $sumD] tcs Wait $cmdId}

} return {}

}

b. Create file “INSX_img_obs_AutoJitter.obdv” with the following contents:PAF.HDR.START;PAF.TYPE "Template";PAF.ID "$Id$";PAF.NAME "INSX_img_obs_AutoJitter";PAF.DESC "IR imaging AutoJitter observation";PAF.CRTE.NAME "";PAF.CRTE.DAYTIM "";PAF.LCHG.NAME "";PAF.LCHG.DAYTIM "";PAF.CHCK.NAME "";PAF.CHCK.DAYTIM "";PAF.CHCK.CHECKSUM "";PAF.HDR.END



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200864 of 78

SEQ.NEXPO "1";SEQ.POISSON.IDIS "10";SEQ.NOFFSET "5";SEQ.JITTER.WIDTH "50";INS.FILT1.NAME "H";DET1.SEQ.DIT "1";

15. Update file “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.tsfINSX_img_acq_MoveToSlit.tsfINSX_img_obs_exp.tsf# Optional#INSX_img_obs_AutoJitter.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”:> cd ~/INSXSource/OS/inoseq/src> make clean all install

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 7.3.3).

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”).

Figure 15: 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].



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200865 of 78

8.4.3 Prepare Technical TSF Files (module: “inmtsf”)Steps:

14. Go to the technical TSF module:> cd ~/INSXSource/MS/inmtsf/

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

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

16. Add the Bias TSF:b. Go to the sources 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_gen_tec_bias.tsfx” and change the keyword “TPL.MODE” as is shown below:TPL.MODE "CALIBRATION"; # Valid for all modes

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

g. Replace the last part of the file with the following and do not forget to save the file:PAF.INCLUDE "inotsfSEQ.tsfx";PAF.INCLUDE "inotsfTCCD_DIT.tsfx";

17. Build and Install the module “inmtsf”.> make clean all install

8.4.4 Prepare Technical Sequence Files (module “inmseq”)Steps:

1. Go to the technical sequencer module:> cd ~/INSXSource/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:> tooReplace optimg_tec_parasitic gen_tec_bias *

k. Update the file “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



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200866 of 78

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 ~/INSXSource/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:> tooReplace optimg_tec_parasitic gen_tec_bias *

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:## INS_ROOT files to be installed#-------------------------------INS_ROOT_FILES = ../config/*.ref ../config/*.obd *.seq

b. Install the files:> make clean all install

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.

8.5 Session SummaryDuring 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.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200867 of 78

9 Exercise #7: Online Image Processing with CLIPThe purpose of this session is to show a practical example of how to do the acquisition of the instrument aligning the object along the slit. A customized version of the NGC IR server will be implemented to generate a simulated star that will be used to compute the image centroid and obtain the offset that will correct the Telescope position. The acquisition template will be modified to implement the high level interaction with the user.

9.1 Exercise Steps

9.1.1 Customize NGC IR ServerThe server will provide the following features:

Static allocation of shared memory. Generation of a simulated image containing an artificial star that will be used to compute

image centroid. Writing the image in shared memory.

NGC IR SW can be extended for instrument specific image post-processing requirements. This is achieved overloading method PostProcCB of the ngcirconEVH class [RD6].

Steps:1. Generate a new module “inircon” from the NGC template:

> cd ~/INSXSource/DCS> cmmCopy ngcircon> cp –r ngcircon/templates/xxircon inircon> chmod –R u+w inircon

2. Rename and replace the module names:

> cd inircon/src> mv xxircon.C inircon.C > tooReplace xx in *

3. Using “getTemplate” tool create the include file “inircon.h”:

> cd ../include> getTemplate

4. Open the include file and add the following contents. This class is similar to the one from the NGC template but modified to include the CLIP libraries and objects (changes in red):

#ifndef INDNGCIR_H#define INDNGCIR_H

#ifndef __cplusplus#error This is a C++ include file and cannot be used from plain C#endif

#include "ngcirconEVH.h"#include "ipclSHM_CONTROL.h"#include "clipvRTD_EVT_SEND.h"#include "clipvIMG_WRAPPER_FLOAT.h"

/* * Server class



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200868 of 78

*/class inirconEVH: public ngcirconEVH{ public: // Constructors inirconEVH(); inirconEVH(ngcdcsCTRL *controller);

// Destructor virtual ~inirconEVH();

// Post-processing call-back int PostProcCB(void *, ngcdcs_finfo_t *, eccsERROR *); int Initialize(); protected:

private: ipclSHM_CONTROL *_shmControl; clipvRTD_EVT_SEND *_rtdEvtSend; ipclShmInfo _shmInfo;};

#endif /*!INDNGCIR_H*/

5. Adapt the class implementation (“inircon.C’’) as it shown below (changes from the NGC template are in red)

> cd ~/INSXSource/DCS/inircon/include

Now update the file with the contents below

/* VLT file header excluded on purpose */#define _POSIX_SOURCE 1

// Uncomment this if you are using the VLT environment#include "vltPort.h"

__attribute__((__unused__)) static char *rcsId="@(#) $Id: inircon.C,v 1.4 2008/08/19 09:04:32 vltsccm Exp $";

#include "inircon.h"

inirconEVH::inirconEVH(): _shmControl(NULL), _rtdEvtSend(NULL){}

inirconEVH::inirconEVH(ngcdcsCTRL *controller): ngcirconEVH(controller), _shmControl(NULL), _rtdEvtSend(NULL){}

inirconEVH::~inirconEVH(){ if (_rtdEvtSend)



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200869 of 78

delete(_rtdEvtSend); if (_shmControl) delete(_shmControl); Verbose("inircon: terminating...\n"); Verbose("inircon: down...\n");}

/* * Post-proces// sing call-back// */ int inirconEVH::PostProcCB(void *buffer, ngcdcs_finfo_t *finfo, eccsERROR *error) { int ret = ngcbSUCCESS; USE(buffer); USE(error);

Verbose(2, "inirconEVH: post processor for %s...\n", finfo->name);

ErrReset(); if (finfo->type == ngcppFRAME_INT) { clipvDATA_IO dataIO; clipvIMG_WRAPPER_FLOAT image;

// Define output channel dataIO.SetOutput(_rtdEvtSend);

// Access image from frame buffer, not really needed for the // exercise. if (image.Read(buffer, finfo->nx, finfo->ny, FLOAT) == FAILURE) { error->ErrAdd(ngcdcsMOD_ID, ngcdcsERR_EXP_PROC, __FILE_LINE__, "wrapping a float frame into a cpl object"); return ngcbFAILURE; }

// Copy the incoming frame clipvIMG_WRAPPER_FLOAT imageCopy(image);

// Hardcoded position of simulated star. // Position is shifted 12 pixels from the center imageCopy.FillGaussian(524,262, 5, 8,8); // Increase the pixel intensity

imageCopy *= 1000;

// Write into shared memory and send image event to the RTD server if (imageCopy.Write(&dataIO) == FAILURE) { error->ErrAdd(ngcdcsMOD_ID, ngcdcsERR_EXP_PROC, __FILE_LINE__, "sending data to the rtd server");

return ngcbFAILURE; }}

return (ret);}

int inirconEVH::Initialize() {



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200870 of 78

int ret = ngcbSUCCESS;

// Camera name is the index for shared memory configuration _shmControl = new ipclSHM_CONTROL("inocam");

// Allocate the shared memory with maximum size of the detector Verbose(2,"Allocating shared memory (1024 * 1024 * (32/8) ..."); if (_shmControl->Allocate("inocam",4194304) == FAILURE) {

Verbose(2,"Error allocating shared memory"); return FAILURE; }

// Get shared memory information if (_shmControl->GetInfo("inocam", &_shmInfo) == FAILURE) { ErrAdd(ngcdcsMOD_ID, ngcdcsERR_EXP_PROC, __FILE_LINE__,

"Error getting shared memory information"); ret = ngcbFAILURE; } // Create object to send RTD image events to the RTD Server _rtdEvtSend = new clipvRTD_EVT_SEND("inocam",

_shmInfo.shmId[0], _shmInfo.semId);

// Register to the RTD Server Verbose(2,"Registering to the RTD server ..."); if (_rtdEvtSend->Init() == FAILURE) {

ErrAdd(ngcdcsMOD_ID, ngcdcsERR_EXP_PROC, __FILE_LINE__,"Error registering to the RTD server");

ret = ngcbFAILURE; }

return (ret);}/* * Control server */static int serverProcess(int argc, char **argv){ ngcdcsCTRL_CLASS controller; inirconEVH server(&controller); int exitStatus;

/* * Server default settings */ server.SysCfgDefault("NGCIRSW/ngc.cfg"); server.DbPointDefault("<alias>ngcircon");

if (server.Initialize() == ngcbFAILURE) return (1); /* * Server main-loop */ exitStatus = ngcdcsServerProcess(&server, argc, argv);

return (exitStatus);}



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200871 of 78

/* * Main entry point */int main(int argc, char *argv[]){ int exitStatus; char procName[64]; ccsERROR error;

/* * CCS init */ memset(procName, 0, sizeof(procName)); ngcdcsSetEnv(argc, argv, procName); if (ccsInit(procName, ccsOBI_CARE_OFF|ccsOBI_CLEANUP_ON,

NULL, ngcdcsEvhKillHandler, &error) == FAILURE) { errPrint(&error); exit(1); }

/* * Call server */ exitStatus = serverProcess(argc, argv);

ccsExit(&error);

exit(exitStatus);}

/*___oOo___*/

6. Rename the CDT file “xxircon.cdt”:

> cd ../CDT> mv xxircon.cdt inircon.cdt> tooReplace xxir inir ini*

7. Go back to the sources and update the “Makefile” including the libraries needed by CLIP (additional libraries are in red):

inircon_LIBS = ngcirconLib $(ngcdcsLIBS) cplcore cpldrs rt ipcl clipm clipv

8. Build and Install the module:

> make all install

9. Modify NGC IR configuration according the new server name:a. Stop NGC IR and OS SW if it they are running (as user “insx”):

> ininsStop –proc NGCIR1> ininsStop –proc OS

b. Go the configuration directory (as user “insxmgr”):

> cd ~/INSXSource/DCS/inngcir/config



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200872 of 78

c. Change NGC IR configuration file (“inngcirNGCIR1.cfg”) with the new server name (keyword “DET.CON.SERVER”). The new setting should be like the following:

# Control server nameDET.CON.SERVER "inircon";

d. Build and install module:

> cd ../src> make all install

10. Modify OS part of the Instrument Configuration according the new server name:

a. Go the configuration directory:

> cd ~/INSXSource/MS/inmcfg/config

b. Change OS configuration file (“inmcfgINS.cfg”) with the new server name (keyword “OCS.DET1.PROCNAME”). The new setting should be like the following:

# Control server nameOCS.DET1.PROCNAME "inircon_NGCIR1";

c. Install the new configuration:

> cd ../src> make all install

11. Verify that new server is working properly (as user “insx”):a. Start server and check that no errors are reported:

> ininsStart –proc NGCIR1> ininsStart –proc OS

b. Put instrument software to state ONLINE from the OS Control Panel.c. Start RTD application and attach it to the camera events (menu “Real-Time”, option

Attach Camera):

> rtd –camera inocam

d. Take an image running the observation template (“INSX_img_obs_exp”). After the exposure is finished, the image should appear in the RTD as is shown in Figure 16.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200873 of 78

Figure 16: Average frame after NGC IR server customization.

9.1.2 Create an RTD acquisition panel

Acquisition panel is intended to replace the second RTD application used by instruments to support the instrument acquisition. This panel can be built using the panel editor and the RTD for CLIP (rtdc).

Steps:

1. Go to the science template module:

> cd ~/INSXSource/OS/inoseq/src

2. Open “panelEditor” tool:

> panelEditor &

3. Once it is already open, enlarge the default panel window to be able to place the RTD widgets.

4. Import the RTD mega widgets from library “librtdcClass.tcl”. You can find this library in the INTROOT (or VLTROOT). Organize the imported widgets within the panel as is shown in the Figure 17:

a. Import rtdcImage.tclb. Import rtdcColorRamp.tclc. Import rtdcPan.tcld. Import rtdcZoom.tcl

5. Define the database current point on each imported mega widget. This is the entry point for the event handling via the database. The defined alias for the RTD acquisition panel is `inortdc’ and this is defined in the template database file (“inoseq/inoseq.db”):

#define rtdcNAME inortdc



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200874 of 78

Figure 17: Building an Acquisition Panel with Panel Editor.

6. Add some buttons to be able to zoom in and out, clear and do the autocut over the image:a. Add button “Clear” with the Tcl command “rtdcClearImg inortdc”b. Add button “Zoom+” with the Tcl command “rtdcIncZoom inortdc 1”c. Add button “Zoom-“ with the Tcl command “rtdcIncZoom inortdc -1”d. Add button “Autocut” with the Tcl command “rtdcAutocut inortdc”

Figure 18: Adding image control buttons.

7. Add image status information for mouse motion events:a. Add an output widget for the pixel intensity and define it as is shown in the figure


Define public variable –dbcwp with alias of the CLIP RTD root point:

<alias>inortdc

TCL command implementing the image autocut feature.

Control buttons


Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200875 of 78

Figure 19: Defining the output values (pixel intensity) related with the mouse position.

b. Add two more output widget for position X and Y using the following data:Length: 8 Widget name: “rtdcX” and “rtdcY” respectively.Label: “X” and “Y” respectively.

8. Save the panel as a class with the name “inoseqAcqPanel” (menu File option “Save Class As ...”). Replace the file with the same name which is only a place holder for the instrument acquisition panel.

9.1.3 Modify the Acquisition Template (MoveToSlit)Steps:

1. Go to the science template module:

> cd ~/INSXSource/OS/inoseq/src

2. Open file “INSX_img_acq_MoveToSlit.seq”:

a. Uncomment the lines related with the clip interaction:

clip Attach inocam obs Start [dcs Subsystem] $expId

set cmdId [obs WaitAsync $expId "-detId [dcs Subsystem]"] clip Wait 120000


In order to have the image intensity at mouse position automatically displayed within the output widget it is needed to define the widget name as “rtdcVALUE”.


Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200876 of 78

b. Adapt the computation of the shift from the slit center:

if {"$SEQ(ACQ.USER)" == "T"} { # Ensure the image has been displayed. update # Call the panel RTD pick object.

lassign [rtdcPick inortdc] posX posY # Close Pick Object Window after 4000 rtdcPickCancel inortdc } else { # Compute automatically the center gass within the # reference box.lassign [clip CenterGauss inocam $SEQ(ACQ.REFX) $SEQ(ACQ.REFY) \

$SEQ(ACQ.WIDTH)] posX posY

}

c. Build the module and execute template “INSX_img_acq_MoveToSlit” from BOB. Figure 20 shows how the final result should look like. The green box and the cross indicate the window used to compute the centroid and its centre. The red cross indicates where the centre was computed.

Figure 20: Final result after the template execution.

d. Change the template keyword “SEQ.ACQ.USER” to “T” to pick object manually, and rerun the template. When the image is displayed, pick the object and observe that the telescope is offset.

9.2 Session SummaryThe course participant should have learnt how to use CLIP from two different interfaces: templates for all requirements having no explicit time constraints and from the NGC IR for the cases when is needed to add post-processing as soon the image is available in the IWS. In addition it has been shown how to build a custom RTD display using the Panel Editor to support the instrument acquisition.



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200877 of 78

10 Appendix AThis appendix contains instructions for how to reconfigure our devices so their configuration matches our setup in the lab. Only “SHUT1” and “LAMP1” are not configured properly yet.

Steps:1. Open the Instrument Configuration, "~/INSXSource/MS/inmcfg/config/inmcfgINS.cfg", with a

text editor.2. Replace the SHUT1 configuration with the following that matches our hardware configuration

in the lab:

# Device shut - Entrance shutter, MEN interface### Order of signals#-----------------------------------------------------# KW description bit SIGUSED #-----------------------------------------------------# SIGBIT1 ".shutSwitchO" 0 1 # SIGBIT2 ".shutOpenI" 1 2 # SIGBIT3 ".shutClosedI" 2 4 # SIGBIT4 ".localI" 3 8 # SIGBIT5 ".faultI" 4 16 ## In our setup, we use ".shutSwitchO", ".shutOpenI", ".shutClosedI" and ".localI",# SIGUSED = 1 + 2 + 4 + 8 = 15#INS.SHUT1.DEVNAME "shut"; # Name of the ICS deviceINS.SHUT1.DEVDESC "Entrance shutter"; # Description of the ICS deviceINS.SHUT1.LCUID 1; # Id. of the LCU managing the deviceINS.SHUT1.SWSIM F; # If T, function is software simulated

INS.SHUT1.ID "SHUT1";INS.SHUT1.NAME "MEN_Shutter";INS.SHUT1.SIGUSED 15;

# MEN digital I/O interface setupINS.SHUT1.SIGDEV "/men3";INS.SHUT1.SIGBIT1 1; # Shutter OPEN Control (output)INS.SHUT1.SIGBIT2 11; # OPEN Status (input)INS.SHUT1.SIGBIT3 12; # CLOSED Status (input)INS.SHUT1.SIGBIT4 10; # Local mode (input)INS.SHUT1.SIGLOW1 T; # Active LOWINS.SHUT1.SIGLOW2 F; # Active HIGHINS.SHUT1.SIGLOW3 F; # Active HIGHINS.SHUT1.SIGLOW4 F; # Active HIGHINS.SHUT1.IGFAULT T;

3. Replace the LAMP1 configuration with the following that matches our hardware configuration in the lab:

# Device lamp - Sodium Lamp, CANBus interface### Order of signals#-----------------------------------------------------# KW description bit SIGUSED #-----------------------------------------------------# SIGBIT1 ".lampSwitchO" 0 1 USED# SIGBIT2 ".standbyO" 1 2 NEVER USED !!!# SIGBIT3 ".localI" 2 4 USED# SIGBIT4 ".lampOnI" 3 8 USED# SIGBIT5 ".standbyI" 4 16 NEVER USED !!!# SIGBIT6 ".faultI" 5 32 USED## In our setup, we use ".lampSwitchO", ".localI" and ".lampOnI" signals,# SIGUSED = 1 + 4 + 8 = 13



Doc:IssueDatePage

VLT-MAN-ESO-17240-46180.2304.10.200878 of 78

#

INS.LAMP1.DEVNAME "lamp"; # Name of the ICS deviceINS.LAMP1.DEVDESC "Sodium lamp"; # Description of the ICS deviceINS.LAMP1.LCUID 1; # Id. of the LCU managing the deviceINS.LAMP1.SWSIM F; # If T, function is software simulated

INS.LAMP1.ID "LAMP1";INS.LAMP1.NAME "Sodium_Lamp";INS.LAMP1.SIGUSED 13;

# CANBus digital I/O interface setupINS.LAMP1.SIGDEV "/canio0";INS.LAMP1.SIGBIT1 32; # Lamp ON Control (output)INS.LAMP1.SIGBIT3 0; # Local mode (input)INS.LAMP1.SIGBIT4 2; # ON Status (input)INS.LAMP1.SIGLOW1 F; # Active HIGHINS.LAMP1.SIGLOW3 F; # Active HIGHINS.LAMP1.SIGLOW4 F; # Active HIGHINS.LAMP1.IGFAULT T;

4. Rebuild and install module inmcfg:

> cd ~/INSXSource/MS/inmcfg/src> make clean all man install> icbConfigSet INSX

5. Start ICS and its GUI as user insx:

> ininsStart –proc ICS> ininsStart –panel ICS

6. Bring ICS to OFF (LOADED) and then ONLINE. NOTE: new configuration is always re-loaded during standard device initialisation. Therefore, after changing and installing new configuration, it is enough to go OFF and ONLINE with these devices in order for the changes to take effect.

7. Test each device including switching simulation ON and OFF.
