CatiROC test GUI

This project is under source control and available as a git repository. To download, it is necessary to have access to a git client.

• Linux users may refer to their preferred package manager for instructions on installing git
• Windows users may use git for windows, mobaxterm of similar

Then, launch a terminal and cd to the location where the project will live, creating necessary folders if necessary

cd d:
mkdir FolderWhereToDownload
cd FolderWhereToDownload

Finally, clone the repository with

git clone https://gitlab.in2p3.fr/CatiROC-test/gui.git catiROC-test-gui

and maybe rename it to something more explicit

mv catiROC-test-gui myGreatSoftwareProject

Just get if from

https://gitlab.in2p3.fr/CatiROC-test/gui/repository/archive.zip

and extract its contents; then maybe rename it to something more explicit

mv catiROC-test-gui myGreatSoftwareProject

The source code may be run from within MATLAB itself, or executed as an stand alone application. Executable files are provided to run under GNU/Linux as well as under windows.

The program has been tested under windows 7, centos 7 and Arch Linux. Due to the lacky implementation of the libusb under GNU/Linux, the performances in terms of readout bandwidth are quite poor. We have measured ~ 10 MB/s. with a recent computer instead of ~ 40 MB/s under windows.

The program has been developed using Matlab R2018a, but maybe new/older releases are compatible too. To run it in stand alone mode in the case R2018a is not installed locally, it is necessary first to install the correct Matlab runtime library, freely available here.

In order to make the usb communication work, it is necessary to install the ftdi libraries from here.

Before running the software, remember to set the nb_asics parameter under generic in the global configuration file accordingly to the number of asics present in the board.

• Matlab

In a Matlab command terminal, just cd to the program and do

catirocgui

• Linux

In a GNU/Linux terminal, just cd to the program and do

./run_catirocgui.sh /opt/MATLAB/R2016a

or equivalent. You’ll probably have to deal with udev rules in your /etc/udev/rules.d/20-ftdi.rules file or similar, as for example

SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", GROUP="user", MODE="666"

Finally, you’ll maybe have to

sudo rmmod ftdi_sio; sudo rmmod usbserial

before being able to connect

• Windows

Just run the provided executable.

This is the list of valid functions provided by the low level software.

Open/close peripheral

'InitializeUSB'

open the usb peripheral

'ConfigureUSB'

configure the usb peripheral

'FinalizeUSB'

close the usb peripheral

'GetIsOpen'

check if the usb peripheral is open or not

Status

'GetNumberDevs'

request number of usb peripheral on bus

'GetRxTxStatusUSB'

request amount of bytes available to read

'GetDescriptors'

request descriptor chain in ftdi usb eprom

Send/read

'ReadUSB'

read data

'WriteUSB'

send data

'PurgeRxTxUSB'

send a null command and erase any trailing data in the usb low level buffers

Note that currently commands are limited to 70 bytes, but this limit may be removed by firmware. This software is agnostic with this respect. Follows a list of all currently implemented functionalities in the firmware.

These commands are provided only for testing the communication with the hardware

• “01” - returns an up counter; amount of bytes is given by bytes 2 to 5 in command array
• “04” - returns an endless up counter
• “05” - returns the command sent

Next commands implement the communication with the ASIC

• “06” - returns ASIC data, used by the “GetASICData” method
• “0B” - returns the AcqRawDataFormatID byte register, see Header section
• “CC” - sends configuration to ASIC, used by the “ConfigureASIC” method

First, load low level library in memory and give it an alias to refer to it

if ~libisloaded('libftdi')
    [notfound, warnings] = ...
        loadlibrary('libftdi_x86_4_0','libftdi_4_0.h', ...
                    'alias','libftdi')
end

Maybe, display a list of all functions available in the library

libfunctions('libftdi', '-full')

Ask for the available number of devices in the usb bus

[ft_status, NbDevices] = calllib('libftdi', 'GetNumberDevs', ...
                                 libpointer('ulongPtr',uint32(0)))

Then instantiate a TestCard object of class test_catiroc.

TestCard = test_catiroc(NbDevices-1)

which implicitly executes

TestCard.Initialize

in the class constructor.

From now on, TestCard will refer to the test card available in the usb bus, and provides access to it, exchanging data in several different modes.

To end current session, just don’t forget to delete the TestCard object.

TestCard.delete

and unload the library from memory

if libisloaded('libftdi')
    unloadlibrary('libftdi')
end

Even simpler, and similar to previous case, create a system object of class system_test.

system = system_test;

This step automatically loads the low level library in memory and instantiates a test_catiroc class object.

From now, system will refer to all test cards available in the usb bus (peripherals). To address one specific peripheral, refer to it by

system.Cards(1)

or simply system.Cards if there is only one card present

TestCard = system.Cards(1);

To end current session don’t forget to delete the system object

system.delete;

which removes from memory the low level library too.

• Check if the peripheral is open

  TestCard.GetIsOpen
  

• Check if there is any incoming data in the usb low level buffers

  AmountInRxQueue = TestCard.GetStatusUSB
  

• Obtain a string chain, describing the usb peripheral

  DescChain = TestCard.GetSerialDesc
  

• Erase any remaining trailing data

  TestCard.PurgeUSB
  

• Send command to the board

  TestCard.SendCommand(Command)
  

• Read data back

Proposed testing methods of the TestCard object.

• Bandwidth

  Measurement of data readout bandwidth, to be run NbTimes

  TestCard.test_bandwidth(1, NbTimes);
  

• Command

  Test data validity. Data is assumed to contain a 8 bits up counter. This tests requests NbPackages of 65536 bytes each.

  TestCard.test_command(NbPackages, 1);
  

• Update configuration data in object

  TestCard = TestCard.UpdateConfig;
  

  This parses all the configuration files and updates the object property structure with all parameters in the configuration files.

  TestCard.configuration
  

  This is useful for modifying any parameter programmatically. Thus, user may set manually any parameter

  TestCard.configuration.verbose = 1;
  

  before sending the configuration to the board

• Send configuration to ASIC

  TestCard.ConfigureASIC
  

  This method will parse the TestCard.configuration structure, convert it to binary format and send it to the hardware.

This section depicts the way to configure the ASIC present in the test card.

A parameters file under configuration folder includes all configuration registers necessary to setup the ASIC. To parse this file use

TestCard = TestCard.UpdateConfig;

This command updates the configuration object property structure. To verify the validity of the updated configuration array use

TestCard.configuration

which is empty by default. It appears in the form of a structure, containing all fields in the parameters file. In case of more than one asic is present, do instead

TestCard.configuration(AsicNumber)

The binary representation (array of bytes) corresponding to this configuration may be found at

TestCard.configuration_array

It is used as command to be send to the board by

At this point, it is possible to send the configuration to the ASIC using

Command = TestCard.configuration_array;

and then

AmountBytesWritten = TestCard.SendCommand(Command);

See previous sections for details. Alternatively, one may just issue

AmountBytesWritten = TestCard.ConfigureASIC;

which handles sending the command to the board, reading it back and checking its validity. This may be done by hand, if considered useful using the command

There exist a reference configuration array too in the object property

TestCard.configuration_array_reference

including the default ASIC configuration at power up. This may be useful to bring the ASIC to its default status replacing previous with

Command = TestCard.configuration_array_reference;

This section shows how to send slow control to the ASIC present in the test card.

Order X“CC”

system = system_test;
TestCard = system.Cards(1);
% Parse configuration file
TestCard = TestCard.UpdateConfig;
% Manually tune configuration
TestCard.configuration.parameter = value
% Should return 0
AmountInRxQueue = TestCard.GetStatusUSB
% Send configuration to hardware
BytesSent = TestCard.ConfigureASIC
system.delete;

This section shows how to send random data to the test card.

Order X“5” will send the same data back.

system = system_test;
TestCard = system.Cards(1);
Order = 5;
% command length
L = 10;
Command = uint8([Order, 250*rand(L-2,1)', 255])
% Should return 0
AmountInRxQueue = TestCard.GetStatusUSB
% Send command, returns L
BytesSent = TestCard.SendCommand(Command)
% Should return L
AmountInRxQueue = TestCard.GetStatusUSB
% Read data back
[ElRead, DataRead] = TestCard.ReadUSB
system.delete;

This example session shows the way to send an arbitrary, not defined command, to
the test card.

Order not implemented in firmware

system = system_test;
TestCard = system.Cards(1);
Order = 227;
% command length
L = 10;
Command = uint8([Order, 250*rand(L-2,1)', 255])
% Should return 0
AmountInRxQueue = TestCard.GetStatusUSB
% Send command, returns L
BytesSent = TestCard.SendCommand(Command)
% Should return 0
AmountInRxQueue = TestCard.GetStatusUSB
system.delete;

The AcqRawDataFormatID may be read from the firmware by sending the following command to the board

Command = uint8([11, 255]);

One byte, the AcqRawDataFormatID, will be made available in return.

In order to take data, it is necessary to use order 6 plus 4 bytes as parameters. A typical command would be the following

Command = uint8([6, ...
                 repmat([...
                     EnabledASICs, ...
                     BoardId, ...
                     ForceTriggerValue*4 + ...
                     EnableExternalTrigger*2 + ...
                     ForceTrigger, ....
                     GlobalParameters.EnableSpecialData*64 + ...
                     GlobalParameters.ReduceDiscriminatorData*32 +...
                     GlobalParameters.EnablePhysicalData*16 +...
                     GlobalParameters.EnableDiscriminatorData*8 +...
                     GlobalParameters.DecodeGray*4 + ...
                     str2double(obj.configuration(1).EnableTacReadout)*2 + ...
                     emulate], ...
                        1, nb_asics), ...
                 255])';

where

Byte one:

EnabledASICs

one byte, one bit by asic, providing an enable / disable functionality for masking data from given asics

Byte two:

BoardId

one byte to identify this board; all data will be tagged with this byte which will appear in last byte in every event

Byte three:

Bit[13-10] ForceTriggerValue

selects the force trigger rate (default to 0), see Fake trigger section for more on this

Bit[9] EnableExternalTrigger

activates the external trigger (default to 1)

Bit[8] ForceTrigger

activate the forcetrigger feature in the firmware (default to 0)

Byte four:

Bit[6] EnableSpecialData

activates special data readout

Bit[5] ReduceDiscriminatorData

activates DDS data reduction (default to 0)

Bit[4] EnablePhysicalData

activates the physical data stream (default to 1)

Bit[3] EnableDiscriminatorData

activates the discriminator data stream (default to 1)

Bit[2] DecodeGray

activates the gray decoding feature in firmware, as data out of the ASIC is gray encoded (default to 1)

Bit[1] EnableTacReadout

parameter from the configuration file (default to 1)

Bit[0] Emulate

activates the “bypass of catiroc” feature in the firmware (default to 0)

Note that here, between the order 6 and the trailing FF the (4 bytes) parameters are replicated number of asics times. This is important to be compliant with the firmware.

In order to take s-curve data, it is necessary to …

Command = uint8([6, ...
                 repmat([...
                     emulate], ...
                        1, obj.nb_asics), ...
                 255])';

Where …

Juno mezzanine board has eight asics, whereas omega test board has only one.

nb_asics = 8;

For debugging purposes during development

verbose = 0;

Id tag to be appended to all évents as its last byte

BoardId = 1;

It is possible to display some acquisition related informations while acquiring data (event and data rate, decoded fields of the first events by data package, etc.).

This parameter sets the number of events to display in command window at run time

ToDisplay = 0;

where

0

no events to display

<5

only special events

>5

this number of events

There exists the possibility to save data on disk and compute/display histograms at the same time. This feature is enabled by using this parameter. It is disabled by default as data lose is expected to occur in this case (cpu resources are taken and not available for acquiring and saving data)

SaveAndDisplay = 0;

This parameter forces mixing up data from two analog memories (ping and pong) in displayed histograms

Randomize = 0;

This parameter sets the number of bytes in a data package to ask for to the usb. It must be an integer multiple of 10. See No data !! section for its effects.

AmountInRxQueue = 65540;

Allow decoding online the default format out of the asic, gray encoding, in the firmware, converting it on the fly to unsigned binary.

DecodeGray = 1;

Enable discriminator data or not. When disabled, discriminator data is just discarded in the firmware

EnableDiscriminatorData = 1;

Reduce discriminator data. When enabled, discriminator data is compressed to a single word, instead of the default of two words by event

ReduceDiscriminatorData = 0;

Enable physical data or not. When disabled, physical data is just discarded in the firmware

EnablePhysicalData = 1;

Enable special data or not. When disabled, special data is just discarded in the firmware

EnableSpecialData = 1;

Enabled ASIC, in hexadecimal format, one bit by ASIC, going from ASIC[8] to the left down to ASIC[1], to the right.

EnabledASICs = "FF";

Force trigger rate: maximum rate is 15. Refer to Fake trigger section for details

ForceTrigRate = 15;

Enable exteral trigger

EnableExternalTrigger = 1;

Ignore fake events from the ASIC; set to zero not to ignore. See Fake events section for details.

IgnoreFakeEvents = 1;

Not implemented in firmware. To ignore.

PacketSize = 2^16;

See S-Curve computing for details.

Minimum, maximum and step values for the threshold

s_curve.th.min = 940;
s_curve.th.step = 2;
s_curve.th.max = 1020;

Methods used:

• Method = 1 -> Use data
• Method = 0 -> Use trigger

s_curve.method = 0;

Number of of periods to average

s_curve.nb_periods = 100;

TimingINL.steps = 300;
TimingINL.time = 10;

When performing data analysis, there is the possibility to only analyse a fix number of events. This parameter sets the number of (10 bytes) events to analyse at the beginning of the data file.

Set it to -1 to analyse the whole file

NbEventsToAnalyse = -1;

This plot is obtained by injecting a constant amplitude signal from a pulse generator, and going through an attenuator to improve SNR. The generator is in sync with the 10 MHz clock of the acquisition, providing a constant measurement of the fine time. This means that we are able to inject a signal from the pulse generator and obtain always the same fine time. Histogramming this measurement provides the resulting gaussian shape, corresponding to a fix time delay setup in the pulse generator.

At this point, adding a delay makes the gaussian shape shift accordingly. Thus, by manually increasing the pulse generator delay in 1 ns. steps we manage to shift the measurement to the left, producing 25 (one by ns.) shifted versions of the same measurement.

Note that a 30 ns. delay is equivalent to a 5 ns. delay due to the periodic 25 ns. coarse time window length.

Horizontal black lines are shown here as a rough reference: they are all the same length (long ones equal 5 ns., and short ones 1 ns.). This provides a first impression of how linear the fine time is when increasing the delay by 1 ns. steps.

Release 0.8 firmware embeds a variable, configurable 97.65 ps digital delay line to replace the manual delay in the pulse generator. This is possible as the delay line acts on the 10 MHz to be sent from the acquisition to the external pulse generator. This replaces the need to manually tune the generator delay parameter.

This effectively provides a means to perform a custom, systematic software scan by programmatically setting the delay steps of the measurement. Fine time characterization has thus been included in release 0.8 software. Details are given below.

In order to reproduce previous plot, and to further execute a scan of the coarse time window, the following steps are to be followed (note that tests were done using a AFG-3022B pulse generator form Tektronix)

• set the following parameter in the configuration file

  SelClkDiv4 = 0;
  

  This forces the ASIC to use the 40 MHz clock from the fpga, effectively removing any ambiguity otherwise. This means that when catiROC generates a 40 MHz clock using the 160 MHz from the fpga, there exists four different possibilities to lock the former with respect to the later. This random behaviour will repeat at each ASIC reset, that’s to say, at each data taking. Sending the 40 MHz clock to catiROC erases this random behaviour, which is an issue in this context

• connect output io_fpga10 to an oscilloscope, and output io_fpga9 to the trigger input of the pulse generator
• setup the pulse generator using an internal reference (continuous mode) to output a pulse of the desired frequency and amplitude; start taking data as usual to check data is coming, note how in io_fpga10 at the oscilloscope a 10 MHz clock signal appears after the acquisition starts: you’ll get the same from io_fpga9, and you’ll notice how the green led lights on
• lock the pulse generator to its 10 MHz clock trigger input (burst mode), and check at the oscilloscope how the 10 MHz clock and the generated pulse are synchronous now
• plug the pulse from the generator to the board and visualize the fine time histogram, where a gaussian shape corresponding to a fixed fine time value should be appreciated
• set the pulse generator delay parameter; the digital delay line will add a delay starting from this point

From here, scanning the coarse time window is a matter of selecting in the Tools menu the Time INL option. Here, the number of 97.65 ps. steps to be used for the scanning is given by the TimingINLsteps parameter in the global parameters configuration file, while the scan time is given in the TimingINLtime in the same file. For example, setting this to 30 and 10 (default values), will perform a 10 seconds data acquisition, before increasing the delay by 97.65 ps steps and then taking data again. One binary data file will be stored on disk by delay.

TODO:

Software for analysis the data.

TODO:

Ancillary soft to the gui.

Bit to disable the feature

DDR makes amount of data to be readout rise beyond limits, specially considering the usb 2. Add a bit to command 6 to disable this feature when requested by the user.

OK

Done in this commit, in parallel to the software.

… bla

Current implementation

check that the current implementation is right, for both omega test board and ABC board

Store data on disk

Use the ’Save Data’ button to store on disk the resulting data from the s-curve scanning. Create a new dir, picking-up its name from a parameter in the global config file (if this parameter is empty, just create a random folder name), and put data in here similar to the standard acquisition. Save .mat and .txt files, along with the figures in .fig and .tiff and .jpeg formats. Implement in the figure manual saving of the curves using the right mouse button