diff --git a/README.md b/README.md index b1a34eb2db7321801b4c1625189a1ec65f6c1b88..5c7bddd56e75ef614d752c229d31fd87eabbd8f7 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,6 @@ # tl;dr -10/05/2021 Use the Scan Operator together with Yarr's devel branch and labRemote's master. Edit the module config in `configs/so_modules.json`, and the scan sequence in `configs/so_yarr`. @@ -9,15 +8,24 @@ Edit the module config in `configs/so_modules.json`, and the scan sequence in `c The Scan Operator (SO) is an integration tool for scan data and DCS data, which is meant to be used during the QC procedure of the Rd53a/Rd53b modules. It uses multiple localDB scripts as well as some integrated tools to achieve these features: - Calls Yarr repeatedly to **run a sequence of scans on the chip**. + - Makes very easy to edit chip-by-chip config parameters (trims, chip name, rx and tx, ...) - Registers a module in LocalDB if it's not already there - **Monitors the Power Supply** (PS) powering the ASIC and storing the DCS data in **InfluxDB** - Synchronizes the DCS data and the scan data in **LocalDB**. - - Makes very easy to edit chip-by-chip config parameters (trims, chip name, rx and tx, ...) - - Checks that temperature and humidity are within a safe range before proceeding to the scans - - Performs IV/VI scans on the Sensor / Module All the DCS-related functionality is optional. The SO provides scripts based on labRemote (LR) to monitor DCS in real time, but any other external tool can also be used as long as it is capable of uploading the DCS data to InfluxDB. + +# Other independent tools included in the SO + +This repository includes the following independent tools: + + - `libDCS/iviscan.py`: safely performs sensor IV and module VI scans + - `libDCS/qaqc.py`: Controls and monitors a power supply. Optionally uploads PS data to influxDB until killed + - `libDCS/parameterOptimizer.py`: Performs trim scans, tap scans, etc on a selected chip to find its best configuration. + +More on this tools [here](#useful-independent-tools). + # Quick Tutorial ### Requirements @@ -29,7 +37,7 @@ To run the Scan Operator, you need *at least*: ## 1. Get the code -If you want to use the SO's DCS integrated tool, start by cloning and building labRemote. *You don't need to do it in another case*. +If you want to use any PS-related functionality, start by cloning and building labRemote. *You don't need to do it in another case*. Make sure to enable the Python bindings using cmake's `-DUSE_PYTHON=on` flag. For a detailed installation guide, follow [labRemote's readme](https://gitlab.cern.ch/berkeleylab/labRemote/). @@ -48,27 +56,12 @@ cmake3 -DUSE_PYTHON=on .. && make -j6 git clone --recursive https://gitlab.cern.ch/YARR/utilities/scan-operator.git ``` -**Use the appropriate version of Yarr** -Yarr's devel is OK. Use Master if devel gives any problem. - - ## 3. Run the Scan Operator The Scan Operator uses many configuration files, all of them located by default under `./configs`. Most of them are intuitive and the SO will tell you when you need to modify them. +Start from `./ScanOperator.sh` to see a complete list of options. -``` -$ ./ScanOperator.sh -Help: - -m [str] : Serial number of the module - -W : upload Yarr's results to localDB (scanConsole's -W) - -o : turn on / off the output of the PS before and after all the scans - -e : Check if T and H are within a setting range before running each scan - -d : Monitor the PS and upload the DCS data to influxDB. - -t : Move DCS data from InfluxDB to LocalDB after each scan. - -c : Create / override Yarr's config files for your chip. - -q : "quiet" mode (cleaner output). -``` ### List of arguments *(a more detailed explanation of the output of `./ScanOperator.sh`)* @@ -79,10 +72,14 @@ Help: #### Optional -- `-c:` Create / overwritte Yarr config files (`controller`, `connectivity` and chip cfg files). Use this option if you are using a module for the first time or you want to regenerate its config from scratch. The cfg files are created in the Scan Operator folder, so everything you have under Yarr's one remains untouched. Summarizing, "-c" does the following. +- `-c:` Create / overwritte Yarr config files (`controller`, `connectivity` and chip cfg files). Use this option if you are using a module for the first time or you want to regenerate its config from scratch. Summarizing, "-c" does the following. - Retrieves the files from localDB if the module is already registered and the connection is good. Creates them offline otherwise. - Edits them based on `so_modules.json` + +The cfg files are created in the Scan Operator's folder, so everything you have under Yarr's one remains untouched +- `-s:` Doesn't look for changes in the config. Can be useful when runing the SO without having modified `so_modules.json`. Saves some time. + - `-W:` This one is equivalent to the `-W` option used when calling Yarr's ScanConsole - `-Q:` This one is equivalent to the `-Q` option you use when calling Yarr's ScanConsole @@ -105,10 +102,10 @@ Here are some example use cases of the Scan Operator. #### *Hello world* ```bash -./ScanOperator.sh -m module_id -c +./ScanOperator.sh -m module_id ``` -You should start from here before going any further. This will just run in series the scans you specified in `scan_list` (in `so_modules.json`). All the DCS / LocalDB / InfluxDB functionality is disabled. +You should start from here before going any further. This will just run in series the scans you specified in `scan_list` (in `so_yarr.json`). All the DCS / LocalDB / InfluxDB functionality is disabled. #### *QC procedure* @@ -129,14 +126,14 @@ If you want to use the SO to monitor DCS (`-d`) and synchronize the DCS data and ``` #### *Monitoring DCS with an external tool* -Say you are using your own tool to upload DCS data to InfluxDB, while using the SO to run all the scans. +Say you are using your own tool (e.g. `libDCS/qaqc.py`) to constantly upload DCS data to InfluxDB, while using the SO to run all the scans. -If it works in real-time, you can use `-t`. If not, do just +Then you can omit -d ```bash -./ScanOperator.sh -m module_id configs/m_powersupply.json -W +./ScanOperator.sh -m module_id configs/m_powersupply.json -W -t ``` -and you will see this before the SO finishes running. +If it doesn' work in real time, use just -W and you will see this message once the SO finishes each scan: ``` [ info ][so] If you want to upload to localDB the DCS data associated to all the scans you have just run (assuming you have it @@ -145,7 +142,7 @@ and you will see this before the SO finishes running. bash /home/mario/work/scan-operator/data/201214_051/moveDCStoLocalDB.sh path/to/idb_to_ldb.json ``` -Refer to the following section if you need any help filling the config file. +Refer to the following section if you need any help filling the config files. ### The SO configuration files @@ -163,23 +160,27 @@ Most of the items are self-explanatory. Here are the ones that may require some - **`.modules`**: Write here the configs for as many modules as you want. The file comes with an example for a SCC and an example for a quad. You will choose between the modules you have defined here in the command line. Notes: - - The name of each module (e.g. `moduleid_quad`) should match the Serial Number of the module. + - The name of each module (e.g. `moduleid_quad`) should (but doesn't have to) match the Serial Number of the module. - For each chip: - For any key written in `"GlobalConfig"`, the Scan Operator will: - - Look for it in Yarr's general chip config file (e.g. `rd53a_test.json`) under `.RD53A.GlobalConfig`. + - Look for it in Yarr's chip config file (in `configs/rd53x`) under `.RD53A.GlobalConfig`. - If found, change the value to the one specified by the user. - If not found, create it and continue. - The same goes for the `"connectivity"` and the `"Parameter"` section. #### Yarr's general configuration file (so_yarr.json) - - **`.scan_list`**: Place here the sequence of scans that you want to run. For a threshold / tot tuning, the second argument in the bracket represents the target threshold / tot (e.g. `["diff_retune_pixelthreshold", 1000]` will retune the pixel threshold of the differential FE to 1000 e), whilst `["diff_tune_globalpreamp", 7]` will tune the ToT to 7). The target charge for ToT tuning / scan is specified under `.YARR.scan` and it's assumed to be the same for all the ToT-related scans. - - **`common_config.max_trials_in_case_of_failure`**: Sometimes, you might get a segfault from Yarr comming from corrupted data. Normally just resumming the scan sequence from where you left it does the job. This option does it for you. + - **`.scan_list`**: Place here the sequence of scans that you want to run. + + - For a threshold / tot tuning, the second argument in the bracket represents the target threshold / tot (e.g. `["diff_retune_pixelthreshold", 1000]` will retune the pixel threshold of the differential FE to 1000 e), whilst `["diff_tune_globalpreamp", 7]` will tune the ToT to 7). The target charge for ToT tuning / scan is specified under `.YARR.scan` and it's assumed to be the same for all the ToT-related scans. + + - For the rest of the scans, the second argument is Yarr's mask option (Yarr's `-m`), either 1, 0 or nothing (Yarr's default). + - **`.common_config.max_trials_in_case_of_failure`**: Sometimes, you might get a segfault from Yarr comming from corrupted data. Normally just resumming the scan sequence from where you left it does the job. This option does it for you. #### Powersupply configuration file (lr_powersupply.json) -Contains the actual information to establish communication with the PS as well as the definition of the channels. Amongst all the channels you have defined, select the ones you want to use in "channels_to_be_used_by_the_scanoperator". The SO will ignore any channel not appearing there. +Contains the information to establish communication with the PS as well as the definition of the channels. Amongst all the channels you have defined, select the ones you want to use in "channels_to_be_used_by_the_scanoperator". The SO will ignore any channel not appearing there. - **`.devices`**: Write here the PS / PSs you want to use. A list of supported "`hw-model`" and "`protocol`" is available in labRemote's docs. To find the port your PS is connected to, look at the output of `ls -l /dev/serial/by-id/`. @@ -200,7 +201,7 @@ Contains the actual information to establish communication with the PS as well a #### InfluxDB to LocalDB configuration file (idb_to_ldb.json) - Used when associating any DCS/ENV data to the scans in LocalDB + Used when associating any DCS/ENV data to the scans in LocalDB - `.influxdb_cfg`: Which DB you want to take the data from. @@ -246,20 +247,45 @@ The SO puts all the scan data under the `data/` folder. There, the data is organ -# Tools +# Useful Independent tools ## IV / VI scan script (./libDCS/iviscan.json) - Run `python3 libDCS/iviscan.py -h` for a list of options - Edit all the scan parameters in `configs/lr_iviscan.json` -## PS Controller / monitor tool +You can specify the number of measurements per step and the sleeping time between measurements. Moving to the initial point, and going back to the initial state after finishing scan is done ramping amoothly. The measured values per step, as well as their standard deviation is displayed in the terminal in real time. -Provides a set of commands to remotely control the PS -It is capable of running in the background uploading PS data (HV, LV, ...) to influxDB at fixed time intervals. +## PS Controller / monitor tool - `python3 libDCS/qaqc.py -h` for a complete set of options. -- (TODO: Exapand this section a little bit more) + +This script can be used to remotely control a power supply. (set/get-voltage, power on/off, etc). It can also be left running in the background (e.g. in a `screen`) constantly monitoring a single channel and uploading the data to influxDB. + +- ## Parameter Optimizer + +- `python3 libDCS/parameterOptimizer.py -h` for usage information + +Used to quickly find the best config values for a single chip. Can be used to scan trim values, tap values or any other config value. Builds a 2D matrix with all the value combinations and fills it in real-time on the terminal. A sample output for a trim scan made with this too is the following: + +``` +haxis: CmlTapBias1; vaxis: CmlTapBias0 + + # 0 100 200 300 400 + 300 76800.0 0.0 8.0 -1.0 -1.0 + 400 258.0 0.0 0.0 1971.0 -1.0 + 500 0.0 0.0 0.0 0.0 54638.0 + 600 0.0 0.0 0.0 0.0 27142.0 + 700 0.0 0.0 0.0 0.0 3513.0 + 800 0.0 0.0 0.0 0.0 0.0 + 900 0.0 0.0 0.0 0.0 0.0 +``` + +The numbers in the matrix indicate the number of failing pixels (0's in the enMask) from a digital. + +The script tries to look for the best region by itself. Once found, you can wait for the whole matrix to get filled, or just kill the script at any stage. After using this script run the SO once, just to reset the configuration to its original state. + + # FAQs diff --git a/ScanOperator.sh b/ScanOperator.sh index 0a71c3bd049929df6d1a8d82648d27362432c0b3..edce21610918e1186305cef3873a7900d118ecc6 100755 --- a/ScanOperator.sh +++ b/ScanOperator.sh @@ -492,7 +492,6 @@ cat $cfgdir/connectivity.json | jq . echo "------------------------" - if [ $dcsOnOff == 1 ] ;then echo -e "\n[ info ][so] Turning ON the PS..." diff --git a/configs/so_yarr.json b/configs/so_yarr.json index a4b44b91a49037d7e20e0c6a63e6ea7b85ef3e32..2c9072accb1322414832c288f835659e0dd60488 100644 --- a/configs/so_yarr.json +++ b/configs/so_yarr.json @@ -3,33 +3,32 @@ "common_config": { "max_trials_in_case_of_failure": 3, - "target_preamp": 10000, - "reset_pixel_masks": 0 + "target_preamp": 10000 }, "scan_list": [ - ["std_digitalscan"], + ["std_digitalscan", 1], ["std_analogscan"], ["std_thresholdscan"], - ["diff_tune_globalthreshold", 3000], - ["diff_tune_pixelthreshold", 3000], + ["diff_tune_globalthreshold", 2000], + ["diff_tune_pixelthreshold", 2000], ["diff_tune_globalpreamp", 7], - ["diff_retune_globalthreshold", 3000], - ["diff_retune_pixelthreshold", 3000], + ["diff_retune_globalthreshold", 2000], + ["diff_retune_pixelthreshold", 2000], ["diff_thresholdscan"], ["diff_totscan"], ["lin_tune_globalthreshold", 2000], ["lin_tune_pixelthreshold", 2000], - ["lin_retune_globalthreshold", 3000], - ["lin_retune_pixelthreshold", 3000], + ["lin_retune_globalthreshold", 2000], + ["lin_retune_pixelthreshold", 2000], ["lin_tune_globalpreamp", 7], - ["lin_retune_globalthreshold", 3000], - ["lin_retune_pixelthreshold", 3000], + ["lin_retune_globalthreshold", 2000], + ["lin_retune_pixelthreshold", 2000], ["lin_thresholdscan"], ["lin_totscan"], - ["syn_tune_globalthreshold", 3000], + ["syn_tune_globalthreshold", 2000], ["syn_tune_globalpreamp", 7], - ["syn_tune_globalthreshold", 3000], + ["syn_tune_globalthreshold", 2000], ["syn_thresholdscan"], ["syn_totscan"] ] diff --git a/scanLauncher.sh b/scanLauncher.sh index 1e1bab98ddcde53a887fb55e647eebf8fd359476..8e632f735cfdc440972d562cd8a187b6c8c536d9 100755 --- a/scanLauncher.sh +++ b/scanLauncher.sh @@ -104,8 +104,8 @@ else targetAmpOrCharge="" fi fi -# Build Yarr's "-m" option (reset px masks, default 0) -reset_masks=0 +# Build Yarr's "-m" option (reset px masks, default -1 (same as in Yarr)) +reset_masks=-1 if echo "${scanName}" | grep "digital\|analog\|noise" >>/dev/null; then if [[ $(echo $scan | jq '. | length') == 2 ]]; then reset_masks=$(echo $scan | jq -r '.[1]')