NSCL DAQ Software Documentation

Table of Contents
I. introduction
1. Introduction
1.1. How does the ring buffer data acquisition system work
1.2. Overview of ring buffer utilities
1.3. Documentation roadmap
II. commands
2. The ringbuffer command
3. Ring piping utilities
4. Command line access to CAMAC via the SBS interface
5. Tcl access to the VME via the SBS interface
5.1. Incorporating Vme Tcl in your scripts
5.2. Sample programs that use the package
III. utilities
6. Readout GUI (ReadoutShell)
6.1. Running and using the ReadoutShell
6.2. Event file organization
6.3. Customizing Readout Shell
7. Epics Channel logging
8. Providing EPICS channel information to Tcl Servers
9. The epics display utility
epicsdisplay NSCLRingDAQ 10.0+ Ron Fox -- Display epics channels
10. CAEN V812 Constant Fraction Discriminator
11. N568B CAENnet shaping amplifier
12. VHS-40xxx SBS support.
13. The tcl server application
14. CCUSB Readout framework
14.1. How the CCUSB readout framework works
14.2. Writing DAQ configuration files
14.3. Writing device support software
14.4. Tcl device driver support
14.5. The slow controls subsystem
14.6. Running CCUSBReadout
15. Dumping events from ringbuffer or from file
15.1. Item dump formats and examples
16. Compatibility utilities
16.1. Format conversion with compatibilitybuffer
16.2. Writing event files with compatibilitylogger
16.3. Convenience scripts
17. daqstart - Starting programs with logging and monitoring
18. DvdBurner - Using Tcl to burn runs to DVD
19. Utilities for burning data to DVD
20. The Event log program
21. The ringselector application
22. Scaler Display Software.
23. The Scaler Display Client
24. Sequencing runs
24.1. Configuring the sequencer.
24.2. Using the sequencer.
IV. libraries
25. Integer byte order conversion library
25.1. Using the conversion library in your code
25.2. Byte order signatures and conversion blocks
25.3. Data conversion
26. Ring master class library.
27. Networked ring buffer access
28. Ring Buffer Primitives
28.1. Incorporating ring buffer software
28.2. Overview and Examples of ring buffers in action.
29. The Tcl ring package
30. The NSCL Exception class library
30.1. Incorporating the library in your programs
30.2. Exception classes
31. Access control and security
31.1. Incorporting the software into your code
31.2. Authenticators
31.3. Interactors
32. C++ encapsulation of a Tcl API subset
33. NSCL DAQ Thread Library
33.1. The thread and synchronization model
33.2. Incorporating the library into an application.
33.3. Pointers to the reference material
34. Parsing and URIs
35. Format of Event Data In Ring Buffers
35.1. The basic data formats
35.2. Selecting Data From a Ring Buffer
35.3. Incorporating the headers and libraries into your applications.
36. SBS Base interface classes to the VME
36.1. The classes
36.2. Incorporating headers and libraries into your program.
37. Tcl CAENet package
38. The CES CBD 8210 Tcl CAMAC Package
38.1. Incorporating camac into your scripts
38.2. An overview of the use of the camac package
39. The Wienercamac Tcl package
39.1. Incorporating wienercamac in your scripts.
39.2. Using wienercamac
40. SBS VME Module level device support software
V. servers
41. The RingMaster server
41.1. The RingMaster Protocol
42. Service Port Manager.
VI. frameworks
43. The SBS Readout framework
43.1. SBS Readout concepts
43.2. Obtaining and building the skeleton application
43.3. Modifying the skeleton application to meet your needs
43.4. Readout commands
43.5. Embedded Tcl server
43.6. Running a readout application
VII. Reference Pages
I. 1compatibility
compatibilitybuffer -- Filter ring items to spectrodaq buffers
compatibilitylogger -- Create spectrodaq formatted event log files.
eventlog-compat -- Provide event logger pipeline for use with ReadoutGUI.
spectcldaq -- Pipe data source for SpecTcl in spectrodaq buffer mode.
spectcldaq.server -- TCP/IP server of ring data in spectrodaq format.
II. 1daq
ringbuffer -- Manage ring buffers.
ringtostdout -- Transmit data from a ring buffer to stdout.
stdintoring -- Pipe stdin to a ring buffer.
evttclsh -- Tcl interpreter that always runs an event loop
Readout Gui -- Encapsulate data sources in a graphical user interface
dumper -- Produce a formatted dump of event data.
daqstart -- Monitor essential programs
eventlog -- Record Event Data to Disk.
ringselector -- Provide selected ring data to non NSCL DAQ aware clients
sclclient -- Maintain scaler state in a tclserver
tkdumper -- GUI Dump of ring buffer items.
III. 1epics
chanlog -- Write a set of channels to file
controlpush --  Push epics data into a Tcl Server (e.g. production readout).
IV. 1tcl
TCL Ring package. -- Access Rings from tcl.
cesbcnaf -- CAMAC operation via a CES CAMAC interface
wienerbcnaf -- CAMAC operation via a Wiener VC32/CC32 board set
bcnaf -- bcnaf via SBS VME CAMAC interfaces
canev812control -- GUI for controlling CAEN V812 CFD modules
loadcfd -- Load settings in to a CAEN V812 CFD module.
loadshaper -- Load setttings into an N568 shaper via SBS/V288.
n568Control -- GUI for the n568 shaper.
vhqControl -- Control panel application for VHQ bias supply modules.
vhsPanel -- Canned VHS Control panel
SBS Vme Tcl package -- Provide access to VME crates to Tcl scripts.
DaqPortManager -- Manage TCP/IP service ports and advertise their allocations
tclserver -- Start a Tcl Server.
serverauth -- Control tcl server authorization.
dvdburn -- Command line tool to burn NSCLDAQ data DVDs.
burngui -- Graphical front end to dvdburn
ScalerDisplay -- Live Scaler Displays
V. 1sbsReadout
Readout -- Start an event readout program.
VI. 3daq
CopyrrightNotice -- Generate license/author credits.
cvt -- Integer byte order conversions
CRingMaster -- RingMaster access.
CRingAccess -- Remote Ring Access
CRingBuffer -- Low level ring buffer primitives
CException -- Abstract base class for the exception class hierarchy.
CErrnoException -- Exceptions that wrap the Unix errno
CRangeError -- Reports and exception for a value out of allowed range.
CStateException -- Exception for invalid state transitions.
CStreamIOError -- I/O error on a C++ stream.
CURIFormatException -- Report errors in universal resource identifiers (uri)s.
CMonitorException -- Exceptions for synchronization class abuse.
CInvalidArgumentException -- Report invalid function arguments.
CAuthenticator -- Abstract base authenticator class.
CPasswordCheck -- Authenticate against a stored password.
CUnixUserCheck -- Authenticate against a unix user name and password.
CTclAccessListCheck -- Authenticate against a Tcl List.
CAccessListCheck -- Authenticate against a list of allowed credentials.
CHostListCheck -- Authenticate from a list of TCP/IP hosts
CInteractor -- Base class for security interactions.
CStringInteractor -- Provide an interactor that processes strings.
CFdInteractor -- Interact with file descriptor
CIOInteractor -- Separate prompt and input interactors.
CTCLApplication 3 --  Base class for TCL/Tk applications.
CTCLException --  Class for reporting exceptional conditions in Tcl applications via the C++ try/catch mechanism.
CTCLInterpreter --  Encapsulate a Tcl interpreter.
CTCLInterpreterObject 3 --  Base class for objects that are associated with a Tcl Interpreter.
CTCLList --  Provide access to Tcl List parsing.
CTCLObject --  Encapsulate Tcl Dual ported objects.
CTCLObjectProcessor --  Abstract base class to encapsulate the Tcl object command interface exposed by Tcl_CreateObjCommand.
CTCLVariable --  Encapsulate Tcl interpreter variables.
CTCLProcessor --  Provide argc, argv extension commands to Tcl.
CTCLChannel --  Provide a C++ abstraction wrapper for Tcl Channels.
CTCLCommandPackage --  Group several related Tcl command extensions and common services they may require together.
CTCLCompatibiltyProcessor --  Adaptor between CTCLOjbectProcessor and CTCLProcessor.
CTCLFileHandler --  Base class for building object oriented Tcl File event handlers.
CTCLHashTable --  Object oriented interface to Tcl's hash table functions.
CTCLHashTableItem --  Encapsulation of an entry in a Tcl Hash table as encapsulated in CTCLHashTable
CTCLHashTableIterator --  Iterator for visiting all elements of a CTCLHashTable
CTCLIdleProcess --  Allows the establishment of an executable object that can be scheduled to be invoked when the Tcl/Tk intperpreter has no events that require processing.
CTCLPackagedCommand --  Base class for a command that lives in a CTCLCommandPackage
CTCLResult --  Provide an object oriented interace to the Tcl interpreter result.
CTCLString --  Provide a wrapper for the Tcl_DString data type and its API
CTCLTimer --  Abstract base class for C++ objects attached to timer events.
CTCLLiveEventLoop -- Run Tcl with event loop.
CTCLChannelCommander -- Accept commands on a Tcl channel from the event loop.
CTCLStdioCommander -- Event driven command input on stdin/stdout
CTCLServer -- Listener for a Tcl server.
CTCLTcpServerInstance -- Channel commander that is a server instance for CTCLServer
CTCLObjectPackage -- Provide common functionality for a set of related commands.
CTCLPackagedObjectProcessor -- Base class for commands living in a CTCLObjectPackage
CItemConfiguration -- Hold a configuration
CConfigurableObject -- Base class for objects tht have a configuration.
Thread -- Abstract base class for thread objects.
Synchronizable -- Wait queue for threads
SyncGuard -- Provide Critical Regions, Monitors
URL -- Parse Uniform Resource Identifiers (URI)
CRingItem -- Encapsulates an item in a ring buffer.
CRingScalerItem -- Encapsulate ring buffer scaler items.
CRingStateChangeItem -- Encapsulate a ring buffer state change item.
CRingTextItem -- Encapsulate ring items that are lists of text strings.
CRingPhysicsEventCountItem -- Provides statistics regarding the number of events produced.
CRingSelectionPredicate -- Base class for predicates that select items from ring buffers.
CAllButPredicate -- Select all ring items except some.
CDesiredTypesPredicate -- Only accept specified ring item types.
DataFormat.h -- Format of ring items.
CVMEInterface -- Class wrapping of the SBS VME library.
CSBSBit3VmeInterface -- Provide access to SBS/Bit3 driver parameters.
CVME<T> -- Reference counted pointer like object to VME address segments.
CVMEModule -- Provide a base set of services for a VME module driver class.
CMmapError -- Report errors in memory mapping requests.
CADC2530 -- Support the Hytec NADC 2530 Peak sensing ADC.
CAENcard -- Support for the CAEN 32 bit digitizers
CBD8210 -- CES CBD 8210 CAMAC branch highway driver (obsolete)
CCAENV1x90 -- Support for the CAEN V1190 and V1290 multihit, complicated TDC.
CCAENV560 -- Support the CCAENV560 non-latching scaler.
CCAENV830 -- Support driver for the CAEN V820/V830 latching scaler module.
CCAENV977 -- Software support for the CAEN V977 I/O register.
CCAMACScalerLRS2551 -- Support software for the LeCroy LRS 2551 12 channel CAMAC scaler
CCAMACScalerLRS4434 -- High level support software for the 32 channel LeCroy LRS 4434 CAMAC scaler module
CCAMACStatusModule -- Provide computer busy status support for the BiRA CAMAC NIM out module.
CCAMACTrigger -- Trigger module for the CES CBD 8210 VME CAMAC Parallel Branch Highway Driver
CCamac -- Manages CAMAC memory maps.
CCamacModule -- Provide support for a generic CAMAC module.
CCamacNimout -- Provides low level support for the BiRa CAMAC Nim output module.
CCrateController -- Encapsulation of a BiRa 1302 CAMAC controller via CES CBS8210.
CSIS3600 -- Support for the SIS 3600 VME latch module.
CSIS3820 -- Low level support for SIS 3820 32 channel latching scaler module
CScaler -- Abstract base class for reading scalers into a vector
CStatusModule -- Abstract base class for status modules.
CTrigger -- Abstract base class for triggers
CVME -- Pointer like object for accessing the VME
CVMEScalerLRS1151 -- High level support for the LeCroy LRS 1151 VME scaler.
CVMEStatusModule -- Implement a status module using the CAEN V262 module.
CVMETrigger -- VME trigger class based on the CAEN V262 I/O module.
CVMEptr -- 
CaenIO -- Support for the CAEN V262 I/O register module.
CMmapError -- Exception that can be thrown in the event of memory mapping errors.
CNimout -- Low level support for the BiRa VME nim output module
CVmeModule -- Convenience base class for implementing VME module support
CSIS3300 -- Low Level support for the SIS 3300 Flash ADC module
CPortManager -- Provide a C++ interface to the server port manager daemon.
CPortManagerException -- Report errors conditions in port manager transactions
VII. 3ccusb
addtcldriver -- Register Tcl command ensemble as a device module
ad811 -- Support the Ortec AD811 ADC
c1205 -- Manage CAEN C1205 QDC modules.
c257 -- Manages the C257 scaler module
lrs2228 -- Manages the LRS2228 TDC
lrs2249 -- Manage LeCroy 2249 QDC modules
lrs2551 -- Manage LRS 2551 modules
ph7xxx -- Define Phillips ADC/TDC/QDC modules
stack -- Create and configure CC-USB stacks.
Module -- Create and manipulate slow control device instances
Slow controls protocol -- TCP/IP slow control protocol
CCCUSB -- Provide access to a CC-USB device.
CCCUSBReadoutList -- Create lists of CAMAC commands for CC-USB controllers.
CConfigurableObject -- base class for devices that have a configuration
cccusb -- Swig wrapping of the CCCUSB C++ class.
cccusbreadoutlist -- Tcl wrapping of CCCUSBReadoutList
VIII. 3tcl
caennet -- Access CAENnet from Tcl scripts.
camac -- Provide access to CES CBD8210 CAMAC to Tcl scripts
wienercamac -- Tcl Script CAMAC access via VC32/CC32 boardset.
CFD812 -- low level control of the CAEN V812 CFD
caenv812gui -- Megawidget control panel for the CAEN V812 CFD
n568b -- Support package for the CAEN N568B shaper.
n568Panel -- Control panel megawidget for N568 shaping amplifier
vhq -- Low level Tcl access to iSEG VHQ2xxx units.
vhqPanel -- Control widget for iSeg vhq2xx VME bias supply.
iSegVhs -- SBS support for VHS 404 modules.
VhsWidgets -- User interface components for VHS 404 power supplies.
portAllocator -- Tcl API for the DaqPortManager daemon.
DvdBurner -- Burn NSCL Data to DVD
sequencer --  Provide a ReadoutGui plugin for nscldaq 8.1 and later that can automate several data taking runs.
IX. 3sbsReadout
CBusy -- Abstract base class for Busy module management.
CCAENV262Busy -- Concrete busy class for the CAEN V262 input module.
CCAENV262Triger -- Trigger module with CAEN V262
CCompoundEventSegment -- Container for other event segments
CDocumentedPacket -- Encapsulate event data in a packet that is documented.
CEventPacket -- Encapsulate an event segment in a documented packet.
CEventSegment -- Base class for all event segments.
CEventTrigger -- Abstract base class for triggers.
CExperiment -- Encapsulate the experiment.
CInvalidPacketStateException -- Exception thrown by documented packets.
CNullTrigger -- A trigger that never fires.
CReadoutException -- Base class for readout specific exceptions
CScalerBank -- Container for individual Scaler objects.
CTimedTrigger -- CEventTrigger that fires periodically
CV977Busy -- Concrete busy class using the CAEN V977 module
CV977Trigger -- Concrete Trigger class using CAEN V977 module.
RunState -- Encapsulate important state of the software.
CScaler -- Base class for scaler readout classes
X. 5tcl
caen812configfile -- Format of configuration files for CAENV 812 software.
n568configfile -- N568 shaper configuration file
vhqconfig --  Config file for
List of Tables
6-1. Data Acquisition configuration parameters
6-2. Directory root configuration parameters
6-3. State Parameters
39-1. Wiener CC32 addressing convention
List of Figures
6-1. Readout GUI Directory tree
List of Examples
2-1. Adding ringbuffer's directory to bash's search path:
2-2. Adding command paths to csh
5-1. Appending the NSCLDAQ Tcl Package repository to Tcl's search path
5-2. Appending NSLCDAQ's TclPackage repository to Tcl's search path
5-3. Requesting the VME Tcl package be loaded.
5-4. Using VME Tcl to locate all 2530 modules
6-1. ReadoutCallouts.tcl sample extension
13-1. Using serverauth to authorize a node
14-1. Creating and configuring devices
14-2. Configuring an event stack
14-3. Setting up a scaler stack
14-4. Obtaining the ccusb driver development kit
14-5. Using a user written CCUSB driver
14-6. A snit CCUSB device driver module
14-7. CCUSB device support example writtin in Incr Tcl
14-8. DAQ config script fragment with tcl drivers.
15-1. Dumping data from the ring buffer named 0400x on spdaq22
15-2. Dumping data from the event file segment /user/0400x/complete/run-1234-00.evt
15-3. State Transition items
15-4. Text List items
15-5. Incremental Scalers dump
15-6. Event count items
15-7. Physics Event items
15-8. Unknown item types
16-1. Converting a ring buffer event file with compatibilitybuffer
16-2. Converting ring buffer data to a 8Kword (16Kbyte) old style event file
16-3. Using compatibilitylogger to convert event files
16-4. Attaching SpecTcl to ring buffers in compatibility mode
17-1. Logging errors and informing on exit
18-1. Requesting the DvdBurner package
18-2. Writing runs to DVD using DvdBurner
18-3. Writing all runs to DVD
20-1. Taking data from a remote ring
21-1. Dumping state changes and sampled event data with od
21-2. Dumping all but packet types
21-3. Attaching SpecTcl
24-1. Loading the sequencer package
25-1. Including the cvt header
25-2. Compiling a C or C++ source file that includes cvt.h
25-3. A makefile rule that builds a C++ program using the cvt package
25-4. Creating a DaqConversion
26-1. Including the header
26-2. Compiling code
26-3. Linking code to the library
27-1. A sample ring specification in URI form
27-2. Substituting local host for the hostname in URI's
27-3. Including the header
27-4. Compiling code that uses CRingAccess
27-5. Linking code that uses CRingAccess
28-1. Compilation line for ring buffer primitives
28-2. Including the ring buffer primitives header
28-3. Linking to the ring buffer primitives
28-4. Sample ring buffer consumer
28-5. A sample Ring Buffer producer program
29-1. Incorporating the ring package in your scripts
30-1. Catching CException and exiting
31-1. Compilation switches for the security includes
31-2. Link switches for the security library
31-3. Boilerplate DAQ Authorization code
33-1. The life of a thread
33-2. Why synchonization is needed
33-3. Using SyncGuard to implement a monitor
33-4. Compiling and linking NSCLDAQ threaded software
34-1. Sample URI library program
34-2. Building urltst.cpp
35-1. Including a ring item class
35-2. Telling the compiler where to find Ring Item headers
35-3. Linking the ring item format libraries
39-1. Enabling a module Lam with wienercamac
41-1. The CONNECT message format
41-2. Format of the DISCONNECT message
41-3. Format of the LIST command
41-4. Format of the REGISTER command
41-5. Format of the UNREGISTER message
41-6. Format of the REMOTE message
43-1. Obtaining the SBS readout skeleton
1. Attaching SpecTcl to a ring buffer in compatibility mode
1. Running spectcldaq.server
2. Connecting to spectcldaq.server
1. Sample output from ringbuffer status
1. making hex dumps of data from a ring buffer.
1. Using stdintoring
1. Logging extension to readout gui
1. Dumping state changes and sampled event data with od
2. Dumping all but packet types
3. Attaching SpecTcl
1. Starting sclclient
1. Viewing a set of channel values interactively
2. Writing a set of channels to a file
3. Appending a set of channels to a file
4. Piping a set of channels to a program for processing
1. Creating a coypright notice on stderr
2. Creating an author credit on stderr
1. Using CRingAccess to connect to a local ring.
2. Using CRingAccess to connect to a remote ring
1. Message filter predicate
1. Calling CStringInteractor specific members
1. evttclsh
1. Selecting sampled event from a ring.
1. Constructing a scaler item from an item gotten from a ring
1. Creating a begin run state transition item
1. Creating a CAENcard geographically
2. Setting a TDC to common stop mode
3. Reading out a CAEN 785 e.g.
1. Initializing branch 0
1. Using the LRS 1151 in the production readout framework.
1. Creating a device driver via private derivation
2. Creating a device driver via inclusion
1. Allocating a port with the port manager
2. Listing the port allocatiosn on a system.
1. Catching a CPortManagerException
1. AD811 configuration file example
1. LRS2228 creation example
1. The lrs2551 command
1. Using the list command to construct pedestals
2. Sample ph7xxx commands
1. Example of the stack command.
1. Listing CC-USB Serial numbers (Tcl).
2. Creating a CCCUSB object by serial number (Tcl).
1. Hooking update methods to recurring timer
1. Allocating a service port in Tcl
2. Listing allocated ports in Tcl
1. Action script example
2. Sequencer column configuration file
1. Creating and registering a V262 as a busy:
1. Deep iteration of CCompondEventSegment elements
2. Deep visitation of CCompoundEventSegment elements
1. Using the CDocumentedPacket class
1. Catching readout specific examples
1. Deep visitation in CScalerBank containers
1. Outputting the state of the run
1. Sample configuration file
1. Sample configuration file
1. Sample configuration file