1.2. What the NSCL DAQ System Provides
Superficially, the NSCL DAQ system provides a data flow system for experimental nuclear physics. It also provides a set of frameworks that attach to this data flow system that allow actual experiments to be constructed. A deeper look at the design reveals that even more important than this functionality, is that the design of the NSCL software attempts to provide a clear separation of concerns between the needs of all experiments and the needs of specific experiments. This separation of concerns allows you to focus on the pieces of software you need to work with to get your experiment built without having to understand the much larger volume of software neede to run all experiments.
Perhaps the best way to undertand the importance of this separation of concerns is to look at some statistics. The NSCL DAQ system is divided into three main subsystems, Spectrodaq, Spectrodaq client DAQ software, and SpecTcl. The source lines of code for each of these systems is as follows:
Spectrodaq data distribution software: about 50,000 lines of code.
Spectrodaq client DAQ software: about 160,000 lines of code.
SpecTcl online analysis program: about 180,00 lines of code.
If you had to understand the nearly 400,000 lines of code that make up this body of software in order to create an experiment, building an experiment would be a very daunting task indeed. Separation of concerns effectively hides most of this code. One of the examples in this manual, the readout, and analysis of data from a CAEN V785 VME ADC module requires only 70 lines of Readout code and about 130 lines of SpecTcl code. A much more manageable proposition.
Separation of concerns takes two forms:
Providing you with prebuilt programs that either need no configuration (e.g. spectrodaq which just runs as a server in all systems invovled with data taking), or can be configured to do useful things with just a simple configuration file (e.g. ScalerDisplay which just needs to know the order in which scalers were read and what you want displayed in which pages).
Providing you with programming frameworks for programs that require you to do some real programming. SpecTcl, and Readout are examples of programming frameworks.
1.2.1. Programming frameworks
If you are used to writing programs, when you first encounter an application framework you may feel slightly lost. Your first reaction will probably be something like "Where's the main()?"
This confusion points to the heart of the difference between writing a program and writing to an application framework. The figure below shows how a classical program will interact with supporting libraries. The Arrows represent function, procedure or method calls.
When you write a program that uses 'classical libraries', your program is responsible for getting the entire flow of control correct. Your main program may call library functions, it may call functions in your own program which may in turn call library functions. Normally, all or most of these calls go one way, from your program to the library.
But the flow of control of a component of a data acquisition system can be hard to get right. Furthermore, the top level flow of control is independent of the experiment. Our philosophy of separation of concerns therefore dictactes that we (NSCL staff programmers) should write this flow of control and ensure that to ensure that it gets done correctly, and you, the experimenter should just provide chunks of code that get called by this flow of control at appropriate times.
This suggests a program structure where we write the main, and provide services you can call, and you provide libraries that our prepackaged main will call at appropriate times, and in appropriate ways. This is exactly what an application framework is. The structure of an application framework is shown in the figure below:
This figure shows that the missing main() is hiding
inside the application framework. The application framework is divided into
three types of code. main() which ensures that the overall
flow of control is correct. Internal services which
are functions, procedures and classes used only by the framework itself, and
public services which are functions, procedures and classes
that are avaialable to user written code.
The application framework calls user code at appropriate times, and the user code in turn can make use of public services provided by the application framework. An example of a public service provided by the framework might be software to support a specific piece of data taking electronics, e.g. the CAEN V785 VME peak sensing ADC. An example of a private service might be code which manages the buffering of events taken by user code and interacts with Spectrodaq to ensure that these data are submitted for distribution to client software.
1.2.2. Programming frameworks provided by nscldaq
The NSCL provides several programming frameworks. Of these, several should be considered obsolete for new development either because newer frameworks exist that have greater functionality, or because newer frameworks perform better in a high rate environment. You may, however find yourself working within an older framework if you are extending existing work. There are currently no plans to remove existing obsolete frameworks, however support for these frameworks has lower priority than the newer software.
All frameworks provide skeleton directories. Skeleton directories contain empty sample implementations of programs that use the framework as well as a Makefile that can be extended to build your software once it is written.
Existing frameworks and their status is shown in the table below:
Table 1-1. Application frameworks at the NSCL
| Name | Skeleton dir | Status | Comments |
|---|---|---|---|
| Readout Classic | DAQHOME/Readout/skel | Obsolete | There's a lot of software that still uses this. |
| High performance Readout Classic | DAQHOME/Readout/hpskel | Obsolete | This can take higher data rates than Readout Classic |
| Production readout | DAQHOME/pReadoutSkeleton | Supported | Use High performance production readout instead if you can. |
| High performance production Readout | DAQHOME/HPpReadoutSkeleton | Supported | Recommended for new projects |
| Scripted Readout | DAQHOME/contrib/scriptedReadout/skel | Supported | Scripted Readout can read many experiments without any programming. |
| SpecTcl | SPECHOME/Skel | Supported | |
| Scripted SpecTcl | SPECHOME/contrib/scripted/skel | Supported | Can analyze some data sets without any programming |
In the table above:
DAQHOME is the top level installation directory of the NSCL data acquisition system. At the NSCL this is /usr/opt/daq/current, this may not be the case at other institutions.
SPECHOME is the top level installation directory of the NSCL SpecTcl histogrammer. At the NSCL, this is /usr/opt/spectcl/current. This may be different at other institutions.
Where possible, use high performance variants of the readout skeletons, they are able to sustain much higher event rates than the other variants.
1.2.3. Prebuilt programs
We provide many other pre-built programs that can be used in specific data acquisition system software. Full desriptions of these programs can be found in the reference part. Use of these programs is optional, if you want their functionality in an experiment, use them. These programs and their summaries are given in no particular order.
- AlarmDisplay/AlarmServerApp
Provide a service for centralized management of events that are exceptional in nature, alarms. Alarms are logged, and can be acknowledged and then dismissed. The software consists of a server and display pages that interact with the alarms in the database maintained by the server
- DaqPortManager
A service that is running in all NSCL DAQ systems. This software allows Tcp/IP servers to allocate a listener port from a pool of free ports. The server can also be interrogated for the list of application/username pairs that own ports, and which ports they own.
- EpicsDisplay
Provides a tabular display of selected EPICS channels and the ability to set alarms on those channels as well as to chart record some subset of the channels. Used in conjunction with controlpush. Requires that EPICS channel access software be installed on the computer
- LogDisplay
Provides a centralized logging capability. This operates in a manner similar to AlarmServer, a log server accepts and maintains a database of logged messages, and the log displayer displays the set of messages accepted by the logserver
- PopUp
This program is like the unix echo command, however the message pops up on the XWindows display in a dialog box.
- ScalerDisplay
Provides displays of scalers periodically read through the data taking run. Alarms can be set on count levels, and selected scalers can be put on a chart recorder. End of run human and machine readable summary files are also created. Works in conjunction with sclclient
- SecretTk
A Tcl/Tk server that obscures its command line so that sensitive information like usernames and passwords can be put on a commandl ine to it.
- bcnaf and wienerbcnaf
Programs that can perform single CAMAC operations on crates controlled by the CES CBD 8210 VME Branch highway driver and Wiener VC32/CC32 board sets respectively
- bufdump
Utility for examining buffers of data from both online and offline systems. This program can create formatted buffer dumps, filter the set of buffers displayed, and do sophisticated searches on the interior of buffers. Formatting is extensible.
- burngui/dvdburn
Utility that takes the event, and ancillary data from a set of runs and burns them on a set of DVDs. The data are burned so that no runs span a DVD. burngui is an Xwindows graphical application while dvdburn is a command line application.
- caenv812control
Control panel for CAEN V812 VME Constant fraction discriminator.
- chanlog
Allows a single snapshot of a set of EPICS channels to be logged either to stdout or to a file.
- controlpush
Pushes control system information from a set of EPICS channels into a Tcl Server.
- cratelocator
Program that helps you determine which VME crate is which. Since most systems don't number VME crates externally, this is an essential tool for multi-crate systems.
- cratemonitor
Utility to monitor the connectivity of a VME crate. A dialog box pops up if a crate becomes unreachable (usually due to power loss).
- daqstart
A utility for starting critical DAQ components. daqstart wraps the program, logging its output and error, and complaining loadly if the program exits.
- eventlog
Logs event data to file. This is usually run by the ReadoutShell application.
- loadcfd
Program to load a CAEN V812 VME constant fraction disriminator. This is intended to be invoked via e.g. the unix
system(3)system call by run initialization software such as a readout program or the callout extensions for the ReadoutShell- loadshaper
Program to load a CAEN N568 shaper via CAENNet. This is intended to be used by software running when data taking is initialized, such as the ReadoutShell
OnBegincallouts or the Readout program itself.- n568Control
Control panel for CAEN N568 shaping amplifiers controlled via CAENNet.
- powerdetect
Application to determine if the power is off on a VME crate.
- sclclient
Application that maintains the state of scalers in a Tcl Server via procedure calls and variable manipulation
- spectcldaq
DAQ client that pipes buffers out stdout. This can be used to adapt between the NSCL data acquisition system and programs that are not aware of the system.
- tclserver
A Tcl/Tk interpreter that has been augmented by the ability to accept and execute commands sent to it via Tcp/Ip clients. This serves as the basis for many of the display applications in the NSCL DAQ system.
- vhqControl
A control panel for iSeg VHQ dual channel VME detector bias supplies.