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

• Point your browser at http://<name>:5000 (<name> is either shocnawe, or shocndisbelief). (1)
• Select the filterwheel tab (2).
• Initialize the filterwheel(s) (3), then select the filter required (4), click "Move" (5). The "Centered" indicator should be green when the wheel is finished moving (6).

• If using external triggering, select the GPS tab (1)
• Ensure timing is valid (2).
• Set the Programmed Output Pulse (POP) parameters (mode (3), pulse width (4), start date (5), start time (6), trigger interval (7)) and click apply (8). The status should change to pending (9).
• Select the camera tab.
• Set the desired Readout Rate, Preamp and Electron Multiplying parameters (NB: EM MODE MAY ONLY BE SET IF YOU HAVE WRITTEN PERMISSION TO DO SO).
• Set the sub image and binning parameters.
• Set the trigger type, exposure and kinetic series parameters.
• Start the acquisition.
• Stop to abort, or wait until completion. The image display area shows snapshots of the images throughout the acquisition.
• When the series is complete, the FITS data cube is copied to /data/<telescope>/<YYMM>/<filename>.fits, where <telescope> is 40in or 74in, YYMM is the year and month, and filename is the instrument abbreviation (SHA or SHD) followed by the date in YYYYMMDD format.

Advanced users guide

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 or external start trigger modes, 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. Arbitrarily short exposre and kinetic cycle times are not possible, due to the time required to read out the image. If you choose an exposure time less than the minimum allowed, the minimum exposure and kinetic cycle times are calculated and automatically displayed.
• In external trigger mode, the kinetic cycle time is determined by the frequency of the GPS POP signals. However, this frequency should not be higher than than the minimum readout time. The minimum allowed kinetic cycle time is calculated and displayed; this may be useful when deciding on the GPS POP frequency to use.
• For all trigger modes, the number of frames in the data cube is determined by the Kinetic Series value.
• The next row down allows the sub-image area and binning to be chosen. For both of these, standard or custom values may be used. Smaller sub-images and higher binning allow faster image readouts, at the expense of image size and resolution. The minimum values discussed above are automatically re-calculated and displayed when the sub-image or binning is changed.
• Below this, the readout speed and preamp gain may be set. Higher readout speeds allow for shorter exposure times, but at the expense of noisier data.
• The last setting is the Electron Multiplying (EM) gain. NOTE: DO NOT USE ELECTRON MULTIPLYING MODE UNLESS YOU HAVE SPECIFICALLY OBTAINED PERMISSION FROM DR AMANDA GULBIS TO DO SO, AND YOU UNDERSTAND HOW AND WHEN TO USE IT. PERMANENT DAMAGE TO THE SENSOR CAN RESULT FROM INCORRECT USAGE. If you are using EM mode, choose the EM output amplifier, and then select a gain. BEGIN WITH LOW GAIN VALUES!
• To get a quick view of the images that will result, press the "Preview" button. Images will be displayed in the left-hand display panel. Press "Stop" when you're done.
• To begin collecting data, press the "Start" button. The kinetic series will start, either immediately or at the designated time if using the GPS, and the data will be spooled to disk. At the same time, temporary images will be displayed in the image display area.
• Once the acquisition is finished (or earlier, if you push the "Stop" button), the header information in the FITS cube will be updated to include various GPS, filter and environmental parameters, an the cube written to disk. The filename for the current or past kinetic series is displayed above the "Start" button. The filename consists of the instrument name, the date and an index. The index is updated every acquisition. and the new filename is calculated and displayed immediately after the "Start" button is pressed.
• The index appended to file names begins at 1, and increments by 1 after each acquisition. It may be edited by clicking on the "Advanced" tab, and changing its value. Note that if you change it to a value already used, it will cause files with that value to be overwritten.
• Once you're finished with the camera, remember to turn it off! It should not be left with the cooler on once the night's observations are finished.

Real-time image display

• As an acquisition proceeds, snapshot images are displayed in the display area of the camera tab, baically as fast as the browser can render them.
• The interface is based on JS9, a Javascript version of the DS9 FITS processing and display engine (so users familiar with DS9 should be able to adapt to the JS9 interface relatively easily.
• Menu items above the image allow users to change the image zoom level, scaling and colour. It is also possible to select regions of the graph for further analysis.

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.