Support Support Home » APIs » XIMEA Linux Software Package » Linux USB30 Support

Linux USB 3.0 Support

General

General support for USB 3.0 on Linux is still in relatively early phase and future releases of Linux kernel and libusb should improve this situation.
Nevertheless, here are the steps needed for enabling USB 3.0 support in XIMEA Linux Software Package:

  • Check kernel version on your system:
    uname -sr
    

    You'll need at least Linux 3.4. Upgrade kernel (if needed Ubuntu users can follow instructions on this page: https://wiki.ubuntu.com/Kernel/MainlineBuilds)
    See example for Linux Ubuntu 12.04 upgrade kernel to 3.4

  • Download and unpack XIMEA Linux Software Package, then start installation using this command:
    ./install
    
  • (Re)connect xiQ USB 3.0 camera
  • Check if current user is in plugdev group
    • If not, execute command: sudo gpasswd -a $USER_NAME plugdev,
    • For changes to apply user has to relog.
  • Most recent version of the troubleshooting guide is in the section 4c of README file included in XIMEA Linux Software Package.

Configure Linux USB Data Path

Most linux distributions needs to be tweaked somehow to ensure that all images from USB3 camera at high data rate will be delivered. This requires some actions:

Increase the USB Buffer Size in Linux

Default USB buffer size in Linux is small (16 MB). This limitation can be removed by command (in Ubuntu):

sudo tee /sys/module/usbcore/parameters/usbfs_memory_mb >/dev/null <<<0

Symptoms: Error code: 13 during startAcquisition()

Increase the USB Buffer Size in xiAPI

Default xiAPI setting is optimized to be compatible with most controllers.
On some controllers (e.g. FL1100) it is possible to increased buffer sizes and counts so data streaming is more reliable.

Change the buffer commit count to 32:

xiSetParamInt(handle, XI_PRM_ACQ_TRANSPORT_BUFFER_COMMIT, 32);

Change the buffer size to maximum:

xiGetParamInt(handle, XI_PRM_ACQ_TRANSPORT_BUFFER_SIZE XI_PRM_INFO_MAX, &buffer_size);
xiSetParamInt(handle, XI_PRM_ACQ_TRANSPORT_BUFFER_SIZE, buffer_size);

Allow to Run Application Realtime

xiAPI has receiving thread that is normally switched to Realtime priority. This requires on some Linux distributions to run with root privilegies. If privilegies does not allow to set priority to realtime - the USB buffer handling remains in normal priority thread and warning message shows.
  • Standard solution:
    • Add following lines to /etc/security/limits.conf
      *               -       rtprio          0
      @realtime       -       rtprio          81
      *               -       nice            0
      @realtime       -       nice            -16
      
    • Create realtime group (groupadd realtime) and add user to it (gpasswd -a user realtime). For changes to apply user has to logoff or just reboot the system.
  • Simple solution - run the application with highest privilegies:
    sudo ./xiSample
    

Change Kernel to be Zerocopy

Default Kernel implementation copy the USB data from kernel space to user space by copying. This is not efficient especially when high amount of data is transferred. In order to overcome this issue - the kernel might be patched to avoid copying (ZeroCopy).
Some developers found the solution. This is 3rd party solution which is not thoroughly tested, but it might help in your case to optimize the system. Here is link to patch for specific kernel.