5 TUTORIAL: IMPLEMENTING A STARTUP TOOL FROM SCRATCH

This chapter is intended to help programmers, who are starting from scratch with the implementation of a startup tool for a new instrument, to implement a working prototype for their specific instrument. Experienced developers are encouraged to use this tutorial as a checklist, to avoid missing some minor implementation points.

5.1 ROADMAP

The implementation of the startup/shutdown scripts consists of the following main steps:

1. Retrieve the Template Instrument software modules.

2. Define the startup tool configuration.

3. Adapt the Template Instrument software modules to the new instrument.

4. Install and run a first implementation of the startup/shutdown scripts.

5. Implement the startup instrument specific code (if needed).

6. Implement the startup panel.

7. Rebuild and install the instrument from scratch, test again.

8. Update the Instrument User's and Maintenance Manuals.

If your instrument is based in the Template Instrument, then the first steps can be skipped. See below for details.

5.2 IMPLEMENTATION ORDER OF ICS, DCS, OS AND STARTUP SCRIPTS

The instrumentation software is normally implemented in the following order: ICS and at least one DCS, then OS. The instrumentation startup/shutdown scripts can be configured in parallel as each instrumentation software component is completed.

By default, xxinsStart will always try to start all applications it knows. If a certain application is not ready yet, but is already described in the configuration file, then the default startup can be suppressed setting a corresponding keyword to `F' (see section 6.15, keywords OCS.CON.DEFAULT, OCS.INS1.DEFAULT, OCS.DETi.DEFAULT).

If your instrument is based on the Template Instrument, and you first followed the tutorials to implement and configure ICS and OS (based on Base ICS and BOSS), then the first sections of this tutorial can be skipped, and this tutorial can be followed starting with section 5.5.

5.3 INSTRUMENT IDENTIFIER AND SOFTWARE MODULE PREFIX

The instrument identifier (e.g. `UVES', represented with `XXXX' or `NNNN' in this document) and the software module prefix are widely used in the instrumentation software to identify files, processes, classes and data items related to the instrument.

The software module prefix are the two first letters of the instrumentation software modules (e.g. `uv', represented with `xx' or `nn' in this document). You have to select a two letters prefix, which is not reserved yet by any other instrument. The prefix is usually the network subnet name assigned to the instrument, as listed in [12], section 5.1; however, it is important to agree this prefix together with ESO: once selected, this prefix can not be modified.

5.4 RETRIEVING THE TEMPLATE INSTRUMENT MODULES

Retrieve the Template Instrument software modules storing them under a directory named according to your own instrument identifier. The startup scripts only need to update files located in modules xxins and xxmcfg. To retrieve the Template Instrument items, you need access to an UNIX account at ESO, in particular to the ESO Software Archive.

1. Software Modules

The Template Instrument software modules can be retrieved from the ESO Software Archive as follows:

mkdir ~/NNNN

cd ~/NNNN

pkginBuild xxins -step RETRIEVE

chmod -R +w *

5.5 DEFINING THE STARTUP TOOL CONFIGURATION

The complete startup tool configuration is kept in a set of FITS keywords stored in two configuration files shared with other parts of the instrumentation software. Please read [23] and the beginning of the Configuration Guide (chapter 6) to understand how configuration works.

It is recommended to supply the complete startup tool configuration before trying to use the startup/shutdown scripts. If ICS (based on Base ICS) and OS (based on BOSS) are already configured, then most of the configuration needed by the startup tool is already available. Please refer to the Configuration Guide for details (sections 6.6 to 6.15). It is advisable to register the config. parameters in the NNNN Instrument User's and Maintenance Manuals, before starting with the implementation itself.

As a result of this step, the following files should have been updated:

1. nnmcfg/config/nnmcfgINS.cfg

See the Configuration Guide, sections 6.6 to 6.14.

2. nnmcfg/config/nnmcfgSTART.cfg

See the Configuration Guide, section 6.15.

5.6 ADAPTING THE TEMPLATE MODULES TO A NEW INSTRUMENT

This section assumes that:

1. You have retrieved the Template Instrument software modules as described in section 5.4.

2. You have defined the startup tool configuration and that you have documented it in your NNNN Instrument User's and Maintenance Manuals as described in section 5.5.

This section describes the files supplied in the template software modules that need to be adapted to your specific instrument, to be able to use the startup tool. The files are supplied in two modules: xxmcfg and xxins.

5.6.1 Module nnins

Module nnins is the integration module of the complete instrumentation software of the instrument, therefore, the module contains files not related with the startup tool. From the startup tool point of view, the following files are needed:

· xxins/src/xxinsStartup

· xxins/src/xxinsStart

· xxins/src/xxinsStop

· xxins/src/xxinsStoo.tcl

· xxins/src/xxinsStartup.pan

· xxins/config/xxinsVuewmrc

· xxins/config/xxinsUwsVuewmrc

1. Rename the files starting with `xx' into your own software module prefix `nn'.

cd xxins/.. ; mv xxins nnins

tooMvReplace xx nn nnins/*/xxins*

2. Update the startup and shutdown scripts (nnins/src/nninsStartup, nninsStart, nninsStop).

Replace `XXXX' with `NNNN' and `xx' with `nn'.

tooReplace XXXX NNNN nninsStartup nninsStart nninsStop

tooReplace xx nn nninsStartup nninsStart nninsStop

3. Instrument specific startup code (nnins/src/nninsStoo.tcl)

File nninsStoo.tcl is the source for file nninsStoo. This file may contain instrument specific startup code. See section 7.2 for details (this file can be updated later, once the startup script at least starts correctly without this code).

4. Instrument specific startup UIF class (nnins/src/nninsStartup_uifClass.tcl)

Normally, it should be possible to use the standard startup panel supplied by the startup tool. In this case, the file nninsStartup_uifClass.tcl is not needed and can be deleted. If an instrument specific panel is needed, then this file has to be updated (see section 5.7).

5. Update the VUE menu configuration files ¹

(nnins/config/nninsVuewmrc,nninsUwsVuewmrc)

These files contain the description for the VUE menus described in section 4.1. These files are manually installed under the ~/.vue directory. The first file may be used in the xxxx account of the instrument workstation, to have the VUE menu available during development. The second file is installed in the xxxx account of the user station at Paranal, i.e. file nninsUwsVuewmrc is the actual file used at Paranal.

Edit both files replacing XXXX with NNNN, xx with nn.

Note: The nninsVuewmrc file is e.g. installed as follows (after having installed module nnins):

cd ~/.vue

cp $INTROOT/config/nninsVuewmrc .

mv vuewmrc vuewmrc.orig

ln -s nninsVuewmrc vuewmrc

6. Update the module Makefile (nnins/src/Makefile).

Make sure that the scripts nninsStartup, nninsStart and nninsStop, TCL script nninsStoo (if needed), panel nninsStartup.pan (if this panel is used, delete the nninsStartup script), nninsVuewmrc and nninsUwsVuewmrc files are registered in the Makefile. Replace all xxins strings with nnins, as necessary.

5.6.2 Module nnmcfg (MS/nnmcfg)

Module nnmcfg contains the instrument configuration files. From the startup tool point of view, the following files are needed:

· xxmcfg/config/xxmcfgCONFIG.cfg

· xxmcfg/config/xxmcfgINS.cfg²

· xxmcfg/config/xxmcfgSTART.cfg

1. Rename the module.

cd xxmcfg/.. ; mv xxmcfg nnmcfg

2. Check file nnmcfgCONFIG.cfg (nnmcfg/config/nnmcfgCONFIG.cfg)

File nnmcfgCONFIG.cfg must contain the basic description of the configuration sets INS and START. The files nnmcfgINS.cfg and nnmcfgSTART.cfg should be registered in this file (keywords CONFIG.SETi.FILEi), together with the corresponding dictionaries (usually: "ICB_CFG OSB_CFG STOO_CFG" is registered in keyword CONFIG.SETi.DICT). See [23], section 3.1 for details.

3. Update the instrument configuration (nnmcfg/config/nnmcfgINS.cfg, nnmcfgSTART.cfg)

The configuration files nnmcfgINS.cfg and nnmcfgSTART.cfg should have been updated according to the instrument configuration, as described in section 5.5.

Note: Both files are installed by user xxxxmgr in the INS_ROOT, however user xxxx should have permission to update file nnmcfgSTART.cfg. Make sure that file nnmcfgSTART.cfg has group write permission, specially after evtl. manually installing it in the INS_ROOT. If in doubt, run after the installation:

chmod g+w $INS_ROOT/SYSTEM/COMMON/CONFIG_FILES/nnmcfgSTART.cfg

5.7 IMPLEMENTING AN INSTRUMENT SPECIFIC STARTUP PANEL

The standard startup panel allows to update a specific set of keywords stored in the nnmcfgSTART.cfg file. If a different set of keywords needs to be updated, then an instrument specific version of this panel is needed. Proceed as follows:

1. Prepare the panel template (nnins/src/nninsStartup.pan)

Delete the script nninsStartup that is not longer needed. Delete it also from the Makefile and register instead the panel nninsStartup.

Use file xxinsStartup.pan supplied in module xxins as a starting point, rename it with the panel editor: Start the panel editor, load the xxinsStartup panel and save it with name nninsStartup.pan. After this, edit the file to rename the string XXXX with NNNN.

2. Edit the panel

Edit the panel with the panel editor. Any widget can be removed or added, but it is recommended to maintain the standard look & feel.

To assign e.g. the logical keyword START.PANEL1.DEFAULT to a UifCheckButton widget, create the widget, open the widget configuration panel and register:

· variable: "cfg__START.PANEL1.DEFAULT", i.e. the keyword name prefixed with "cfg__" (with two underscores).

· ON value: "T"

· OFF value: "F"

There is no need to register any TCL command in the widget. The code available in the panel template takes care of loading the keyword value into the widget when the panel is started and to update the keyword value according to the widget state when the Save button is pressed.

Proceed accordingly to assign other keywords to other widgets.

3. Install and Test

Build and install the updated module nnins. Test the panel calling as usual:

nninsStartup

5.8 INSTALLING AND TESTING

It is possible to install and test the startup tool, when at least:

1. The applications to be started (ICS, DCS and/or OS) are properly implemented, configured and installed.

2. The startup tool is properly configured according to the available subsystems as described in the previous sections.

3. You have access to the necessary WS and LCUs, and ACC is properly configured.

5.8.1 Installation

Install the instrument software as usual; if the installation is based on pkginBuild, then basically:

· Make sure that environment variables INTROOT and INS_ROOT are defined.

· From the ~/NNNN directory, execute e.g.:

pkginBuild nnins -env wnnnn lnnics1 lnnics2

Specify with the -env argument the environments you wish to build.

5.8.2 Testing the Startup Tool

Run and test as described in the demo session (chapter 3) or in the user's guide (chapter 4). Adjust the configuration as needed.

5.9 FINAL REMARKS

1. At the end, when the software is approx. stable, it is recommended to archive all software modules (cmmCopy), delete (or rename) the main ~/NNNN directory and test if the instrument software can be rebuilt and installed correctly from the Software Archive.

2. The NNNN Instrument User's and Maintenance Manuals should be checked and completed, specially the configuration described in the Configuration Guide should reflect the final configuration of the instrument.

¹

The manual and xxins template will be updated when CDE is used at Paranal.

²

This manual uses the xxmcfgINS.cfg file as representation of the INS configuration set.

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