Author: Henrique Vieira de Souza, APC – Paris
[email protected]
This documents servers do clarify and help the data acquisition with CAEN digitizers. All the software, drivers and manuals are available at caen.it.
The acquisition is done with Wavedump, a free software distributed by CAEN. The versions modified by me have two minor implementations: (1) continuous writing will save only 10,000 waveforms and stop and (2) one can change the number of points per waveform saved, this decreases the sampling rate from 2 ns to 4 ns, for example, by skipping one point (only works for binary files for now).
Please, keep in mind that the implementation (2) will not reduce the acquisition rate of the digitizer, just of the saved waveforms.
If you search “Added by Henrique Souza” in the WaveDump.c file, you will find all the modifications made by me.
Wavedump saved data in a file named wave0.dat when saving as BINARY (or wave0.txt when saving as ASCII). I am assuming you have wisely chosen binary as format.
wave0.dat refers to the waveforms of channel 0, while wave1.dat refers to channel 1.
If you want to save several .dat data files you need to move these waveX.dat files to another folder before saving new ones. As this task can be very tedious, I’ve created a GUI with QtCreator to transfer the files and menage data taking more efficiently. The GUI is not mandatory, it should just make your life easier!
The installation script will install “cmake” and “build-essentials” and the software “gnuplot”.
Please, if you find any bug, miss information or some nasty mistake, feel free to talk to me by email.
- Introduction
- Wavedump
- QtCreator GUI
- Extra: Creating a shortcut for Wavedump
- Extra: recompiling wavedump
- Extra: File structure
- Extra: Common variables
- FAQ
Clone this repository inside the “Documents” folder:
cd ~/Documents
git clone https://github.com/hvsouza/CAEN_Control.git
cd CAEN_ControlTo install the digitizer drivers and wavedump there are a few requirements and steps. I invite the user to read the manual of the digitizer and wavedump and also to search about the installation.
The script caen_installation.sh will install the required software and drivers and applied the changes to customize to the version created by me. As this is done in a single step, there will be a 3 seconds pause between each installation so you can check for errors output. If you see any, please, try to fix it before installing everything.
NOTE: you need to disable “Secure Boot” at the BIOS.
./caen_installation.shYou need to specify the digitizer sampling rate and the sampling rate you want. You can only change by a factor of 2:
If the digitizer has a sampling of 500 MSamples/s, you can change it to 250 MS/s, 125 MS/s or 62.5 MS/s.
If you are installing for the first time, you probably need to restart the computer.
If the digitizer is connected and installation was successfully, open a terminal and just type “wavedump”, it should show you something like this output:
Wavedump cannot run if there is no ADC connected, but wavedump was successfully installed if you see the following message:
**************************************************************
Wave Dump 3.10.3
**************************************************************
Opening Configuration File /etc/wavedump/WaveDumpConfig.txt
Can't open the digitizer
If wavedump failed to start, try to reboot the digitizer.
The script has also created the folder: ~/Desktop/WaveDumpData. To use the GUI, you need to execute wavedump while inside that folder, so wavedump will save the data there.
You can create a shortcut to execute Wavedump inside the correct folder, you can find instructions at #extra-creating-a-shortcut-for-wavedump
If you want to enable the option to decrease wavedump writing sample rate or to change the number of waveforms saved each time, please look at #extra-recompiling wavedump.
Please, refer to the wavedump manual to better understand the acquisition configuration.
The configuration file of wavedump is located at /etc/wavedump/WaveDumpConfig.txt.
The current important parameters to take care are reported at #extra-common-variables.
You can configure wavedump using the GUI instead (see #using-the-gui)
Using wavedump is quite simple, just type wavedump at the terminal. By pressing [SPACE] the help menu is printed as bellow. Please keep in mind that [T] means “shift + t key”, for instance.
The commands you will use most are:
- [R]
- [s]
- [w] (repeating this will overwrite the file with only one waveform)
- [W] (After the 10,000 events you can press it again to save 10,000 more and so on)
- [P] also [p]
- [T] also [t]
- [k] Make wavedump ask again the number of waveforms (added by author)
Please, take a time to understand the acquisition by playing around and making some plots before moving forward.
- Make sure you memorize the shortcuts.
- Learn how to control the graphs at gnuplot
(to check the gnuplot keybindings, open a terminal, execute
gnuplot, typeshow bindand press enter).
When pressing [W], wavedump will ask you the amount of waveforms to be saved. If you want to keep this as default during this sessions, press y to the next question. If you want to change it at any point, press k. If you choose to save 10,000 waveforms in the .dat files, when it finishes, you should see this in your screen:
When you press [P] for continuous plot, what can happen is that gnuplot window will keep in your way (that is very annoying!). One way to stop this is to make sure that the plot is not over the windows you are trying to use, for example the terminal. If the two windows are not overlapping you should be able to use it normally. Another way is to enable “Prevent windows which require attention from stealing focus” (search this configuration for your Linux distribution).
For the acquisition and in order to properly use the GUI, you should do the following during the acquisition:
Assuming you have [s] already running, user’s chosen setup done and triggering events.
- [W] save 10,000 (if you want to save 10,000 more, press [W] again at the end).
- Move the .dat files by yourself or with GUI (see #using-the-gui)
For acquire more data, repeat this.
If you want to understand the binary file structure, please check #extra-file-structure.
NOTE: if you are using the standard version of wavedump, when you move the file it is kept open, so if you press [w] one more time after the continuous read, it will save one extra waveform and close the file.
NOTE: to keep continuous writing indefinitely, when asked the number of waveforms to be saved insert-1.
Some times, the digitizer will not be recognized by the computer (this usually happens after using different digitizers, usb devices or cables). One way to fix it:
Disconnect the digitizer, turn it off
cd ~/Documents/ CAEN_Control
./fix_usb.shConnect the digitizer and turn it on. Cross your fingers and try again.
If the USB is still failling to connect, check if the CAEN Digitizer is being recognized by the system: lsusb, which should result in some lines and one should look like this:
Bus 003 Device 010: ID 21e1:0000 CAEN CAEN DT5xxx USB 1.0
If the output is like this and wavedump is still not recognizing the ADC. Check the file at /dev/usb/ folder:
ls /dev/usb/If there is a file named V1718_X, you should set the USB port at the config file #extra-common-variables:
OPEN USB X 0
A reported problem at Debian was the following error when trying to install the usb driver:
Installing CAENUSB make -C /lib/modules/5.10.0-18-amd64/build M=/home/user/Documents/CAEN_Control/Installation/PreInstallThis/CAENUSBdrvB-1.5.4 LDDINCDIR=/home/user/Documents/CAEN_Control/Installation/PreInstallThis/CAENUSBdrvB-1.5.4/../include modules make[1]: * /lib/modules/5.10.0-18-amd64/build: No such file or directory. Stop. make: * [Makefile:36: default] Error 2 cp: cannot stat 'CAENUSBdrvB.ko': No such file or directory make: * [Makefile:43: install] Error 1
This solved the problem:
sudo apt install linux-headers-$(uname -r)
Since October 2022, the GUI is now made in python3, to use it you need to install Qt5 libraries:
python3 -m pip install pyqt5
NOTE: you might need to update your pip:
pip install --user --upgrade pip
To check if the GUI is working, you can type:
python3 ~/Documents/CAEN_Control/pythonQt/move_files.py &
The & lets your terminal free in case you want to use it.
During data taking, with the terminal open at ~/Desktop/WaveDumpData/ you can execute the GUI by calling:
./move_files.sh
The GUI is just an interface to automatically move files from the WaveDumpData folder to another folder. It will keep a track of run and subrun number for you, renaming it with a standard.
Default Acquisition
- “Run” is the run number
- “subrun” is the subrun number
- “Block1” is a block of text to compose the name of folder and files (separated by underline, not spaces)
- “Block2” is a second block of text in case you want to keep block1 fixed and change only block2.
- “Extra info” is any extra information that will be written at the end of the files (not folders), see bellow.
In example above, the named will be composed by the two blocks as block1_block2 (you can use only one of the two blocks if desired, just leave it as blank). The option “Extra info” keeps the same functionality. In the example above folders and files would be named as:
In the example from the image above, the GUI will create a folder named new_data at ~/Documents/ADC_data/BLEND_data (the lock option is just to not change the name by mistake, you don’t need to lock it).
After taking data with two channels, for example, you should have “wave0.dat” and “wave1.dat” at WaveDumpData.
When pressing “Move files”, a folder named “run0_two_different_blocks_of_text” will be created (note: “extra info” will not be placed in the name of the folder), inside the folder “new_data” and the two files will be moved there as:
(Placing the mouse over “Move_files” will show a tooltip with the name of the folder in which the files are going to be transfer)
0_wave0_two_different_blocks_of_text.dat 0_wave1_two_different_blocks_of_text.dat
(note: if you have written “some_comments” at the “Extra info” field, the name of the file would be “0_wave0_42V30_20ADC_Ch0_some_comments .dat)
(note: the GUI will only transfer the data of the enabled channels configured at “Config.”, see #config)
In the GUI, the subrun number should have been changed from 0 to 1. If you take another set of data and click “Move files” again, you should have now four files in total named as:
0_wave0_two_different_blocks_of_text.dat 0_wave1_two_different_blocks_of_text.dat 1_wave0_two_different_blocks_of_text.dat 1_wave1_two_different_blocks_of_text.dat
And subrun should be equal 2 on the GUI.
Whenever you are finished with this run (lets say, changing SiPM bias, threshold or just because you want a different run in which you will give details on a README file later), you click “Finish run”.
This should put subrun back to 0 and Run now will be equal 1.
(A way to play with the GUI is to simply create empty waveX.dat files and transfer they to see the structure of the data).
The buttom “Save config. file” will save the current wavedump configuration file as “used_config.log” in the corresponding run folder.
Please, keep in mind that the run and subrun numbers can be changed by hand. So if you make any mistake you can change the value back there, however, the move is done with the tag “-n” so the data is not overwritten, if you need to replace subrun 0, for instance, delete the wrong one first.
Style2 Acquisition
- “Run” is the run number
- “subrun” is the subrun number
- “Voltage” is the bias voltage of the SiPMs (always set a number with one or two decimals only, ex: 34.0 or 34.00)
- “Threshold” is the the threshold set at the ADC (this should always be a integer number)
- “Trigger Ch” is the channel in which you are triggering, HOWEVER, the field there can be any text, so you can write, for instance, “Ch0_and_Ch1” or even include some extra information and write something like this “Ch0_and_Ch1_cosmic_run_after_lunch_break”
- “Extra info” is any extra information that will be written at the end of the files (not folders), see bellow.
In the example from the image above, the GUI will create a folder named new_data at ~/Documents/ADC_data/BLEND_data (the lock option is just to not change the name by mistake, you don’t need to lock it).
After taking data with two channels, for example, you should have “wave0.dat” and “wave1.dat” at WaveDumpData.
When pressing “Move files”, a folder named “run0_42V30_20ADC_Ch0” will be created (note: “extra info” will not be placed in the name of the folder), inside the folder “new_data” and the two files will be moved there as:
0_wave0_42V30_20ADC_Ch0.dat 0_wave1_42V30_20ADC_Ch0.dat
The GUI can also control the configuration file of wavedump. In the example above, channel 0 and 1 are enabled, the trigger is set to Ch0 on a trigger level of 10 ADC channels.
The baseline is set to 10% for ch0 and 20% for ch1. And post trigger set to 50%.
The acquisition window is set to 20~us with a sampling rate of 250 MSamples/s, this corresponds to 5,000 points per waveform.
Please, note that this is calculating the number of points to be acquired. The ADC sampling rate is fixed (at 500 or 250 MSamples/s) and so we are ignoring points to virtually have the requested sampling rage. In the example, a ADC of 500 MSamples/s will still take 10,000 points, but we will only save 5,000 by skipping one point out of two (see #recompile).
Pulse polarity is set to positive and file type as binary.
If External trigger is selected, the individual trigger is disabled and one should set the type of sync (TTL or NIM).
Please, refer to #extra-common-variables and the wavedump manual for a better understanding of the configuration.
You can load previous config. files used by clicking at “LAr Test” on the top left corner.
The default configuration of wavedump (done following the instructions at #wavedump) is to reduce the sampling rate by a factor of 2. That is, if the digitizer nominal sampling rate is equal to 500 MSamples/s, wavedump will virtually reduce it to 250 MSamples/s by skipping one point out of two. This can be changed by informing the digitizer nominal sampling rate and the desired sampling rate.
Please, keep in mind that this will not reduce the dead time of the digitizer.
Besides, when “Continuous writting” is enabled at wavedump, the default configuration set wavedump to save 10,000 waveforms and then stop. To change the maximum number of events change the value of “# of waveforms” to the desired one. If not value is given, the default of 10,000 is used. To set non-stop continuous writting, set the value to a negative number.
In the example above, wavedump will be recompiled setting a maximum of 500 waveforms per continous writting and a sampling rate of 250 MSamples/s (half of the digitizer capability).
Inside the folder ~/Documents/CAEN_Control/installation_files/install_by_hand you will find the file WaveDump.desktop. Replace the user from “henrique” to yours. Copy the .desktop file into ~/.local/share/applications/ (the tumbnail should be already placed at ~/Pictures). Now, open the menu (windows key) and search for CAEN you should find the shortcut (if not, try login out and login in). You can place this short cut at your dock/panel, this makes much easier to launch wavedump in a way that is saves the data at ~/Desktop/WaveDumpData/.
If you want to decrease/increase the sampling rate of the saved data, for example from 500 MS/s to 250 MS/s, or to 125 MS/s and so on, you need to edit the WaveDump.c file and “enable” my modifications. The same goes for changing the number of waveforms saved each time you enable continuous writting.
If you are using the GUI, that fairly easy (see #recompile).
Another alternative is to use the script recompile_wavedump.sh followed by the number of waveforms you want to save and by the reduction factor of your sampling rate. Ex.:
. recompile_waveform.sh 2000 4
This will change the maximum number of waveforms to 2,000 and will reduce a 500 MSamples/s digitizer to 125 MSamples/s.
Another way to do it is to change manually
cd ~/Documents/CAEN_Control/wavedump-3.10.3/srcSet the maximum number of waveforms by changing the value at line 1493:
uint64_t mymaximum = -1; // Added by Henrique Souza
Open the file WaveDump.c, set the factor which you want to divide the sample rate at line 1515:
int factor = 2; // Added by Henrique SouzaNow you just need to compile wavedump again:
(NOTE: by doing this, WaveDumpConfig.txt will be overwritten with the default version. Make sure you backup your version if that is important)
cd ~/Documents/CAEN_Control/wavedump-3.10.3
./configure
make
sudo make installNow, if your digitizer have 500 MHz and you set factor = 2, by setting
RECORD_LENGTH 5000
in the config file, wavedump will save 2500 points per waveform, spaced 4 ns instead of 2 ns.
The binary file structure is presented at the wavedump manual. Each waveform saved is composed by 6 headers (each header with 4 bytes) and n = RECORD_LENGTH (each point with 2 bytes). Here is an illustration:
Bellow are the the most used variables configuration at the /etc/wavedump/WaveDumpConfig.txt, not all variables are being displayed.
NOTE: In the example above, trigger is made with Ch0 and Ch1 as or. Ch0, Ch1 and Ch2 are acquired and Ch3 is not.
Please note that the original config file doesn’t have the individual CHANNEL_TRIGGER option. When acquiring with external trigger, one should set
EXTERNAL_TRIGGER ACQUISITION_ONLY
and set to DISABLED each channel trigger.
# OPEN: open the digitizer # options: USB 0 0 Desktop/NIM digitizer through USB OPEN USB 0 0 #(if you have some USB devices connected, you might need to change this value to 1 or 2) # RECORD_LENGTH = number of samples in the acquisition window RECORD_LENGTH 2000 # POST_TRIGGER: post trigger size in percent of the whole acquisition window # options: 0 to 100 # On models 742 there is a delay of about 35nsec on signal Fast Trigger TR; the post trigger is added to # this delay POST_TRIGGER 50 #PULSE_POLARITY: input signal polarity. #options: POSITIVE, NEGATIVE # PULSE_POLARITY POSITIVE # EXTERNAL_TRIGGER: external trigger input settings. When enabled, the ext. trg. can be either # propagated (ACQUISITION_AND_TRGOUT) or not (ACQUISITION_ONLY) through the TRGOUT # options: DISABLED, ACQUISITION_ONLY, ACQUISITION_AND_TRGOUT EXTERNAL_TRIGGER DISABLED # FPIO_LEVEL: type of the front panel I/O LEMO connectors # options: NIM, TTL FPIO_LEVEL NIM # OUTPUT_FILE_FORMAT: output file can be either ASCII (column of decimal numbers) or binary # (2 bytes per sample, except for Mod 721 and Mod 731 that is 1 byte per sample) # options: BINARY, ASCII OUTPUT_FILE_FORMAT BINARY # OUTPUT_FILE_HEADER: if enabled, the header is included in the output file data # options: YES, NO OUTPUT_FILE_HEADER YES # ENABLE_INPUT: enable/disable one channel # options: YES, NO ENABLE_INPUT NO #BASELINE_LEVEL: baseline position in percent of the Full Scale. # POSITIVE PULSE POLARITY (Full Scale = from 0 to + Vpp) # 0: analog input dynamic range = from 0 to +Vpp # 50: analog input dynamic range = from +Vpp/2 to +Vpp # 100: analog input dynamic range = null (usually not used)* # NEGATIVE PULSE POLARITY (Full Scale = from -Vpp to 0) # 0: analog input dynamic range = from -Vpp to 0 # 50: analog input dynamic range = from -Vpp/2 to 0 # 100: analog input dynamic range = null (usually not used)* # # options: 0 to 100 BASELINE_LEVEL 50 # TRIGGER_THRESHOLD: threshold for the channel auto trigger (ADC counts) # options 0 to 2^N-1 (N=Number of bit of the ADC) # *The threshold is relative to the baseline: # POSITIVE PULSE POLARITY: threshold = baseline + TRIGGER_THRESHOLD # NEGATIVE PULSE POLARITY: threshold = baseline - TRIGGER_THRESHOLD # TRIGGER_THRESHOLD 100 # CHANNEL_TRIGGER: channel auto trigger settings. When enabled, the ch. auto trg. can be either # propagated (ACQUISITION_AND_TRGOUT) or not (ACQUISITION_ONLY) through the TRGOUT # options: DISABLED, ACQUISITION_ONLY, ACQUISITION_AND_TRGOUT, TRGOUT_ONLY # NOTE: since in x730 boards even and odd channels are paired, their 'CHANNEL_TRIGGER' value # will be equal to the OR combination of the pair, unless one of the two channels of # the pair is set to 'DISABLED'. If so, the other one behaves as usual. CHANNEL_TRIGGER DISABLED [0] ENABLE_INPUT YES BASELINE_LEVEL 10 TRIGGER_THRESHOLD 500 CHANNEL_TRIGGER ACQUISITION_ONLY [1] ENABLE_INPUT YES BASELINE_LEVEL 10 TRIGGER_THRESHOLD 500 CHANNEL_TRIGGER ACQUISITION_ONLY [2] ENABLE_INPUT YES BASELINE_LEVEL 10 TRIGGER_THRESHOLD 500 CHANNEL_TRIGGER DISABLED [3] ENABLE_INPUT NO BASELINE_LEVEL 10 TRIGGER_THRESHOLD 500 CHANNEL_TRIGGER DISABLED
- Probably not. You should update your digitizer firmware. Download the newest digitizer firmware from CAEN and install it using CAENUpgrader.
- Make sure you have java installed. This will change from system to system, but make sure you google it properly and you will find normal solutions of how to install java (jdk). Here is my output from
java --version:openjdk 11.0.16 2022-07-19 OpenJDK Runtime Environment (build 11.0.16+8-post-Ubuntu-0ubuntu122.04) OpenJDK 64-Bit Server VM (build 11.0.16+8-post-Ubuntu-0ubuntu122.04, mixed mode, sharing) - There is a problem with CAENUpgrader on Ubuntu 21.10 and 22.04 (possibly 20.04). It will crash and you cannot perform any action. The easiest solution is to create a virtual machine with linux Cinnamon (v. 23.3 tested) so you can use CAENUpgrader.
- Wavedump version 3.10.4 have a problem with the baseline level, already reported to CAEN.
- It could be that I do not have time right now, or that I have not worked with the digitizer for I while or that I just don’t care because it is working for me like that. In any case, you can add it by yourself, downloading the proper softwares/drivers and installing either manually or by editing the installation bash script. Feel free to contribute to the project. Or, please do send me an email and I will be glad to update if necessary.
There are quite a few possibilities here and it is hard to debug (remember, this installer is nothing official, it should just help you out).
- First of all, check if each installation was done correctly. There is a 3 seconds pause between each driver/software installation, make sure there is no error messages (you can edit the bash script and increase the pause).
- If there is an error in any installation, check if the problem is the script it self or if you need to download any new release (please, inform the author of this project).
- try following the instructions to debug the USB at #debugging-usb.
- If none of those work, please refer to the documentation to understand the installation and contact CAEN Support.
- Absolutely not! The GUI was created to make your life easier :) if it is making it worse, kick it.