Dirigent 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 ~/dirigent/config/.
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 --opto-dict modules.json may be specified either in the command line, when running the scan similar to the following example:
dirigent -C dirigent.toml --opto-dict modules.json <dirigent calibration name>
or it can be set in the TOML config as follows:
opto_dict = 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 apply to every dirigent scan that is run. The second part is then separated into the different possible scans. To make the overview a bit simpler, the settings, that apply to every dirigent scan 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.:
# Infos related to module and Ph2_ACF
ipaddress = '192.168.10.100'
opto_dict = 'modules.json'
instruments = 'instruments.json'
ph2_dir = '' #path to ph2_acf installfolder - If none, it is assumed, that ph2_acf is loaded already
firmware = '' #name of the firmware on the SD card. May be a specific name
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 scan. Also this is currently not implemented for many scans (principally for the module_calibration scan).
If the directory, where dirigent is executed already features a CMSIT.xml file, the file is not overwritten. This means, that the here indicated 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 scan and are not used for any other scan than the indicated one. Calibration-specific configuration values are specified in a section corresponding to the scan with the same name. For TOML this looks as follows:
[test_calibration]
test_option = 111
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 scan, it is helpful to consider the information for scans:
dirigent -C dirigent.toml <calibration_name> --help
It’s important to remember: sensible defaults are provided in the calibrations themselves. 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 scans 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) and an assignment of instrument channels to their respective modules with an indication of their roles.
Instruments
The definition of the instruments is done in the node “instruments”. Here, each instrument is built as a dictionary with an assigned key used later to assign it to the respective channels. An example of 4 instruments can be found in ~/dirigent/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 currently the following options available:
HV supplies:
"Keithley2410"
"CaenDT8033N"
LV supplies:
"TTI"
"HMP4040"
"KeysightE3633A"
Relay Board / Adc Board
"RelayBoard"
"AdcBoard"
Climate chamber
"Binder"
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
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)
channels
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 scans (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 adc board connected that is named rb_2:
"channels":{
"0":{
"lv": {"instrument":"lv_1", "channel":2},
"hv": {"instrument":"hv_2", "channel":1},
"rb": {"instrument":"rb_2"}
}
It is to be noted, that the relay_board/adc_board 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.
modules.json
The third file that is needed to complete the required information to run a module tuning is the modules 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 file will be created, if a CMSIT.xml file is already present in the run directory.
Following, an example of a module setup is given:
{
"Hybrid": {
"1": {
"RD53Bv1": {
"info" : {"module_name" : "CLQ8", "type" : "2x2", "subdetector" : "TBPX", "sensor" : "LF21_10_Q5"},
"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 straight forward. Different modules are separated by Hybrids. Each Hybrid number 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, 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. All the information stored in info is related to uploads to the database 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 scans 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 (footnote)
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 scan 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 scans are run in this session. After a scan, the session is Not closed.
There are multiple problems that are currently occuring, when running with tmux. This is why it is not recommended:
tmux requires the parameter ph2_dir to be set. Currently the environment variable indicating the Ph2_ACF instance is not handed over to the new session
Cancelling a scan in the tmux session will prevent it from sending the signal that it is finished. This will result in dirigent freezing. There has been no solution yet how to unfreeze it.
Cancelling a scan 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,
...