PENN ARRAY/NRAO-GB SOFTWARE INTERFACE
-13mar03 bsm 1st draft
-01apr03 bsm revised to reflect Simon Dicker iteration; pass
	 to Melinda Mello

General Reqmts/Philosophy [Melinda: this bit was for Simon's benefit,
and may be irrelevant if we go the low-level route]
=========================

-there must exist adequate handshaking

-in addition it is desirable to be able to directly query for
parameter values and general status. The more meaningful this is, the
better-- i.e., to the extent possible & reasonable, these queries
should propagate down to the hardware & back.

-the array control software should take care of keeping its own time
accurate via 1PPS (provided) and NTP (provided).

-at a given point in time, the array control computer should be able
to say when it will be "READY" to start a scan (READY is an "official
state" -- see "Receiver States" below).  In normal failure-free
operation this information once given "commits" you, as the
information is used by our system to coordinate devices (antenna, Rx,
etc) for the start of an observing scan.  The details of the timing
model clearly we will hammer out with experience.

-the communication protocol should be implementable by people who are
not professional sofwtare engineers. They can be assumed to know C,
and know (or be able to learn) the difference between a blocking and a
non-blocking socket call (for instance).


Receiver States
===============

An overall encapsulation of this could be accomplished with a set of
flags.  These might be implemented as a bitwise OR of individual
flags.  An attempt at an exhaustive list of flags:

  -DAQ electronics on/off
  -DAQ software is in requested configuration
  -load curve executing/clear
  -fridge cycling/clear
  -filterwheel acquiring/clear

-->When all of these flags are "clear" the receiver is considered
ready to start a scan.

Commands
========

-start a scan
-stop a scan
-set the cal flash characteristics
  *period
  *duration
-set the integration period (this may simply
  be relayed to the java stuff without processing;
  we need to know more about the java DAQ software
  to define what's done)
-specify/change location to write the data to (a socket?)
-specify/change location to write housekeeping
  data to (a socket?)
-specify/change periodicity with which to write
  housekeeping data.
-do a loadcurve  

    --> This is a special procedure which does the following:
    1) set the detector bias voltage
    2) wait ~5 detector time constants
    3) read out the detector responses
    4) change the bias voltage and go back to 2
    This is done over a specified range of voltages. The
    responses at each step are sent to the manager for
    realtime display and/or recording to a special fits file.

-recycle fridge 

    --> This is also a special procedure. It does the following:

  1:turn of the heatswitches, (turn off power wait ~10 minutes) 2:Turn
  on heaters to the He3 and He4 charcoal heating the He3 up to ~30K
  and the He4 to ~45K then wait for the he4 evaporator to cool to
  ~3.5K (about 45min) 3:Turn off the He4 heater and turn on the He4
  heatswitch and then wait for the He3 evaporator to cool to ~.8K
  (~30min).  4:Turn off the He3 heater and turn on the He3 heatswitch
  and wait for the fridge to stabilize at ~.260K (~30 min). This
  process has been fully automated in the DAQ computer. ALL THESE
  TIMES AND TEMPERATURES ARE APPROXIMATE AND CAN BE CHANGED TO SUIT
  THE USER.  For example a shorter cycle is possible at the expense of
  hold time while external loads on the pulsetube lengthen the time
  taken to cool the He4 system.

-set the filter wheel position to X. X={hot load, narrowband, wideband, narrowband with sunglasses}.  This takes a second or two to acqure.
-send DAQ electronics into standby mode.
-manually control each of two heatswitches and each of two heaters
  on the sorption fridge
-manually control cool-down heat switch

-tell me X specific parameter (see below)

-tell me how long before you will be "ready"

Parameters
==========
these are set implicitly or explicitly by commands.  

.... [I will fill these in later...]


=======================

The Data comprise: 64*16bit readings at 1KHz 130 Kbytes/second.  With
timestamps. [ONE TIMESTAMP PER WHAT?]  Also a cal status flag [a bit
or byte with each ... TIMESTAMP?  SAMPLE?]

=======================

The Housekeeping data comprise: 
 -16 ROX Temperature readings.
 -bias voltage
 -power supply voltages
 -vacuum gauge reading
 -possibly a few more

======================


Information on receiver characteristics for the analysis software
--------------------------------------------------------------------------
As well as realtime data some receiver information will be needed for data
anaylsis.  This information would be measured when the receiver is 
commissioned and will not change.  Programs to analyse data can have this
information 'hardwired' into them.:

1 Location of each bolometer with respect to the center of the array.
2 Any non-functioning detectors.
3 Beam pattens for each detector.
4 Time constants for each detector.