aposong module
**************

aposong provides a Python interface to the observing system for the SONG node at Apache
Point Observatory. It communicates with devices attached to other computers on the
internal APO network: the Planewave 1m telescope, the Planewave mirror covers,
the focal plane unit and camera on the telescope, the dome, a safety monitor that checks
status of other telescopes on site, and, eventually, a spectrograph camera.

Communication with these devices is achieved, for the most part, using the
ASCOM/Alpaca protocol, although a few more specialized commands are communicated
through non-standard interfaces (Planewave has an API that provides more functionality
than their ACSCOM driver). 

The main module, aposong, opens up an Alpaca device for each of the devices. It
provides routines for many basic observatory tasks, e.g., opening and closing,
slewing, taking exposures, etc., coordinating commands to different devices
as needed. Individual devices can also be addressed using the Alpaca device
instantiations and the standard ASCOM command sets for more experienced users
if needed.

It can be used to run an interactive Python client. To run the software, simply issue

.. code-block:: 

    aposong

This will start an ipython client, load appropriate modules and commands, and instantiate
a pyvista TV tool into the variable, disp.

Commands
++++++++

Information about individual commands and parameters is best obtained through
the docstrings, available below or using interactive help when running the
Python interface, but a summary of commands is:

Observatory commands:
  - domeopen(): open dome, mirror covers
  - domeclose(): close mirror covers, dome, and park
  - issafe(): check safety moniotor for status

Dome commands:
  - domehome(): move dome to home position
  - domesync(True|False) : starts/stops thread to sync dome to telescope position
  - louvers(True|False) : open/close louvers

Telescope commands :
  - slew(ra,dec): slew to coordinates
  - offset(dra,ddec): offset telescope in ra/dec
  - offsetxy(dx,dy): offset telescope in detector coordinates
  - usno([ra,dec]) : find/slew to USNO A2.0 star
  - altaz(az,alt): slew to az/alt coordinates
  - foc(focus) : set focus to specified value
  - tracking(True|False): turn tracking on/off
  - mirror_covers(True|False): control mirror covers
  - fans(True|False): control telescope fans
  - port(port): move tertiary to requested port
  - park(): park telescope and dome

Camera commands :
  - expose(exptime,filt,**kwargs): take an exposure, returns named Exposure tuple with data, hdu, etc.
  - gexp(exptime,**kwargs): take an exposure with guide camera binned 1x1 (frontend to expose())
  - sexp(exptime,**kwargs): take an exposure with spectrograph camera binned 2x2 (frontend to expose())
  - focrun(cent,step,nsteps,exptime,filt,**kwargs): take series of exposures at different focus positions
  - settemp(temp): set camera temperature set point
  - cooler(state): set camera cooler state on (True) or off (False)
  - chiller([temp]): get/set chiller temperature
  - chiller_fault(): get chiller fault status


Focal plane unit commands :
  - iodine_position([val]) : get or set (with val) iodine stage position
  - iodine_tset(val) : set iodine temperature (both channels)
  - iodine_tget(): get actual iodine temperatures
  - iodine_home : home iodine stage
  - iodine_tset(val) : set iodine temperature (both channels)
  - iodine_tget(): get actual iodine temperatures
  - iodine_get(quantity): get various TC300 values (tset,voltage,current,enable,dark,light)

Calibration commands :
  - calstage_in() : move calibration stage into beam, and adjust focus (if needed)"
  - calstage_out() : move calibration stage out of beam, and adjust focus (if needed)
  - calstage_position([val]) : get or set (with val) iodine stage position
  - calstage_home : home iodine stage
  - cal.getlamps() : get eShel lamp status
  - cal.lamps() : control eShel lamps
  - cal.cals() : turn lamps on, take sequences of flats and ThAr, turn lamps off
  - cal.shutter() : open/close shutter in direct calibration feed

Alpyca devices
++++++++++++++

Importing aposong exposes several Alpyca devices as Python objects:

- T : Telescope device
- F[] : Focuser devices : Planewave focuser (ASCOM) , Zaber focuser (Alpaca) , iodine stage (Alpaca)
- C[] : Camera devices : Port 1 QSI camera (ASCOM), Port 2 acquisition camera (ASCOM), Port 2 Shelyak camera (ASCOM)
- Covers : Covercalibrator device :Planewave mirror covers (ASCOM)
- D : Dome device : APOAshDome Alpaca device
- S : Safetymonitor device : APOSafety  Alpaca device
- SW[] : Switch devices : Thorlabs TC300 temperature controller (Alpaca), Shelyak calibration unit (Alpaca)

Configuration
+++++++++++++

Some basic configuration is done using the aposong.yml file. This file configures
the IP addresses for the ASCOM Remote servers, the PWI4 server.

Module functions
++++++++++++++++
.. automodule:: aposong
   :members:
   :member-order: bysource