Running Calibrations with Dirigent

This guide assumes you have followed all of the dirigent installation instructions in doc:installation.rst <installation>, and that you have a working experimental setup. The experimental setup includes the PC with all appropriate software installed (dirigent, Ph2 ACF, etc.), ensuring all the hardware is connected to the PC and powered on (LV and HV power supplies, FC7(s) and FMC(s), coldbox, needle card(s)), and that you have a fully-assembled, functioning CMS Inner Tracker hybrid module (or modules) connected appropriately.

Setting up the environment

Firstly, create a new directory for the module(s) or test setup in your module testing folder. We typically name the folder after the modules we want to calibrate, but is not necessary:

cd path/to/module/tests/folder/
mkdir C2HQ7
cd C2HQ7

Copy the dirigent.toml, instruments.json and modules.json files into the new directory. This is everything dirigent needs to function:

cp path/to/software/dirigent/dirigent-3.1.0/config/* .

Activate the python environment containing your dirigent install, source thisroot.sh for the correct ROOT install, and change directory to your Ph2 ACF install and source the setup.sh script for the correct version of Ph2ACF:

. path/to/software/dirigent/dirigent-3.1.0/.venv/bin/activate
. path/to/software/root/bin/thisroot.sh
cd path/to/software/Ph2_ACF
. setup.sh

Alternatively, Ph2 ACF can be loaded by dirigent directly, by setting the path to the installation into the ph2_acf parameter in the dirigent.toml file.

If you entered your Ph2 ACF install folder, make sure to change directory back into your newly created module folder:

cd -

Now fill the config files out appropriately for both your setup and the measurements you wish to perform. For assistance, please consult the documentation in doc:config_file.rst <config_file>:

vim dirigent.toml # change settings as required
vim instruments.json # change settings as required
vim modules.json # change settings as required

Calibrations

To run a calibration:

dirigent -C dirigent.toml <calibration>

where <calibration> is the name of the calibration. You can also simply ignore the -C parameter. dirigent will by default use the dirigent.toml in your current folder. You can list the available dirigent calibrations and their descriptions by running:

dirigent --help

For example, if you run:

dirigent test_calibration

dirigent will run through the Python script module_testing/calibrations/test_calibration.py. All this does at the time of writing is print out a list of all CROCs in the system, powers them, runs a Ph2 ACF reset, then powers off the modules.

You may have noticed that test_calibration has an optional parameter test_option. You can modify this in two ways. Firstly make a copy of your dirigent.toml and give it a new name:

cp dirigent.toml dirigent_test.toml

Then open dirigent_test.toml with your favourite text editor, add the following lines to the bottom of the file, and save. Make sure everything is spelled correctly:

[test_calibration]
    test_option = 42

Now run:

dirigent -C dirigent_test.toml test_calibration

In the output, you will see that test_option has now changed to 42. If you try:

dirigent -C dirigent.toml test_calibration

You will see that it has returned to 123. This is because there is no definition in the dirigent.toml, and dirigent will use the default value defined in test_calibration.py.

The second way to modify this is to enter it in the command line. To demonstrate priority order, use dirigent_test.toml again but this time, give the option --test_option in the command:

dirigent -C dirigent_test.toml test_calibration --test_option 6

You will see that test_option now equals 6. The priority order is: command line > TOML file > PY file. You can also give the short form of the parameter as an option:

dirigent -C dirigent_test.toml test_calibration -t 6

Inspecting the folder by running ls, you can see that the Ph2 ACF XML and TXT files have been automatically created. These are what dirigent uses to run Ph2 ACF scans, and will be created any time a dirigent scan is run, provided they do not exist already.

It is also possible to run on an existing CMSIT.xml file without letting dirigent create a new one. For this, just put the respective CMSIT.xml file along with the correct TXT files into the run directory. Dirigent will then not create or change anything in these files before starting the calibrations.

This guide will be expanded to include some tips for all calibrations.

Troubleshooting

Problems communicating with instruments Make sure all components are correctly connected and addressable on the module testing PC. i

It can be helpful to use the icicle command line interface for this. For help, please check the `ICICLE gitlab repo <https://gitlab.cern.ch/icicle/icicle`_. To list the available commands, run:

ls -la /path/to/software/dirigent/dirigent-3.1.0/.venv/bin/

For instance, for a TTI device you can use:

tti --help

for help with any icicle instrument, replacing tti with the desired instrument command. You can verify the instrument with the command:

tti -R ASRL/dev/ttyACM0::INSTR identify #replace <ttyACM0> with the respective resource name

If you don’t now the resource name, there are many ways to find it. I recommend unplugging the USB cable of the device, and running:

ls -la /sys/class/tty

then plugging the USB cable in again and running the command again. The newest device will be at the bottom of the list. It may have a name such as: /dev/tty0, /dev/tty1, or /dev/ttyUSB0.

Problems with Ph2 ACF* Sometimes when Ph2 ACF flashes on the screen for a short time but doesn’t actually run the scan. For this, you can try a reset. To do this you need an XML file, and there are a few options for how to get one

Allow dirigent to create the XML file by running a simple calibration such as test_calibration
Manually run the script /path/to/dirigent/scripts/copy_ph2_acf_files.py
Copy the XML from your Ph2 ACF install /path/to/Ph2_ACF/settings/CMSIT_RD53B.xml and edit accordingly
Copy an XML from another location on your PC

Once you have an XML file, run:

CMSITminiDAQ -f <CMS XML file> -r

You should see the message Now you can start using the DAQ ... enjoy!.

If this still doesn’t work, try reloading the FPGA firmware:

fpgaconfig -c <CMS XML file> -i <name of firmware>

and running the reset again. You can also try power cycling the FC7. If dirigent simply will not run Ph2 ACF. Verify Ph2 ACF works on its own with:

CMSITminiDAQ -f <CMS XML file>

You can also try running with a scan such as -c pixelalive. Once you have confirmed Ph2 ACF is working on its own, try running dirigent again. If it still fails, delete all unnecessary files in your working directory, leaving just the dirigent.toml, modules.json, and instruments.json file and run dirigent again.

Note It is possible to let dirigent execute CMSITminiDAQ instances in tmux instead of xterm. However, tmux is not thoroughly tested. To change the shell, use the flag sub_shell=”tmux”/”xterm” either in the dirigent.toml or in the command line. The respective shell has to be separately installed. Also the option with tmux requires the variable ph2_dir in the dirigent.toml

Note If desired and if your rights on the computer allow it, devices can be assigned aliases with the udevadm rules. This is some initial investment, but can be useful, if a fixed link to an instrument is desired. In the following link, you will find a very rudimentary guide to use udevadm (CERN login required) https://codimd.web.cern.ch/s/HvKK3gQCp . But keep in mind, that this tool is very powerful and as it as root user access, wrong commands can cause serious problems to a computer.