4 INSTALLATION GUIDE

The CCD sw is delivered as part of the VLT sw distribution kit.

This section describes step by step all what is needed to make the CCD sw ready to run and the test procedures to verify the correctness of the installation

4.1 GENERAL

The VLT CCD Control Software currently includes:

· the LCU-Transputer interface (LCU and ACE part).

· the CCD Software (WS, LCU and ACE parts for science and technical CCDs).

and all the relevant documentation in both printed and PostScript file format.

The distribution kit contains all the sources needed to regenerate the software and can be installed with or without the real camera hardware (ACE in simulation).

4.1.1 Copyright

See [7].

4.2 SUPPORTED CONFIGURATION

4.2.1 Hardware

The following components are needed by ACE based CCD systems, in addition to the VLT standard ones, listed in [7]:

WS

· one or more big hard-disk(s) for image storage.

LCU (not needed if LCU sw is simulated):

· a 19" VME bus chassis with power supply and 32-bit backplane

· CPU board (currently MVME167), equipped with enough RAM to accommodate the whole software and at least one full image (minimum 8 MBytes; for scientific cameras: 32 Mbytes or more is recommended)

· Transputer Link Interface Board (INMOS B016). This board uses 24-bits addresses and therefore it must be connected to the CPU board over the backplane also on the P2 connector. This board is not needed if ACE sw is simulated (see section 2.4).

· ESO Transputer Link Adapter Board. For TCCDS systems it is connected to the Transputer Link Interface Board through a flat cable over P2 (cable delivered with the system). This board is not needed if ACE sw is simulated.

· (optional) ESO Time Interface Module (TIM) to connect to the Time Reference System (TRS). This board makes special usage of the P2 connector. It must therefore be plugged in the VME chassis in a slot where P2 is not connected to the backplane.

ACE (not needed if ACE sw is simulated)

· Complete ACE box

Note: More information about the hardware configuration of TCCDS systems can be found in [15].

4.2.2 Software

UNIX Operating System (see [7] for the types and versions supported).

VLT Common Software - OCT98, installed including RTAP and VxWorks according to [7])

(optional) VLT Real Time Display, installed according to [26].

(optional) INMOS D4305 package.
This package is needed to compile and generate the transputer part of the CCD sw, running on ACE. For all those configurations where this package is not available, no compilation takes place and executable files are directly installed. The installation procedure assumes that the INMOS package is available if the environment variable ISEARCH is defined.

(optional) Perimos DTM560 package.
This package is needed to compile and generate the DSP part of the CCD sw, running on ACE. For all those configurations where this package is not available, no compilation takes place and executable files are directly installed. The installation procedure assumes that the Perimos package is available if the environment variable DSP_ROOT is defined.

4.3 CONTENTS

The VLT CCD Control Software is delivered as part of the VLT sw release. See [7] for more information about the contents.

4.4 PROBLEM REPORTING/CHANGE REQUEST

See [7] for how to report problems/errors or suggested changes in software or documentation.

4.5 INSTALLATION

See [7].

4.6 CONFIGURATION

After successful installation of the software, the following steps will take you through the configuration of a complete CCD system. A CCD system requires a WS environment, an LCU and an ACE. Although existing environments can be used, we suggest to perform the configuration using new environments. Once you are familiar with that, the integration of the CCD software to an existing project is a straight forward process.

This section assumes that you master the process of creating/configuring environments, including the directory structure and available tools. (If not, please have a look to the configuration and verification section of [7]).

4.6.1 Environment variables.

Some environment variables are used on Workstation by the CCD sw and therefore must be defined; some of them, marked with (*), are optional: if they are not defined, the specified default value is taken.

HOST
name of the local Workstation. It has to be set to the value returned by the command hostname:

$ setenv HOST `hostname`

RTAPENV
name of the workstation CCS environment where CCD sw runs. Example:

$ setenv RTAPENV wmyccd

INS_ROOT
name of the root directory where data dictionaries, setup and configuration files are stored/retrieved (see [4] for the full directory structure). At least the root directory must exist, all the sub-directories needed by the CCD software, if not existing, will be created and populated in the next step (4.6.4).

Note that, although INS_ROOT has been defined only for instrumentation sw, it has to be defined and must exist also for technical CCD cameras.

CCDNAME
name of the CCD camera (max. 7 characters). Examples:

$ setenv CCDNAME myccd right

$ setenv CCDNAME myccdred wrong! (8 characters)

The alias name of the root point for the database CCD branch (see also point 4.6.3) must be the same as the value of the environment variable CCDNAME.

CCDLENV
name of the LCU environment where CCD sw runs. Example:

$ setenv CCDLENV lmyccd

CCDDXF (*)
name of the WS host receiving CCD image data (see [23]). If not defined, default is the contents of the environment variable HOST (same LAN used for messages and data). Example:

$ setenv CCDDXF texxAtm

INS_HOST (*)
name of the Workstation hosting the disk containing the INS_ROOT directory. If not defined, default is the local Workstation (see HOST above). Example:

$ setenv INS_HOST $HOST

INS_USER (*)
INS_ROOT branch for setup files search (see [4] for more details). If not defined, default is SYSTEM.Example:

$ setenv INS_USER SYSTEM

CCDDID (*)
Name of Data Interface Dictionary to be used (excluded prefix ESO-VLT-DIC.). If not defined, default is CCDDCS. Example:

$ setenv CCDDID FORS

The Data Interface Dictionary file must be stored in $INS_ROOT/SYSTEM/Dictionary.

The default Dictionary file (ESO-VLT-DIC.CCDDCS) is in $VLTROOT/config.

In the following sections we assume as example that the following definitions are done (all optional variables are defaulted):

$ setenv CCDNAME myccd

$ setenv RTAPENV wmyccd

$ setenv HOST `hostname`

$ setenv CCDLENV lmyccd

$ setenv INS_ROOT /diskc/myName/insroot

4.6.2 Single CCD stand-alone camera

Whenever the CCD camera is going to be used as a simple stand-alone instrument, and therefore WS and LCU environments can be configured to support the CCD sw only, the script ccdEnvFromTeplate.sh can be used. It creates and configures WS and LCU environments for one single CCD camera, taking the values of environment variables described in section 4.6.1.

$ ccdEnvFromTemplate.sh

In this case, the first part of sections 4.6.3 and 4.6.7 can be skipped (just perform the verification indicated in sub-sections 4.6.3.1 and 4.6.7.1).

4.6.3 WS Environment

1. Create a new environment as in [7]. Remember, the environment shall be named as in $RTAPENV. Do not forget to properly configure /etc/services, /etc/$RTAPROOT/RtapEnvList (or $RTAPROOT/etc/RtapEnvList on older Rtap releases), etc.

a. start ccsei

$ ccsei &

b. select "CCS Environment Setup.". The utility vccEnv is started.

c. enter in the vccEnv panel the name of the environment to create

d. Press the button Create

e. Keep the panel vccEnv open: you will need in the next steps as well.

2. Configure the database

a. set to the environment dbl directory:

$ cd $VLTDATA/ENVIRONMENTS/wmyccd/dbl

b. Add the CCD to the database:

i. edit DATABASE.db file (see also example in section 3.6).

ii. move to application definitions section.

iii. Add the following lines (see also manual page of ccd.db in section 3.6):

#define CCDNAME myccd // camera name

#define CCDROOT :Appl_data:myccd // CCD branch root point

#include "ccd.db" // build CCD branch

c. add a dedicated point in the scan system configuration:

i. edit USER.db file (see also example in section 3.6)

ii. move to the scan system section.

iii. Add the following lines (instead of lmyccd use your CCDLENV!)

POINT "<VLT scan dev>" "ccs_config:scan config:LAN:lmyccd"

BEGIN

Alias lmyccd

END

d. regenerate the (RTAP) database files:

$ make clean db

e. verify the correctness of the generated RTAP files:

$cd ../DB/Appl_data

$ls

...if the CCD branch has been successfully created, a subdirectory myccd exists

$cd ../ccs_config/scan\ config/LAN

...if the CCD scan point has been successfully created, a subdirectory lmyccd exists.

3. generate the environment and then shutdown it:

a. Press the button Init in the vccEnv panel

4. Start the environment:

a. Press the button Start in the vccEnv panel

b. Close the panel vccEnv: not needed any more (File->Quit)

c. Close the panel ccsei: not needed any more (File->Quit)

4.6.3.1 WS Environment Verification

1. If an LCU is used, edit the file $VLT_LOG_ROOT/logLCU.config to define the log node for the LCU. Example:

lmyccd wmyccd

2. Verify (with RtapDbConfig) that point Appl_data contains a sub-point myccd (alias as well), having the structure shown in Fig.5 (in this example, the CCD branch root point is ccdtest instead of myccd):

3. Verify that the needed processes are running in the CCS environment (use RtapPerfMon for verification):

Proc Name pid prio %cpu qid rx #msg bytes debug select

1 RtapScheduler 25043 NRT . 3676 . . . . ..

2 RtapMonitor 25044 NRT . 2780 . . . . ..

3 RtapQServer 25045 NRT . 216986 . . . . ..

4 RtapEventTrig 25047 NRT . 35187 . . . . ..

5 RtapEventConfg 25048 NRT . 33088 . . . . ..

6 RtapTimeKeeper 25049 NRT . 69989 . . . . ..

9 RtapDbCfServer 25053 NRT . 1891 . . . . ..

10 RtapScanMngr 25055 NRT . 1293 . . . . ..

11 ccsScan 25078 NRT . 400 . . . . ..

12 logManager 25054 NRT . 13892 . . . . ..

13 msgServer 25057 NRT . 695 . . . . ..

14 cmdManager 25058 NRT 1 696 . . . . ..

15 RtapASServer 25059 NRT . 397 . . . . ..

16 RtapASLogger 25060 NRT . 398 . . . . ..

17 RtapDHMngr 25077 NRT . 399 . . . . ..

20 envsKill 25056 NRT . 5494 . . . . ..

58 RtapMQDBM 25052 NRT . 10890 . . . . ..

4.6.4 Files needed for CCD operations

Some files containing information needed to operate a CCD camera must be installed in the proper subdirectory of INS_ROOT; to do that, the CCD sw provides a UNIX shell script (ccdInstall.sh, see manual page in section 3.3).

Before running this script, it is strongly recommended to save the contents of the current INS_ROOT in a backup directory: the script will overwrite some files, in particular the files defining the CCD database configuration values.

The script needs as parameter the name of the file containing information about the specific camera used; there is one file for each CCD system; to list them all (see [7] for VLTROOT or INTROOT):

$ls $VLTROOT/config/ccd*.dbcfg

The choice of the right file for the system to be used should be straightforward if the following criteria are followed

· For TCCDS systems the file name is ccdTec<n>.dbcfg (e.g. ccdTec21.dbcfg). The integer number <n> correspond to the number of the CCD camera head used (this number can be read on a side face of the CCD camera head. Example (from UNIX shell):

$ccdInstall.sh ccdTec21.dbcfg

The template file ccdTecTemplate.dbcfg is available as extrema ratio if no appropriate file is found.

· For SCCDS the choice, due to the limited number of delivered system, should be even easier. The files have prefix ccdSci<instrument{Arm]> (e.g. ccdSciFors.dbcfg). Example (from UNIX shell):

$ccdInstall.sh ccdSciFors.dbcfg

The template file ccdSciTemplate.dbcfg is available as extrema ratio if no appropriate file is found.

For verification, do the following:

1. change working directory to $INS_ROOT

cd $INS_ROOT

2. Show contents of sub-directories:

ls -R

At least the following directories must exist (see [4] for the meaning):

$INS_ROOT/SYSTEM/DETDATA

$INS_ROOT/SYSTEM/Dictionary

ESO-VLT-DIC.CCDDCS

$INS_ROOT/SYSTEM/COMMON/CONFIGFILES

At least the following files must exist:

ccdDcsFixed.dbcfg

ccdSciTemplate.dbcfg (*)

ccdTecTemplate.dbcfg (*)

<CCDNAME>.dbcfg

$INS_ROOT/SYSTEM/COMMON/SETUPFILES

$INS_ROOT/SYSTEM/COMMON/SETUPFILES/REF

$INS_ROOT/SYSTEM/COMMON/SETUPFILES/DET

At least the following files must exist:

ccdCmdBias.det

ccdCmdDisplay.det

ccdCmdFlat.det

ccdCmdStartAg.det

ccdCmdStartLp.det

ccdSetupComplete.det(*)

All files and directories listed above must be present to be able to run the system. They must not be deleted nor modified. The only exceptions are template files, marked with (*), which might be useful to the user, but are not strictly needed, and the file <CCDNAME>.dbcfg, which might be modified (not deleted!) to accommodate modifications in the camera configuration (see chapter "Configuration" in [16]).

Note: if the file <CCDNAME>.dbcfg is already existing, it is first saved as <CCDNAME>.dbcfg.BAK and then overwritten. The old information, if changed by the user, must then be re-entered (see chapter "Configuration" in [16]).

4.6.5 Real Time Image and World Coordinates Display

CCD Software can work with or without the Real Time Display. If you have RTD installed, check that the process rtdServer is already running:

$ ps -aef | grep rtdServer | grep -v grep

If this is not the case, start it:

$ rtdServer &

If It is intended to show the actual World Coordinates of the objects being displayed, some parameters have to be entered into the CCD sw. As already said in section 2.15.1, a script is used for this purpose: ccdDcsWcs.sh (see section 3.3). Example:

$ccdDcsWcs.sh $CCDNAME $RTAPENV 1.0 1.0 0.5 0.0 1950 0.0 PIXEL

4.6.6 Setting source mask for FITS logs

As already said in section 2.17, the source mask for FITS log has to be defined, using the script ccdDcsSetLogMask.sh (see also section 3.3). Example:

$ ccdDcsSetLogMask.sh $CCDNAME $RTAPENV "UT1AGA"

4.6.7 LCU Environment

After successful configuration of the workstation CCD software, one can already proceed to the CCD camera configuration operations (see chapter "Configuration" in [16]) and then run and operate a CCD camera in simulating the LCU Software (see chapter "Getting started" in [14]).

If you do not have an LCU skip to the next session. For all other operational modes, the LCU environment must be configured as well.

1. Create a new environment as in [7]. Remember, the environment shall be named as in $CCDLENV. Do not forget to properly configure /etc/services, /etc/$RTAPROOT/RtapEnvList (or $RTAPROOT/etc/RtapEnvList on older Rtap releases), the LCU booting parameters, the communication parameters, etc.

a. start ccsei

$ ccsei &

b. select "CCS Environment Setup..". The utility vccEnv is started.

c. enter in the vccEnv panel the name of the LCU environment to create. Check if the WS host and boot environment are set as wanted; if needed, change these entries.

d. Press the button Create.

e. Press the button Config. The utility vccConfigLcu is started.

f. Enter in the vccConfigLcu panel the LCU boot parameters. In particular:

i. In the Modules Configuration area enter, in the same order as below:

System Mod:

lcudrv, lculog, lqs, tim, lcc, ntp, cai, scan, b016

User Mod:

ccd

ii. in the Processes area enter (optional, not strictly needed):

lccServer, msgServer, rdbServer

Fig.6 shows an example of vccConfigLcu panel.

g. Press the button Write files to save the defined configuration

h. Press the button Configure LCU to store the boot parameters in the LCU CPU board.

i. Press the button Reboot LCU to verify that the defined configuration is OK and the LCU boots properly.

j. Close the vccConfigLcu panel (File -> Quit)

k. Close the ccsei panel (File -> Quit)

2. Configure the database

a. go to the LCU environment dbl directory

$ cd $VLTDATA/ENVIRONMENTS/lmyccd/dbl

b. Add the CCD to the database:

i. edit DATABASE.db file (see also example in section 3.6)

ii. move to application definitions section.

iii. Add the following lines (see also manual page of ccd.db in section 3.6):

#define CCDNAME myccd // camera name

#define CCDROOT :myccd // CCD branch root point

#include "ccd.db" // build CCD branch

Please note that the definition of the CCD branch root point CCDROOT is different with respect to the WS environment (:Appl_data:myccd see 4.6.3)

c. add a dedicated point in the scan system configuration:

i. edit USER.db file (see also example in section 3.6)

ii. move to the scan system section.

iii. Add the following lines:

#define RTAPENV wmyccd // CCD WS environment

POINT "<VLT scan dev>" LAN:RTAPENV // build CCD scan point

BEGIN

ALIAS RTAPENV

END

d. regenerate the (LCU) database files:

$ make clean db

e. verify the correctness of the generated RTAP files:

$cd ../DB

$ls

...if the CCD branch has been successfully created, a subdirectory myccd exists

$ls LAN

...if the CCD scan point has been successfully created, a subdirectory wmyccd exists.

3. No special definition in the userScript is needed by the CCD sw. Note however that the directory specified on the Workstation in the environment variable INS_ROOT (see 4.6.1) must be NFS mounted on the target LCU and the path string on both WS and LCU must be the same. Examples:

a. on CCD WS: INS_ROOT = /diskc/no_backup/vltccd/insroot

on CCD LCU /diskc is mounted to CCD WS /diskc -------> OK, no further action.

b. on CCD WS: INS_ROOT = /tmp_mnt/notCcdWs/diskc/no_backup/vltccd/insroot

on CCD LCU /diskc is mounted to CCD WS /diskc -------> add line in userScript:

nfsMount ("notCcdWs","/diskc","/tmp_mnt/notCcdWs/diskc")

4. Reboot the LCU.

4.6.7.1 LCU Environment Verification

1. Verify that the registered processes are:

$rlogin <lcuname>

-> lqsPrintLocalTbl

PID Process-Name ReadCId WriteCId ......

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

1 msgServer 32783408 22 ......

2 lqs 17 0 ......

3 lccTime 32891072 21 ......

4 lccLogger 32760284 24 ......

5 lccEvent 32757788 25 ......

6 lccDevice 31240840 23 ......

7 lccServer 30690912 26 ......

8 rdbServer 30580372 28 ......

2. Verify using the browsing facility of the ccseiDb or lccei utility (see manual page) that the CCD branch and scan point have been added:

a. Select point @lmyccd:myccd

b. Read attribute opStateLcu.

c. Select point @lmyccd:LAN (scan system). A sub-point wmyccd must exist

4.6.8 Scan System configuration

Before starting to use the CCD sw WS and LCU parts, one has to configure in the OLDB the table of LCU attributed which have to be updated on WS through the CCS Scan System.

To do this, the CCD sw provides a UNIX script, called ccdDcsScan.sh (see also manual page in 3.3). Type from the UNIX shell:

ccdDcsScan.sh $CCDNAME $RTAPENV $CCDLENV

If the stand-alone panel is intended to be used, also the attributes needed by its Graphical User Interface must be included in the scan table. In this case, the script ccdosScan.sh must be run in addition to the previous one (see also manual page in 3.3):

ccdosScan.sh $CCDNAME $RTAPENV $CCDLENV

Note that, in order them to succeed, both WS and LCU environments must be properly configured and active.

4.6.9 ACE Verification

If one intends to use the CCD sw simulating the ACE Software (e.g. no ACE available, see also section 2.4), this section must be skipped.

If a ACE box is available and connected, the following verification test must be performed on the LCU console or from the host ($> rlogin <lcu>) to verify the proper connection of the ACE box to the LCU:

1. l<lcu> -> cd "/VLTROOT/vw/bin/MC68040"

2. l<lcu> -> acecom0

3. The following message should appear:

---> Test LCU-ACE connection <---

Loading transputer process ...

Attaching channel ...

Sending message to transputer ...

Reply is correct !

---> Test has been successful !!!

value = 2 = 0x2

4.6.10 Example

The following is an example of a sequence of UNIX shell commands needed to configure the CCD sw for usage. It is assumed here that the CCS environment, including OLDB, has been created and is active, as well as rtdServer. These commands are typically included in a CCD configuration script.

$ setenv HOST `hostname`

$ setenv RTAPENV wmyccd

$ setenv INS_ROOT /diskc/myName/insroot

$ setenv CCDNAME myccd

$ setenv CCDLENV lmyccd

$ ccdInstall.sh ccdTec58.dbcfg

$ ccdDcsWcs.sh $CCDNAME $RTAPENV 1.0 1.0 0.5 0.0 1950 0.0 PIXEL

$ ccdDcsSetLogMask.sh $CCDNAME $RTAPENV "UT1AGA"

$ ccdDcsScan.sh $CCDNAME $RTAPENV $CCDLENV

4.7 CCD CAMERA VERIFICATION

To verify the installation and configuration, execute the following steps:

1. start ccdVerifyGui and push the button Check: the correctness of WS, LCU and ACE configuration, both sw and hw, including cabling, is checked (see also "Complete self-test" in [16]):

$ ccdVerifyGui

2. get familiar with the user interface:

execute the "Simple Demo Session" as described in "Getting started" in [14].

3. run the WS processes:

execute the "LCU Simulated Session" as described in "Getting started" in [14].

4. run the WS and LCU processes:

execute the "ACE Simulated Session" as described in "Getting started" in [14].

4.8 USE THE CCD SOFTWARE

After successful completion of all the steps described in this chapter, the CCD software and the environment are ready for usage.

It is suggested to follow the steps described in "Running the system" in [14].

Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com