PSEC3 eval Software Documentation
Andrew Wong
Department of Physics and Astronomy,
University of Hawaii, 2505 Correa Road,
Honolulu, HI 96822, USA
June 3, 2011
Abstract
This is the documentation for the software corresponding to the PSEC3 eval board.
1
Introduction
PSEC-3 is a custom 256-point waveform sampling ASIC intended for the readout of micro-channel plate (MCP) pulses. [4] This chip was developed by the Large Area Picosecond Photodectors (LAPPD) group at the University of Chicago.
2
Board Specifications
Specifications of the board are as follows:
• Power consumption: 5V via a positive and negative voltage connector • External Trigger: 3V pulse, triggers on falling edge.
• Input signal range: Display range is from 0-1.2V. The input signal may be added to a pedestal voltage on the board, also ranging from 0-1.2V, to achieve the display range.
• Input channels: Four
• Sampling speed: 10 GSa/sec or 5.1 GSa/sec.
3
Installation
Download the installation package and unzip the files to a directory. The remaining steps differ depending on which operating system you are using:
3.1
Windows
Development was done in wx-devc++ version 7.3.1.3, which comes with wxWidgets 2.8. wx-devc++ can be found at [1].
1. Install the Cypress EZ-USB IDLAB-STD driver, if it is not already installed. The drivers can be found at either at [5] or [6].
2. Open wx-devc++. Open PSEC3 eval.dev from the folder you extracted the files to. 3. From the Execute menu, select “Compile & Run”.
As an alternative to the Cypress drivers, one could use the libusb-win32 libraries [3] - then the Linux USB drivers can be used.
If all goes well, there should be executable files built, and the software should open up.
3.2
Linux
Due to the portable nature of wxWidgets applications, the software also works under Linux. It should be noted that the stdUSB libraries differ under both Linux and Windows, and thus there are two separate versions of the stdUSB files. Testing was done under Ubuntu, but (in theory) should work on any version that supports wxWidgets. (though it hasn’t been fully tested with older versions of Linux)
1. Install libraries - libUSB for USB support, an OpenGL library, and wxWidgets. wxWidgets may need to be rebuilt from source because the library needs to be compiled with OpenGL support (e.g. run ./configure –with-openglto enable OpenGL support) to show the displays. wxWidgets with OpenGL support requires an OpenGL library installed in order to compile.
2. Change to the folder containing the files, and runmake.
3. You may need to add /usr/local/libto your LD LIBRARY PATH and rerunldconfig.
4. Run PSEC3 eval as root - USB access with non-root credentials often is limited. (There is a way around requiring root access, but it is beyond the scope of this document; also, if one is only using the offline event viewer, root access is not necessary). Also, it is recommended to use gksudo rather than sudo, since .ICEconfiguration, a security Linux configuration file, tends to get chown’d to root during execution.
Testing has not been fully performed on a wide variety of Linux distributions, but moderate success (minus some glitches) has been achieved with compiling it using the provided makefile.
4
Quick Start Guide
This section is if you are trying to read out data and want to know a quick set of steps to getting data readouts.
2. Generate a lookup table.
3. Set your pedestal voltage according to what your input range is expected to be - the goal is to get the readouts in the 0.0 to 1.0 V range.
4. Generate a pedestal file - this file is dependent on the current pedestal voltage. If you need to do external triggering, the following steps are also necessary: 1. On the config tab, set the pedestal voltage if it hasn’t been done already.
2. Set init settings: sampling speed to desired rate (though some speeds may not be supported); triggering mode to internal, negative trigger sign (currently external trigger still operates via this mode); trigger threshold, set this fairly high (to avoid the internal trigger from occurring) - 4,000 should be more than sufficient for most applications.
3. Enable SYNC USB from the Online tab.
5
User Interface
5.1
Oscilloscope
The display shows a grid with the signals. The four board signals are shown by default, and signals can be stored into one of four ’saved’ channels, allowing the user to save specific signals for comparison.
By default, one vertical box = 100 mV, but this is changable on a per-channel basis. Timebase depends on the sampling speed.
5.2
Online controls
• Create LUT - Performs readout for a lookup table (ADC value to voltage). This is done by applying pedestal voltages and reading the channel data.
• Save LUT - saves the current LUT in memory to a file. • Create Pedestal - Creates a pedestal.
• Save Pedestal - Saves pedestal data to a file.
• SYNC USB - Enables/disables SYNC USB mode. This mode disables the software trigger preceding a readout, as well as tells the board to return a smaller packet when no data is available to read out. • Log Data - Enables/disables the logging of readout data to a file. When selected, the user is prompt
for a filename.
• Reset Event # - Resets the software event counter - it is unknown whether there is a way to reset the one read out on the board.
• Single Event - Performs a single readout on the board. Note that in external trigger mode, data may be unavailable when this button is selected, and no readout may occur.
• Continuous Readout - Performs readouts continuously on the board until the button is untoggled.
5.3
Offline controls
• Load Log File - Indexes a log file for random access for viewing. Log files are limited to 2GB in size due to limitations with cross-platform file access. Note that this does NOT load the contents into memory - if the file is deleted from disk while it is open, it may cause unexpected behavior (though it shouldn’t be allowed since the file is still open).
• Event scrollbar - Allows the user to select an event from the currently loaded file.
5.4
Scope controls
These functions control how channel signals are displayed on the display.
• Channel selection box - Selects which channel the other controls on this page affects. • Display CH - Toggles whether the given channel is displayed.
• Vertical Offset - Controls the position of the channel in the display.
• Vertical Scaling - Controls how many volts equals one box on the scope display. • Copy to - Copies the channel data (voltage data) to a ’saved channel’.
5.5
Config
• Load LUT - Loads a lookup table from disk. • Load Pedestal - Loads a pedestal file from disk.
• Set Pedestal Voltage - Adds a fixed DC voltage to all the channels - this is used in generating LUT files, as well as dealing with negative voltages in input signals.
• Init settings - sets sampling speed, trigger type, and internal trigger threshold.
5.6
Statistics
• Save spike histogram - Saves data about where spikes occur in readout data. This is mainly used in debugging.
5.7
Status Bar
The status bar consists of the following fields:
1. Information - displays information when an operation finishes, e.g. LUT generation, event file loading, etc.
2. USB indicator - The USB devices are polled every second or so when the USB is not in use - if the USB cable is connected, this indicator is displayed. Note that the indicator can still be displayed even if the device is not powered.
3. PED indicator - Indicator showing if pedestal file is loaded. If a pedestal has been created and not saved, a star denotes this.
4. LUT indicator - Similar indicator for lookup table.
6
Implementation Details
6.1
Startup commands
Upon starting up the software, no startup commands are sent to the board.
If the files exist, LUT.txt and pedestal.txt are loaded automatically. These files should be located in the same folder as the executable.
7
Quirks
The following software issues are noted regarding the TARGET eval software, due to limitations with the hardware or the USB driver.
• When running the board for a while under external trigger, then suddenly removing external trigger mode while the program is still running, it often causes three bad readouts to occur. After those, the readouts return to normal.
The following issues seem to exist with the firmware; however, they are corrected for in software. They are listed here in case the code needs to be modified on a future date and it is unclear why a certain snippet of code exists.
• When switching from external trigger to software trigger mode, a few dummy readouts are performed to clear the bad readouts from the buffer.
• When doing a readout under external trigger mode, there is a chance the readout gets broken into two parts. In this case, the first two values of the readout (the header and event number) are read in the first packet, while the remainder of the event is in the second. In this case, the software pieces the two parts together when they are read (since they always occur in succession).
•
A
Data Format
PSEC3 eval uses the Cypress EZ-USB interface to connect the readout board to the computer. Data is sent from the board to the computer sixteen bits at a time (2 bytes), while data sent to the board occurs in two 16-bit send operations.
A.1
Received Data
Upon a successful readout of the board, 1,036 16-bit words are read. Offset Data size Description
0 1 word Header (0x1234)
1 1 word ?
2 256 x 4 words Waveform data 1032 1 word Event number 1035 1 word Footer (0x4321)
A.2
Board Commands
Board commands follow the general format: high-bits low-bits (in hexadecimal)
The low bits determine which command is executed; the high bits represent the parameter for the command, if any.
high-bit (hex) low-bit (hex) Description
0000 or 0001 0001 Enables (1) or disables (0) SYNC USB mode, which affects readout. When enabled, readouts will return incomplete data (2 values) if no data is available to read. When dis-abled, readouts will suspend until data is available. 0000 0002 Sends a software trigger to the board. No parameters. (new value) 0003 Sets the pedestal voltage on the board. This voltage is
added to every cell in the waveform data. value is the number of counts; to get voltage, multiply by 1.2/4096. new value 00ff Sets INIT value. Init value controls internal trigger
thresh-old level, trigger mode (though not currently implemented in firmware), and sampling speed (still buggy).
INIT value format:
aa b c yyyyyyyyyyyy
a = sampling rate ( 00 = 10 GSa/sec, 01 = 2.6 GSa/sec, 10 = 5.1 GSa/sec, 11 = 15.4 GSa/sec) b = trigger mode ( 0 = external, 1 = internal) - currently both modes use internal
c = trigger sign ( 0 = negative, 1 = positive) y = internal trigger threshold, x 1.2/4096 V
Also note that the pedestal voltage can trigger the internal trigger threshold.
B
Pedestal File Format
Pedestal files consist of a baseline ADC value for each of the 1024 cells (256 cells x 4 channels) on the board. These are stored as one integer per line.
C
Lookup Table Format
Lookup Table (LUT) files are stored as a table of 4096 rows by 5 columns. The first value contains the ADC value, while the remaining columns state the voltage value corresponding to that ADC value. If the given ADC value is out of range, a -1 is listed in the corresponding row.
D
Log File Format
Log files consist of the four channel data, followed by a blank line between events. Only the ADC counts (e.g. not voltages) are stored, so voltage lookup as well as pedestal subtraction needs to be performed on this data.
E
Packages installed under Linux
This section lists the dependencies installed under various distros of Linux. Note that this isn’t a complete list, since many of these packages have dependencies of their own.
E.1
Ubuntu
Installation was done under Ubuntu. • g++
• libglut3-dev (needed for GL headers, apparently... there may be something else that satisfies this dependency)
• libgl1-mesa-dev (GL library) • libusb-dev (USB library)
References
[1] wxDev-C++, a development environment for Windows, available for download at http://wxdsgn.sourceforge.net/
[2] wxWidgets, a cross-platform GUI library, http://www.wxwidgets.org [3] Libusb Win32 port, http://sourceforge.net/apps/trac/libusb-win32/wiki
[4] PSEC3 documentation, https://hepblog.uchicago.edu/psec/psec1/wp-content/uploads/2011/03/psec3 eval doc.pdf
[5] Cypress EZ-USB drivers, http://download.cypress.com.edgesuite.net/design resources/developer kits/contents/cy3681 ez usb fx2 development kit 15.zip [6] Cypress EZ-USB driver (inf/sys only), http://www.phys.hawaii.edu/ wongandr/projects/ezusb.zip
