-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
  Cornell/CESR Beam Instrumentation Control (CBIC) Application
                       User Manual

  5-September-2009 (Draft)       M. Rendina (mcr38@cornell.edu)
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

The CBIC application is the primary control program for managing beam
measurement instruments and requesting various kinds and quantities of 
data.

[[ As of 5-September-2009, the application only supports control of
   CBPM-II instruments deployed as the standard orbit/betatron phase
   acquisition system from locations 12W - 12E, (with a single-instrument 
   gap or two) and EXTra instruments at a handful of other scattered
   ring locations. ]]

The same program is designed to be general enough to serve multiple needs.
The primary but separate responsibilities of the application are:

 1) To provide on-demand beam position data in two distinct request modes:
    a) Local-application mode - Provides a menu-driven interface allowing
       the user to request various types of data acquisitions from a
       configurable set of deployed beam measurement instruments.  
       This mode also allows maintenance tasks to be performed on the 
       assorted files and instruments used during operation as well as
       allowing for the adjustment of application behavior/configuration.

    b) BPM server mode        - Provides a non-interactive BPM data server
       that responds to requests delivered through the 'CBPM CONTROL' MPM
       database node.  The measurment types and parameters are pre-defined
       and will be detailed below.  CESRV depends on a server or servers
       running in this mode to provide it with BPM data for orbit and 
       betatron phase measurements of a stored beam.

 2) To provide continuous monitoring of bunch by bunch beam currents under
    4ns feedback conditions.
    This mode uses a single beam monitoring instrument assigned specifically 
    to this task.
       






This manual is divided into several sections.
   I - Setting up for use
  II - Starting the application


(I)  - Setting up for use:
-----------------------------------
The application's behavior can be configured by editing a file in the local working directory
called 'cbic.conf'.  This is the only hardcoded path and filename that the application expects.
An example of this file is provided below.


#========================================================
#        CBIC Application Configuration File
#
#  Please note: All parameters below are CASE SENSITIVE
#========================================================
[APPLICATION_CONFIG]

   #---------------------------
   #  Application/Server  ID
   #---------------------------
   .APPLICATION_ID    BPM-TEST
   .CBPM_SERVER_ID    55


   #-----------------------------
   # DSP Sofware Flashing
   #  The instrument loader 
   # (exe) file to use when 
   # a flash command is 
   # issued from the main menu.
   #-----------------------------
   .CBI_PT_INST_EXE_PATH   /home/mcr/devel/instr/CBPM-TSHARC/dsp/bin/cbi_PT_INST_exe.ldr


   #-------------------------------------------
   # Data file output directories
   # (Do not provide a trailing '/' character)
   #-------------------------------------------
   .PHASE_DATA_DIR         /nfs/cesr/instr/cbpm_data/tsharc/phase
   .PROC_DATA_DIR          /nfs/cesr/instr/cbpm_data/tsharc/proc
   .RAW_DATA_DIR           /nfs/cesr/instr/cbpm_data/tsharc/raw
   .TSCAN_DATA_DIR         /nfs/cesr/instr/cbpm_data/tsharc/tscan
   .PARAM_INDEX_DIR        /nfs/cesr/instr/cbpm_data/tsharc/config


   #-----------------------------------------------------
   # File containing List of instruments to bring online
   #-----------------------------------------------------
   .INSTRUMENT_LIST        /nfs/cesr/instr/allocation/BPM_instrument_list


   #----------------------------------------------
   # Instrument Operational Parameters File Path
   #----------------------------------------------
   .PARAM_FILE             /nfs/cesr/instr/cbpm_data/tsharc/config/configuration_parameters.cfg


   #----------------------------------------------
   # Instrument Defaults
   #----------------------------------------------
   # Timing Setup
   #  Valid options are:
   #    4ns_P
   #    4ns_E
   #    6ns_P
   #    6ns_E
   #    10ns_P
   #    10ns_E
   #    14ns
   #    4ns_P_FIX_G
   #    4ns_E_FIX_G
   #    6ns_P_FIX_G
   #    6ns_E_FIX_G
   #    10ns_P_FIX_G
   #    10ns_E_FIX_G
   #    14ns_FIX_G
   #----------------------------------------------
   .DEFAULT_TIMING_SETUP       4ns_P


   #----------------------------------------------
   # Gain Setting
   # Valid options are: 0 - 10
   #----------------------------------------------
   .DEFAULT_GAIN_SETTING       7


   #----------------------------------------------
   #  Communications
   # Valid options are:  ETHERNET,  XBUS
   #----------------------------------------------
   .COMM_METHOD           ETHERNET


-------------------------------------------------------------------------------------------


Starting the application in a working directory where no cbic.conf file exists will create
a template cbic.conf file in that directory similar to the above.  This must be 
editied/populated with configuration details before the program will function as expected.

.APPLICATION_ID   Is a text label that can be associated with an instrument or group of
                  instruments.  It allows one to bring a certain subset of instruments
                  online.

.CBPM_SERVER_ID   A positive integer associated with a given instance of a CBPM data server
                  This value gets published in the 'CBPM CONTROL' mailbox when a BPM data
                  server is started and must be unique among all running BPM servers.
                  If a server is already running with the given ID number, a cbic instance
                  configured with the same ID number will not be permitted to enter server
                  mode.

.DEFAULT_GAIN_SETTING   [See the section Instrument Gain Settings below for details.]

.PHASE_DATA_DIR   Output data file directory used for betatron phase measurement files.

.PROC_DATA_DIR    Output data file directory used for processed data files.  These files
                  are produced when orbits are taken.  They contain button values averaged
                  over some number of turns. These values may also be scaled based on gain
                  setting and/or have pedestals subtracted.

.RAW_DATA_DIR     Ouput data file directory used for raw (turn by turn) button data.
                  Values provided are in ADC counts.

.INSTRUMENT_LIST  The full file path of the instrument list to reference when starting
                  the program.  This file provides
 
[[ As of 5-September-2009, a valid excerpt of this file looks like the example here: ]]

#----------------------------------------------------------------------------------------------------
# Hostname   XBUS-PKT-Node  Element  Server-Type/ID    PS-Relay-Element    Annotation
#----------------------------------------------------------------------------------------------------
ctacf033    CBPM PKT TST      3       BPM-TEST       BENCH TEST

ctacf074    CBPM PKT EXT      1       BPM-123     8AW
ctacf076    CBPM PKT EXT      2       CURRMON     12W2
ctacf097    CBPM PKT EXT     12       BPM-123     47AE
ctacf038    CBPM PKT EXT      3       BPM-123     12W3

  #ctacf101    CBPM PKT STD     10       BPM     NO comm, NO timing

                  The default is the master instrument list which is stored in 
                  /nfs/cesr/instr/allocation/BPM_instrument_list,
                  but another file following the same formatting conventions may be 
                  specified here for special sessions or testing.
                  [ See the header of that master BPM instrument list file for
                    details on the file specification or filespec document 'XXXXX' ]



.PARAM_FILE       The full file path of the instrument operational parameters file to 
                  read in when the application starts.  This file contains all the timing
                  parameters, gain parameters, and MPM database addressing information
                  pertinent to instruments that may publish data into the traditional
                  orbit and betatron phase database locations such that third-party
                  applications like ORF or CESRV may receive orbit and betatron phase
                  measurement.
                  [ See the header of the master operational parameters file
                    in /nfs/cesr/instr/cbpm_data/tsharc/config/configuration_parameters.cfg
                    for additional information on file syntax and content. ]


(II) - Starting the application:
-----------------------------------

The application is typically named 'cbic' unless renamed for informative purposes.
The various command-line options that the application honors are:

  -h     : HELP                 Prints the list of available command-line options.

  -v     : VERSION              Prints the application version, build ID, and communication
                                 structure ID stamps for all supported instrument platforms.

  -d #   : DEBUG PRINTOUT MODE  During runtime, prints out varying levels of additional
                                debugging information based on the verbosity level requested
                                by the numeric parameter provided.
                                  0 - No extra debugging output
                                  1 - Non-communications status statements for non-obvious
                                      operations
                                      State-confirmations (timing setup, timing mode, etc...)
                                  5 - Maximum detail level of debugging output
                                      Individual communications transfers, packet word-counts
                                      and other high-volume minutae are provided.
                                      NOTE: The maximum level prints a LOT of additional
                                            information and may in fact clutter useful 
                                            information or scroll it off the screen more rapidly 
                                            than it may be productively used.  It is recommended
                                            that the application is run in a terminal window 
                                            with a large scrollback buffer so that runtime 
                                            details are not lost.
                                [As of 5-September-2009, this option is hardcoded to a maximum
                                 value to provide the most debugging output possible when
                                 invoked.]

  -g     : GUI MODE             Graphical User Interface mode.  An alternative to console-based
                                application control, draws windows on the screen allowing 
                                keyboard and/or mouse-based input of certain commands and
                                parameters.

  -m #   : MAINTENANCE MODE     Starts up the application in one of the collection of available
                                'maintenance modes' that allow for the follwing options:
                                  1 - Brings instruments online with the usual communications
                                      and version checks, but skips reading in all but the
                                      location and naming instrument-specific parameters.

                                       [[ As of 5-September-2009, this is the only maintenance mode
                                          supported. It is invoked with a solitary '-m'. ]]

                                  2 - Brings instruments online but with no software component
                                      version checks.
                                  3 - Brings instruments online but with no communication,
                                      software component version checks, or instrument-specific
                                      timing parameters.  Useful for bringing a brand-new
                                      instrument with no instrument EXE, or a very 
                                      out-of-date instrument EXE loaded, as it skips all the
                                      checks that would normally prevent an instrument
                                      from being brought online.

  -a     : ALL INSTRUMENTS      Bring all instruments that are not commented out in the 
                                specified 'cbic.conf' file online, ignoring all 
                                APPLICATION_ID labels.

  -c     : CURRENT MONITOR      A specialized mode that brings a SINGLE, specially-allocated
                                instrument online to provide continuous monitoring of 
                                bunch-by-bunch beam currents.  
                                [The Instrument List file must have a single instrument
                                 designated 'CURRMON'. See section 'Current Monitor Mode'
                                 below for details.]