****************   CESR BPM DAQ program (controls side)   *********************
*******************************************************************************

Located on the VAX.
Current version in USER$DISK:[CESR.PALMER.TS101.BPM]
Development version in USER$DISK:[CESR.PALMER.TS101.BPM.DEV]

Before doing any work, type
@[CESR.PALMER.TS101.COM]init
This will assign some symbols, which can be of use when for instance analyzing measurement
data.

To compile either of these 2 versions, type @doit once you're in the correct
directory.
Once a new version of software has been tested in the .dev directory, one can
use the "backup" command to copy files to the main directory ("backup" will 
retain the creation date and time of the file"), e.g.
backup myfile.f;3 [-]myfile.f;3
For this purpose, one can also use the following scripts:
- [CESR.PALMER.TS101.BPM]COPY_TO_OLD.COM will copy source files from the .BPM
  directory to the [CESR.PALMER.TS101.BPM.OLD] directory
- [CESR.PALMER.TS101.BPM.DEV]COPY_TO_REF.COM will copy source files from the
  .BPM.DEV directory to the [CESR.PALMER.TS101.BPM.OLD] directory

*******************************************************************************
To get the DSP executable from UNIX (assuming tanke as user), type:
ftp /user=tanke cesr34 "get cesr_home/ts101V4/bpm_v1/Debug/dsp_bpm_v1.ldr dsp_bpm_v1.ldr"

To flash and enable the DSP memory type one of the following:
@DL_BPM_DAQLAB_2
@DL_BPM_DAQLAB_3
@DL_BPM_V1_R101_4
@DL_BPM_V1_R101_5
The first one in case the DSP is connected to XBUS line 2 in the DAQLAB
The second one in case the DSP is connected to XBUS line 3 in the DAQLAB
The third one in case the DSP is connected to XBUS line 4 in R101
The fourth one in case the DSP is connected to XBUS line 5 in R101 (this is the normal
location for the first of the new TS101 BPM units, connected to BPM6W1).
*******************************************************************************
To run the executable, type:
run BPM_V1.EXE

The executable will read the file BPM_V1.INI, which has a certain number of default
values. Here is an example of this file:
n        <--- If "y", prompt user for settings; if "n", read settings from this file
n        <--- If "y", reset the relay farm; if "n", do NOT reset the relay farm
n        <--- If "y", take pedestals from file; if "n" measure them along with data
1        <--- number of post-trigger turns to be acquired
t        <---| 
r        <---|--- select the unit in R101, XBUS line 5 
5        <---| 
e        <--- acquire "e" (even),"o" (odd),"a" (all) channels. Typically e for e-, o for e+ 
1045     <--- TglobA
1045     <--- TglobB
6        <--- Gain for even numbered channels (0,2,4,6)
6        <--- Gain for odd  numbered channels (1,3,5,7)
678      <--- "Card" timing for chanel 0 (typically needs to be between 600 and 800)
695      <--- "Card" timing for chanel 1 (typically needs to be between 600 and 800)
695      <--- "Card" timing for chanel 2 (typically needs to be between 600 and 800)
700      <--- "Card" timing for chanel 3 (typically needs to be between 600 and 800)
702      <--- "Card" timing for chanel 4 (typically needs to be between 600 and 800)
720      <--- "Card" timing for chanel 5 (typically needs to be between 600 and 800)
707      <--- "Card" timing for chanel 6 (typically needs to be between 600 and 800)
725      <--- "Card" timing for chanel 7 (typically needs to be between 600 and 800)
79       <--- Clock setting
1  70000 <--- select HW trigger (0,1 or 2) and the # of turns for to delay acquisition by
8        <--- select the routine (here it is the post-trigger routine (#8))
1024     <--- 1024 pre-trigger turns to be acquired
-1       <--- This setting (-1) causes the program to exit after execution 

Apart from the bpm_v1.ini file, there are some more .ini files that have been created. The idea
is that these files each correspond to a specific type of measurement (and/or measurement routine)
whereby one can use a script to make a measurement. Examples are TSCANPLOT_AUTO_E.COM and 
TSCANPLOT_AUTO_P.COM which are electron and positron time scans respectively and 
TSCANPLOT_AUTO.COM which does both species simultanuously.
These scripts copy the apropriate files and then start the execution; finally, data is sorted
( using timesort_auto) and results are plotted (using wlplot). Details about wlplot can be found
at http://cesrelog.lns.cornell.edu/documents/control/software/wlplot.html

Bunches are given names (like T02B05E for Train2Bunch5 e- and T04B01P for Train4Bunch1 e+.
Bunch names used by BPM_V1.EXE are stored in the bunmap.txt file. Again, a certain number
of alternative bunch name files have been created (e.g. E_ECLOUD_BUNMAP.TXT) which can by
copied to bunmap.txt prior to executing BPM_V1.EXE.

*******************************************************************************
As mentioned, to run the executable, type:
run BPM_V1.EXE

If one is in prompt mode (first flag in bpm_v1.ini set to "y"), you will get a menu that looks
like this:
                   BPM main menu

Exit                                          (-1)
Shell command                                  (0)
Time scan                                      (1)
Get raw data                                   (2)
Get sets of raw data (software triggered)      (3)
Get n averaged data                            (4)
Get l averaged data                            (5)
Get averaged positional data                   (6)
Get sets of raw data (for different Tchan)     (7)
Get post-triggered raw data                    (8)

For each of the data taking routines, one will need to select the bunches one wants to take
data on. 
If in prompt mode, 2 graphics menus will come up, one after the other, that allow one
to select electron and positron bunches. The default values are in the files ebunches.dat and
pbunches.dat; these defaults can be changed by clicking on the save button in the graphics
display. If one does not click on the save button, the bunches selected will be used for the
measurement, but will not be stored in the file as new default.
If not in prompt mode, assuming @[CESR.PALMER.TS101.COM]init was typed earlier, one may set
the bunch selection before the measurement by typing
set_dsp_bunches xxxxx.dat
where xxxxx.dat can be any bunch selection file (e.g. ebunches.dat or PBUNCHES_ECLOUD.DAT).
The contents of a bunch selection file looks something like:
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000000000000000000
00000000000000000001000000000000
         172
00000000001000000000000000000010
01000000000000000000010000000000
00000000000001000000000000000000
00001000000000000000000010000000
00000000000000001000000000000000
00000000000000000000000000010000

The first 6 lines contain zeroes and ones; these correspond to the 183 possible bunches in
CESR, whereby a 1 means the bunch is selected, a 0 means it is not. There are an extra 9
zeroes here, which are not used for bunch selection, but are needed for the format.
The next line is a number in the range (0..182) and is the DSP bunch number corresponding to
T1B1 in CESR.
The last 6 lines correspond to the bunches which may be used for pedestals. These one may 
set by typing
set_dsp_pedestals xxxxx.dat
where xxxxx.dat can be any bunch selection file (e.g. ebunches.dat or PBUNCHES_ECLOUD.DAT).
Again, a script may be used to copy a file like PBUNCHES_ECLOUD.DAT to pbunches.dat.
*******************************************************************************
Output files produced by these routines are typically:
1) bpm_cur_xxxxx.dat
2) bpm_yyy_xxxxx.dat
where xxxxx is a five digit number that increments by one for each new measurement. This
number is updated in file FILE_NUM.INP

The first file (bpm_cur_xxxxx.dat) contains general measurement and beam related data as they
were at the moment data were taken:
First line:  #selected bunches, #turns per average, #averages, #turns between averages (note
             that if #turns per average=1, the # of averages=# of turns)
Second line: selected bunch #, DSP bunch #, bunch name
Following line(s) as second line if more than one bunch; followed by trigger type, time stamp,
lattice name, bunch by bunch info (currents, L, L/I), beamsizes, various settings in the machine
and saveset numbers. Towards the end there is more information on settings used by the DSP.

The second file contains the data taken; the yyy indicates the name of the type of 
measurement:
tim for timing scan (menu option 1); files written to current directory
raw for raw data    (menu option 2); files written to log3$disk:[cesr.cesrbpm.bpm6w.zz]
                                     where zz equal the highest two digits in xxxxx
                                     In the case of raw data, a third file will be written,
                                     containing pedestal values (here yyy=ped)
mrw for multi-raw   (menu option 3); files written to current directory. Also in this case
                                     a third file will be written, containing pedestal values
                                     (here yyy=ped)
nav for n averages  (menu option 4); files written to current directory. 
lav for l averages  (menu option 5); files written to current directory. In this case a 
                                     third file will be written, containing the board
                                     temperatures in Celcius (column 1 is the acquisition
                                     number, 2,3,4,5 the temperatures on the ADC boards,
                                     6 on the timing board and 7 on the digital board. This
                                     last one is to be ignored (it is not connected). Note 
                                     that here yyy=tmp.
apo for average pos (menu option 6); files written to current directory; under development.
                                     Note that the apo file is empty.
mrt for multi tscan (menu option 7); files written to current directory. Also in this case
                                     a third file will be written, containing pedestal values
                                     (here yyy=ped). A fourth file (yyy=tsc) is also written;
                                     it contains the RMS values of the data in the mrt file.
raw for raw data    (menu option 8); files written to log3$disk:[cesr.cesrbpm.bpm6w.zz]
                                     where zz equal the highest two digits in xxxxx
                                     In the case of raw data, a third file will be written,
                                     containing pedestal values (here yyy=ped)
*******************************************************************************
Brief description of routine (1): Time scan
For the selected bunches and channels, a timing scan will be made. In this routine
TglobA and TglobA will be stepped through whereby for each step, data will be 
measured as an average over a user specified number of turns. The scanning range and
step size are set by the user. The DSP code stores these averages in SRAM and
the VAX code will read these out using the XBUS. 
*******************************************************************************
Brief description of routine (2): Get raw data
For the selected bunches and channels, raw data will be taken over a user specified
number of turns. The VAX code will read these raw data directly from the ADC
buffers using the CBI_NET (ethernet). 
*******************************************************************************
Brief description of routine (3): Get sets of raw data ("multi-raw",software triggered)
For the selected bunches and channels, raw data will be taken over a user specified
number of turns. After the first acquisition, the user will be asked if another
acquisition is required etc. The VAX code will read these raw data directly from the
ADC buffers using the XBUS. 
*******************************************************************************
Brief description of routine (4): Get n averaged data
NSETS sets of data will be taken whereby each set of data corresponds to data averaged
over a user specified number of turns (n_turns) for selected bunches seen by all ADC 
channels. Data will be acquired over NSETS * n_turns turns, meaning that the data
taken are "continuous" in time, the averages are "continuous" averages. The VAX code 
will read these averages from SRAM using the XBUS. 
*******************************************************************************
Brief description of routine (5): Get l averaged data
NSETS sets of data will be taken whereby each set of data corresponds to data averaged
over a user specified number of turns (n_turns) for selected bunches seen by all ADC 
channels. Sets of data will be acquired LDELTA turns apart in time, meaning that
the averages are not "continuous". The VAX code will read these averages from SRAM
using the XBUS. 
*******************************************************************************
Brief description of routine (6): Get averaged positional data
Under development. The intent is to plot in realtime H and V positions as a function
of time for all the selected e- and e+ bunches. Plotting scales are in the file
bpm_apos_plot.dat. Acquistion may be interrupted by typing the letter q.
Currently this routine can only be of use to observe fast changes in position. Slow
drifts are meaningless as the Xilinx does not have as yet a feedback loop for the
temperature control of the DSP unit (it would control the fan speed).
*******************************************************************************
Brief description of routine (7): Get sets of raw data (for different Tchan)
For given values of TglobA and TglobB, take a series of raw data measurements,
where different measurements are for different channel timings (=Tchan). The
user will specify the +/- range to scan around the default Tchan value. This
routine may be helpful in finding the optimum Tchan value. The VAX code will read
data directly from the ADC buffers using the XBUS.  
*******************************************************************************
Brief description of routine (8): Get post-triggered raw data
This routine operates in "post-trigger" mode whereby sampling is continuous until
the module receives a hardware trigger, whereafter sampling continues for a user
specified number of turns and then stops. The VAX code will read these raw data
directly from the ADC buffers using the CBI_NET (ethernet). 
*******************************************************************************
Historically, older output files have been (manually) copied to the server:
/nfs/acc/temp/ts101/BPM6W1_data
More recently, all the raw files have been written to:
log3$disk:[cesr.cesrbpm.bpm6w.zz]
where zz equal the highest two digits in the raw data file name.