************************
author: Baptiste Gouraud
contributors: Olivier Morin (time-stamps acquisition)
file: www.nsup.org/~gouraud/phdfiles/Readme_FpgaProgramming.txt
description: Readme for FpgaProgramming.zip, tools for programming an FPGA board for Synchronization or Time stamp acquisition. 
revision: 0.0 2015-08-28
************************

1. Introduction
2. Disclaimer
3. Requirements
4. Usage
5. Files
6. Known bugs

************************
1. Introduction
************************
We use FPGA boards for two relatively simple circuit design:

    - Synchronizer : Generates a series of digital outputs used to trigger the many instruments of a physics experiment.
        Comes with a Python scripted redefinition of the experimental sequences. Some parameters can be changed via USB communication without the need of recompiling. Graphical interface available for easier handling of the experimental sequences, and different parameters.
    
    - Time-stamps acquisition : Arrival times of input pulses and saved as time-stamps and transferred to an external computer for analysis.
        Analysis includes graphical interface and plotting "real time" histograms.

Python routines and GUI are used for compiling and loading to FPGA.
Used with Xilink compiling tools and FPGALink (Chris McClelland) for USB communication between FPGA board and external computer.

The point of using an FPGA here is mostly its speed, and price. The proposed files use 10 ns as a fixed value, but can be adjusted to different values.

As a beginner in digital circuit design and FPGA programming, most of the work was to chose and setup the third party tools (here Xilink tools and FPGALink library). The circuit design itself is rather straightforward.

Have a look at www.nsup.org/~gouraud/phd.html. And first appendix of my PhD's manuscript.

***********************
2. Disclaimer/Share
***********************
I am not a professional programmer and worked on the present programs mostly as a side project. This code which end up to be very useful, was mostly used for now by myself only, or with my supervision. There are bugs, for sure.
Don't hesitate to contact me (firstname.name@nsup.org) and share your experience. I will be happy to help/know if someone is using part of this code.

***********************
3. Requirements
***********************
An FPGA board:
    Tested with Digilent's Nexys 3 boards.
    The code should be adapted easily to other boards compatible with FPGALink (see documentation). 

FPGA compiling tools:
    Tested with Xilink ISE webpack (available online after registrating on Xilink website).
        The command-line compiling tools (xst, ngdbuild, map, par, bitgen, impact) should be in the path.

Loading programs to FPGA, communication with FPGA:
    Tested with FPGALink (https://github.com/makestuff/libfpgalink).

External computer:
    Tested mostly on:
        Windows 7 version 6.1, Python 2.7.6, wxPython 3.0.0.0, matplotlib 1.3.1
    
    As well on:    
        Linux Mint 14, Python 2.7.3, wxPython 3.0.3,
            + unsuccessful test of the acquisition GUI with matplotlib 1.5, apparently this version of matplotlib and wx are incompatible?

***********************
4. Usage
***********************
    Unpack the zip file.

    I. Install proper software:
        1. Python distribution
        1. Compiling tools: should be in the path.
            Note using Xilinx ISE on Linux: Xilinx provides a "settings" script to setup proper environement variables. But this defines LD_LIBRARY_PATH and messes up the standard libraries used by other parties, i.e. wx. Apparently, its ok for the usage I have of Xilinx tools to a. First run the Xilinx settings script. b. Reset LD_LIBRARY_PATH. c. Run the present code.
        FPGALink: A copy (older from what is currently available online) is provided with the present files. Some setup might be required (LibUSB drivers), have a look at FPGALink documentation (http://www.swaton.ukfsn.org/docs/fpgalink/verilog_paper.pdf).

    II. Basic tests (mostly from main.py file):
        1. Basic FPGALink test:
            Have a look at main.py. In the end of the file are example codes. Adjust the <VID:PID> (originalVp) to your FPGA board's, uncomment the loadFirmware() line and run the program.
            If you use Nexys3, try the next line: bit2Fpga('simplesync_files/sync.xsvf'). You should see the leds turning on/off one after the other.
        2. Compiling test: 
                        try to compile without changing anything: execute veri2bit('sync','simplesync_files')
                        try to compile for your own chip: 
                            If lucky, you only have to update the chip name on top of main.py, and the .ucf file in simplesync_files, try to compile.
                            If this doesn't work correctly, you want to look more carefully at the compiling chain options. It can help to start Xilinx ISE interface, try to create a simple project for your chip, compile it and look at the command line options used by the compiling tools.
        3. Load the program (bit2Fpga line). If the outputs are connected to leds (default for Nexys3), you should see them blinking.
        
        4. Try the tests from simplesync.py (end of the file). This is the very basic synchronizer.
        Note the awkyard notation I am using for defining a time: t=(A s,B ms,C mus,D ns*) t is the sum of A in seconds, B in milliseconds, C in microseconds, D in nanoseconds here, but in 10nanseconds increments (1 clock period at 100MHz) for syncComSubseq.
        
        5. If everything has worked so far, you should be able to use the more complete synchronizer: syncComSubseq, from python command line (synchronizer.py) and graphical interface (SyncWidget.py).
        You should also be able to compile and load the time stamp acquisition design (APDacq), transfer data to your computer with the command line or graphical interface.

***********************
5. Files
***********************
    main.py: utilities independent of the particular design, includes compilation, loading program to the FPGA chip

    **** Synchronizers ****    
    simplesync.py + simplesync_files/
        A simple synchronizer.
        
    syncComSubseq.py + syncComSubseq_files/
        A more advanced synchronizer, including communication with the FPGA, and a subsequence repeated inside the main sequence.
    
    synchronizer.py
    SyncWidget
        Interfaces (python command line and graphical for the syncComSubseq)
    SyncConfigs/
        Saved configurations for the synchronizer.
    
    **** Time stamp acquisition. ****    
    APDacq.py + APDacq_files
        Time stamp acquisition.
            
    Nano_Fiber_EIT_MEM.py
    Nano_Fiber_DLCZ.py 
        Two GUIs interfacing APDacq for particular physics experiment, with some data analysis, plotting, and taking control on the rest of the experiment.
            EIT_MEM -> single input
            DLCZ -> three inputs
            
    libfpgalink-20120621/
        Chris McClelland's FPGALink library
            
***********************
6. Known bugs
***********************
The following do not execute correctly on the tested linux environment: Linux Mint 14, Python 2.7.3, wxPython 3.0.3, matplotlib 1.5
    Nano_Fiber_EIT_MEM.py
    Nano_Fiber_DLCZ.py