.. _config: ********************** 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 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 --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::INSTR Typically: ASRL/dev/ttyUSBx::INSTR Devices connected through TCPIP will have:: TCPIP::::::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, ...