Quantum Scientific Imaging, Inc.

QSI Linux API README

The QSI Linux API is supplied in source code form and is built and installed using the standard GNU auto tools.

The QSI API supports two driver libraries for the USB connection to the the camera via an FTDI USB interface.  You may use either
libftdi (an open source release), or libftd2xx from FTDI (a binary release - www.ftdi-chip.com) for that connection.  
The choice is mutually exclusive; You cannot configure both libraries simultaneously. 

Libftdi is included as a package in most modern distributions of Linux.  You can use the appropriate package manager 
(rpm/dnf/app-get) to install libftdi and libftdi-devel, rather than doing a manual build/install.
 
During the QSI api build process, use the configure command to select the ftdi library of your choice.

To use libftd2xx, use the --enable-libftd2xx option on the ./configure command:

./configure --with-ftd=ftd2xx

To use libftdi-1.x, use the --with-ftd=ftdi1 option:

./configure --with-ftd=ftdi1

To use the legacy libfdi-0.2 use the --with-ftd=ftdi option.  This is deprecated and not recommended.

The ./configure defaults to libftd2xx if no option is specified.

See the QSI Linux API Reference Manual for more information.

Install libftd2xx or libftdi and their dependencies before building and installing the QSI api.

*******************************************************************************************************

As of release 7.4, QSI cameras using the Cypress FX3 USB 3.0 chipset are now supported.

NOTE: All 500 and 600 series cameras do not require this driver stack.  It is recommended
that you exclude this driver (by not specifying --enable--cyusb).  The Cypress driver is for
experimental purposes only.

If you do wish to include the Cypress device support, add the --enable-cyusb 
to the configure command line.

For example: ./configure --enable-cyusb

Proceed with the instructions below to add the require supporting libraries:

This change requires that the Cypress libcyusb library, udev development files,
and the libusb-1.0 libraries be installed prior to building the QSI API release.

libusb-1.0 can be found at: http://www.libusb.com.

Follow the instructions provided with the download to build and install the release.

You must also install the development package for libudev.
  
On Fedora before release 18, the package name is "libudev-devel".
On Fedora 18 and beyond, the package name is systemd-devel.
On Ubuntu, the package name is "libudev-dev".

This package installs the libudev.h header file required by libcyusb.

For example:
dnf install libudev-devel

The Cypress libcyusb release can be found at: http://www.cypress.com/?docID=42387&dlm=1

Download and install fx3_sdk_v1.3.1_linux.tar.gz from the link above.  
The Cypress download site will require that you create a login for their web site 
to allow the download.  Registration is free of charge.

Unzip the downloaded file:

tar -xvf fx3_sdk_V1.3.1_linux.tar.gz

run make in the top directory to build the library:

make

run make in the src directory:

cd src
make
cd ..

Run the install.sh script in the top directory to install the library. 
You must have root permissions in install the library.

sudo ./install.sh

Copy the cyusb.h header file to the /usr/local/include directory:

cp cyusb.h /usr/local/include

Update the shared library cache:

sudo ldconfig -n /usr/local/lib

The installation of the Cypress FX3 library is now complete. You can now proceed
with the QSI API Installation.

********************************************************************************************************

QSI API Installation

Insure that the kernel is configured for USB support and the device permissions are correct. 

With root permissions:

--------------------------------------------------------------
If you have selected libftdi (--with-ftd=ftdi1):

Use your package manager to install libftdi (this will install the latest libftdi-1.x version).

--------------------------------------------------------------

-----------------------------------------------------------------------------------------------------------
If you have selected libftd2xx (--with-ftd=ftd2xx):

Download and install libftd2xx. (Available at: http://www.ftdichip.com/Drivers/D2XX.htm )
  
Install it as directed by the README from the libftd2xx release.  

Insure that libusb or libusbx (or later) is installed, as required by libftd2xx. See the libftd2xx README.
------------------------------------------------------------------------------------------------------------

Extract the release files from the qsiapi tar archive (y and y below represent the specific release version).
	
	tar -xvf qsiapi.x.y.0.0.tar.gz
	
Run configure:
	
	In the extracted qsiapi.x.y.0.0 directory
	
	./configure --with-ftd=ftdi1
	
	 ---or based on your library selection---
	 
	./configure --with-ftd=ftd2xx
	
	make all
	make install
	

Confirm the installation of the include and library files.
	The include files qsiapi.h and QSIError.h are installed in /usr/local/include. 
	The libraries libqsiapi.so, libqsiapi.a, etc. are installed in /usr/local/lib. 

Run ldconfig for the newly installed libraries:
	cd /usr/local/lib
	ldconfig /usr/local/lib

Insure that the USB device permissions are correct.  Update udev as appropriate.
Check the permission /dev/bus/USB/xxx/yyy, where xxx is the hub number and yy is the device number.
With the camera plugged in, you can use lsusb to find the device address.

Users of the QSI API must have read/write permissions to the QSI camera USB device.

Connect the QSI camera to AC power and connect the USB cable from the camera to an available 
USB port on the computer. Use lsusb to verify proper USB installation and that the permissions
are properly set.

Confirm that all libraries are loaded and the system is properly configured.

Run qsiapitest in the src subdirectory:

	./qsiapitest
	
	qsiapitest first displays the version of the api. If there is a QSI camera connected to the system, 
	it will execute a series of command to exercise the camera. See the qsiapitest.cpp source code for further details.
	
**************************************************************************************************************

Troubleshooting:

You may need to install the g++ compiler and other build tools to run the above. If so, run: 
	apt-get install build-essential

If you have problems with the installation steps above, first use usbview or lsusb to
 confirm that the USB file system is mounted properly and the QSI camera is connected to the system.

Some problems may be related to the ftdi_sio driver loading. You must unload this driver (and usbserial)
 if it is attached to your device ("rmmod ftdi_sio" and "rmmod usbserial"as root user).

Insure that the user running the api has read/write access to the camera usb raw device. Check the permissions
 in /dev/bus/usb/XXX/YYY, where XXX is a hub number and YYY is the device number obtained from lsusb.

To set device permissions other than root:

udev changes:

For example, to give rw access rights to all users for all QSI USB cameras in Fedora 24:

Create a file in /lib/udev/rules.d called 99-qsi.rules with the following contents:

KERNEL=="*", SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="eb48", MODE="0666"
KERNEL=="*", SUBSYSTEM=="usb", ATTR{idVendor}=="0403", ATTR{idProduct}=="eb49", MODE="0666"

After saving the file, execute the following:
sudo udevadm control --reload-rules
sudo udevadm trigger


In Ubuntu 6:

In the file /lib/udev/rules.d/40-permisssions.rules

after:
#USB devices (usbfs replacement)
SUBSYSTEM=usb_device, MODE=0664

Add the following lines:
SUBSYSTEM=usb_device, SYSFS{idVendor}==0403, SYSFS{idProduct}== eb48, MODE=0666

SUBSYSTEM=usb_device, SYSFS{idVendor}==0403, SYSFS{idProduct}== eb49, MODE=0666

