Software

Installation

The software to run the configuration, tests of the readout board and a simplified DAQ is rather lightweight. The only strict prerequesite is UHAL/IPbus and python3 (at least 3.8.10). Depending on the operating system, you can run sudo yum install cactuscore-uhal-python3 or if you have Ubuntu 20.04 you can try these instructions. IPbus for uhal needs to be compiled from source for linking with python3. However, if you are in a pinch you can use the docker instructions.

The software is only strictly tested for python 3.8.10. Feedback is always welcome, issues are open on gitlab.

First, clone the software from the Gitlab repository:

git clone https://gitlab.cern.ch/cms-etl-electronics/module_test_sw.git

Dependencies

As always it is recommend to create a virtual environment to install dependencies. For example using Conda:

conda create -n tamalero
conda activate tamalero

Then install then requirements:

pip install -r requirements.txt

- for an interactive python shell (ipython) run pip install ipython - if desired, jupyter for notebook usage. Install with pip install jupyter.

To properly set all paths, run

source setup.sh

Docker

Instructions for install using Docker can be found here, - https://gitlab.cern.ch/cms-etl-electronics/module_test_sw#using-docker

Interlude: KCU firmware

Firmware has to be loaded on the KCU before running the software below. Please refer to the instructions on the documentation page on how to update the firmware.

Run Software

You now can run the test software that contains a minimal example of usage of this package. Communication with the KCU is handled through the CERN control hub. To check if control hub is running use /opt/cactus/bin/controlhub_status. To start control hub use,

/opt/cactus/bin/controlhub_start

Configuration of default readout board

The simplest power up routine is the following, and can be used for a bare readout board (nothing else connected):

ipython3 -i test_tamalero.py -- --power_up --kcu IPADDRESS

IPADDRESS specifies the IP address of the KCU board (default is 192.168.0.10).

For other arguments, refer to python3 test_tamalero.py -h. Most options are for debugging only.

--verbose                   Verbose output
--power_up                  Do lpGBT power up init?
--reconfigure               Configure the RB electronics: SCA and lpGBT?
--adcs                      Read ADCs?
--i2c_temp                  Do temp monitoring on I2C from lpGBT? (not recommended, debugging only)
--i2c_sca                   I2C tests on SCA?
--run_pattern_checker       Read pattern checker?
--reset_pattern_checker     {None,prbs,upcnt}
                            Reset pattern checker?
--kcu KCU                   Specify the IP address for KCU
--force_no_trigger          Never initialize the trigger lpGBT.
--allow_bad_links           Select to allow bad link initialization
--read_fifo READ_FIFO       Read 3000 words from link N
--alignment [ALIGNMENT]     Scan/load alignment? If load, pass in file path. If scan, don't pass in anything.
--etroc ETROC               Specify ETROC version.
--eyescan                   Run eyescan?
--recal_lpgbt               Recalibrate ADC in LPGBT? (instead of using saved values)
--control_hub               Use control hub for communication?
--host HOST                 Specify host for control hub
--devel                     Don't check repo status (not recommended)
--configuration [CONFIG]    Select the readout board configuration, {default, emulator, modulev0}. Make sure to choose the right configuration, or leave as default if unsure.

Afterwards, you can run without the --power_up option, e.g. to read the ADC values of lpGBTs and SCA:

ipython3 -i test_tamalero.py -- --kcu IPADDRESS --adcs

Configuration of a readout board connected to ETROC2 EMULATORS

To get all GPIOs and ADCs properly configured for the emulator breakout boards use the following command:

ipython3 -i test_tamalero.py -- --power_up --kcu IPADDRESS --configuration emulator

Configuration of a readout board connected to ETROC2 Module v0 / v0b

Important: Use the correct version of the Module v0 board in the --configuration argument. For Module v0 (initial version), use --configuration modulev0, for the v0 revision b board (second revision) use --configuration modulev0b:

ipython3 -i test_tamalero.py -- --power_up --kcu IPADDRESS --configuration modulev0b

This script configures both the readout board and any module / ETROC that is connected to it.

You can test a connected Module v0 using the test_ETROC.py script. Pay attention to use the right configuration, which should be either modulev0 or modulev0b (similar to above):

ipython3 -i test_ETROC.py -- --kcu IPADDRESS --module MODULENO --test_chip --configuration modulev0b --moduleid ID

Currently, only the first module slot is supported (i.e., the module has to be connected right below the VTRx+ optical transceiver), which corresponds to MODULENO=1 (default setting). When running in interactive mode the tested ETROC chip is available to be interacted with through an ETROC instance etroc, e.g. writing to a register like etroc.wr_reg('PixelSanityConfig', VAL, row=I, col=J). Data is being read through the FIFO instance fifo. For example, a single L1A command can be issued like fifo.send_L1A() and the data can be read in a human-readable format with data = fifo.pretty_read(df).

A few sanity checks are run if --skip_sanity_checks is not used. This includes printing of the peripheral configuration and status registers. Every register that has a different value than the default shown in the ETROC2 manual will be flagged as red. Some of the registers are changed deliberately, e.g. in the default_config method. The peripheral status registers are always shown as yellow as the expected value is currently not entirely clear.