1. Support Center
  2. Understanding USBFS on Linux

Understanding USBFS on Linux

Applicable products

  • All USB cameras

Application note description

This application note describes how USB-FS affects Linux users and why proper settings impact performance.

What are buffers?

When an image is captured by a camera it is automatically transferred to the PC and stored in the PC's RAM. The space assigned to store that image in memory is called a buffer.

The Steam Buffer Count Mode can be configured as either Auto or Manual.

  • Auto: the number of buffers allocated in memory is automatically assigned, based on the maximum frame rate of the camera.
  • Manual: the number of buffers associated with a camera can be manually configured by assigning a value to the Manual Stream Buffer Count.

For more information on buffers, see Understanding Buffer Handling.

Why configure USB-FS?

By default, USB-FS on Linux systems only allows 16 MB of buffer memory for all USB devices. This may result in image acquisition issues from high-resolution cameras or multiple-camera set ups. This limit must be increased to make use of the imaging hardware's full capabilities.

FLIR recommends that users configure USB-FS to use 1000 MB of buffer memory to ensure incoming images can be buffered. If using multiple USB cameras, the USB-FS memory limit may need to exceed 1000 (Example B at the end of this article); this helps to prevent crash issues associated with buffer allocation when starting the camera.

Configuring USB-FS

This method applies to Ubuntu 16.04/18.04 standard installations. For ARM boards, see our article on Using Spinnaker on ARM and Embedded Systems.

The Spinnaker installer asks to automatically set the appropriate USB-FS memory settings, but you can also run the included configuration script (in the same directory as the install script) at any time:

$ sudo sh configure_usbfs.sh

To manually configure the USB-FS memory:

1. If the /etc/rc.local file does NOT already exist on your system, run the following commands to create and make it executable

$ sudo touch /etc/rc.local
$ sudo chmod 744 /etc/rc.local

2. Open the /etc/rc.local file in any text editor,

$ sudo nano /etc/rc.local

If this file was just created add the following to it,

#!/bin/sh -e
echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb
exit 0

If this file already existed then add the following before the exit 0 line,

echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb

3. Save your changes and close the file.

4. Restart the machine. 

To confirm that the memory limit has been updated, run the command:

$ cat /sys/module/usbcore/parameters/usbfs_memory_mb

If this fails to set the memory limit, one can TEMPORARILY modify the USB-FS memory until the next restart by running the following command:

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

Understanding how much USB-FS memory is needed

The USB-FS memory needed depends on two parameters: image size and the number stream buffers allocated (Resulting Stream Buffer Count).

1. The image size is calculated by the resolution and bit-depth.

        Image Size = Resolution X Bit-depth

2. The USB-FS memory size needed can be calculated by the Image Size and Resulting Stream Buffer Count, for all USB cameras.

        USB-FS needed = ∑ Image Size X Resulting Stream Buffer Count

Example A:

One camera is to stream at the resolution of 1920 x 1080 and at 8-bit pixel format.

        Image Size = 1920 X 1080 X 8 bits = 16,588,800 bits (2,073,600 bytes) = ~2 MB

If 300 stream buffers are allocated (Resulting Stream Buffer Count = 300), then at least 600 MB (2 MB X 300) of USB-FS memory needs to be available.

Example B:

2 cameras are to stream at the resolution of 1920 x 1080 and at 8-bit pixel format at the same time.  If 300 stream buffers are allocated (Resulting Stream Buffer Count = 300) for each camera, then

        USB-FS needed = 2 MB X 300 X 2 = 1200 MB

In this case, the USB-FS needs to configured to be at least 1200 MB (recommended to be over 1200 MB). 

Alternatively, if the USB-FS memory size is preferred to be configured to 1000 MB, how should the buffers be allocated? Stream Buffer Count Mode needs to be set to Manual, and the Manual Stream Buffer Count needs to be set to a value lower than 300 (such as 200). In this way, the total buffer memory needed for all cameras (2 MB X 200 X 2 = 800 MB) will not exceed the configured USB-FS memory size (1000 MB).