Configuration
The User Interface of dirigent depends on 3 different files. Each of them fulfils a different purpose. From these files, all required files for the tuning are created and scans are run. Following, each of the files is explained in detail:
dirigent.toml
The main dirigent configuration file is written in TOML format. A documented example file (including sensible configuration values for all global and calibration-specific parameters) is provided in the config/ folder.
Please pay attention to the version number written at the top of the configuration file underneath the logo. As dirigent is developed, older dirigent.toml files may no longer work as expected. After installation of a new dirigent version, please also use the dirigent.toml file provided with that installation.
Configuration parameters within this file match the CLI interface for a calibration 1 to 1. This means, that every entry in this file represents an option flag that could also be added in the command line. For example, the global option --module-json modules.json may be specified either in the command line, when running the calibration similar to the following example:
dirigent -C dirigent.toml --module-json modules.json <dirigent calibration name>
or it can be set in the TOML config as follows:
module_json = modules.json
If you define the same variable in both places, the entry in the command-line will overwrite the entry in the configuration file.
The first part of the dirigent.toml file applies to every dirigent calibration that is run. The second part is then separated into the different possible calibrations. To make the overview a bit simpler, the settings, that apply to every dirigent calibration can be separated into 3 sections:
Global settings
Currently only the verbosity level of dirigent. Usually no change is required here.:
verbosity = 1 # 2 for debugging mode (will be a lot of printout)
Ph2_ACF definition and support files
Here, the supporting files and technical information about the setup is defined. Software and firmware versions for the Ph2_ACF implementation can be given and the ip address of the FC7 has to be set.:
# Info related to modules and Ph2_ACF
fc7_address = '192.168.10.100'
module_json = 'modules.json'
instruments = 'instruments.json'
ph2_dir = '' # path to ph2_acf install folder - If empty, it is assumed, that ph2_acf is loaded already
xml_file = '' # path to CMSITminiDAQ XML file - If empty, 'CMSIT.xml' will be used
firmware = '' # name of the firmware on the SD card - If empty, current firmware will be used
felis = false # indicates if Felis should be executed and uploads are to be performed
Be aware, that the upload to Panthera with felis will ask you for your credentials after the calibration. Also this is currently not implemented for all calibrations (principally for the module_calibration calibration).
If the directory, where dirigent is executed already features a CMSIT.xml file, the file is not overwritten. This means, that the here indicated FC7 ip address and the information about the module are ignored. This is on purpose to allow any file to be used. If it is desired to start with a clean file, it is sufficient to just remove the CMSIT.xml file. The TXT files are then overwritten.
Note, that the actual description of the desired CMSIT.xml file is discussed in the section modules.json.
Monitoring information
Here, monitors are enabled or disabled. A monitor is working in the background and has a functionality as software interlock. Also it saves the measured values to a file that is then stored in the results folder of dirigent.
For each monitor, there are two parameters: add_*_monitor activates the monitor with default values.
Currently, there are four different monitors:
leakage_monitor (HV supply)
supply_monitor (LV supply)
climate_monitor (climate chamber)
coldbox_monitor (coldbox)
Expert users may want to change the monitoring parameters. To do this, *_monitor_settings can be used to overwrite default settings. This is a list of variables. In the dirigent.toml file, an explanation of the monitor options is listed in the default configuration file. For every standard operation, it should be enough to just turn the monitors on or off. Therefore, it is not recommended to change these settings for non-experts:
# Options for Monitors in Monitoring
add_leakage_monitor = true
# To change the behaviour of the monitor, uncomment the `leakage_monitor_settings` line. Each element corresponds to a different property as explained following (in order of the list):
# - Name of the monitor (DEFAULT: "LeakageMonitor")
# - Allowed current before interlock sets in - If this value is higher than the compliance current, interlock is factually turned off (DEFAULT: "1e-4")
# - Polling interval in seconds (DEFAULT: "1")
# - Integration cycles (only applies to Keithley24* devices) (DEFAULT: "1")
# - Averages (also only for Keithley24* devices) (DEFAULT: "1")
# - monitor broker / host for the mqtt client to send monitoring data to (DEFAULT: "" (which also means, that this feature is off)) - Do not enable, if no mqtt client is running
#leakage_monitor_settings = ["LeakageMonitor","1e-4","1","1","10","localhost"]
add_supply_monitor = true
# To change the behaviour of the monitor, uncomment the `supply_monitor_settings` line. Each element corresponds to a different property as explained following (in order of the list):
# - Name of the monitor (DEFAULT: "SupplyMonitor")
# - Polling interval in seconds (DEFAULT: "1")
# - Enable interlock (DEFAULT: "True")
# - Desired operation mode in constant current ("cc") or constant voltate ("cv") operation. If mode changes, interlock is triggered (DEFAULT: "cc")
# - channel to monitor on. "-1" means default channel (DEFAULT: "-1")
# - monitor broker / host for the mqtt client to send monitoring data to (DEFAULT: "" (which also means, that this feature is off)) - Do not enable, if no mqtt client is running
#supply_monitor_settings = ["SupplyMonitor","1","False","cc","-1","localhost"]
add_climate_monitor = false
# To change the behaviour of the monitor, uncomment the `climate_monitor_settings` line. Each element corresponds to a different property as explained following (in order of the list):
# - Name of the monitor (DEFAULT: "ClimateMonitor")
# - Maximal allowed temperature in (degC) (Interlock condition) (DEFAULT: "60")
# - Maximal allowed relative humidity (in percent) (DEFAULT: "80")
# - Polling interval in seconds (DEFAULT: "2")
# - monitor broker / host for the mqtt client to send monitoring data to (DEFAULT: "" (which also means, that this feature is off)) - Do not enable, if no mqtt client is running
#climate_monitor_settings = ["ClimateMonitor","60","80","2","localhost"]
add_coldbox_monitor = false
# To change the behaviour of the monitor, uncomment the `climate_monitor_settings` line. Each element corresponds to a different property as explained following (in order of the list):
# - Name of the monitor (DEFAULT: "ColdboxMonitor")
# - Maximal allowed temperature in (degC) (Interlock condition) (DEFAULT: "60")
# - Polling interval in seconds (DEFAULT: "2")
# - monitor broker / host for the mqtt client to send monitoring data to (DEFAULT: "" (which also means, that this feature is off)) - Do not enable, if no mqtt client is running
#climate_monitor_settings = ["ColdboxMonitor","60","2","localhost"]
If one of these devices is not connected, please do turn off the respective monitor too. Dirigent should catch this, but it is still better to not have unreasonable settings.
Calibration settings
These settings are the settings that apply to a specific calibration and are not used for any other calibration than the indicated one. Calibration-specific configuration values are specified in a section corresponding to the calibration with the same name. For TOML this looks as follows:
[iv_curve]
max_voltage = -350
The settings belonging to a specific calibration will have no influence on the performance on another calibration.
To find out the options that can be set for each calibration, it is helpful to consider the information for calibrations:
dirigent -C dirigent.toml <calibration_name> --help
It’s important to remember: sensible defaults are provided in the calibration files themselves (e.g. module_testing/calibrations/iv_curve.py). These will be overridden by the config file, which in turn will be overridden by any options specified on the command line. The settings for the calibrations relevant for the production will be fixed at some point. When this has been done, these default settings should be used.
Instruments.json
The other two required files are both in JSON format. Reason for this, is, that they are very nested and this is better handled in this format.
The instruments.json file defines the instruments used for the setup and which channel is connected to which module. This is separated in two parts; a definition of the instruments in the setup (generally just all instruments without indicating a specific role) using the "instruments" node (or dictionary) and an assignment of instrument channels to their respective modules with an indication of their roles using the "channels" node (or dictionary). These are described in the following sections.
“instruments” dictionary
The definition of the instruments is done in the "instruments" node. Here, each instrument is built as a dictionary with an assigned key used later to assign it to the respective channels. An example of some ICICLE instrument definitions can be found in config/instruments.json. The definition of a low voltage power supply and a high voltage power supply can look like this:
"lv_1": {
"class": "TTI",
"resource": "ASRL/dev/tti::INSTR",
"default_voltage": 2,
"default_current": 8
},
"hv_1": {
"class": "Keithley2410",
"resource": "ASRL/dev/keithley2410::INSTR",
"default_voltage": -80,
"default_current": 5e-6
},
The class indicates the ICICLE instrument class that is to be used. There are many options available, including but not necessarily limited to:
HV supplies:
"Keithley2410"
"Keithley2470"
"CaenDT8033N"
LV supplies:
"TTI"
"HMP4040"
"KeysightE3633A"
Probe (or 'needle') cards
"ETHProbecard"
"PSIProbecard"
Climate chamber/temperature-controlled boxes
"Binder"
"PSIColdbox"
The resource has to be given in VISA syntax. For serial devices, this means:
ASRL<absolute path to device>::INSTR
Typically:
ASRL/dev/ttyUSBx::INSTR
Devices connected through TCPIP will have:
TCPIP::<ip address>::<port>::SOCKET
For the PSIProbecard ICICLE instrument (TEPX-flavour probe cards), a unique resource is currently required. The device’s channel number must be appended to TCPIP. For example, if the probe card you wish to use is connected to channel 4 of the 8-channel PSIColdbox instrument, your resource should look like:
TCPIP4::<ip address>::1883::SOCKET
Note that the port is always 1883 for PSIColdbox and PSIProbecard instruments.
The rest of the parameters are default values to be set for all the channels of the devices. They do carry generic names, but should be quite clearly understandable (be aware, the default_voltage and default_current are enforced for HV and LV power supplies):
default_voltage : normal operation voltage for the device.
Recommendations: LV: 2V (with sensing) | HV: -80V
default_current : normal operation current / compliance current.
Recommendations: LV: 2A per chip | HV: 5e-6 (depends strongly on the sensor quality)
default_delay : delay between voltage steps for HV supply.
Recommendations: between 0 and 2 (seconds)
default_step_size : step size for normal ramping of HV supply.
Recommendations: usually 5V or 10V (default 5V)
Some additional, optional parameters for different instruments are discussed here:
"lv_1": {
"class": "TTI",
"resource": "ASRL/dev/tti::INSTR",
"default_voltage": 2,
"default_current": 8,
"wait_time": 5
},
"cb_1": {
"class": "PSIColdbox",
"resource": "TCPIP::192.168.6.27::1883::SOCKET",
"default_temperature": 15,
"temperature_tolerance": 0.5,
"validation_time": 20,
"validation_timeout": 600
}
"wait_time" for LV-type instruments will simply pause for the number of seconds provided after powering on a device. This can be useful to allow modules to properly power on (or “settle”) before continuing with automated measurements. However, this can also be used in combination with manually-controlled cooling devices. When powering on an already cooled module, the temperature increase can cause stable Peltier elements to react, and increase their power, and enter into overshoot-undershoot, oscillatory behaviour. Results of I-V measurements can be sensitive to this, displaying increases and decreases in leakage current as a result of the fluctuating Peltier temperature.
"temperature_tolerance", "validation_time", and "validation_timeout" are unique to the PSIColdbox ICICLE instrument class. These optional parameters are used, after switching on the coldbox TECs, to validate the temperature and humidity, before continuing with measurement automation. The coldbox will attempt to set the temperature to the value given to the "default_temperature" parameter, if the dew point is low enough. If the dew point is not low enough, the temperature will be set to intermediate temperature(s) until the dew point decreases (as a result of dry air input) below the "default_temperature". Once the "default_temperature" has been reached, plus or minus the "temperature_tolerance", a timer is started equal to the value given to the "validation_time" parameter, and makes sure the temperature remains above "default_temperature" - "temperature_tolerance" and below "default_temperature + "temperature_tolerance" for the "validation_time". If the temperature goes outside of this range, dirigent waits until it re-enters this range, and starts the timer again. Once the "validation_time" has been reached, the temperature is considered stable, and measurement automation continues. To avoid potentially infinite loops, this cycle is repeated until a separate timer, started at the beginning of this process, reaches the value given to the "validation_timeout" parameter. None of these parameters are finalised, and users are expected to experiment and report on values that work best for them.
“channels” dictionary
This second part of the instruments.json file maps instrument channels to modules and assigns them roles. There is currently no absolutely strict mapping from the modules defined here and the modules as seen in the XML file and used for Ph2_ACF. Stronger links will be created soon. However, each module receives a key that in the default file is just a numbering starting from “0”. To keep an overview, it is possible, so set the module name in this key instead of the number. This key is used to name the corresponding monitor and other measurement calibrations (such as the iv_curve or the sldo_vi_curves output).
Otherwise, the structure is such, that each module has a key that can be freely chosen. This key is connected to a dictionary that contains fixed keys for each role and then information about the instrument name and channel number for each of these roles.
The following example lists a module with name 0 that is connected to channel 2 of a low voltage supply that is named lv_1 and to channel 1 of a high voltage supply named hv_2. Also it has an probe card connected that is named ab_2:
"channels":{
"0":{
"lv": {"instrument":"lv_1", "channel":2},
"hv": {"instrument":"hv_2", "channel":1},
"ab": {"instrument":"ab_2"}
}
It is to be noted, that the ETHProbecard (TBPX-flavour probe card) does not need a channel definition. The instrument control software treats each probe point of the board as one channel, so there all the channel of the device belong to the same module. However, the PSIProbecard ICICLE instrument does require a channel definition. This should be provided like the other instruments, IN ADDITION to the number appended to TCPIP in the instruments definition. A small example where the module is connected to channel 1 of the coldbox, but is using the needle card connected to channel 4 is provided below:
{
"instruments": {
"cb_1": {
"class": "PSIColdbox",
"resource": "TCPIP::197.11.152.21::1883::SOCKET",
},
"ab_1": {
"class": "PSIProbecard",
"resource": "TCPIP4::197.11.152.21::1883::SOCKET"
}
},
"channels":{
"0":{
"cb": {"instrument":"cb_1", "channel":1},
"ab": {"instrument":"ab_1", "channel":4}
}
}
}
modules.json
The third file that is needed to complete the required information to run a module tuning is the modules.json file. This also has a JSON format and contains the important information for the modules. It is built in a way, that a lot of custom settings can be filled in according to the structure of the XML file that Ph2_ACF uses. Most of the information in this file is used to create the CMSIT.xml file for Ph2_ACF.
It is to be noted, that NO new XML file will be created, if a CMSIT.xml file is already present in the run directory. This feature is intentional, and enables dirigent to automatically perform Ph2 ACF scan sequences (thradj > threqu > injdelay > etc.). If something goes wrong after running a dirigent calibration, please delete (or backup) your XML and TXT files, and allow dirigent to create the XML and TXT from scratch, using the information in the modules.json. Another use-case allows dirigent to perform calibrations on modules that have already been tuned. An appropriate XML and their TXT files can be placed in the user’s current working directory, and the xml_file parameter in the dirigent.toml can be given, with the name of the XML file (e.g. Run000016_CMSIT.xml).
Following, an example of a module setup is given:
{
"Hybrid": {
"1": {
"RD53Bv1": {
"info" : {"module_name" : "CLQ8", "type" : "2x2", "subdetector" : "TBPX", "sensor" : true},
"0": {"Lane": 0, "LaneConfig": {"outputLanes": "0001"}, "Settings": {"VOLTAGE_TRIM_DIG": 10, "VOLTAGE_TRIM_ANA": 7, "VREF_ADC": 837}},
"1": {"Lane": 1, "LaneConfig": {"outputLanes": "0001"}, "Settings": {"VOLTAGE_TRIM_DIG": 8, "VOLTAGE_TRIM_ANA": 10, "VREF_ADC": 815}},
"2": {"Lane": 2, "LaneConfig": {"outputLanes": "0001"}, "Settings": {"VOLTAGE_TRIM_DIG": 5, "VOLTAGE_TRIM_ANA": 6, "VREF_ADC": 833}},
"3": {"Lane": 3, "LaneConfig": {"outputLanes": "0001"}, "Settings": {"VOLTAGE_TRIM_DIG": 8, "VOLTAGE_TRIM_ANA": 6, "VREF_ADC": 809}}
}
}
}
}
For users, that know Ph2_ACF configuration files, this structure should be rather straightforward. Different modules are separated by Hybrid nodes. Each Hybrid number ("0", "1", "2", etc.) corresponds to the physical port on the FC7 to which the module is connected to. Currently, only ports on L12 are supported. Also it is to be noted, that the hybrids 3 and 4 have different properties and need special setting to be used.
Depending on the chip version of the module you are testing, either "RD53Bv1" or "RD53Bv2" should be used. In case, a Ph2_ACF version older than v5-01 is used, only CROCv1 is supported, and the string at this position is reduced to "RD53B".
The keys in the dictionary belonging to "RD53BvX" consist of two parts; "info" and the chip definitions, "15", "14", "13", "12" for TEPX modules, for example.
All the information stored in "info" is related to uploads to the Panthera database by Felis, and are required to have the correct information on the database. They are irrelevant to the creation of the CMSIT.xml file. There are the following required points:
module_name : the name the module has. Currently there is no universal syntax for this yet.
type : Either 2x2, 1x2 or 1x1
subdetector : TBPX, TEPX or TFPX
sensor : Currently actually a boolean, should be a string of the sensor name at some point.
The subdetector settings are relevant for the data-merging calibrations that need this information to assign the correct mappings.
The second part of the dictionary with the chip information is structured such, that the key of the dictionary corresponds to the chip ID. Then, the structure is exactly the same as in the XML files. If desired, any chip setting from the XML file can be defined here. In the example, the most sensible settings are given:
Lane number : indicates, what the output lane of the chip is. Depends on Subdetector and data merging mode
outputLanes : similar setting also depends on subdetector
VOLTAGE_TRIM_DIG/ANA : Trim bits to make sure, the chip receives 1.2V out of the LDO circuit. These are specific to each chip. Should be stored in a database.
VREF_ADC : Setting that indicates conversion rate between deltaVcal and electron charge. Required to make threshold accurate. Also stored in a database
Commenting in config files
Comments in TOML are prepended by # at the beginning of a line.
Comments in JSON aren’t really supported, but are added as unused fields, with the convention that the field name starts with ##, somehow similar to:
"## GLOBAL": "Global options",
Alternative file types
The main dirigent file (
dirigent.toml) does not necessarily have to be a TOML file. If you want, you can also create a JSON configuration file. However, for this file type, there is currently no working example provided.
To set a variable in JSON format, the entry in the configuration file looks similar to the following:
{
... ,
"default_lv_voltage": 1.8,
...
}
If you want to change calibration specific settings in the JSON format, the command looks similar to this:
{
...
"test calibration": {
"test_option": 111
}
}
Additional settings
TMUX
There is one setting that can be activated. It is not recommended to use it, because the abort handling and cleaning up after the calibration is not fixed. But in case, no display is available this could be useful:
sub_shell = 'tmux' # xterm by default
This requires tmux to be installed. Generally, if this setting is changed, instead of an xterm window, a tmux session with name Ph2_ACF_instance is created and calibrations are run in this session. After a calibration, the session is Not closed.
There are multiple problems that are currently occuring, when running with tmux. This is why it is not recommended:
tmuxrequires the parameterph2_dirto be set. Currently the environment variable indicating the Ph2_ACF instance is not handed over to the new sessionCancelling a calibration in the tmux session will prevent it from sending the signal that it is finished. This will result in
dirigentfreezing. There has been no solution yet how to unfreeze it.Cancelling a calibration in the dirigent window (fully cancelling a dirigent calibration) will not send an interruption to
tmux. The scan will just continue there until it is manually stopped. Usually this goes with a lot of errors, as the module is being turned off by dirigent.
Simulation
It is possible to implement an instrument as a simulated device. This should only be used for debugging and is not intended for regular users. If this has to be done, a parameter can be added to the instrument description, that looks like:
...
"sim": true,
...