Reference Manual

Installing a Previously Configured Finder
Finding Finder
Installing Finder
Telling Ssh on the Bunker Computers About the New Finder
Alignment
Configuring a Finder Computer from Scratch
Before You Begin
Setting Up
Initial Configuration
Installing Linux
Change Default Passwords!
SSH Sshenanigans
Set the Coast User ID
More SSH Sshenanigans
Mounting Oberon as an NFS (Network File System) Drive
The CCD Drivers
The Finder Application
Check it All Works!
Time Synchronisation (optional)
Building Finder
The Application
The Drivers
Running Finder as a Transportable DIMM
Introduction
Setting up your host PC
Connections
Running finder
Shutting down
Actions which have been found to crash finder or the controller (don't do them!)
Actions which will reduce the scientific value of the data
Converting a HX516 to run in DIMM mode [deprecated]
Appendices
The Finder Configuration File
Enumeration Reference


Installing a Previously Configured Finder

A finder computer at COAST has failed for some reason, but being the forward thinking (and modest) individual I am, I have programmed and tested a spare board for you. This section describes what you need to get this board running. The procedure is not quite plug-and-play but you should be back on the air in a matter of minutes, fast enough to recover during an observing run.

Finding Finder

The spare board is in a blue plastic carry-case that looks something like an oversized lunchbox. At the time of writing it was stored at the south end of the COAST bunker on a table along with other finder spare parts. The finder that has failed will be in the telescope electronics enclosure, horizontal, in the top of the rack.

image of Arcom case
The case containing the spare Arcom board and accessories.

Image of SBC in telescope housing
The location of an installed board in a telescope electronics housing.

Installing Finder

Take the usual anti-static precautions when handling a disconnected board.
The spare finder is called "cstfinderx". The COAST network knows about this hostname and the corresponding IP address, so the board will work immediately on connection.
Go out to the failed telescope with the spare board and a phillips head screwdriver.

Go back into the bunker.

Alignment

The crosshair position for the new computer will most likely need to be changed. Ideally you would set it in the same way as you would at the start of the night, but at this point you're probably in a hurry and not too happy about how your observations are going. Hence:

Configuring a Finder Computer from Scratch

As a result of some cataclysmic event at COAST, you find yourself with a blank Arcom single board computer and an urgent need to reprogram it as a finder. Possibly a board has failed and you have a replacement, or a board has had its drive wiped as a result of an accident or malicious hacking. The configuration of a replacement board is non-trivial and this documentation, the distillation of many weeks of learning on my part, should help a lot. Even if you want to use a different single board computer or just want to know how finder is set up it will help to read this.

The general strategy is to do only the basic configuration as a stand-alone system, install the board on the COAST network and complete the installation (more conveniently) over the network.

Before You Begin

You will need the following:
Image of CD in case
The CD in its case.
Image of SBC-GX1 computer
The SBC-GX1 and the VGA adapter cable required to connect it to a monitor.

Note: The "Arcom Development Kit" is a carry-case that looks like a big blue lunchbox containing all sorts of useful Arcom accessories and hopefully a spare board. It should eventually be found at COAST along with the spare finder parts.

You will also need the following information:

Setting Up

Before applying power to the single board computer:
Image of CMOS link position
Move this link towards the backup battery.

Initial Configuration

Installing Linux

Screen dump of package options
Screen dump of network settings

Change Default Passwords!

Two users are installed by default, these are "arcom" and "root". Both have the password "arcom". For security, you should change these to the COAST standard passwords and users before connecting to the network! So:
You can now install the computer in a COAST telescope and continue the installation from your office. There are three connectors: USB, ethernet, and power. All the telescopes are wired up the same way so you can use another one as an example.

SSH Sshenanigans

You have put a new computer on the network with the same name and IP as an old one. But ssh knows  the difference, because they will have different cipher keys. If your host has accessed the finder before and you try to connect to it with ssh you will get a complaint about a possible "man in the middle attack" and a refusal to connect. So on your host and on every host likely to have ever accessed that finder:

Set the Coast User ID

The coast user should have the same ID as they do on the other computers in the network, mainly to avoid confusion during NFS file sharing:

More SSH Sshenanigans

The coast user needs to be able to run the finder executable from selected computers without a password (otherwise launching finder with pulldown menus on a remote host won't work). This requires a program called xauth to be present, not part of the Arcom distribution. Also, X11 forwarding needs to be turned on in ssh so that finder can be displayed remotely. This is done by sshd, but the version supplied by Arcom is crippled in this respect. The easiest way to fix this is to copy these programs from a finder with versions that work (I have compiled replacements):
Wait about half a minute and then see if you can login as coast without a password from one of the COAST machines. Then test X11 forwarding: type xterm and see if an xterm appears. If you get an X11 error it might be that you needed the "-X" option to ssh when logging in (shouldn't be necessary on any of the bunker machines).

Mounting Oberon as an NFS (Network File System) Drive

The finder program and CCD drivers are stored in directories on oberon which are NFS mounted by the finders. Hence when the program or drivers get updated it is only necessary to update one set of files on oberon rather than one set on each of the finders. Hence all the finders are guaranteed to be running the same version of the program! When finder produces data (when saving images or movies), the data is also stored on oberon as the local storage capacity is limited.

So set up NFS directories:
This works pretty well, except we had to use the "nolock" option in /etc/fstab. This means that more than one program can write to a file at a time (definitely not a good idea) because the finder has no idea whether another program is trying to access the file or not. This can be fixed if we also install a daemon called portmap. This is not part of the standard arcom distribution so copy the files from another finder (apfinder1, 172.24.225.211, for example):

The CCD Drivers

It is now necessary to install USB drivers (Arcom neglected to provide them but I have compiled some) and CCD drivers. The CCD drivers don't really get installed, we just put in a symbolic link to the drivers on oberon. The USB drivers can most easily be copied from another finder.
#! /bin/sh
insmod usbcore
insmod usb-ohci
insmod /net/oberon/soft/finder/ccd.o
# Use "model=5" for the Starlight Xpress MX516
# Use "model=-5" for the HX516.
insmod /net/oberon/soft/finder/sx_usb.o model=-5
        mknod /dev/ccda  c 127 0
        mknod /dev/ccda1 c 127 16
        mknod /dev/ccda2 c 127 32
        mknod /dev/ccdA  c 127 128
        mknod /dev/ccdA1 c 127 144
        mknod /dev/ccdA2 c 127 160
        mknod /dev/ccdb  c 127 1
        mknod /dev/ccdb1 c 127 17
        mknod /dev/ccdb2 c 127 33
        mknod /dev/ccdB  c 127 129
        mknod /dev/ccdB1 c 127 145
        mknod /dev/ccdB2 c 127 161
        chmod 0666 /dev/ccda
        chmod 0666 /dev/ccda1
        chmod 0666 /dev/ccda2
        chmod 0666 /dev/ccdA
        chmod 0666 /dev/ccdA1
        chmod 0666 /dev/ccdA2
        chmod 0666 /dev/ccdb
        chmod 0666 /dev/ccdb1
        chmod 0666 /dev/ccdb2
        chmod 0666 /dev/ccdB
        chmod 0666 /dev/ccdB1
        chmod 0666 /dev/ccdB2

The Finder Application

Finally, we need to install finder itself, or rather, a symbolic link to finder on oberon:
We also need to install a configuration file so that the local incarnation of finder gets telescope-specific information:
# Finder configuration file
#
# NOTE: This file is automatically generated! Changes
# made to parameters will be remembered, but comments
# will be overwritten!
#
Name East_Telescope

TelescopeIP apcsttel.phy.private.cam.ac.uk

Port 2703

Crosshair 345 197
Change the name and port to the values for your telescope as described here. More information on the file format can be found here.

Check it All Works!

Registered ccd @ major #127
usb.c: registered new driver starlight-xpress
hub.c: USB new device connect on bus1/2, assigned device number 2
starlight-xpress: probing usb_device 0x0547:0x2131
starlight-xpress: found EZUSB device
starlight-xpress: RESET 8051
starlight-xpress: Download 341 code records
starlight-xpress: un-RESET 8051
usb.c: USB disconnect on device 2
starlight-xpress: disconnect
hub.c: USB new device connect on bus1/2, assigned device number 3
starlight-xpress: probing usb_device 0x4444:0x4220
starlight-xpress: found ECHO2 device
starlight-xpress: read 0xFF model from camera
starlight-xpress: writing 0x05 model to camera
starlight-xpress: camera model is Starlight Xpress HX5/16
Registered CCD mini-driver: Starlight Xpress HX5/16 @ minor #0 and #128
starlight-xpress: camera has 1 serial ports

Time Synchronisation (optional)

The clocks on the finder computers can be synchronised using the Network Time Protocol (NTP). For the finders installed in the COAST telescopes this is desirable so that results can be compared with fringe data and autoguider data taken simultaneously. A network connection is required so it is not possible to use NTP on a stand-alone DIMMWIT box in a remote location.

As with much of the previous installation, it is easiest to copy the required files from an existing finder. Suppose we want to install onto apfinder1 (172.24.225.211) using apfinder5:

cd /usr/sbin/
scp ntp* 172.24.225.211:/usr/sbin
scp tickadj 172.24.225.211:/usr/sbin
cd /etc
scp -r ntp 172.24.225.211:/etc
scp ntp.conf 172.24.225.211:/etc
cd /etc/init.d
scp ntpd 172.24.225.211:/etc/init.d
cd /lib
scp libcap.so.1.10 172.24.225.211:/lib
cd /lib
ln -s libcap.so.1.10 libcap.so
ln -s libcap.so.1.10 libcap.so.1

# Time servers...
131.111.8.74    aquila          ntp0.cam.ac.uk
131.111.12.21   janus           ntp1.cam.ac.uk
131.111.8.42    chimaera        ntp3.cam.ac.uk
131.111.48.8    mraos           mraos.ra.phy.cam.ac.uk

/etc/init.d/ntpd start
/usr/sbin/ntpq -p


...should return something like...

     remote           refid      st t when poll reach   delay   offset  jitter
==============================================================================
+aquila          ntp2.ja.net      2 u    5  256  377    1.177    1.020   0.295
-janus           spanner.eng.cam  3 u    -  256  377    1.897   -0.166   0.057
*chimaera        ntp2.ja.net      2 u  251  256  377    1.136    1.007   0.086
-aptitania       spanner.eng.cam  3 u  252  256  377    0.431   -0.090   0.161
+apcstapd        spanner.eng.cam  3 u   45  256  377    0.390    0.672   0.048

Ideally we would just leave NTP running all the time, but it periodically interacts with its servers over the network. If this happens while a DIMM file is being recorded, dropouts in the acquisition can occur. We could use the cron program to switch on NTP only during daylight hours, but cron itself wakes up once a minute to see if there are any tasks that need doing. Again, there is a risk of dropouts. So instead we tell oberon to start and stop NTP on the finders during the day and let the finder clock run by itself during the night. This way, there are no unnecessary processes running during observing hours.

To do this, we need to give coast on oberon the power to run the /etc/init.d/ntpd script on the finder, which normally requires root privileges. To do this without compromising security too much we install the super program on the finder.
cd /bin
scp super 172.24.225.211:/bin
cd /etc
scp super.tab 172.24.225.211:/etc

super ntpd stop
super ntpd start


...you should see the ntpd daemon either appear or not when you type ps.
Finally, oberon needs to know when to start and stop ntpd on the finder. If you are replacing a finder it probably already knows but it doesn't hurt to check.
crontab -e
01 9 * * * ssh apfinder1 super ntpd start > /dev/null
51 14 * * * ssh apfinder1 super ntpd stop > /dev/null
The first and second columns are the minute and hour of the day respectively that you want NTP to start and stop. I prefer to start or stop NTP on each finder a minute apart so that the load is spread out.


Building Finder

There are two parts to finder, the main application that the user sees and the driver modules for the CCD.

The Application

Compilation should be straightforward on a linux system provided you plan to dynamically link the application to run-time libraries. Compilation has been tested under RedHat 7.2 and 8.0, and Debian Testing (Sarge). The libraries required are:
However, the single board computers only have a minimal Redhat installation. In particular, Qt is not present. Hence it is necessary to link static libraries at compile time to produce an executable. The libraries required are:
Up to RedHat 7.3, RPMs of these libraries were available. From 8.0, however, RedHat no longer made them (except for libmng), nor did Debian. It has hence become necessary to download and install the static libraries manually. Most troublesome is libqt, you might have to download the right distribution and compile it just to get the libqt.a file.

The Drivers

The drivers are a set of two modules, ccd.o and sx_usb.o that need to be dynamically loaded by the kernel before the Starlight Xpress CCD camera can be accessed via the USB cable. In order to compile them you will need a source tree for the target kernel. For the single board computers the source tree is on our copy of the Arcom development kit CD ROM.

Running Finder as a Transportable DIMM

Introduction

Setting up your host PC

You can change your computer's settings accordingly, or you can instead create a virtual ethernet device which will not affect your usual network connectivity:
Password:
DEVICE=eth0:1
BOOTPROTO=static
BROADCAST=192.168.20.255
IPADDR=192.168.20.2
NETMASK=255.255.255.0
NETWORK=192.168.20.0
ONBOOT=yes
# DIMMWIT single board computer
192.168.20.1            dimmwit
# This machine when talking to DIMMWIT
192.168.20.2            dimmwithost
When connected to dimmwit your computer will now use the 192.168.20. subnet and be called "dimmwithost" but when connected to your usual network it will have its usual name and IP.

It is also a good idea to set up NFS on your PC so that dimmwit can save files direct to your hard disc (the onboard space is limited):
# Starlight Xpress single board computer
/directory/that/contains/program     192.168.20.1(ro)
/directory/that/contains/data        192.168.20.1(rw)

Connections:

Running finder:

ssh coast@dimmwit finder
ssh coast@dimmwit remotefinder

Shutting down:

Actions which have been found to crash finder or the controller (don't do them!):

Actions which will reduce the scientific value of the data:


Converting a HX516 to run in 1D DIMM mode [deprecated]

NOTE: This section is retained for archival purposes. The cause of the problem has finally been discovered: the horizontal clocking for the HX516 is the inverse of that for the MX516. The drivers have been modified to support the HX516 clocking and the artefacts have gone away.

    - Bodie Seneta 19 October 2004


We have two kinds of Starlight Xpress camera head in the COAST group, the MX516 and the HX516. The MX516 works in 1D DIMM mode without modification, but the HX516 is much more problematic. Often the result of a HX516 1D DIMM measurement is a series of vertical lines within which the original data is lost.
DIMM mode artefacts
DIMM artefacts.
Unfortunately for DIMM purposes, the HX516 is the camera installed in the COAST telescopes. However, we have a single HX516 which functions correctly in 1D DIMM mode as is, currently installed in the east telescope. Furthermore, Terry Platt at Starlight Xpress has suggested a hardware modification for the HX516 that sometimes mitigates the problem. The solution is to reduce the value of the black level clamping capacitor in the camera head from 10nf to 1nf. We are in the process of converting other COAST cameras over. There is a supply of surface mount 1nf capacitors in the kit of spares at COAST. The modification is described below by Terry:
SX modification

Another workaround is to use 2D DIMM mode instead, which always works.

Appendices

The Finder Configuration File

Each Finder computer runs an identical copy of the Finder program (the original is currently stored on Oberon). However, there are things each Finder needs to know which are unique to the telescope it is in, which may need to be changed without recompiling the source code or which must be remembered even during power cycling. These are stored in a local file (the default name is finder.conf but others can be loaded or saved via the File menu). The file is loaded at runtime and saved upon quitting or user request. It is also text-editable, although no comments or formatting will be preserved the next time Finder writes it.

Example of finder.conf (it may change):

# Finder configuration file
#
# NOTE: This file is automatically generated! Changes
# made to parameters will be remembered, but comments
# will be overwritten!
#
Name East_Telescope

TelescopeIP apcsttel.phy.private.cam.ac.uk

Port 2700

Crosshair 160 89

# as the first character in a line denotes a comment. The rest of the line is ignored.

Name is the name to appear on the particular Finder window title bar and all ancilliary dialog boxes, to avoid confusion when several Finders are displayed on the same monitor.

TelescopeIP is the name or IP address of the telescope controller computer.

Port is the ethernet port number used to communicate with the telescope controller.

Crosshair is the X and Y coordinates of the current crosshair position (the target point which finder and the telescope will try to move the star image towards such that it also lands on the autoguider).

Enumeration Reference

For "historical reasons", the telescope nomenclature associated with Finder can be confusing. However, the following table, correct at the time of writing, might assist in resolving ambiguities:

Telescope number
Finder computer name
IP address
Foundation
Beam
Finder-telescope ethernet port
1
apfinder1
172.24.225.211
N4
4
2704
2
apfinder2
172.24.225.212 C
1
2700
3
apfinder3
172.24.225.213 E1
3
2703
4
apfinder4
172.24.225.214 W7
2(W)
2702
5
apfinder5
172.24.225.215 W2
2(E)
2701
(spare)
apfinderx
172.24.225.216
(spare)
(spare)
(spare)
reserved IP
apdimm
172.24.225.217
none
none
not connected

apfinderx is a spare single board computer configured as a replacement for failed boards in telescopes. apdimm is an IP address allocated in case we should wish to connect a DIMMWIT to the COAST network.
This page last updated 20th October 2004 by  bodie@mrao.cam.ac.uk