Home

Welcome

This is the wiki of pyBAR – the Bonn ATLAS Readout in Python and C++

Support

To subscribe to the pyBAR mailing list, click here. Please ask questions on the pyBAR mailing list (subscription required) or file a new bug report / feature request here.

Download

To clone the master branch

 git clone https://github.com/SiLab-Bonn/pyBAR 

and

 git clone https://github.com/SiLab-Bonn/pyBAR -b branch_name

to clone a specific branch/release where branch_name is the name of the branch (e.g. master, 2.0.1).

Installation

Have a look at the README. If there are still questions left or you have no experience with python we recommend our Step-by-step Installation Guide.

Usage

The scan scripts are placed in the scans folder (file name prefix: “test_”, “scan_” and “tune_”). A “run” is when running a scan. Runs are numbered starting from 1. Configuration files can be selected by the run number.
A run script can be executed immediately from the console by just executing the python scrip from the scans folder, e.g.:

 python scan_digital.py 

Or a run can be executed from an integrated development environment (IDE) (e.g. Eclipse, click here for instructions).
By default, the python script uses the settings from the configuration.yaml file in pybar folder. The configuration.yaml contains information about the hardware setup (e.g. readout card, adapter card, …), the FEI4 flavor, configuration, and the data output folder. The configuration.yaml can be extended to also include run configuration for each type of run (e.g. Analog Scan, Digital Scan, …) and run configuration for all runs.
The data output folder (will be created on first run) contains raw data generated during a run, and analyzed data, PDF output files, and the configuration files, which are generated at the end of each run. In addition one can find the run.cfg containing information about each run (exit status, run name, start and stop time), and the crash.log containing traceback information if the exit status was “CRASHED”.

How-to: Running an Analog Scan

The initial configuration.yaml from repository looks similar to this example:

dut : dut_mio.yaml

dut_configuration : dut_configuration_mio.yaml

fe_configuration : 

fe_flavor: fei4a # initial flavor

module_id : module_test
AnalogScan:

    scan_parameters : {’PlsrDAC’: 280}

    enable_shift_masks : [“Enable”, “C_Low”, “C_High”]

First, change dut and dut_configuration parameter according to your setup. dut_mio.yaml is compatible with the FEI4 Single Chip Adapter Card (default) and the Burn-in Card (4-chip adapter card). To change the adapter card, edit dut_mio.yaml. Change dut to dut_mio_gpac.yaml and dut_configuration to dut_configuration_mio_gpac.yaml if you are using the GPAC card.
Second, change the fe_flavor parameter according to the FEI4 flavor you are using (fei4a or fei4b). The initial configuration file will be initialized based on that parameter.
Third, change fe_configuration. If left blank, the configuration from the last run with status FINISHED will be used. Use a number to use the configuration file from the run with the given run number. Or enter a specific path to a configuration file (use quotes).
Fourth, change the module_id parameter to identify your module and specifies the data output folder. A subfolder with the given name will be created inside the folder where the configuration.yaml is located.

Additional help is given inside the configuration.yaml from the repository.

It is highly recommended to install a good python editor to edit and to run scripts (e.g. PyDev for Eclipse). Nevertheless you can simply run the Analog scan by double clicking on scan_analog.py or by typing

 python scan_analog.py 

into the console.

Further Information on Usage

You will find more in depth information in the User Guide.
Please also note the examples in the examples folder.

Development

Please contact the pyBAR developers if you want to contribute or fork this repository and submit a pull request.

Policy for Commit Messages

The following codes should be used for commit messages. The commit message should have one of the following letter codes at the beginning of the first line followed by a colon.

API: an (incompatible) API change
BLD: change related to build environment
BUG: bug fix
PRJ: add/update project related files
DEP: deprecate something, or remove a deprecated object
DEV: development tool or utility
DOC: documentation
ENH: enhancement
MAINT: maintenance commit (refactoring, typos, etc.)
REV: revert an earlier commit
STY: style fix
TST: addition or modification of tests
REL: related to release
GIT: git related (name changes, …)
REG: regression, a bug that was introduced without implementing a new features that is related to the bug

Host Software

Please obey the Python coding conventions and style recommendations posted here (PEP 8 — Style Guide for Python Code).

FPGA

The firmware is based on Basil framework. Some parts of the firmware that were developed in early stages of pyBAR have been added to the Basil framework.
The firmware can be build with Xilinx ISE Design Suite. A project file (.xise) is available in the repository (click here).

Simulation

RTL simulation of the FPGA modules is provided by the Basil framework. Examples on how to use the simulator are in the Basil repository.
Full simulation of the pyBAR readout (FPGA) and a FEI4 will be provided in the near future.

Hardware

Documentation of the USBpix hardware is available here and here. The Single Chip Adapter Card, Burn-in Card (aka “BIC” or 4-Chip Adapter Card) and the General Purpose Adapter Card (GPAC) are supported.
Please note: the regulators on the BIC are not yet supported by Basil.
Please read this document on how to power the Single Chip Card (SCC) externally.

Status LEDs

LED 5 (System and SRAM FIFO status):

• flashing at 1Hz: OK
• flashing at 3Hz: TLU connected to RJ45 jack (auto sensing)
• off: DCM not locked
• on: SRAM FIFO full

LED 1-4 (RX FIFO status):

• flashing at 1Hz: OK
• flashing at 3Hz: RX decoder error counter >0
• off: no RX sync
• on: RX FIFO overflow || RX FIFO full

USBpix Ports

RJ45 Jack / TLU Port
This connector is used to connect USBpix to the EUDET TLU.

LEMO Connectors
RX0: External Trigger Input
RX1: Trigger Reset
RX2: TDC input
TX0: TLU Clock (also goes to TLU port)
TX1: TLU Busy signal (also goes to TLU port) or FEI4 Command Busy signal when trigger is disabled
TX2: TLU Trigger (loop-through from TLU port) or TDC signal (loop-through from from RX2) when no cable connected to the TLU port

Note: use 3.3V CMOS levels

Pin Header P9
Not used.

License

Host Software

The host software is distributed under the BSD 3-Clause (“BSD New” or “BSD Simplified”) License.

FPGA Software

The FPGA software is distributed under the GNU Lesser General Public License, version 3.0 (LGPLv3).