4.5. The ReadoutGUI
ReadoutGui is a supported NSCL Data Acquisition system program. It:
Provides a convenient graphical front end to the Readout program.
Allows you to launch and control the readout program while logged into a system remote from your spdaq system.
Coordinates the activities of Readout and the event logger to ensure that data is recorded when desired.
Maintains the file structure described in the previous section.
This section will:
Describe how to start the Readout GUI
Provide an operational overview of the program. (See the reference material for full operational information
Suggest scripts that can be used to reliably start and stop the readout GUI and the Readout program it manages.
4.5.1. Starting the Readout GUI.
The command syntax for ReadoutGUI depends on the version fo the DAQ system you are using. For NSCLDAQ-8.0 and before, you must start this program as follows:
Example 4-9. Starting the Readout GUI in NSCLDAQ-8.0 and earlier.
/usr/opt/daq/current/Scripts/ReadoutShell.tcl host path ftphost [passwd]
- host
is the name of the computer system on which the Readout program will be launched. This should be the TCP/IP name of the computer that is connected to the experimental hardware.
- path
is the full path to the Readout program you want to launch on host
- ftphost
Is the TCP/IP name of a computer that is running an ftp server over which data will be saved. Prior to nscldaq-8.0, event recording was done over ftp, since it was thought that was faster. Since NFS write performance has caught up to ftp, so in 8.0 and later ftp host is no longer important (although for historical reasons still required).
- passwd
An optional password that provides a password on the ftp server (for 7.4 and earlier), not required in 8.0, if not provided in 7.4, the ftp password is read from ~/.passwd Be sure that you chmod 0600 ~/.passwd if you choose to use this mechanism. Otherwise other people might find and be able to read this password file.
For NSCLDAQ-8.1 and later, you must start this program as follows:
Example 4-10. Starting the Readout GUI for NSCLDAQ-8.1 and later.
ReadoutShell [-host=hostname] [-path=readoutProgram] [-ftphost=ftphost] [-passwd=password]
Where:
- hostname
Is the internet name of the computer on which you want to run your readout software. Notet that this computer must have a shared filesystem with the one you are running on.
- readoutProgram
Is the full path (relative or absolute) to the readout program. Your readout program should not make any assumptions about the state of the current working directory when it runs.
- ftphost
Is a host on which ftp based event recording will be done. At present, this must be defined (see below however), but is ignored (event recording is done by doing file system I/O in the local system). In the future, if this is present, ftp based recording will be done, otherwise, direct file system I/O will be done to record events.
- password
If ftp event recording is being done, this must be a password for this user on the ftp serer
The 8.1 Readout Gui application saves its command line parameters in configuration files for the next time it is run. Some configuration parameters can also be specified via environment variables. A normal way to use the ReadoutGUI is to run it once, the first time with the required parameters to set it up, and subsequently run it without any command line parameters.
4.5.1.1. How ReadoutGui 8.1 configures itself
ReadoutGui 8.1 has a sophisticated configuration system that attempts to deal with several concerns that were raised by users of previous ReadouGui versions. In particular, users wanted to be able to manage test accounts that might have multiple independent data taking areas.
ReadoutGui 8.1 uses default values, environment variables, configuration files, and command line parameters in that order to establish its configuration. When ReadoutGui 8.1 starts it first establishes a set of default values where there are sensible defaults for a configuration parameter. For many parameters environment variables can be defined to override the default values. ReadoutGui next determines which environment variables are defined, and overrides parameters as appropriate. Next it reads several configuration files, if they exist. Each configuration file has the opportunity to override the values of any configuration parameter that was defaulted or set by a previous configuration file. Configuration files are just Tcl Scripts and parameters are set using the Tcl set command. Finally the command line parameters described previously are processed.
Configuration files are read out of several directories, if they exist. The assumption is that you may have configuration values that are specific to the user, the working directory (project), and the event area (experiment/test run). Configuration files read are as follows:
- ~/.daqconfig
This file is assumed to have configuration values that are to be used by all cases where Readout is running in this account, for example often a single spdaq system is shared by multiple users of a test account, this might be configured here.
- ./.daqconfig
Readout programs in specific directories are often used to perform specific tests or tasks. Configuration parameters that are specific to these tasks can be defined in this configuration file.
- .daqconfig in the experiment's run view
By the time this configuration file is processed,
Experiment(see below) must be defined. The ReadoutGui itself maintains several configuration parameters in this file such as the next run number, the saved title, and the encrypted password. The user should not add configuration parameters to this file as it will get ovewritten by the ReadoutGui.
The Readout GUI stores passwords in DES encrypted form. This is a somewhat stronger encryption than that used by prior versions of ReadoutGui. In addition, the current invocation prompts for the password if you have not provided it on the first run, so that it does not appear in the unix process display.
The list below describes the configuration parameters that ReadoutGui8.1 knows about, where applicable their default values and the environment variables that can be used to configure them.
Parameter Tcl name: StageArea
Environment Variable: EVENTS
Default value: ~/stagearea
Purpose: The location the event data will be stored.
Parameter Tcl name: Experiment
Environment Variable: EXPDIR
Default value: ~/experiment
Purpose: The location the run view of the experiment will be stored.
Parameter Tcl name: SourceHost
Environment Variable: DAQHOST
Default value: - no default -
Purpose: The name or IP address of the host that is attached to the experimental hardware. This host is the computer the Readout program should be run on
Parameter Tcl name: ReadoutPath
Environment Variable: RDOFILE
Default value: - no default -
Purpose: The location fo the Readout program.
Parameter Tcl name: FtpHost
Environment Variable: EVTHOST
Default value: - no default -
Purpose: The name of the host on which event recording will take place if not localhost
Parameter Tcl name: Password
Environment Variable: PASSWD
Default value: - no default -
Purpose: The password. When in a configuration file this will be a DES
encrypted password. When an evironment variable, this is the cleartext
password. The password is used when establishing an ftp session with
FtpHost. The DES encryption keyis a combination
of a number of things which I am not describing here.
Parameter Tcl name: BufferSize
Environment Variable: - no env variable -
Default value: 8192 bytes
Purpose: The size of event buffers in bytes. This must be twice the
number provided to daq_SetBufferSize() in
your readout program as that daq_SetBufferSize()
is in units of 16 bit words.
Parameter Tcl name: title
Environment Variable: -none-
Default value: -none-
Purpose: The title of the next data taking run.
Parameter Tcl name: run
Environment Variable: -none-
Default value: -none-
Purpose: The run number of the next data taking run.
Parameter Tcl name: scalers
Environment Variable: -none-
Default value: -none-
Purpose: For readout classic, this is the number of scaler channels that
will be put in the buffer unless daq_setScalerCount()
is called to override this.
Parameter Tcl name: period
Environment Variable: -none-
Default value: -none-
Purpose: The number of seconds between scaler reads, unless this has been
programmatically set in the readout program (e.g. by
a call to daq_SetScalerReadoutInterval() in
Readout classic).
4.5.2. An operational overview of Readout GUI
The 'old' readout GUI prior to version 8.1 is shown below:
The readout Gui for version 8.1 and later is shown below:
The differences between these two graphical user interfaces are purely cosmetic. Both windows have spaces for the run title and run number. These are saved in the .readoutconfig file in the experiment directories.
Runs are controlled via two pushbuttons and a checkbox. The checkbox or determines whether or not the run will be recorded to disk. The state of this button can only be modified when the run is inactive. The leftmost run control pushbutton is initially labelled . When clicked, the run will start and the button will be relabeled . At that time, the right hand button will be enabled.
Clicking on an active run will temporarily pause data taking, and relabel that button to . Clicking will end the run. If data recording was enabled, the run number is automatically incremented. Clicking on a paused run will restart data taking for the same run. If event recording is enabled, additional data will be appended to the event file.
Runs may also run for a fixed duration. Timed runs are initiated by setting the duration of the run and checking the button prior to starting the run. Regardless, the Elapsed Time shows the amount of time the run has been active.
The menu allows you to specify a new readout program, restart a crashed readout and source a file into the standard input of the running readout. The menu allows you to set the scaler readout period and the number of scalers to put in the buffer.
4.5.3. Reliably starting and stopping the Readout GUI
When starting your ReadoutGUI, you do have to worry a bit about handling error cases. In particular if you improperly exit the readoutGUI, it can leave the readout program running in the background. This is usually undesirable. This is especialy undesirable if it happens in the middle of a data taking run, as then this readout will compete with any subsequen readout for triggers.
A fairly typical script to start the readout gui prior to 8.1 is shown below. This script assumes you have set up ssh to not require a password to login to remote hosts. If you do not know how to do this, see the Other resources section at the end of this chapter.
Example 4-11. A Readout Gui startup script
#!/bin/bash # # godaq by convention is the guy that starts up the readout program. # it just start ReadoutShell.tcl . ~/.bashrcssh $DAQHOST killall -9 Readout
$DAQROOT/Scripts/ReadoutShell.tcl $DAQHOST ~/bin/Readout $EVENTHOST \ $(cat ~/.passwd)
ssh $DAQHOST killall -9 Readout
- In some environments, such as a desktop shortcut, the bash initialization scripts do not get run. This line ensures that ~/.bashrc is sourced so that the environment variables we will use later on in this script get defined.
-
This line kills all Readout processes we have the privilege to kill
on the computer name stored in the environment variable
DAQHOST. As we have recommended theDAQHOSTenvironment stores the name of the data taking system connected to the experiment haredware. This command is why we need to have password free ssh logins on$DAQHOST - Starts the Readout GUI (prior to 8.1). In this case we have made a symbolic link between ~bin/Readout and the actual location of the Readout program. This may not be appropriate for test accounts that may need to run more than one readout program.
- Here we attempt to ensure that readout is killed prior to the end of the script. If the ReadoutGUI is normally exited this line will ensure that any hanging Readout is killed. If not, the kill at the beginning will take care of this.
In some cases, a production readout program may need to be passed some command line parameters. This can be handled by having the ReadoutGui run a script that in turn passes the appropriate parameters to the actual Readout program. When taking this approach, be sure that you don't make any assumptions about the environment this script is run in. In particular you will not know the home directory, nor if any shell initialization scripts will have been run.
The script below shows a sample Readout startup script that the ReadoutGui may run. It passes a configuration script to the scripted readout program.
Example 4-12. Sample readout startup script
#!/bin/bash
#
# Starts the readout program. The readout program
# lives in $DISTRIBROOT/readout/Readout
# it requires a parameter that is the hardware configuration file.
# called $CONFIGDIR/hardware.tcl
#
. ~/.bashrc
$DISTRIBROOT/readout/Readout $CONFIGDIR/hardware.tcl
Here again, the ~/.bashrc was manually sourced in order to
ensure that the needed environment variables (DISTRIBROOT and
CONFIGDIR were defined.