Merge pull request #24 from SiLab-Bonn/development

v1.0.0 release

.travis.yml

@@ -1,36 +1,44 @@
 language: python
 python:
   - 2.7
-
+  - 3.7
+
 sudo: required
-dist: trusty
+dist: xenial
 
 before_install:
   - sudo add-apt-repository -y ppa:team-electronics/ppa
   - sudo apt-get update
 
 install:
   - sudo apt-get install -qq libhdf5-serial-dev
-  
-  #- sudo apt-get -y install iverilog-daily  
+
+  #- sudo apt-get -y install iverilog-daily
   - sudo apt-get install gperf
   - git clone https://github.com/steveicarus/iverilog.git
   - cd iverilog && autoconf && ./configure && make && sudo make install && cd ..
-  
+
   # Install conda
-  - wget http://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh
+  - wget http://repo.continuum.io/miniconda/Miniconda2-latest-Linux-x86_64.sh -O miniconda.sh
   - bash miniconda.sh -b -p $HOME/miniconda
   - export PATH=$HOME/miniconda/bin:$PATH
   - conda update --yes conda
-  - conda install --yes numpy bitarray pytest pyyaml pytables  
-  - pip install cocotb
-
-  # Install basil  
-  - git clone -b v2.4.10 https://github.com/SiLab-Bonn/basil; cd basil; python setup.py develop; cd ..;
+  - conda create --yes -n test-environment python=$TRAVIS_PYTHON_VERSION pytest numpy psutil qtpy pyqt pyyaml pyzmq pytables
+  - source activate test-environment
+  - pip install cocotb==1.0.dev3
+  - pip install xvfbwrapper  # fake x server for Qt gui tests
+
+  # Install basil
+  #- git clone -b v3.0.0 https://github.com/SiLab-Bonn/basil; cd basil; python setup.py develop; cd ..;
+  - pip install basil-daq>=3.0.0
 
-  # Install tlu
+  # Install pytlu
   - python setup.py develop
-
-script:
-  - cd tests;  py.test -s
 
+  # Install EUDAQ
+  - source tests/setup_eudaq.sh
+
+script:
+  - cd tests
+  - python --version
+  - pytest -s -v

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2015-2018 SiLab, Institute of Physics, University of Bonn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

MANIFEST.in

@@ -0,0 +1,4 @@
+include README.* VERSION requirements.txt
+include pytlu/*.yaml
+recursive-include pytlu/firmware *
+recursive-include firmware *

README.md

@@ -1,59 +1,71 @@
-# pytlu
+# pytlu
 
 [![Build Status](https://travis-ci.org/SiLab-Bonn/pytlu.svg?branch=master)](https://travis-ci.org/SiLab-Bonn/pytlu)
 
-DAQ software and firmware for the [Trigger Logic Unit (TLU)](https://twiki.cern.ch/twiki/bin/view/MimosaTelescope/TLU).
+DAQ software and firmware for the EUDAQ [Trigger Logic Unit (TLU)](https://twiki.cern.ch/twiki/bin/view/MimosaTelescope/TLU).
 
 ## Description
 
 The main features of the DAQ software and FPGA firmware are:
 
-- protocol compatible with original firmware 
-- integrated TDC (1.5625ns resolution, 640 MHz)
-- configurable input inversion
-- configurable input acceptance based on the pulse width
-- trigger acceptance based on input rising distance
-- continuous data storage of accepted triggers (trigger id, timestamp, TDC)
-- testbench for software and firmware
-- example fpga receiver module : https://github.com/SiLab-Bonn/basil/tree/master/firmware/modules/tlu
+- Protocol compatible with original EUDAQ TLU firmware
+- Integrated TDC (1.5625ns resolution, 640 MHz)
+- Configurable input inversion
+- Configurable input acceptance based on the pulse width
+- Trigger acceptance based on the distance of the input pulse leading edge
+- Continuous data storage of accepted triggers (trigger ID, timestamp, TDC)
+- Testbench for software and firmware
+- Example FPGA module provided by basil: [TLU/trigger FSM](https://github.com/SiLab-Bonn/basil/tree/master/firmware/modules/tlu)
+- Data monitoring provided by the [online_monitor](https://github.com/SiLab-Bonn/online_monitor) package
 
-The data of all accepted triggers will be stored in a .h5 file. It contains the following data:
+The data of all accepted triggers will be stored in a HDF5/PyTables file. It contains the following data:
 
-- timestamp of the trigger (64 bit number, 40 MHz)
-- trigger id (32 bit number)
-- distance between leading edge of input pulse and generation of trigger signal for each input channel (each of them 8 bit numbers)
+- Timestamp of the trigger (64-bit number, 40 MHz)
+- Trigger ID (32-bit number)
+- Distance between leading edge of input pulse and generation of trigger signal for each input channel (each of them 8-bit numbers)
+
+
+## Online Monitor
+
+The pytlu online monitor displays the trigger rate vs. time.
+![Pytlu online monitor](online_monitor.png)
 
 ## Installation
 
-Install [conda](http://conda.pydata.org).
+Installation of [Anaconda Python](https://www.anaconda.com/download) or [Miniconda Python](https://conda.io/miniconda.html) is recommended.
 
-Install required packages:
+Install dependencies:
 ```bash
-conda install numpy bitarray pyyaml pytables 
+conda install numpy psutil qtpy pyqt pyyaml pyzmq pytables
+pip install pyusb pySiLibUSB
+pip install basil-daq>=3.0.0
 ```
 
-Install pytlu via:
+Install pytlu from PyPI:
 ```bash
 pip install pytlu
 ```
 
+or install pytlu from sources:
+```bash
+python setup.py develop
+```
+
 For development/testing see [.travis.yml](https://github.com/SiLab-Bonn/pytlu/blob/master/.travis.yml) for details.
 
+### USB Driver
 
-If you use the TLU for the first time, you need to add a udev rule in order to set the correct permissions. Create the file `/etc/udev/rules.d/54-tlu.rules` and add the following lines:
+Install libusb library by following the pySiLibUSB [installation guide](https://github.com/SiLab-Bonn/pySiLibUSB/wiki).
 
+If you are using the TLU for the first time, you need to add a permanent udev rule in order to access the TLU. Create the file `/etc/udev/rules.d/tlu.rules` and add the following lines.
+For a RedHat-based distribution (e.g., SL7/Centos 7) use:
 ```
-# for Red Hat, e.g. SL5
-SYSFS{idVendor}=="165d", SYSFS{idProduct}=="0001", GROUP="NOROOTUSB", ←-
-MODE="0666"
+SUBSYSTEM=="usb", ATTR{idVendor}=="165d", ATTR{idProduct}=="0001", GROUP="NOROOTUSB", MODE="0666"
 ```
-if you are using a Red Hat-based distribution or:
+OR for a Debian-based distribution (e.g., Ubuntu) use:
 ```
-# for Debian
-ACTION=="add", DRIVERS=="?*", ATTR{idVendor}=="165d",
-ATTR{idProduct}=="0001", MODE="0666"
+SUBSYSTEM=="usb", ATTR{idVendor}=="165d", ATTR{idProduct}=="0001", MODE="0666"
 ```
-in case you are using a debian-based distribution.
 
 ## Usage
 
@@ -62,7 +74,99 @@ In order to get a description of the possible input arguments run:
 pytlu -h
 ```
 
+In order to start pytlu online monitor run:
+```bash
+pytlu_monitor
+```
+
 Example:
 ```bash
 pytlu -t 10000 -c 10000 -oe CH1 --timeout 2
 ```
+
+## EUDAQ integration
+
+Pytlu can connect to the data acquisition framework [EUDAQ 1](https://github.com/eudaq/eudaq/tree/v1.x-dev), which is the common run control software used at *pixel test beams*. For the installation of EUDAQ 1.x please follow this [wiki](https://telescopes.desy.de/EUDAQ). To use the EUDAQ libraries within pytlu a [python wrapper](https://github.com/eudaq/eudaq/blob/v1.x-dev/python/PyEUDAQWrapper.py) is used. This wrapper is not build with default settings, thus the following cmake option must be specified when building EUDAQ `-DBUILD_python=ON`.
+
+### Example minimal installation
+The following commands setup EUDAQ 1.x development version for pytlu with minimum requirements (no [ROOT](https://root.cern.ch/), no [Qt](https://www.qt.io/)) and are tested on *Ubuntu 14.04 LTS*. This installation is sufficient to use and test the pytlu eudaq producer. The paths `/home/user/git` have to be adjusted to your system, of course.
+#### Install dependencies
+EUDAQ needs a recent [cmake3](https://cmake.org/download/) version that might not be shipped with your distribution. This is a [known issue](https://github.com/eudaq/eudaq/issues/466). To install a recent version under Ubuntu do
+```bash
+wget https://cmake.org/files/v3.11/cmake-3.11.1.tar.gz
+tar xf cmake-3.11.1.tar.gz
+cd cmake-3.11.1
+./configure
+make -j 4
+sudo apt-get install checkinstall
+sudo checkinstall
+```
+#### Install eudaq
+```bash
+git clone -b v1.x-dev https://github.com/eudaq/eudaq
+cd eudaq/build
+cmake -DBUILD_python=ON -DBUILD_gui=OFF -DBUILD_onlinemon=OFF -DBUILD_runsplitter=OFF -DUSE_ROOT=OFF ..
+make install -j 4
+```
+The producer has to know the installation path of EUDAQ. One way is to specify `PYTHONPATH` to include the `python` folder in the EUDAQ directory, e.g.:
+```bash
+export PYTHONPATH="${PYTHONPATH}:/home/user/git/eudaq/python"
+```
+This is not needed when you mention the path of the eudaq installation for every call to `pytlu_eudaq` (see below).
+
+**Run control GUI**
+
+When you want to have the run control GUI for more convenient testing change the CMAKE option to:
+```
+-DBUILD_gui=ON
+```
+Warning: you have to avoid calling `cmake` within the anaconda environment, since the anaconda QT5 version cannot easily be used to build code.
+
+### Usage with Pytlu
+A simple command line interface is provided to start the pytlu producer:
+```bash
+pytlu_eudaq --help
+```
+Please read the help output for program parameters.
+Since there are configuration parameters which exist within the [EUDAQ TLU controller](https://github.com/eudaq/eudaq/blob/v1.x-dev/producers/tlu/src/TLUController.cc) but not within the 
+pytlu producer and vice versa, only the following configuration parameters can be set using the EUDAQ config file:
+
+ - `TriggerInterval`
+ - `AndMask`
+ - `DutMask`
+
+These are mapped properly to the format needed by pytlu. Of course, the usual parameters supplied by pytlu can be specified, e.g.:
+
+```
+pytlu_eudaq --timeout 5  -f /path/to/data/
+```
+
+Please note that the settings specified in the EUDAQ configuration file will overwrite the settings specified by the command line interface.
+
+
+If you did not add the EUDAQ directory to the `PYTHONPATH` explicitly after installation (see above) you can give the path when running `pytlu_eudaq`, e.g.:
+
+```
+pytlu_eudaq --path /home/user/git/eudaq
+```
+
+### Debugging and testing
+#### Replay feature
+It is possible to replay a recorded pytlu raw data file with correct timing to test the system. This allows development and debugging without hardware. To replay a [pytlu raw data file](https://github.com/SiLab-Bonn/pytlu/blob/development/data/tlu_example_data.h5) one has to type:
+
+```
+pytlu_eudaq --replay /home/user/git/pytlu/data/tlu_example_data.h5
+```
+
+Sometimes it is not needed to replay the data in real time. You can delay the data sending for every read out by an arbitrary time by specifying a `delay` parameter. For example to add a delay of one second you can type:
+
+```
+pytlu_eudaq --replay tlu_example_data.h5 --delay 1
+```
+
+#### Unit test
+A unit test is also available to test the complete chain: pytlu producer + DataConverter + Run Control. To test if everything is setup correctly open a console and make sure you added eudaq to you python path (see above). Then go to the [pytlu/tests](https://github.com/SiLab-Bonn/pytlu/tree/development/tests) folder and type
+```
+python test_eudaq.py
+```
+This test succeeds if everything is setup correctly.

VERSION

@@ -0,0 +1 @@
+1.0.0

firmware/src/stream_fifo/stream_fifo.v

@@ -1,9 +1,10 @@
 /**
  * ------------------------------------------------------------
- * Copyright (c) All rights reserved 
+ * Copyright (c) All rights reserved
  * SiLab, Institute of Physics, University of Bonn
  * ------------------------------------------------------------
  */
+
 `timescale 1ps/1ps
 `default_nettype none
 
@@ -27,7 +28,7 @@ module stream_fifo #(
     output wire [1:0] SRAM_BW_N,
     output wire SRAM_OE_N,
     output wire SRAM_WE_N,
-    
+
     output wire FIFO_READ_NEXT_OUT,
     input wire FIFO_EMPTY_IN,
     input wire [15:0] FIFO_DATA,
@@ -36,8 +37,6 @@ module stream_fifo #(
     input wire STREAM_READY,
     output wire STREAM_WRITE_N,
     output wire [15:0] STREAM_DATA
-
-
 );
 
 wire IP_RD, IP_WR;
@@ -61,8 +60,8 @@ bus_to_ip #(
     .IP_DATA_IN(IP_DATA_IN),
     .IP_DATA_OUT(IP_DATA_OUT)
     );
-    
-    
+
+
 stream_fifo_core #(
     .ABUSWIDTH(ABUSWIDTH)
 ) stream_fifo_core (
@@ -81,16 +80,16 @@ stream_fifo_core #(
     .SRAM_BW_N(SRAM_BW_N),
     .SRAM_OE_N(SRAM_OE_N),
     .SRAM_WE_N(SRAM_WE_N),
-    
+
     .FIFO_READ_NEXT_OUT(FIFO_READ_NEXT_OUT),
     .FIFO_EMPTY_IN(FIFO_EMPTY_IN),
     .FIFO_DATA(FIFO_DATA),
-    
+
     .USB_STREAM_CLK(STREAM_CLK),
     .STREAM_READY(STREAM_READY),
     .STREAM_WRITE_N(STREAM_WRITE_N),
     .STREAM_DATA(STREAM_DATA)
-    
+
 );
 
 endmodule