Skip to content
Snippets Groups Projects

2.1. Configuration files

Last edited by Thomas Christian Senger

BDAQ53 comes with only two configuration files that are intended to be changed by the user:

  • testbench.yaml defines properties of your test environment (hardware, setup, ...).
  • periphery.yaml defines optional power supplies if they should be controlled by BDAQ. See Periphery.

All configuration parameters used in a scan are stored in the same data file where also the chip data of the scan is stored. See Output files for more details.

The standard settings of chips, that is also used for the first scan, can be changed in the appropriate chip_name.yaml in the chips folder. This is usually not needed and the std. settings are frequently updated by bdaq developers to match current chip operation knowledge.

Testbench configuration file

The testbench configuration file is located at [BDAQ root directory]/bdaq53/testbench.yaml and defines the properties of your test environment:

general: # General configuration
  output_directory: # Top-level output data directory, default is the current folder where the bdaq script is started
  use_database: True  # Check if chip is in data base, log error if not
  abort_on_rx_error: True # Abort scan when RX error occurs

periphery: # Configuration of the BDAQ53 Periphery module
  enable_periphery: False
  monitoring: False # Monitor all connected powersupplies and sensors regularly
  monitoring_interval: 10 # Interval for DCS monitoring in seconds
  analog_monitoring_board: False

# Connected Modules
modules:
  module_0: # Arbitrary name of module, defines folder name with chip sub folders
    identifier: "unknown" # Module/wafer/PCB identifier, has to be given (e.g. SCC number)
    powersupply:
      lv_name: LV-0
      lv_voltage: 1.7
      lv_current_limit: 2.0
    #   hv_name: HV-0
    #   hv_voltage: 5
    #   hv_current_limit: 1e-6
    power_cycle: False # power cycle all chip of this module before scan start
    chip_0: # Arbitrary name of chip, defines folder name with chip data
      chip_sn: "0x0001"
      chip_type: "rd53a"
      chip_id: 0
      receiver: "rx0" # Aurora receiver channel (ranges from 'rx0' to 'rxN', N board-dependent)
      chip_config_file: # If defined: use config from in file (either .cfg.yaml or .h5). If not defined use chip config of latest scan and std. config if no previous scan exists
      record_chip_status: True # Add chip statuses to the output files after the scan (link errors and powering infos)
      use_good_pixels_diff: False
      send_data: "tcp://127.0.0.1:5500" # Socket address of online monitor

  # module_1:  # Arbitrary name of module, defines folder name with chip sub folders
  #   identifier: "unknown" # Module/wafer/PCB identifier, has to be given (e.g. SCC number)
  #   powersupply:
  #     lv_name: LV-0
  #     lv_voltage: 1.7
  #     lv_current_limit: 2.0
  #   #   hv_name: HV-0
  #   #   hv_voltage: 5
  #   #   hv_current_limit: 1e-6
  #   power_cycle: False  # power cycle all chip of this module before scan start
  #   chip_0:  # Arbitrary name of chip, defines folder name with chip data
  #     chip_sn: "0x0002"
  #     chip_type: "itkpixv1"
  #     chip_id: 15
  #     receiver: "rx4" # Aurora receiver channel (ranges from 'rx0' to 'rxN', N board-dependent)
  #     chip_config_file: # If defined: use config from in file (either .cfg.yaml or .h5). If not defined use chip config of latest scan and std. config if no previous scan exists
  #     record_chip_status: True  # Add chip statuses to the output files after the scan (link errors and powering infos)
  #     use_good_pixels_diff: False
  #     use_ptot: True  # Enable PTOT mode
  #     send_data: "tcp://127.0.0.1:5500" # Socket address of online monitor


  #   chip_1:
  #     ...
  # module_1:
  #   ...

hardware: # Setup-specific hardware settings
  bypass_mode: False # Configure chip and BDAQ board for bypass mode. You have to provide all clocks externally!
  enable_NTC: False # Only enable if you know you have the correct resistors mounted on the BDAQ board!

TLU:
  TRIGGER_MODE: 0 # Selecting trigger mode: Use trigger inputs/trigger select (0), TLU no handshake (1), TLU simple handshake (2), TLU data handshake (3)
  TRIGGER_SELECT: 1 # Selecting trigger input: HitOr (individual, TDC loop-through) (16), RX1 (multi purpose) (8), RX0 (TDC loop-trough) (4), HitOR [DP_ML_5 and mDP] (logical OR of all eight lines) (3), HitOR [mDP only] (logical OR of all four lines) (2), HitOR [DP_ML_5 only] (logical OR of all four lines) (1), disabled (0)
  TRIGGER_INVERT: 0 # Inverting trigger input: HitOr (individual, TDC loop-through) (16), RX1 (multi purpose) (8), RX0 (TDC loop-trough) (4), HitOR [DP_ML_5 and mDP] (logical OR of all eight lines) (3), HitOR [mDP only] (logical OR of all four lines) (2), HitOR [DP_ML_5 only] (logical OR of all four lines) (1), disabled (0)
  TRIGGER_LOW_TIMEOUT: 0 # Maximum wait cycles for TLU trigger low.
  TRIGGER_VETO_SELECT: 0 # Selecting trigger veto: AZ VETO (2), RX FIFO full (1), disabled (0). Set to (2) if SYNC FE is enabled.
  TRIGGER_HANDSHAKE_ACCEPT_WAIT_CYCLES: 5 # TLU trigger minimum length in TLU clock cycles
  DATA_FORMAT: 0 # Select trigger data format: only trigger number (0), only time stamp (1), combined, 15 bit time stamp + 16 bit trigger number (2)
  EN_TLU_VETO: 0 # Assert TLU veto when external veto. Activate this in order to VETO triggers if SYNC FE is enabled.
  TRIGGER_DATA_DELAY: 31 # Depends on the cable length and should be adjusted (run scan/tune_tlu.py)

TDC:
  EN_WRITE_TIMESTAMP: 1 # Writing trigger timestamp
  EN_TRIGGER_DIST: 1 # Measuring trigger to TDC delay with 640MHz clock
  EN_NO_WRITE_TRIG_ERR: 1 # Writing TDC word only if valid trigger occurred
  EN_INVERT_TDC: 0 # Inverting TDC input
  EN_INVERT_TRIGGER: 0 # Inverting trigger input, e.g. for using Test output from EUDET TLU.

calibration: # Setup-specific calibration constants
  bdaq_ntc: # Resistors on BDAQ board for NTC readout
    R16: 200.00e3
    R17: 4.75e3
    R19: 2.50e3

notifications: # Notification settings
  enable_notifications: False
  slack_token: "~/slack_api_token"
  slack_users:
    - AAAAAA123

# Standard analysis settings
# Scans might overwrite these settings if needed.
# Detailed description of parameters in bdaq53/analysis/analysis.py
analysis:
  skip: False # Omit analysis in scans
  create_pdf: True # Create analysis summary pdf
  module_plotting: True  # Create combined plots for chip in a module
  store_hits: False # store hit table
  cluster_hits: False # store cluster data
  analyze_tdc: False # analyze TDC words
  analyze_ptot: False  # analyze PTOT words (only possible for RD53B)
  use_tdc_trigger_dist: False # analyze TDC to TRG distance
  align_method: 0 # how to detect new events
  chunk_size: 1000000 # scales amount of data in RAM (~150 MB)
  blocking: True # block main process during analysis

Although most parameters have comments, some parameters in the testbench.yaml are explained in more detail here:

  • general section:

    • output_directory: Here you can define the full path to your data output directory. The default is your current working directory + /output_data/. In the data output directory a sub-directory structure is created according to the modules section.

  • modules section: Here you have to define all the modules in your test setup connected to one readout board. Each module_N entry must have an identifier (e.g. SCC card, module ID, wafer ID). For multi-chip modules add as many chips as are mounted on the module. For each module entry one can optionally specify power supplies connected to the module (required when periphery is enabled). Note: The section names for the module and chip entries (module_N, chip_M) can be arbitrarily chose and can also be different from the proposed scheme. It merely defines the folder structure, where data is stored.

    • chip_M entry: Defines the configuration of one front-end chip in the setup.
      • chip_type: The type of the chip under test, i.e. 'rd53a' or ...
      • chip_sn: The Serial Number of the chip under test.
      • chip_id: The chip command receiver ID. 8 means broadcast to all chips. 0 is the default if you only have one chip connected to your BDAQ board. If you connect multiple chips, make sure they have different chip IDs.
      • receiver: The Aurora receiver channel on the readout board used to readout this chip. 'rx0' is the default if you only have one chip connected. Depending on which readout board/firmware is used you can connect more than one chip and assign the appropriate receiver channel (up to 'rx6' with BDAQ board).
      • send_data: This parameter defines the socket address of the bdaq53 online monitor (see Online monitor). If you want to run the online monitor on the same PC that is running BDAQ, leave this parameter to be localhost.
      • chip_configuration: This parameter allows to pin the chip configuration file that is used. Usually, one can leave this empty and BDAQ automatically finds the correct chip configuration file corresponding to chip_type and the folder structure.
      • disable_pixel: single pixel can be disabled or larger areas by using start_column:stop_column, start_row:stop_row. For example: 
           disable_pixel:
     - 0, 0 #single pixel
     - 12, 13
     - 10:50, 0:100 #large area

  • hardware section:

    • bypass mode: Set to True if you connected your chip to an external clock and want it to run in Bypass Mode.
    • enable_NTC: Set to True to enable the NTC readout, if you know you have the correct resistors, components on jumpers soldered on your BDAQ board.

  • TLU section: Collection of settings to configure a Trigger Logic Unit connected to your setup. For a more detailed explanation, please have a look here. Usually, this can be left untouched, since the scans using the TLU module will configure it automatically.

  • TDCsection: Collection of settings to configure the TDC firmware module. Usually, this can be left untouched, since the scans using the TDC module will configure it automatically.

  • calibration section: This section contains setup specific (not chip / SCC specific(!)) calibration values.

    • `bdaq_ntc: This item contains the three resistor values for the NTC readout circuit, which define the readable temperature range. Refer to NTC readout Make sure these match the actual resistor values soldered to your board if you want to use the NTC.

  • notification section:

    • slack_token: If you are using Slack, bdaq53 can notify you vie direct message once a scan has finished. To use this feature, create a Slack bot with direct message privileges on the Slack website and copy the resulting API token here or to a file on your computer and put the path to this file here.
    • notify_users: The Slack user direct message ID of people you want to be notified by your Slack bot. You can find this ID in the URL of a direct message with the user or channel.

Changing the chip configuration

When running a scan the configuration from the previous scan is used or the std. chip configuration from the default configuration file. If you want to change a chip setting, you can use the chip section in the testbench.yaml. All sections from the default chip configuration file are supported (trim, register, calibration, masks). For example, the default configuration for RD53A defines the following values in 4 sections:

chip_type          : rd53a
# Default trimbit values obtained from statistical analysis.
# If you need more exact values, please trim your individual chip.
trim:
  VREF_A_TRIM      : 24
  VREF_D_TRIM      : 23
  MON_BG_TRIM      : 12
  MON_ADC_TRIM     : 5

# Default calibration values should be ok to get an order of magnitude reading.
# If you need more exact measurements, please calibrate your individual chip.
calibration:
  ADC_a            : 0.2     # Conversion factors ADC counts - voltage: slope
  ADC_b            : 15.5    # Conversion factors ADC counts - voltage: offset
  Nf               : 1.24    # Chip specific conversion factor for on-chip T sensors: voltage - temperature

  # Default charge calibration is based on 50x50um modules and should be ok for bare chips as well.
  # For optimal results, perform a charge calibration on your individual chip!
  e_conversion:
    # [slope] = Electrons / Delta VCAL
    slope          : 10.4
    slope_error    : 0.10
    # [offset] = Electrons
    offset         : 180
    offset_error   : 60

# DAC settings (inner layer, bare chip, 5 uA operating point)
# For other settings, have a look at the individual FE guides.
registers:
  IBIASP1_SYNC     : 90
  IBIASP2_SYNC     : 140
  IBIAS_SF_SYNC    : 80
  IBIAS_KRUM_SYNC  : 55
  IBIAS_DISC_SYNC  : 300
  ICTRL_SYNCT_SYNC : 100
  VBL_SYNC         : 380
  VTH_SYNC         : 390
  VREF_KRUM_SYNC   : 450
  CONF_FE_SYNC     : 0x0002 # High gain, normal ToT

  PA_IN_BIAS_LIN   : 350
  FC_BIAS_LIN      : 20
  KRUM_CURR_LIN    : 32
  LDAC_LIN         : 130
  COMP_LIN         : 110
  REF_KRUM_LIN     : 300
  Vthreshold_LIN   : 415

  PRMP_DIFF        : 511
  FOL_DIFF         : 542
  PRECOMP_DIFF     : 512
  COMP_DIFF        : 1023 # (FPM), for FEM use 528
  VFF_DIFF         : 40   # (FPM), for FEM use 140
  VTH1_DIFF        : 600
  VTH2_DIFF        : 50
  LCC_DIFF         : 20
  CONF_FE_DIFF     : 0 # Default: LCC off, if leakage current higher than 1 nA, LCC can be switched on.

To change the VREF_A_TRIM trim from the std. value of 24 to 30 and the linear FE threshold to 450 one has to specify in the testbench.yaml

modules:
  module_0: # Arbitrary name of module, defines folder name with chip sub folders
    identifier: "unknown" # Module/wafer/PCB identifier, has to be given (e.g. SCC number)
    chip_0: # Arbitrary name of chip, defines folder name with chip data
      chip_sn: "0x0001"
      chip_type: "rd53a"
      trim:
        VREF_A_TRIM: 30
      registers:
        Vthreshold_LIN: 450