Running Calibrations with Dirigent ================================== This guide assumes you have followed all of the ``dirigent`` installation instructions in doc:`installation.rst `, 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 `:: 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 where ```` 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 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 a) Allow ``dirigent`` to create the XML file by running a simple calibration such as ``test_calibration`` b) Manually run the script ``/path/to/dirigent/scripts/copy_ph2_acf_files.py`` c) Copy the XML from your Ph2 ACF install ``/path/to/Ph2_ACF/settings/CMSIT_RD53B.xml`` and edit accordingly d) Copy an XML from another location on your PC Once you have an XML file, run:: CMSITminiDAQ -f -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 -i 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 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.