added CACAO set up

operating/cacao.rst

@@ -0,0 +1,144 @@
+CACAO Setup
+===================================
+
+MagAO-X uses the "Compute and Control for Adaptive Optics" software package.
+This document describes how to start up CACAO on MagAO-X and use it for normal operations.  It assumes that
+software installation and configuration is already complete.
+
+Terminal Interface Setup
+-------------------------
+
+1. The basic interface to CACAO is through the terminal.  We normally set up a three-panel terminal.  Open a terminal on AOC,
+   and first "split left/right".  Then in the left half, "split up/down".
+
+2. In each of the resultant terminals, ssh to rtc (or to icc) as xsup.
+
+3. Next:
+
+   ::
+
+     [xsup@rtc ~]$ cd /opt/MagAOX/cacao/tweeter-vispyr/tweeter-vispyer-rootdir
+
+
+   For ICC the path is `/opt/MagAOX/cacao/ncpc/ncpc-rootdir`.  This should be done in the lower left and right hand
+   terminals.  It is not required in the upper left.
+
+4. Now that you are in the `rootdir`:
+
+   - in the upper left panel, run the command `milk-procCTRL`
+   - in the right-hand panel, run the command `cacao-fpsctrl-TUI`
+
+   The following image shows the state just before the above commands are run
+
+   .. image:: figures/cacao_term_setup.png
+
+   *CACAO terminal preparation*
+
+    The following image shows the state after the above commands are run
+
+   .. image:: figures/cacao_term_inop.png
+
+   *CACAO terminals in operation*
+
+   In the upper left panel where you have run `milk-procCTRL`, you will want to change the font size to fit it all in.  You
+   can do this by pressing `ctrl` and using the scroll wheel on the mouse.  `ctrl +` and `ctrl -` also work.
+
+.. note::
+     The above steps are ripe for scripting.  Someday a grad student will pay enough attention to CACAO and rise to the challenge.
+
+.. note::
+     Joseph you are the only person who will read this, you are not allowed to prompt grad students nor help any brave souls who dare to venture here.
+
+Graphical User Interface
+-------------------------
+
+To start the GUI for loop control for the high-order loop on AOC:
+
+  ::
+
+    [xsup@aoc ~]$ loopCtrlGUI ho
+
+  .. image:: figures/holoop.png
+
+And for the LOWFS loop:
+
+  ::
+
+    [xsup@aoc ~]$ loopCtrlGUI lo
+
+  .. image:: figures/loloop.png
+
+High-order Loop
+-----------------
+
+.. note::
+     Almost all CACAO CLI commands must be executed in the `rootdir` of the relevant loop.  On RTC this is
+     `/opt/MagAOX/cacao/tweeter-vispyr/tweeter-vispyer-rootdir`, which is in the lower-left terminal after the above setup.
+
+1. First decide which calibration you wish to load.  On RTC this is currently almost certainly `default`.
+
+2. To see a list of calibration available, execute
+
+   ::
+
+      [xsup@rtc tweeter-vispyr-rootdir]$ ls ../tweeter-vispyr-calibs.
+
+.. warning::
+     Ensure the loop is open before loading a new calibration, or re-loading the current calibration.
+
+3. To load a calibration, in the lower left terminal run
+
+   ::
+
+    [xsup@rtc tweeter-vispyr-rootdir]$ cacao-calib-apply XXXX
+
+   where `XXXX` is the name of the calibration. You do not include the full path.  For most things, you probably want
+   `default`.  So:
+
+   ::
+
+    [xsup@rtc tweeter-vispyr-rootdir]$ cacao-calib-apply default
+
+Low-order T/T Loop
+-------------------
+
+.. note::
+     Almost all CACAO CLI commands must be executed in the `rootdir` of the relevant loop.  On ICC this is
+     `/opt/MagAOX/cacao/ncpc/ncpc-rootdir`, which is in the lower-left terminal after the above setup.
+
+The low-order T/T loop uses light rejected by the coronagraph to control residual vibrations.  The "wavefront sensor"
+for this mode is a program running a center-of-light algorithm on either `camflowfs` or `camllowfs`, or the average image
+from either camera.
+
+1. First, setup the desired camera.  The ROI size does not really matter, but typically we use 32x32 to make the
+   centroiding algorithm efficient.
+
+    - You can run the LOWFS cameras extremely fast.  This can be advantageous to control saturation since roughly 100% of the
+      star light is rejected by the coronagraph.  However, you may want to run the loop slower.  So you can use the
+      averager for the camera to effectively reduce the exposure time.
+
+.. warning::
+     Ensure the loop is open before changing cameras, loading a new calibration, or re-loading the current calibration.
+
+2. Now to setup CACAO to use the desired camera, run the command
+
+    ::
+
+      [xsup@icc ncpc-rootdir]$ lowfs_switch camflowfs_fit
+
+   In addition to `camflowfs_fit` you can select `camflowfs_avg_fit`, `camllowfs_fit`, or `camllowfs_avg_fit`.
+
+3. Now load the desired calibration.  Note that this only depends on the camera, not whether you are using the averager
+   for that camera.  For `camflowfs` run:
+
+    ::
+
+      [xsup@icc ncpc-rootdir]$ cacao-calib-apply flowfsTT
+
+   and for `camllowfs` run:
+
+    ::
+
+      [xsup@icc ncpc-rootdir]$ cacao-calib-apply llowfsTT
+
+

operating/index.rst

@@ -1,24 +1,25 @@
 Operation of the MagAO-X instrument
 ===================================
 
-The MagAO-X instrument has (at last count) several thousand controllable 
-degrees of freedom, three computers, and dozens of processes. To manage 
+The MagAO-X instrument has (at last count) several thousand controllable
+degrees of freedom, three computers, and dozens of processes. To manage
 that complexity, we have the guides and tools detailed herein.
 
 Good starting points include the :doc:`startup <startup>` guide and the
-:doc:`troubleshooting <../troubleshooting>` guide. Useful tools include 
-:doc:`software/utils/xctrl`, :doc:`software/guis/cursesINDI`, and 
+:doc:`troubleshooting <../troubleshooting>` guide. Useful tools include
+:doc:`software/utils/xctrl`, :doc:`software/guis/cursesINDI`, and
 :doc:`software/utils/logdump`.
 
 Viewing camera output and DM input (really, any shared memory image) uses
-`rtimv`, which is documented in its own 
+`rtimv`, which is documented in its own
 `User Guide <https://github.com/jaredmales/rtimv/blob/master/doc/UserGuide.md#rtimv>`_.
 
 .. toctree::
    :maxdepth: 2
 
    startup
    daily_startup
+   cacao
    daily_shutdown
    shutdown
    alignment
@@ -27,5 +28,5 @@ Viewing camera output and DM input (really, any shared memory image) uses
    software/guis/index
    software/utils/index
    software/apps/index
-   abeginnersguidetomagaox   
-   
+   abeginnersguidetomagaox
+