UNSWIRF: control software

The UNSWIRF instrument consists of five main components:

The Queensgate Fabry-Perot, which is placed in the f/35 beam just in front of IRIS.
The motorised slide which moves the Fabry-Perot in and out of the beam, with a reproducability of around 1 micron (much less than one IRIS pixel).
The Queensgate CS100 controller (borrowed from TAURUS) that allows the Fabry-Perot spacing and parallelism to be controlled.
The PC computer that supervises the operation of the motorised slide and the CS100.
The software (on the PC, a Sun workstation, and the VAX) that links everything together.

Controlling UNSWIRF from ICL

There are five ways of sending commands to the UNSWIRF PC:

The commands can be entered on the keyboard of the PC in the cassegrain cage. To see the affect of the commands you will need a monitor connected to the PC.
Commands can be typed into any of the ``UNSWIRF PC communications'' windows on the Sun workstations or xterminals. These windows act like ``virtual PCs'': what you see is very similar to what you would see on the monitor of the PC.
You can type ``telnet unswirf 2000'' and establish a telnet session to UNSWIRF. This is the same mechanism that is used by the ``UNSWIRF PC communications'' windows.
On the Sun, as user ``obsred'', you can type, for example,
ditscmd UNSWIRF SEND x -8 y 13 z 530 slide in
You should receive a three-line acknowledgement from UNSWIRF, including the last 20 or so characters displayed on the PC screen.
On the VAX (left-hand terminal, with the ``ICL>'' prompt) you can type, for example,
obeyw aatssy##UNSWIRF SEND x -8 y 13 z 530 slide in
where ``aatssy'' is the name of the Sun workstation being used to communicate with UNSWIRF. You should receive the same three-line acknowledgement from UNSWIRF that you do on the Sun.

To send a sequence of commands to UNSWIRF, possibly interleaved with IRIS commands and telescope offset commands, it is best to use the ICL script UNSW.ICL on the VAX. This must first be loaded into ICL by typing (from the left-hand VAX terminal with the ``ICL>'' prompt):

load disk$data:[obsred.unswirf]unsw.icl

Note: if the file is not available, you can obtain a copy from aatssy by typing (on the Sun):

cp /home/aatssy/unswirf/icl/unsw.icl /vaxdata/obsred/unswirf

Sometimes you have to type the ``load'' command twice. Once loaded, you can use the script by typing

unsw myfile.dat

where ``myfile.dat'' is a file of UNSWIRF, IRIS, and telescope offset commands, which is in the directory disk$data:[obsred.unswirf], which is also accessible from the UNIX workstations as /vaxdata/obsred/unswirf/. To change this directory you will need to edit the unsw.icl file.

Sometime you have to type the ICL load command twice. If it complains that the offset file is already open, type ``close offset_file''. It sometimes helps to type ``tidy'', twice.

The format of the UNSWIRF run file is as follows. It consists of ASCII text. There are four type of lines:

Comments start with an exclamation mark, and are ignored.
Commands to be sent to UNSWIRF start with
aatssy##UNSWIRF SEND
followed by an UNSWIRF command. For example to set ``z'' to 300 you would put the following line in the file:
aatssy##UNSWIRF SEND z 300
Lines starting with an ``@'' are sent to ICL just as if you typed them on the keyboard (without the ``@''). For example, to slew the telescope without using a night assistant you can use:
@SLEW 20:12:01 -31:16:21 1998 0 0 1998 false
All other lines are IRIS run commands and must start with
aatssy##UNSWIRF
and are in a similar format to those in offset-run files used normally with IRIS.

The UNSW.ICL script has the ability to work with or without telescope offsets. This is useful if you do not wish to control the telescope (e.g., when doing calibration observations during the day). UNSW.ICL decides whether or not to send offset commands to the telescope on the basis of the first IRIS run command in the file---if this line contains an offset, then the telescope will be controlled, if this line does not contain an offset then the telescope is not controlled (and any offset commands later in the file are ignored). Offset commands are only sent to the telescope if the offset has changed from the last offset (the first offset command is always sent).

Changing the Sun workstation used to control UNSWIRF

UNSWIRF is currently configured to communicate via the Sun workstation known as ``aatssy''. If you really have to, it is possible to change the workstation being used. You will need to know the IP number of the Sun (you can find this using, e.g., ``grep aatssy /etc/hosts''). Then proceed as follows:

Change your observing files to refer to the new Sun (e.g., lines such as ``aatssy##UNSWIRF'' need to have the name of the new Sun).
This section is incomplete...

Starting the UNSWIRF control software

Turn on the PC in the cass cage, wait till it boots. After some initial tests the PC should give a ``UNSW >'' prompt. If the hard disk fails to work, you can boot from the UNSWIRF floppy (labelled UNSWIRF BOOT, its in the cardboard box of UNSWIRF bits).
Login as ``obsred'' on aatssy (note: if you are doing this from an Xterminal or a computer other than aatssy use "xhost aatssy" before telnetting to ensure that aatssy can open windows).
On a Sun workstation, type ``/usr/sbin/ping unswirf'' to check that the PC is communicating on the ethernet. If not, ask Bob Dean to investigate. Note that you can also use ``ping'' on the UNSWIRF PC (first you have to exit the UNSWIRF program by typing ``q'' followed by CNTRL/C to stop the batch job). On the PC you must use a numeric IP number, e.g., ``ping 192.231.166.36'' to ping aatssf.
On the Sun workstation designated as the controller (currently aatssy) type:
```
      /home/aatssy/unswirf/bin/unswirf_start
```
After a short delay, an xterm titled ``UNSWIRF PC communications'' should appear, followed by text similar to the following:
```
        Escape sequence is ^]
	Trying 192.231.166.26...
	Connected to unswirf.
	Escape character is '^]'.
	UNSW version 3.2; ERIC V3.6; compiled on Jun 22 1999 at 16:20:34
	Jun 22 16:39:25 ECHO
	..\run\UNS.ini
	Jun 22 16:39:26 UNSW > 
```
If desired, you can make copies of this xterm on other displays. You do this by typing CNTRL-] and then, for example, ``+ 192.231.166.75:0.0'' (alternatively, the macros ``left'', ``middle'', ``right'', and "sun" are defined to put windows up on the left, middle, and right-hand Xterminals, and the Sun in the AAT console area). The displays you select must allow X connections from aatssy (use ``xhost +aatssy''). All output from the UNSWIRF PC goes to all of the ``UNSWIRF PC communications'' windows. Any input from any of these windows goes to the UNSWIRF PC.
Now, in your original xterm type:
```
      ~drama/dramastart -v 20jul
      source $DRAMA/drama.csh
      cleanup
      dits_netstart
      /home/aatssy/unswirf/drama/unswirf_drama &
      ditscmd UNSWIRF SEND beep
```
If you get the message ``receiver fails to bind socket: Address already in use'' this probably means that there is someone else running DRAMA on aatssy.
This should have resulted in a ``beep'' command being sent to UNSWIRF, and you should hear a ``beep''.
Now, on the ICL terminal, try the VAX-Sun communication link by typing:
```
 ICL> obeyw aatssy##UNSWIRF SEND "beep"
```
Once again, UNSWIRF should respond to the ``beep'' command.

Restarting the DRAMA software on the Sun

Once or twice a night the VAX will typically fail to talk to the Sun properly. The symptom is that an ``obeyw aatssy##UNSWIRF SEND'' command issued from ICL on the VAX will correctly send the command to UNSWIRF, but will never return. A ``ditscmd UNSWIRF SEND'' from the Sun will still work. The solution is to restart the DRAMA task on the Sun using:

      ditscmd UNSWIRF EXIT
      dits_netclose
      (wait a while, maybe 30 seconds)
      cleanup
      dits_netstart
      /home/aatssy/unswirf/drama/unswirf_drama &

If the ``ditscmd UNSWIRF EXIT'' command does not respond, you might need to do:

      ps x|grep unswirf_drama
      kill ????                 ! where ???? is the process PID from the
                                ! ps command

UNSWIRF commands

UNSWIRF has about 50 different commands available, but only a subset will usually be of interest to the observer.

  status        displays the status of UNSWIRF
  slide in      moves the FP slide into the beam
  slide out     moves the FP slide out of the beam
  slide `n'     moves the FP slide by `n' steps (+ moves out, - moves in)
  x `n'         sets the model FP x coordinate to `n'
  y `n'         sets the model FP y coordinate to `n'
  z `n'         sets the model FP z coordinate to `n'
  dx `n'        makes a delta change to the model FP x coordinate
  dy `n'        makes a delta change to the model FP y coordinate
  dz `n'        makes a delta change to the model FP z coordinate
  fpt           allows the nine coefficients of the FP transform to be set
  quit 0        quits and restarts the UNSWIRF program
  q             quits your connection to the UNSWIRF program (the program
                continues to run, and you can reconnect to it)

The FP transform: model and reality

Three numbers define the setting of a Fabry-Perot: the separation between the centres of the plates, and the relative slope of the plates in the x and y directions. The separation determines the wavelengths that the FP passes. If the slope of the plates is non-zero, then the wavelength passed depends on position across the FP. In a perfect FP, the separation would be linearly proportional to the ``z'' setting, and the slopes would always be zero. In a slightly less perfect FP, the separation would still be linearly proportion to ``z'', and the slopes could be independently set to zero by changing ``x'' and ``y'' respectively. Welcome to the real world. The FP in UNSWIRF has the following properties:

the plate separation is linearly proportional to ``z'', but also depends slightly on the settings of ``x'' and ``y''.
the plate separation depends quite strongly on wavelength. This is not unreasonable when you consider that each plate has a multilayer dielectric coating which is many wavelengths thick - the effective plate separation depends on where in this coating you consider the reflection occuring, and this depends on wavelength.
the slope of the plates has a small linear dependence on ``z''. This dependence is large enough that you have to correct for it to maintain the parallelism of the plates.
to change the ``x''-slope of the plates (where the ``x'' direction is defined as the horizontal axis when a FITS image of UNSWIRF data is displayed), you have to tweak the FP ``x'' and ``y'' settings (although the ``y'' setting has the largest effect on the ``x''-slope).
similarly, the ``y''-slope of the plates is mostly a function of the ``x'' setting, but is also affected by ``y''.

Luckily, the behaviour of the UNSWIRF FP (at constant temperature and humidity), while non-ideal, is extremely reproducible, and hence can be corrected for in software. This is done by having two concepts of the FP settings: the ``model'' (which the user interacts with) and ``reality'' (the numbers actually sent to the CS100 controller). The transform between the two is a 3x3 linear matrix and an additive term:

    X = (t11 * x) + (t12 * y) + (t13 * z)  + c1
    Y = (t21 * x) + (t22 * y) + (t23 * z)  + c2
    Z = (t31 * x) + (t32 * y) + (t33 * z)  + c3

NOTE: The transform is now done in the program ``cube.pl'' on the Sun workstations rather than on the PC. The PC transform matrix is now set to the unity matrix.

Where (x,y,z) are the model settings, (X,Y,Z) are the actual settings, t[i,j] is the matrix of coefficients, and c1,c2,c3 are the additive terms.

X, Y, and Z, must be numbers in the range -2048 to +2047, so that they can be sent to the 12-bit analog-to-digital converter in the CS-100 controller. Currently, x, y, and z are also constrained to this range, and if this results in an X, Y, or Z setting outside the range, the value is clipped.

The transform has been set to have the following properties:

the slope of the FP is independent of ``z''
the plates are approximately parallel when ``x'' and ``y'' are zero.
the ``x''-slope and ``y''-slope of the FP are still linearly dependent on both ``x'' and ``y''

The transform can be set using the ``fpt'' (Fabry-Perot transform) command on the UNSWIRF PC, although this is no longer needed, since the transform is done on the Suns. The transformation matrix coefficients are entered in the following order:

fpt t11 t12 t13 t21 t22 t23 t31 t32 t33

If you enter all nine numbers, you will receive a message saying that the transform has been updated. The current transform can be displayed using the ``status'' command. The additive term is built-in to the software and can not be altered by a user command.

IRAF setup

cd wherever you want to  (~obsred/unswirf is a good choice)
mkdir iraf
cd iraf
mkiraf
cp /home/aatssy/unswirf/iraf/unsw* .
# specify a terminal type of "xgterm"
# edit "login.cl" to change the following:

set	imdir		= "hdr$"
set	editor		= emacs
set	clobber		= yes
set	imclobber	= yes

# create loginuser.cl with:

task unswfit = home$unswfit.e
task unswslope = home$unswslope.cl
keep

Crucial UNSWIRF files

The UNSWIRF files are in /home/aatssy/unswirf, as follows

 bin/telnet_to_pc 	! A program for communicating with the PC
 bin/unswirf_start	! A program to start the PC communication in an xterm
 drama/Makefile		! For making the DRAMA communication program
 drama/README           ! Documentation
 drama/dmakefile 	! DRAMA makefile
 drama/unswirf_drama    ! Executable for communicating with DRAMA
 drama/unswirf_drama.c  ! Source code for the above
 fpz/README		! Documentation
 fpz/fpz		! A useful program for calculating FP settings
 fpz/fpz.c		! Source code for the above
 fpz/libsla.a		! Slalib library for the above
 fpz/slalib.h		! Slalib include file for the above
 fpz/slalib_c.tar.gz	! Slalib C source
 icl/unsw.icl           ! ICL program for communicating with the UNSWIRF PC

 pc/			! This directory contains files from the UNSWIRF PC
 pc/atbrds.cfg		! National Instruments configuration program
 pc/autoexec.bat
 pc/autoexec.flo	! A version of AUTOEXEC.BAT used for floppies.
 pc/config.flo		! A version of CONFIG.SYS used for floppies.
 pc/config.sys
 pc/diginout.exe	! For testing the National Instruments card
 pc/e990622.zip		! Source code for the UNSWIRF PC program
 pc/format.inp		! Used when formatting floppies
 pc/makeboot.bat	! To make a bootable floppy
 pc/ni-pnp.exe		! To configure the National Instruments card
 pc/ni-pnp.ini          ! Used with the above
 pc/smc_wd.com		! Packet driver for the ethernet card
 pc/telnet.cfg		! Turbotcp TCP/IP configuration file
 pc/turbotcp.exe	! Turbotcp TCP/IP program
 pc/u970620.exe		! An old version of the UNSWIRF executable
 pc/u970701.exe		! An old version of the UNSWIRF executable
 pc/u990622.exe		! The current version of the UNSWIRF executable

 tools/			! Files to assist with creating observing scripts
 tools/BS3421.dat
 tools/arc.pl*
 tools/cube.pl*
 tools/cube_Ar_1.6519.dat
 tools/cube_Ar_2.1534.dat
 tools/cube_Kr_2.1165.dat
 tools/cube_Kr_2.2485.dat
 tools/cube_Kr_2.3340.dat
 tools/docube*
 tools/dokeys
 tools/doscube*
 tools/flat_2.12.dat
 tools/sdf2iraf*
 tools/std.pl*

Last updated 17-Nov-1999

UNSWIRF: software / Michael Ashley / mcba@newt.phys.unsw.edu.au