SHOC

SHOC User Manual

Introduction

The SHOC systems consist of a filterwheel unit (with one or two filterwheels), a GPS unit for providing accurate timing triggers, an Andor iXon camera, and a control PC. Currently there are 2 production, and 1 development computer systems that go with the SHOC instrument. There are 2 working Andor cameras.

The SHOC website may well have more extensive detail about this instrument.

Dr. Marissa Kotze has written some pipeline software which may help with reduction of SHOC data.

Quick Start

Web interface

• The primary means of controlling SHOC is via a web interface. The Firefox or Chrome browsers are preferred.
• Point your browser at http://<name>:5000 (where name is the name of the SHOC instrument you're using; either shocnawe or shocndisbelief). For example, http://shocnawe:5000
• The interface should appear, showing three tabs: Filterwheel, GPS and Camera.

Filter wheel

• Select the filterwheel tab. There may be one or two wheels physically present; the interfaces to these are displayed side-by-side. The interface values for a wheel will be empty if the wheel is absent.
• Initialize the wheel by clicking the "Initialize" button (usually only at the start of the night, but may also be done if you suspect that the controller has lost its way). The wheel will move around to the reference position; this may take several seconds. While still moving, the "Moving" indicator above the controls will be red. Once there, the "Initialized" and "At Ref" indicators should turn green. The value in the "Current Position" field should be 1 after initialization.
• Select the filter required, by using the up and down arrows on the right of the "Required Position" field. The filter name will indicate the filter in the selected position. Click the "Move" button. The indicators above the wheel controls should change; once the wheel has reached the required position, the "Moving" indicator should turn grey, while the "Centred" indicator should be green. The "Current Position" field will indicate the slot number and name of the filter now in the light path.

GPS

• The GPS tab allows the user to view the time, GPS state, and to change the Programmed Output Pulse (POP) settings.
• Check that the time is valid, and that there are no alarm conditions indicated.
• To set the Programmed Output Pulse, choose whether you want a single or repeating pulse, then choose a pulse width, the start date and time (in local time, 24 hour format), and for repeating pulses, the repeat interval. Then push the "Apply" button. Note: the POP may only be set to occur in the future; if an error occurs, check that you haven't chosen a time in the past.
• To stop the pulses from being sent, click the "Stop" button.

Camera

• The camera tab allows control and setting of the SHOC imaging camera.
• Before using the camera, you need to switch it on: click the "Turn Camera On" button.
• Once the camera has been initialized, the camera setting and view interface is displayed.
• On the left is the image display area; more on that later.
• On the right is the settings area, with three tabs for camera control, analysis and advanced settings.
• When switched on, the camera starts cooling to its target temperature. The temperature display button is orange while the camera is not yet at the target temperature, and green once it is. If using a non-standard temperature, this may be set using the "Advanced" tab.
• The camera may be used in internal, external or external start modes, selectable using the "Triggering" drop-down.
• While in internal mode, the exposure time may be set, and the kinetic cycle time is automatically calculated and displayed. The latter is the period between the start of successive frames in a kinetic series. If you choose an exposure time of 0, the

SHOC Components

The SHOC instrument uses an Andor iXon camera, an Intelligent Reference TM-4 GPS unit, and a host PC which acts as a controller for the instrument. A filter wheel is usually used in conjunction with these. The host PC and GPS are installed in a crate which is mounted beneath the telescope. The filter wheel and camera are mounted beside this, in the light path. The software describing the various components is described below.

Using a web interface to control the instrument

While this system still runs on Windows, there is a mini-webserver that's supplied with flask. We're running this to provide the interface to the filter wheel software (and the GPS software). This will almost certainly change in the future, but for now, it's how it is.

To get the webserver to run as a service [so that every reboot brings the service back up automatically], we're using cygwin. The main challenge is that the COM port seems to change depending on which SHOC system is being used - or perhaps which USB port is used on the system. This results in the service having to be un-installed and re-installed when the COM port changes.

Here are the steps to do the change:

Overview

1. Log in as administrator
2. Stop the service
3. Remove the [existing] filterweb service
4. Re-install the filterweb service
5. Start the filterweb serivce
6. Test the GUI

Detailed steps

2. Stop the service [Note - you MUST be administrator to do ALL the steps expect test the GUI,. All steps can be done from the SAME cygwin terminal window]
• Open a cygwin terminal session
• Type

/cygdrive/c/cygwin/bin/cygrunsrv.exe -E filterweb   [This stops the service]

3. Remove the [existing] filterweb service
• In the same cygwin terminal from above, type the following:

/cygdrive/c/cygwin/bin/cygrunsrv.exe -R filterweb

4. Re-install the [new] filterweb service [remember to change the COM port]

/cygdrive/c/cygwin/bin/cygrunsrv.exe -I filterweb
                                     -e 'PYTHONPATH=c:\cygwin\home\Administrator\shoc\instruments\filterwheel\'
                                     -c 'c:\cygwin\home\Administrator\shoc\instruments\filterwheel\'
                                     -p 'c:\Python33\python.exe'
                                     -a 'web\manage.py --serial COM8 runserver -r -d'
                                     -1 /cygdrive/c/var/log/filterweb.log
                                     -2 /cygdrive/c/var/log/filterweb.err

This will install a service called filterweb. Please check the COM port and replace COM8 above with whatever COM port the USB-2-Serial adapter is showing under the Device Manager (type devmgmt.msc) in Windows.

5. Start the filterweb service

/cygdrive/c/cygwin/bin/cygrunsrv.exe -S filterweb

You can look under services on Windows to check that filterweb has started again. Start -> Run then type services.msc

6. Test the GUI

On any machine (could even be your laptop), open a browser and type:

http://shocnWhatever.suth.saao.ac.za:5000

Which should open the web gui. You should be able to move the filter wheel and get it's status, etc.

Filter Wheel

Filter_wheel_software

GPS Unit

Introduction

The GPS unit is used to provide accurate timing information to the camera. This is sent in the form of precisely times pulses, either one-shot or repeating. The software may be used to check the state of the GPS unit (and hence the quality of the time signals) and to program the start time, frequency and width of the pulses sent to the camera. As with the filter wheel software, the GPS software may be used in stand-alone mode ort as part of an integrated system, such as SHOC.

The GPS software may be accessed through a command line interface (CLI), though most users will prefer to control the GPS through the web-interface provided.

There also exists a version of the GPS software which is suitable for embedding in a scriptable interface.

Command Line Interface

This is the most basic menas of interacting with the GPS unit.

To start the CLI, double-click the gps_cli icon (in Windows), or in a bash shell, type gps_cli.py (Linux).

The CLI may be invoked with a number of options. The -h option presents the user with a list of command line options, and explanations as to their use.

To specify a non-default serial port for the GPS connection, use the --serial <port> command (e.g. --serial /dev/ttyUSB2).

To specify the log level, use --log <level>, where <level> is one of debug, info, warn, critical or error.

To specify the logfile, use --logfile <file>. If this option is not specified, the default is to use gps_cli.log.

From within the CLI, the user is presented with a number of options. The single character options are:

h - Display the list of options s - View the current GPS status q - Exit the program

There are then a number of options, of the form set <option>, which allow the user to set mask angle, user time bias, the timing mode used by the GPS, the location, and the programmable output pulse (POP).

Finally, there are get options of the form get <option>, allowing the user to get the mask angle, user time bias, timing mode, geometric quality, timing status, oscillator tuning mode, alarm states, satellite information, and POP settings.

The programmable output pulse is the primary use of the GPS unit. The user may choose:

• a one-shot pulse, at a specified time and with a specified width, or
• a repeating pulse, starting at a specified time, with a specified interval and pulse width.

The date for the POP should be entered in the format MMDDYYYY, and the time in the format HHMMSS.SSSSSSS (the fractional time part may be specified to seven decimal places, although it's hard to imagine suuch accuracy being required!) Specifying a date/time combination in the past gives an error and does not change the POP settings on the unit. Also note that the GPS unit uses UTC, so the time specified should be in UTC.

Web Interface

The web interface is the primary means of interacting with the GPS unit. As with the filterwheel software, the control software and web server are started as a service (on Windows) or a daemon (on Unix) and the user should not need to start these. The web server provides a means of viewing the GPS status, and setting the Programmable Output Pulse (POP) parameters.

Pressing the "Receiver Status" button brings up a display of the status and signal strength for each of the twelve channels available.

The other indicators display:

• the timing status of the GPS (whether it is able to determine a valid time from the satellites in view),
• the oscillator status (whether the onboard oscillator has already reached minimum accuracy levels, and
• antenna alarm status (whether all antenna circuits are operating normally.

When setting the POP, the description for the input parameters in the CLI holds, but note that the web interface requires the input time to be in localtime (which is then converted to UTC before being sent to the GPS unit).

Once set, the POP indicator status changes to yellow (one-shot POP) or orange (repeating POP), indicating a pending pulse. Once the start time is reached the indicator status changes back to green (if the timing status is still valid), or red (if the timing status is not valid). If, while a repeating POP is active, the timing status becomes invalid, the indicator also becomes red. In either case, if the indicator status becomes red, the POP will need to be cancelled or reset.

A scheduled, running or failed pulse may be cancelled with the "Cancel" button, or the "Off" mode may be chosen (and saved).

Diagnostic Interface

As with the filter wheel, the diagnostic interface is invoked by starting the command line interface, using the --diagnostic_mode flag. It automatically sets logging to the most verbose level, and provides greater details on the data strings sent to and received from the GPS.

There is also the ability to set various parameters which are not normally accessible in the CLI or web-based interface. These include the mask angle, user time bias, the timing mode used by the GPS, and the exact latitude, longitude and altitude.

Scriptable interface

To enable the GPS to be configured as part of a complex workflow, there is also a scriptable interface. This is similar to the scriptable interface presented by the filter wheel software.