mesytec data parsing library & GANIL acquisition interface

Website and class reference documentation: https://mesytec-ganil.pages.in2p3.fr/mesytec_data/

This package provides the shared library

libmesytec_data.so

for analysing Mesytec data.

It can also provide the executable application

mesytec_receiver_mfm_transmitter

which encapsulates data received from the Mesytec acquisition application mvme into GANIL MFM metaframe format data (with frame type 0x4ADF) which are published on a ZeroMQ port: see below for more details.

The shared library

libzmq_narval_receiver.so

defines a Narval actor which can receive data from a ZeroMQ port and inject it into the Narval dataflow (this can be used with any type of data, not only Mesytec. The actor simply copies the incoming buffer to its output buffer).

It can also provide the

libmesytec_data_root_interface.so

library if ROOT is found on the system, which can be used to automatically convert Mesytec data to the TTree format.

Prerequisites

To build <tt>mesytec_receiver_mfm_transmitter</tt>:

Configure the build with CMake option -DENABLE_RECEIVER_TRANSMITTER=ON

ZeroMQ [optional]

Required to build mesytec_receiver_mfm_transmitter and libzmq_narval_receiver.so.

If installed from Ubuntu/Debian packages, make sure to install the dev package.

If you have more than one version on your system in different places, you can specify the path to use when configuring the build by setting either ZeroMQ_DIR or ZeroMQ_ROOT CMake variable with the path to use (see below).

Build and install

$ mkdir build
$ cd build
$ cmake [source_dir] -DCMAKE_INSTALL_PREFIX=[install_dir] -DCMAKE_BUILD_TYPE=[Release|RelWithDebInfo|Debug]
$ make -j[ncpu] install

replacing [source_dir], [install_dir] and [ncpu] with appropriate values

The CMAKE_BUILD_TYPE determines the amount of optimisation of code: for production versions, use Release or RelWithDebInfo for the fastest execution.

To build mesytec_receiver_mfm_transmitter add option -DENABLE_RECEIVER_TRANSMITTER=ON.

If required, add -DZeroMQ_DIR=[path] or -DZeroMQ_ROOT=[path] to use a specific installation of ZeroMQ.

Define VME configuration

Parsing data requires a file containing the definitions of modules in the VME crate, and optionally a file with a correspondence between each bus/channel and detector.

Example crate_map.dat

MDPP_0,0x20,16,SCP
MDDP_1,0x1,32,MDPP_QDC
MMR_1,0x10,8,VMMR
Free_Trigs,0x0a,32,MVLC_SCALAR

Each line has the format: name, crate-address, number_channels, firmware

crate-address is the HW address of the module: remember that Mesytec data only uses the top two nibbles of these addresses, therefore make sure all modules have addresses such as 0xXY, not 0x0XY or 0x00XY.

number_channels is the number of channels (16 or 32) for MDPP modules, number of buses for VMMR (each bus is assumed to have 128 subaddresses).

firmware can be: (note that only MDPP modules can have different firmwares; for other modules the 'firmware' is used to define the type of the module - KLUDGE!)

for MDPP: SCP, QDC, CSI, MDPP_QDC, MDPP_SCP, MDPP_CSI
for MTDC: MTDC
for VMMR: VMMR
for MVLC: MVLC_SCALAR

Example detector_correspondence.dat

0x10,2,1,PISTA_DE_2_1
0x10,0,64,PISTA_DE_0_64
0x20,0,PISTA_E_0
0x20,4,PISTA_E_4
0x20,5,PISTA_E_5

Each line has the format: crate-address, channel_number, name (MDPP modules) or crate-address, bus_number, channel_number, name (VMMR modules)

Data analysis

Buffers of data can be parsed with class mesytec::buffer_reader. See example_analysis.cpp.

GANIL Acquisition Interface

Using timestamps from CENTRUM/BEAST/GTS modules

In order to correlate data with other DAQ systems at GANIL, we add timestamps to each Mesytec data frame which can be retrieved from one of 2 modules placed in the same VME crate:

TGV module (with either CENTRUM or BEAST timestamp provider);
AGAVA module (with GTS timestamp provider)

The appropriate module should be added to the crate_map.dat file:

TGV,0xFF,16,TGV

AGAVA,0x17,32,AGAVA

Only the 'firmware' (TGV or AGAVA) and the crate address are important here. Note that the crate address need not be the physical address of the module, rather it must correspond to the one used in the mvme interface when data from the module is read out.

MFM encapsulation

Run the mesytec_receiver_mfm_transmitter executable with suitable arguments in order to encapsulate data received by ZMQ from the mesytec mvme software into MFM frames which are in turn published on a ZMQ PUB socket:

$ mesytec_receiver_mfm_transmitter
 
Usage:
  --help                         produce this message
  -c [ --config_dir ] arg        directory with crate_map.dat and 
                                 mvlc_crateconfig.yaml files
  -h [ --mvme_host ] arg         url of host where mvme-zmq is runnning
  -p [ --mvme_port ] arg (=5575) [option] port number of mvme-zmq host
  -z [ --zmq_port ] arg (=9097)  [option] port on which to publish MFM data
  -b [ --buffer_size ] arg (=64) [option] buffer size to use (in kilobytes)
  -t [ --timeout ] arg (=1000)   [option] timeout for buffer flush (in 
                                 milliseconds)
  --debug                        [option] enable debug output
  --trace                        [option] enable trace output

You must give at least the path to the files describing the setup, and the URL of the machine running the Mesytec mvme DAQ software. For the other (optional) arguments:

--mvme_port, -p : in case mvme is not running its Zmq transmitter on the default port, 5575;
--zmq_port, -z : change the default port used to publish the MFMMesytecFrame data produced;
--buffer_size, -b : adapt size of buffers used to transmit encapsulated data to keep buffer emission rate not too high (<<1000 buffers/sec.);
--timeout, -t : change time after which, if no further data is received from mvme, the current buffer of MFMMesytecFrame data will be transmitted;

Narval receiver

libzmq_narval_receiver.so is a Narval actor which can receive the MFM frames produced by mesytec_receiver_mfm_transmitter in order to inject them into a Narval dataflow. Give the specification of the ZMQ port (tcp://hostname:port) in the algo_path option of the actor.

Use by other projects (CMake)

For other projects to use us we provide two targets in the mesytec_data:: namespace:

mesytec_data::mesytec_data: compile and link with libmesytec_data.so;
mesytec_data::mesytec_data_root_interface: compile and link with the ROOT/TTree interface

You can build and link your own projects which use either libmesytec_data.so or libmesytec_data_root_interface.so by adding to your CMakeLists.txt the following:

find_package(mesytec_data [optional:minimum version] [REQUIRED|QUIET])
 
# executable using libmesytec_data.so
add_executable(MyApp my_code.cpp)
target_link_libraries(MyApp PRIVATE mesytec_data::mesytec_data)
 
# shared lib using libmesytec_data_root_interface.so
add_library(MyLib SHARED my_class1.cpp my_class2.cpp)
target_link_libraries(MyLib PUBLIC mesytec_data::mesytec_data_root_interface)