Project

General

Profile

User guide to running the DAQ

Setting the environment

At every new login, the environment script must be sourced:

source gm2trackerdaq/software/setup.sh

This script grabs information from a dedicated environment file for your host. See here for more information.

Building the code

Below is an overview of the main software build targets:

  • make all (or just make)
    • Finds dependencies and builds everything
    • Must be used for the first build of a clean git clone, or if files are added,removed or renamed
    • Best to always use this after a new git pull
  • make fast
    • Much faster than make all, but does not build the dependencies list so if files have a been added/removed then you will have problems
  • make clean
    • Cleans out all compiled libraries, objects and executables
    • Must do make all after this

These are contained in cd $GM2_TRACKER_DAQ_SRC/Makefile. The targets must be run from this directory, e.g.

cd $GM2TRACKERDAQ_DIR/software
make

DAQ system overview

The g-2 DAQ system is MIDAS. Within this framework we write frontends for controlling our hardware. The system we have is:

  • mhttpd - the MIDAS web interface (the thing the user interacts with)
  • mserver - the MIDAS server (the thing doing most the the work)
  • MasterGM2 - a master trigger for the other frontends (slaves)
  • EB - an event builder for collecting data fragments from all frontends into a single event
  • mlogger - writes data from MIDAS (from the EB) to a file (.mid/.mid.gz)
  • StrawTrackerDAQ - the frontend controller the tracker DAQ system (one frontend controls all 3 trackers)
  • LVandSC - a frontend that periodically writes slow control data relating to the tracker readout boards and LV system to a database (one frontend per LV create, e.g. per tracker)
  • StrawTrackerHV - a frontend that periodically writes slow control data relating to the tracker HV system to a database

A DAQ system such as this built from MIDAS is referred to as a MIDAS experiment.

A script called midas-tool.sh is provided to helping with many common tasks.

Creating a new MIDAS experiment

To create a new MIDAS experiment (e.g. when setting up a new test bench), follow these instructions (assumes you have already followed the installation guide.

midas-tool.sh init                     #Initialise the experiment
odbedit -c "load <some example ODB>"   #Load clean ODB
midas-tool.sh run_reset                #Reset MIDAS run number after load
init-equipment.sh                      #Init all equipment according to your system (file paths, etc)
midas-tool.sh start                    #Start MIDAS experiment

Once MIDAS is running you should not need to restart it unless a major problem occurs. If required, restart MIDAS using:

midas-tool.sh restart

Running the MIDAS DAQ

The user interacts with the MIDAS experiment via the mhttpd web interface. View this from a web browser such as firefox):

firefox $MIDAS_HOST:$MHTTP_PORT &

If you cannot see this page, check that an mhttpd process is running on this machine and that you are running your browser from a location that has access to the web server (you may need to use a proxy).

ODB

MIDAS stores run time parameters in an Online Data Base (ODB). View this by pressing the "ODB" button on the MIDAS web interface.

There are many different variables here, but of most interest is the "Equipment" directory. In this is a directory for each frontend in your system. Each has a few subdirectories, with "Common" and "Settings" being the only two most people need to use.

To dump a copy of the ODB (for example to share it with someone else, or so it can be saved to the git repository):

odbedit -c "save <path/name>.odb" 

To load a dump back into the ODB:

odbedit -c "load <path/name>.odb" 

Important ODB parameters

  • StrawTrackerDAQ/Settings/Globals/Trigger source
    • Defines where the DAQ expects its triggers to come from
    • Set to Periodic to self-trigger periodically, and set the period in StrawTrackerDAQ/Settings/Globals/Trigger period clocks (unit is 25ns clock ticks)
    • Set to Hardware to trigger asynchronously from an external source (for example the CCC system)

Programs

View all programs in your experiment by pressing the "Program" button on the MIDAS web interface. This page will show you a list of available programs (e.g. the executables for your frontends etc).

If a program is running it will appear in green, otherwise it will be red (it may be orange whilst starting up). Start/stop a program by clicking the "start"/"stop" button next to its name.

In general the order programs are started/stopped in does not matter. The one exception is the StrawTrackerDAQ and LVandSC01,02,03 frontends. StrawTrackerDAQ must be started after the LVandSC frontends and stopped before them. This is because both share a single resource (the USB line to the LV controller board), and they uses an owner (LVandSC) - user (StrawTrackerDAQ) model to ensure they don't interfere with each other.

Most of these programs are started in a screen. Type the following in the terminal to view all screens currently running:

screen -ls

The console output of a program/frontend will appear in its screen. To connect to a screen:

screen -r <name>

To exit a screen, type <ctrl>+a, then d.

Taking a run

First, make sure you have started all programs that you want to use in the run. If you do not want to use a given frontend, make sure to change the ODB variable Equipment/<name>/Common/Enabled to "n", otherwise the event builder will expect data from it and throw an error when it does not see any.

Then click the "Status" button in MIDAS to go the main status screen. Check all frontends you want to run are green. Then start a run by clicking the "Start" button. You may have to fill in a few fields (leave the run number as it is), then click OK.

It may take around a minute or more to start a run, as the frontends are configuring the boards via the USB lines which takes a bit of time.

Once the run has started, the box around the "Start" button will go green. If it does not, it probably means a frontend crashed during run start. Click the "Messages" button and check for errors.

Stop the run using the "Stop" button that replaces the "Start" button once the run has started.

Data from the run

After the run has stopped, there will be a file containing data from the run. The directory the data is written to will be displayed near the top right of the "Status" page.

The files themselves are binary and have the extension .mid, or .mid.gz if compression is used.

You can dump the contents of the file using:

mdump -f x -x <file>

This output may be very large, so it is common to pipe the output into something like "less", e.g.

mdump -f x -x <file> | less

This is only used to sanity check the data has been written. In general we look at data either using the DQM (online) or using art (offline).

Important configuration files

In addition to the ODB, there are a number of configuration files used by the DAQ. These are located in:

source gm2trackerdaq/software/cfg

Environment files

Each machine that the DAQ is being run on needs a dedicated environment file describing the system. See here for details.

IPBus XML files

IPbus is a protocol for communicating with our boards, and allows register R/W via the ethernet network.

The connections.xml file specifies each IPbus device in the system, including the IP address, connection protocol, and the address table.

Each device has an address table XML file which defines the public registers of that device. The hierarchical names of these registers can be used during register W/R.

Python scripts

The core tracker DAQ code that the StrawTrackerDAQ MIDAS frontend uses also has python bindings. This allows python scripts to be written for specific tests/tools. Some specific examples are listed below.

These scripts reside in:

$GM2TRACKERDAQ_DIR/software/tests

Some of these scripts have many command line options that are not all listed here. Use the following to see all options along with descriptions:

python <script> -h

DAQ config XML files

The python scripts do not directly read from the MIDAS ODB. Instead, they parse XML dumps of the "Equipment/StrawTrackerDAQ/Settings" directory. To create this dump:

midas-tool.sh dump_straw_settings

You can then view and edit this file, which is pointed to by the DAQ_CONFIG_FILE environment variable.

If you want to write the change you made to your DAQ config XML file to the ODB:

midas-tool.sh load_straw_settings

Send triggers and read back the events

The following script configures the DAQ system, then sends triggers and reads back (and unpacks if desired) the resulting events.

python $GM2TRACKERDAQ_DIR/software/test/SendTriggerAndReadEvent.py [-u] [-dr] [-n <num triggers>]

The -u argument unpacks the event and dumps it to screen. The -dr argument dumps the raw data to screen.

There are a number of other command line arguments for more detailed debugging tasks (such as dumping boards registers or RAM contents before/after triggers), use -h to see them all.

This is one of the most useful scripts for checking the system is working.

Count events

The following script is used to test that all boards are returning data, and that no errors are observed. It is used as a unit test of the system, and should be run each time firmware, hardware or software is changed.

python $GM2TRACKERDAQ_DIR/software/test/EventCounter.py [-nt <num cycles>] [-nt <num triggers per cycle>]

A "cycle" means "configuring the DAQ and sending some triggers", so importantly the DAQ is reconfigured fresh at the start of each cycle.

Noise scan

This script loops through all channels in the straw system (e.g. all straws) and disables all others, then cycles through a range of ASDQ discriminator thresholds and sends a trigger to see how many hits are returned. It is used to evaluate the noise level in each straw as a functions of discriminator threshold.

python $GM2TRACKERDAQ_DIR/software/test/NoiseScan.py [-lb <logic board ID>]

<logic board ID> is the hierarchical ID of a a given logic board, e.g. "AMC13-0/FC7-1/LB-3".

Plot the results using:

python $GM2TRACKERDAQ_DIR/software/test/plotNoiseScanResults.py [-lb <logic board ID>]

Configure the DAQ system

The following script configures the DAQ system:

python $GM2TRACKERDAQ_DIR/software/test/SetupDAQ.py

In practise this is rarely used, as all the other scripts configure the DAQ before they do anything else.

Run the straw DAQ state machine

Launch a GUI with buttons for each DAQ command:

python $GM2TRACKERDAQ_DIR/software/test/StrawDAQGUI.py

Run the straw DAQ for N seconds:

python $GM2TRACKERDAQ_DIR/software/test/StrawDAQRun.py run -d <num seconds>

Start the straw DAQ in listen mode (useful for emulators)

python $GM2TRACKERDAQ_DIR/software/test/StrawDAQRun.py listen

These two scripts don't do anything with the data, but can be useful for debugging.

GUI for IPbus devices

The following script launches a GUI that displays the values of all IPbus registers for a device.

python $GM2TRACKERDAQ_DIR/software/test/IPBusDeviceGUI.py -d <device ID> [p <polling period ms>]

<device ID> is the ID of the device in the connections.xml file.

There is a list box for defining whether values are printing in decimal, hex or binary.

If a register is writable, double click on its value and an input box will appear. Write a new value here and it will be written to the board.

If the device has many registers (e.g. the AMC13), use -p to define a large polling period (e.g. 5000ms) or the GUI will become unresponsive.

R/W script for IPbus registers

Can also read/write to a specific IPbus register from the command line:

Read:

python $GM2TRACKERDAQ_DIR/software/test/IPBusDeviceRW.py -d <device ID> -n <node> read 

Write:

python $GM2TRACKERDAQ_DIR/software/test/IPBusDeviceRW.py -d <device ID> -n <node> write -v <value(s)> 

There are quite a few additional arguments for handling register block, offsets, etc, so use -h for more info.

Troubleshooting

"No such file or directory: /tmp/<user>/uhal" at run time

IPbus needs this directory to exist at run time. If get this error, make the directory manually ("mkdir -p /tmp/<user>/uhal") then run again.

Logger ERROR [add_event,ERROR] Invalid tag

This is to do with the MIDAS history function trying to find variables that don't exist. To solve this just turn off the history for that frontend - set /Equipment/FE_NAME/Common/Log History to 0. This can be turned on at a later date when the variables exist or are adjusted as necessary. Although as it stands we don't use the history function.