Using Linux with USB 3.1

This Application Note explains the components and steps that are necessary to install and configure Linux for use with FlyCapture and USB 3.1. Testing is ongoing. Wherever possible, limitations have been noted; however, as more testing is completed this information may change. All possible configurations may not experience the same results.

Supported System Configuration

Before installing, you must have the following prerequisites:

• A computer with a Gen2 PCIe slot is required to achieve maximum USB 3.1 transfer rates.
• A USB 3.1 cable.
• Linux distribution Ubuntu 12.04 or later. Download from http://www.ubuntu.com
• USB 3.1 imaging camera, Blackfly, Chameleon3, Flea3, or Grasshopper3. This TAN does not apply to other Teledyne FLIR machine vision cameras (USB3 GenICam, FireWire, USB 2.0, GigE, or CameraLink).

The configuration of the test environment we used was:

Installing and Configuring Linux

For Ubuntu installation instructions see the Ubuntu documentation at:
https://help.ubuntu.com/ 

Ubuntu 12.04.2 provides USB 3.1 support.

For FlyCapture2 to run on a Linux Ubuntu system, the following dependencies must be installed:

• libgtkmm-2.4-dev
• libglademm-2.4-dev
• libusb-1.0

These libraries are usually packaged with Ubuntu distributions or updates. If they are not pre-installed, use the apt-get console command, as in the following examples:

Ubuntu 16.04

user$: sudo apt-get install libraw1394-11 libgtkmm-2.4-1v5 libglademm-2.4-1v5 libgtkglextmm-x11-1.2-dev libgtkglextmm-x11-1.2 libusb-1.0-0

Ubuntu 14.04

user$: sudo apt-get install libraw1394-11 libgtkmm-2.4-1v5 libglademm-2.4-1v5 libgtkglextmm-x11-1.2-dev libgtkglextmm-x11-1.2 libusb-1.0-0

Ubuntu 12.04

user$: sudo apt-get install libgtkmm-2.4-dev libglademm-2.4-dev libusb-1.0-0

Checking your Linux Version

If you have already installed a version of Ubuntu but are unsure if it supports USB 3.1 run the following command:

$ uname -r

The results look like this:

3.5.0-<specific release>

If the version is 3.5.0 or newer, it supports USB 3.1 and you can move to the next section, Configuring USBFS.

If the version is older than 3.5.0, run the update manager tool to install the newest updates, or run the following command:

$ sudo apt-get update && sudo apt-get upgrade

To install the kernel run the following command:

$ sudo apt-get install linux-generic-lts-quantal

If you prefer not to upgrade, proceed to Compiling a Custom Kernel for USB 3.1 Support to manually configure your system.

Configuring USBFS

By default, Linux limits image capture to 2 MB. To capture images over 2 MB, extend the USBFS limit on how many buffers can be locked into the driver. This is done by updating the boot params in grub. You can set the memory limit until the next reboot, or set it permanently.

• To set the maximum usbfs memory limit until the next reboot, run this command:

$ sudo modprobe usbcore usbfs_memory_mb=1000

• To set the maximum usbfs memory limit permanently:

1. Open the /etc/default/grub file in any text editor. Find and replace:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"

with this:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash usbcore.usbfs_memory_mb=1000"

2. Update grub with these settings:

$ sudo update-grub

3. Reboot and test a USB 3.1 camera.

If this method fails to set the memory limit, run the following command:

$ sudo sh -c 'echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb'

To confirm that you have successfully updated the memory limit, run the following command:

cat /sys/module/usbcore/parameters/usbfs_memory_mb

Installing the FlyCapture SDK

To install the FlyCapture2 SDK:

1. Download FlyCapture2 SDK from our webpage. 
2. Unpack the software in the directory where you want to install it. There are ten packages:

• libflycapture-<version>_<platorm>.deb
• libflycapture-<version>_<platorm>-dev.deb
• libflycapturegui-<version>_<platorm>.deb
• libflycapturegui-<version>_<platorm>-dev.deb
• libflycapture-c-<version>_<platorm>.deb
• libflycapture-c-<version>_<platorm>-dev.deb
• libflycapturegui-c-<version>_<platorm>.deb
• libflycapturegui-c-<version>_<platorm>-dev.deb
• flycap-<version>_<platorm>.deb
• flycapture-doc-<version>_<platform>.deb

The packages with a preceding 'lib' are all the shared objects and their respective dev packages. The flycap package installs the capture application which can be launched by entering 'flycap' in a terminal or through the applications menu. The flycapture-doc package contains Point Grey documentation in pdf format.

3. Run the install script in the same directory into which you unpacked the software. 

user$ sudo sh install_flycapture.sh

4. Follow the instructions of the script. This installs all the FlyCapture2 libraries, example code, sample applications, and documentation.
   
   The script prompts you to configure udev so that devices can be used by a particular user. If you choose to configure devices, the script changes permissions on the nodes by overwriting the default Ubuntu permissions and giving the user full read and write access to the device nodes.

5. Restart your computer for the user permissions to take effect.

Note: If you are using a USB 3.1 device on an Intel system, you may notice that the FlyCap2 viewer is slow to respond. To avoid this problem, ensure the following kernel versions are used:

• 16.04 use kernel 4.4.0-25 or later
• 14.04 use kernel 4.2.0-41 or later, or 3.19-64 or later

Use the following commands to update the kernel:

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get dist-upgrade

Screenshot of FlyCapture2

Compiling the Examples

The FlyCapture SDK includes a number of example applications to help get you started in programming common API tasks. The example files are installed under /usr/src/flycapture/src/.

Copy the extracted folder and sub-folders to a location with write access.

To compile the examples, install the GNU C++ (g++) compiler that is included with the build-essential package:

user$ sudo apt-get install build-essential

Some of the examples are GUI-based. The gtk and glade libraries are required to build these examples. These libraries should already be installed under Section 0. Note that the FlyCaptureGUI example must be built before the FlyCap2 or FlyCapture2GUITest examples can be built.

To compile a specific example, run the makefile located in the example directory. Binaries are copied to the bin directory, and libraries are copied to the lib directory. For example:

user$ cd <extraction folder>/FlyCapture-<version>/src/FlyCapture2Test
user$ make

Limitations Using Linux

Linux users do not have access to Microsoft Windows-only technologies such as:

• DirectShow
• Cognex AIK
• Twain
• Managed .NET API
• ActiveX

FlyCapture2 on a Linux device does not support:

• DriverControlGUI
• RegistryControl
• Recording window in FlyCap2 viewer

Viewing Images and Videos

We suggest the following tools for viewing previously recorded images and videos. FLIR does not officially endorse these tools.
For image viewing:

• gimp
• ImageJ

For video viewing:

• VLC media player

For working with Glade files:

• Glade

Removing FlyCapture

To remove FlyCapture, run the uninstall script.

user$: sudo sh remove_flycapture

Delete any extracted files or newly compiled files on your system.

The uninstall script also removes the udev rules therefore restoring the original Ubuntu permissions on the device nodes.

Compiling a Custom Kernel for USB 3.1 Support

To compile Linux Kernel, the following is required:

• gcc latest version
• ncurses development package
• Up-to-date system packages

To install the dependencies, run the following commands in terminal and enter the password for the user when prompted.

Gcc Installation

$ sudo apt-get install gcc

Ncurses dev package

$ sudo apt-get install libncurses5-dev

Update to the newest packages

$ sudo apt-get update && sudo apt-get upgrade



Getting the Kernel

1. Download the kernel from kernel.org. The kernel with USB3 support is 3.5-rc3.  To download Kernel version 3.5-rc3 run this command:

$ wget http://www.kernel.org/pub/linux/kernel/v3.0/testing/linux-3.5-rc3.tar.bz2

2. Locate where the package was downloaded (most commonly in the Downloads directory):

$ cd Downloads/

3. Untar the package into /usr/src.  You will need root permissions to do this.

 $ sudo tar -xvf linux-3.5-rc3.tar.bz2 -C /usr/src

The unpacking may take some time. 

4. Once unpacked, go to that directory to proceed with configuring the kernel.

 $ cd /usr/src/linux-3.5-rc3/

Configuring the Kernel

Most of the default options for the kernel are appropriate for our use. However, you must select the ext4 file system and enable USB 3.1 support.

1. To start configuration, run this command:

$ sudo make menuconfig

2. From the Kernel Configuration menu, select File systems, and ensure ext4 is selected.
3. From the Device Drivers menu, select USB Support, and ensure that xHCI USB3 is selected.
4. Exit and save the configuration. This creates a file called .config in your root kernel src directory.
5. Open the .config file in a text editor:

$ sudo gedit .config

6. Find the rts5139 module and comment it out using #.

Compiling and Installing the Kernel

Compilation can take about an hour. 

• To compile, run this command:

 $ sudo make

When asked if you want to add the commented out module, answer N.

• To install, run this command:

$ sudo make modules_install install

This creates a number of files under your /boot/ directory and also makes an entry in grub.cfg for the new kernel.  You should check that you have all these files in the /boot/ directory:

• System.map-3.5.0-rc3
• vmlinuz-3.5.0-rc3
• initrd.img-3.5.0-rc3
• config-3.5.0-rc5

Once the kernel is compiled, reboot your computer. It can now capture images up to 2 MB. To capture images larger than 2 MB, follow the instructions in Configuring the USBFS.