The ReadoutShell can be customized in several ways.
Environment variables can affect the operation of the ReadoutShell.
The ReadoutCallouts.tcl script can provide additional code that executes at times during state machine transitions.
The-> menu command can load an arbitrary Tcl script which can register itself with the run state machine.
The-> menu command can add library directories that are searched for packages that supply additional data source providers.
The remainder of this section describes these customization paths. Each subsection points to appropriate reference information.
This section describes sets of related environment variables that can affect the way the ReadoutShell operates.
Table 6-1. Event logger environment variables
|Variable Name||Default Value||Meaning|
|EVENTLOGGER||$DAQROOT$/bin/eventlog||Selects the program that will be used to log events.|
|EVENTLOGGER_RING||tcp://localhost/$::tcl_platform(user)||Selects the ring from which the event logger logs data. Note that ::tcl_platform(user) is a Tcl variable that is always defined to be the name of the logged in user.|
|EVENTLOGGER_NSRCSFLAGS_SUPPORTED||true||If true the event logger will be started with the
|EVENTLOGGER_UNCONTROLLED_SOURCE_COUNT||0||Integer value added to the base source count
to provide the value for
|EVENTLOGGER_USE_GUI_RUNNUM||0||If Tcl boolean true, the run number for the
current run will be provided to the eventlog
program via the |
|EVENTLOGGER_USE_CHECKSUM_FLAG||1||If Tcl boolean true, an sha512 hash of
all logged data will be computed by
passing the |
Note that settings made using the-> override environment variables. This includes settings that have been saved from prior runs of the program.
The table below describes the settings used to control where data is saved.
Table 6-2. Experiment file systems environment variables
|Variable Name||Default Value||Meaning|
|EVENTS||~/stagearea||The root of the directory tree that ReadoutGUI will use to manage the event and related data.|
|NOTE - difference from prior versions|
In the 10.x and prior versions it was possible to separate where the experiment view lived from where the event view lived by specifying the EXPDIR environment variable. This variable is now ignored and that the experiment directory will always live in the stagearea directory tree.
SSHPipe clients also have default parameterizations. These are based on the environment variables that were used by the 10.x readout shell. Reliance on these environment variables is not recommended, as they only populate the sshPIPE parameter prompter and because the point of this software is to manage multiple data sources rather so the concept of default data source parameters becomes a bit meaningless.
The table below shows the environment variables that can populate the SSHPipe settings prompter:
Table 6-3. SSHPipe prompter environment variables
|Variable Name||Default Value||Meaning|
|DAQHOST||localhost||Host in which the readout program runs|
|RDOFILE||undefined||The path to the program to run.|
One last word. In the past, ReadoutShell has failed to run properly because users have defined the environment variable TCLLIBPATH to include Tcl package directories from an older version of NSCLDAQ. In the 11.x version of the program, if TCLLIBPATH is defined the program will exit with an error message unless you additionally define TCLLIPATH_OK which indicates that you are sure your TCLLIBPATH definition doesn not include any NSCLDAQ directories.
As with the 10.x and earlier ReadoutShells, the 11.0 program looks for a ReadoutCallouts.tcl file which, if found is sourced as the program is initialized. This script can contain anything, however it's main purpose is to define one or more of a set of procs that can be called by the ReadoutShell at specific times during the program's execution.
The ReadoutShell looks for the ReadoutCallouts.tcl file in the following three locations. Any ReadoutCallouts.tcl script found is sourced in at the global level. The search order (and thereby execution order) is:
~ your home directory.
~/stagearea/experiment/current The location the metadata associated with the current run is stored.
. the current working directory. at the time ReadoutShell was first started.
If ReadoutCallouts or any other script sourced into ReadoutShell provides them the following procs are called.
Two additional callouts not available in ReadoutCallouts.tcl scripts for NSCLDAQ-10.x and earlier have been added.
This command is invoked when the Halted state is left for the Active state. The command is passed the number of the run that is about to be started.
This command is invoked when the Halted state is being entered from either the Active or Paused states. As with OnBegin the run number of the run being ended is passed to the command.
Called when the Paused state is entered. The run number of the current run is passed in.
Called when the Paused state is left for Active. Again the current run number is passed to the command.
Called wen the Halted state is entered from the Starting state indicating that all event sources have started without errors.
Called when NotReady is entered from any state other than NotReady.
Note that all procs described above are called at the global level (uplevel #0).
Besides automatically sourcing the ReadoutCallouts.tcl script described in the previous section, the ReadoutShell's ReadoutGUI API packages.-> allows you to choose a Tcl/Tk script and source it at the global level at any time. The script you source can define any of the procs described inthe previous section. It can also invoke API procs from the packages described in
The Introduction for reference information on data source providers.-> menu command allows you to choose a directory to be added to your library path. One of the main reasons to do this is to add a custom data source provider. This section describes in general terms how to create data source providers. See
Data source providers can be thought of as a class whose instances manage data sources. In order to create a data source provider you must:
Create a provider package that encapsulates the provider's interface into a Tcl namespace.
Optionally create a prompter package that encapsulates provides a custom GUI prompter for the parameterization of the data sources your data source provider manages.
A data source provider has a name which we will refer to as providername in this chapter. The provider must provide a Tcl package. The name of that package must be providername_Provider. Furthermore it must define a namespace ::providername. If these conditions are met, and the provider's package is in the Tcl library search path, the ReadoutShell's -> will list the providername as one of the providers available to add a data source
Data sources have parameterizations. It is differences in their parameterizations that typically distinguish between the data sources a provider manages. Data sources describe their the form of their parameterizations via their providername::parameters proc. The parameters proc is described in parameters
If the data source provider does not provide a parameter prompeter, the ReadoutShell will construct a default simple prompter from the information returned by the data sourcde provider's parameters proc. This prompter will just be a bunch of verbose names and text entries for each name.
If this prompter is too simplistic, it is possible for a data source provider to also define a prompter. A prompter is provide by providing a package named providername_Prompter which defines the proc ::providername::promptParameters. This proc is called by the ReadoutShell with no parameters and is expected to return the either the parameterization dict (see start) for information about this dict. If the user declines to provide parameters (e.g. cancels the dialog prompter's dialog), the prompter should return an empty string.
The parameterization of a data source, along with a data source id are passed to the ::providername::start proc to start a data source. The source id is a unique value that is generated by the ReadoutShell and used to refer to individual data sources. The data source id is globally unique (not just unique to the provider). For more information abut starig data sources see: start.
Not all data sources are created equal. Thus a data source must provide a proc named ::providername::capabilities that returns a dict that descsribes the capabilities of the data sources it manages. For example, if a data source is not capable of pausing an active run its capabilities proc will report that in the dict it returns. For more information see: capabilities
Data sources must also provide a ::providername::check proc. The check proc is passed the data source id and is expected to return a boolean that is true if the data source is still alive or false if the data source is no longer alive. The data source provider can expect the ReadoutShell to periodically poll its check proc so that it is able to report to the user an unexpected exit of a data source. The check proc is described more completely in check.
Data source providers must know how to end a data source. This mechanism is exposed to the ReadoutShell via a proc named: ::providername::stop. This proc is passed the source id of the source to stop. For more information see: stop.
Finally, providers must be able to actually control their data sources. This implies at a minimum providing ::providername::begin to start a run and ::providername::end to end a run. In addition, if the provider's capabilities include the ability to pause and resume an active run, ::providername::pause and ::providername::resume must also be supplied.
The data source manager is capable of sending on-demand initialization to its registered data sources. It is thus required that each provider implements a proc named: ::providername::init to handle on-demand initialization procedures. It is particularly useful for doing things like loading firmware.
The ReadoutShell is a very small script. It simply creates an instance of a ReadoutGui object after getting the package paths set up properly. This allows you to customize the way the Readout GUI is produced, not only via ReadoutCallouts.tcl scripts and State maching callback bundles, but by writing your own container script.
If you are going to do this you'll certainly need to know about ReadoutGUI API packages and their contents so that you can effectively customize the behavior and appearance of the resulting GUI.
Assuming the environment variable DAQROOT is defined and points to the top directory of the DAQ installation The example below shows a minimal ReadoutGUI startup script with comments that show where to include customizations.
Example 6-1. Custom ReadoutGUI startup script
ReadoutGuiAppwhich drives the Readout Graphical user interface.
The line itself creates an instance of the class named
r. Creating an
object creates the user interface and initializes it.
Initialization includes locating the
ReadoutCallouts.tcl script and
ReadoutGuiAppapplication object has been created additional customizations can be done here. These customizations include invoking procs and methods from the various ReadoutGUI API packages which might alter the appearance or the behavior of the application.
Similarly, data source providers and additional run state machine callback bundles can be registered at this time.
This section will describe in general terms the packages that make up the ReadoutGui's application programming interface. pointers to reference material will be provided as well.
This package provides the
class. This can be used to ring alarm bells in accordance with
See bells for reference information.
Provides a manager for configuration data. This package allows you to define configuration variables and their defaults. It also supports overidding default values with environment variables. Normally this package is used in conjunction with the StateManager package to save and restore the state of configuration parameters to the configuration file.
See Configuration for reference information.
Provides access to parameters that affect data taking. This package provides both query and modify access. It uses the Configuration package above.
See DAQParameters for reference information.
This package manages the data source providers and data sources. You need to interact with this package if you want to create data sources yourself (e.g. to create an exportable pre-packaged ReadoutGUI for a specific setup).
This package provides the user interface
elements that prompt for data source parameters.
It provides at least one useful class
can be used to build custom prompters for
data source providers.
Provides simple error/warning/info dialogs. See: Diagnostics
Provides read/write access to configuration parameters that determine where event data and related meta-data are stored. See: ExpFileSystemConfig
Provides the readout GUI application class which strings everything together. See ReadoutGui
Provides a group of API elements that allow you
to modify the user interface presented by the
Implements the run state machine. This also provides the mechanism to register custom callback bundles. See: RunStateMachine
Provides a package that supports simple Tcl configuration files. A simple Tcl configuration file is a script with a bunch of set commands that define configuration variables. The package allows you define variables that are exported/imported from these files and getters and setters for those variables.
Provides access to all elements of the user interface. Before using this package, see if you needs are met by the ReadoutGUIPanel package since that tends to be easier to use.