= MosBot =

Mosbot is a python program that tries to adjust our observing scripts
to adapt to changing conditions through the night.

Run it by logging in to the *mzls@mayall-idl* machine and then running:
{{{
cd ~/obsbot
python mosbot.py <pass1.json> <pass2.json> <pass3.json>
}}}

You will need to keep that window open, because you want mosbot to
keep running all night.  "pass[123].json" are the 'plan' or 'JSON'
files that Arjun should have given you; they contain lists of
exposures we want to take depending on what the conditions are doing.
It is probably most convenient to run mosbot from a Terminal window on
the mayall-2 display.  You don't need to read any of the output it
produces, but you should check periodically that it is still running;
the code is under development and some bugs remain.


Mosbot does two things:
- On startup, it reads the `pass[123].json` files, drops exposures
  that should happen before the current time, for each exposure writes
  two little shell scripts, and also writes a top-level script
  `/mosaic3/exec/mosbot/tonight.sh`
- It then starts waiting for new images to appear in the $MOS3_DATA
  directory.  Whenever an image appears, it analyzes it and, based on
  the measured conditions (seeing, sky brightness, transparency), it
  decides which pass we should be running, and what our exposure times
  should be, and it overwrites the next few scripts.


Comments about how this works:

- mosbot by default starts with PASS 2 observations.  And by default,
  we set all the exposure times to our minimum exposure time of 80
  seconds.
- THEREFORE, if you kill mosbot after it has written out the
  `tonight.sh` script, you will run pass 2 with short exposures all
  night long.  This is almost certainly not what we want to happen!!
- The `tonight.sh` script is not smart.  Each exposure is written to a
  script, and the scripts are numbered.  If you kill and re-start
  `tonight.sh`, you will start from the beginning of the night (or the
  last time mosbot was run).  If you have to stop the `tonight.sh`
  script, PLEASE re-run mosbot to regenerate an appropriate
  `tonight.sh` script.
- The `tonight.sh` script writes to a file
  `/mosaic3/exec/mosbot/seqnum.txt` to indicate which exposure it is
  currently running.  The `mosbot.py` script reads that file to figure
  out which upcoming exposures it should update.  Mosbot by default
  writes 1, 2, and 3 exposures ahead of the current sequence number.
- Each exposure is split into two scripts.  For example, exposure 3
  happens in `expose-3.sh`, which takes the exposure, and then
  `slewread-4.sh` slews to exposure number 4 while reading out
  exposure 3.  If the file `quit` is found in the directory in which
  `tonight.sh` is run, the script will quit after a readout (without
  slewing).  This should ensure that we don't lose any data, so that
  is the way the `tonight.sh` script should be stopped.  (It will
  delete the `quit` file just before it quits.)

About git:

- the `~/obsbot` directory is a git checkout of the repository:
  https://github.com/legacysurvey/obsbot
- There is a "MzLS Observer" github account set up to log in with an
  ssh key, so you should be able to *git commit* and *git push* any code
  changes without having to know any passwords.