¶ Configuring optoboard with the latest software
Optoboard documentation from Bern - https://optoboard-system.docs.cern.ch/
Optoboard repository - https://gitlab.cern.ch/bat/optoboard_felix/
Latest software release for configuring optoboard: https://gitlab.cern.ch/bat/optoboard_felix/-/tree/master?ref_type=heads
Documentation :
- https://optoboard-system.docs.cern.ch/software/
- https://edms.cern.ch/ui/file/2786670/1/ITk_FDR_EDMS_AT2-IP-ER-0019_Optosystem.pdf
The latest (Feb 2024) software for configuring the optoboard can be run several ways:
- Through a container (https://gitlab.cern.ch/atlas-itk-pixel-systemtest/itk-demo-sw/containers/optoboard-container)
- With Felix-star or Felixcore
- Independent of FELIX software
All of the following instructions are for configuring the optoboard without a container and with no dependencies on Felixcore or Felix-star
¶ First-time setup
¶ Getting Software
Following the instructions at : https://gitlab.cern.ch/bat/optoboard_felix/-/tree/main?ref_type=heads
Install the release using:
pip install optoboard-felix --index-url https://gitlab.cern.ch/api/v4/projects/113584/packages/pypi/simple --extra-index-url https://gitlab.cern.ch/api/v4/groups/33370/-/packages/pypi/simple
This will install the InitOpto package, storing files at (depending on releases)
~/.local/lib/python3.9/site-packages/optoboard_felix/
For FELIX firmware version greater than 5.3, it is recommended to configure the optoboard via the itk-ic-over-netio-next library. This requires an additional installation.
Visit the itk-ic-over-netio gitlab and follow the install instructions.
¶ Configuring Optoboard
¶ Setting up Environment
To configure the optoboard, the appropriate config file is needed, which will be customized to the user's setup. The best way to do this is by creating a local environment where the customized optoboard configuration can be stored. This can be done just outside of the felix-distribution environment, for example:
# in felix-distribution
cd ../
mkdir optoboard
cd optoboard
cp #config_file .
The file needed to configure the optoboard independent of the container will follow the name:
optoboard{OPTOBOARD NUMBER}_lpgbtv{LPGBT VERSION NUMBER}_gbcr{GBCR VERSION NUMBER}_vtrxv{VTRX VERSION NUMBER}_default.json
So for example if a setup contained Optoboard v2, LpGBT v1,GBCR v2, and VTRX v1_3, config file optoboard2_lpgbtv1_gbcr2_vtrxv1_3_default.json would be used.
The config files will be found at a path similar to ~/.local/lib/python3.9/site-packages/optoboard_felix/configs, with the exact file path depending on the release of python used to install. The list of config files can be found in the distribution at https://gitlab.cern.ch/bat/optoboard_felix/-/tree/master/src/optoboard_felix/configs?ref_type=heads.
¶ Customize Config File
To run without the container, using the locally installed InitOpto release, the following needs to be added to beginning the config file, with the user filling in the appropriate numbers for their setup:
"Optoboard":
{
"serial": "00000000",
"flx_G": 0,
"flx_d": 0,
"vtrx_v": "1.3"
},
Additionally, depending on the setup, the polarity of the EPRX and EPTX registers might need to be changed. Notes on this are provided below in the troubleshooting section.
¶ Configuration
To configure the optoboard, first make sure that the correct FELIX environment is set up:
cd <Felix-distribution directory>
export REGMAP_VERSION=0x0500
source setup.sh
then navigate to the location of the customized optoboard config file.
To configure using the itk-ic-over-netio-next tool, felix-star must be running. Visit Installing FELIX software, firmware, and driver, if felix-star has not yet been installed.
To run felix-star, download the following bash script: run-felix-star.sh. You may need to transfer the run-felix-star.sh script to using a linux bash format via dos2unix run-felix-star.sh. It can then be ran via:
source run-felix-star.sh [card_num]
Configure the optoboard using:
InitOpto --config_path CONFIG_FILENAME.json --optoboard_serial SERIAL_NUMBER --vtrx_v "VERSION" --configure 1 --commToolName itk-ic-over-netio-next
Where CONFIG_FILENAME.json and the serial numbers are to be replaced with the custom config file and the appropriate versions.
At this point, one might run into some issues. Check the troubleshooting section below.
All possible InitOpto options can be seen on the software distribution page as well as with InitOpto --help. Note that -commToolName flpgbtconf is specifying a method for running without Felixcore or felix-star dependencies.
After the optoboard is successfully configured, the current will increase from around 600mA to 1.34A and all four links should be shown to be active if flx-info -c 0 LINK is checked, as shown in the images below:
Now we are ready to configure the pixel chip.
¶ Troubleshooting Errors
Bug fixes for some specific errors:
¶ InitOpto Error - IPython
Run:
Python3 -m pip install ipykernel
¶ InitOpto Error - itk-ic-over-netio-next
You will have to navigate to the optoboard-felix source code and delete text in CommBackend.py. By default, this file should be located as:
/home/{usr}/.local/lib/python3.11/site-packages/optoboard_felix/driver/CommConfig.py
Open this file, navigate to line 366 and delete the highlighted (orange and blue) texts in the image:
¶ FELIX error
2024-02-28 16:51:56,217 - INFO - Lpgbt.py - lpgbt1 object initialised!
2024-02-28 16:51:56,221 - INFO - Lpgbt.py - lpgbt2 object initialised!
2024-02-28 16:51:56,222 - INFO - Lpgbt.py - lpgbt3 object initialised!
2024-02-28 16:51:56,224 - INFO - Lpgbt.py - lpgbt4 object initialised!
2024-02-28 16:51:56,225 - INFO - Gbcr.py - gbcr1 object initialised!
2024-02-28 16:51:56,232 - INFO - Gbcr.py - gbcr2 object initialised!
2024-02-28 16:51:56,234 - INFO - Gbcr.py - gbcr3 object initialised!
2024-02-28 16:51:56,235 - INFO - Gbcr.py - gbcr4 object initialised!
2024-02-28 16:51:56,237 - INFO - Vtrx.py - vtrx object initialised!
2024-02-28 16:51:56,238 - INFO - Optoboard.py - Optoboard object initialised!
2024-02-28 16:51:56,239 - INFO - InitOpto.py - The optoboard object 'opto' in position OB0 is now available!
2024-02-28 16:51:56,244 - INFO - InitOpto.py - Starting configuration of Optoboard with serial: 00000000
2024-02-28 16:51:56,248 - INFO - Optoboard.py - Configuring lpgbt1..
2024-02-28 16:51:56,289 - ERROR - CommWrapper.py - Failed to parse the reply from flpgbtconf! Check if FelixCore is running!
2024-02-28 16:51:56,289 - INFO - InitOpto.py - configure key was not found for optoboard 00000000 in optoListConfig, it will not be automatically configured
This error will appear if the optoboard is configured using the flpgbtconf communcation tool while felix-star or Felixcore is running. Cancel any Felixcore or felix-star sessions then attempt again to configure.
For other errors where the configure key is not found, check to make sure a link status exists with FELIX by running flx-info -c 0 LINK. If no links are showing, power cycle and reconfigure FELIX then check again to make sure a LINK is established.
¶ YARR error
If when running a YARR scan the chip can configure but can't send data in any of the mask stages, the polarity of the register EPRX00INVERT might need to be changed from 0 to 1 or 1 to 0 depending on the setup. This can be done in the optoboard config file, where the register value will be shown as:
"EPRX00INVERT": [1, 1, 1, 1] # change to all 0 or all 1 depending on the needed polarity
After changing the polarity, power cycle the optoboard and reconfigure using the new value. Note that any felix-star sessions running will need to be paused to reconfigure the optoboard.