6.4. Customizing the ReadoutShell

The ReadoutShell can be customized in several ways.

The remainder of this section describes these customization paths. Each subsection points to appropriate reference information.

6.4.1. Environment variables

This section describes sets of related environment variables that can affect the way the ReadoutShell operates.

Table 6-1. Event logger environment variables

Variable NameDefault ValueMeaning
EVENTLOGGER$DAQROOT$/bin/eventlogSelects the program that will be used to log events.
EVENTLOGGER_RINGtcp://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_SUPPORTEDtrueIf true the event logger will be started with the --number-of-sources option provided as described earlier. If false, this flag will be omitted. The variable accepts any valid Tcl boolean value (e.g. true, false, on, off, 1, 0).
EVENTLOGGER_UNCONTROLLED_SOURCE_COUNT0Integer value added to the base source count to provide the value for --number-of-sources
EVENTLOGGER_USE_GUI_RUNNUM0If Tcl boolean true, the run number for the current run will be provided to the eventlog program via the --run flag to determine the name of the event files.
EVENTLOGGER_USE_CHECKSUM_FLAG1If Tcl boolean true, an sha512 hash of all logged data will be computed by passing the --checksum flag to the program.

Note that settings made using the Settings->Event Recording... 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 NameDefault ValueMeaning
EVENTS~/stageareaThe root of the directory tree that ReadoutGUI will use to manage the event and related data.

NoteNOTE - 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 NameDefault ValueMeaning
DAQHOSTlocalhostHost in which the readout program runs
RDOFILEundefinedThe 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.

6.4.2. ReadoutCallouts.tcl

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 directories. Only the first one is sourced in. Sourcing is done at the global level.

If ReadoutCallouts or any other script sourced into ReadoutShell provides them the following procs are called.


Two additional callouts not avaialble 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).

6.4.3. Integrating Tcl scripts

Besides automatically sourcing the ReadoutCallouts.tcl script described in the previous section, the ReadoutShell's File->Load... 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 ReadoutGUI API packages.

6.4.4. Libraries and Data source providers

The File->Library... 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 Introduction for reference information on data source providers.

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:

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 Data Source->Add... 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.

6.4.5. Using the ReadoutGUI in your own container script

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

set TclLibs [file join $::env(DAQROOT) TclLibs]    (1)
lappend auto_path $TclLibs

package require ReadoutGui
ReadoutGuiApp  r                                  (2)

This line and the next add the NSCLDAQ Tcl library directory tree to the search path used by package require.
The previous line incorporates the ReadoutGui package. This package includes the entire Readout GUI graphical user interface object set and also defines the ReadoutGuiApp which drives the Readout Graphical user interface.

The line itself creates an instance of the class named r. Creating an ReadoutGuiApp object creates the user interface and initializes it. Initialization includes locating the ReadoutCallouts.tcl script and sourcing it.

Once the ReadoutGuiApp application 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.

6.4.6. ReadoutGUI API packages

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 bells class. This can be used to ring alarm bells in accordance with some pattern.

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).

See DataSourceManager


This package provides the user interface elements that prompt for data source parameters. It provides at least one useful class DialogWrapper which can be used to build custom prompters for data source providers.

See DataSourceUI


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 ReadoutGuiApp application object. See: ReadoutGUIPanel


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.

See StateManager


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.

See ui