Introduction
============

This explains how to start up and use the ShaneAO real-time controller,
and how to set up parameters to run it.

Startup
-------

Startup consists of 3 steps:

    * Starting the real-time code and its operator display
    * Starting the motor controller
    * Starting the science camera

Start the :ref:`real-time code <shaneao>` from the unix comman prompt with::

    shaneao

This starts the real-time code and connects it to the AO sensors and deformable mirrors.
To run the "real" code, this must obviously be run on the real time processor machine, **rtc.ucolick.org**.
It can be run in :ref:`simulator <sauce>` mode on another unix machine (it cannot be run in
simulator mode on **rtc** though)

After the real-time code is running, it is listening on a data server socket. To display real-time
data, open a terminal on another machine (not rtc), usually the operator's designated console,
and start the :ref:`peeko <peeko>` code::

    peeko

See :ref:`Motion Control <motors>` for steps to start up the motor controller.

See :ref:`ShARCS <sharcs>` documentation for starting up the science camera.

Top level command processor
---------------------------

There is a simplified command-line interface to the AO real-time controller.
The command set performs basic functions like calibration, setting gains, and
opening and closing the control loops.
Script files can use the top-level commands.

    * :ref:`shaneao <shaneao>`   - The top level command and script processor

Basic introduction to the `rtc.py` and `rtc2.c` codes
-----------------------------------------------------

These codes implement the real-time controller and its supervisor.
The real-time code is written in c and the supervisor in python.
The rtc parameter file set defines the behavior of the controller.
The supervisor is responsible for initializing and loading the parameter files into the real-time code.

Files:

    * :ref:`rtc.py <rtc>`     -   The rtc supervisor
    * :ref:`rtc2.c <rtc2>`    -   The rtc c code (c-extension)
    * setup.py                -   The instructions to python to create the c-extension. Invoke with bash-prompt$ python setup.py build. This builds the rtc2.so dynamic library.
    * :ref:`parameterFiles <file-system>`      -   Directory containing the .fits parameter files
    * :ref:`parameterFiles/scripts <scripts>`  -   Directory contining scripts that generate the .fits parameter files

When :ref:`rtc` is initialized, it:

    * Connects python to the c-extension :ref:`rtc2`
    * Loads parameter files into the c-extension memory
    * Defines a basic set of "supervisory" commands

The rtc.so needs to be built and stored in a library directory visible to python.::

    python setup.py install --home==(path to library dirctory)

The :ref:`rtc <rtc>` and :ref:`rtc2 <rtc2>` codes are initialized automatically when the :ref:`shaneao <shaneao>`
top level simple command line processor
is started. Starting the top level command proccessor will do the following initialization steps:

    * import all the needed python packages, notable numpy and pyfits
    * imports :ref:`rtc` and initializes it
    * creates an object that has a number of methods that implement supervisory functions and instance variables that are in one-to-one corresponding to parametric and real-time data in the c-extension :ref:`rtc2`.

It is possible to run the supervisor directly from a python command line, bypassing the
top level command processor::

    python
    from rtc import *
    self = rtc('16x')