Linux Troubleshooting

This section is intended to help you debug common issues related to using our cameras on Linux hosts.

Setup UDEV rules for USB

Hint

You can test if you are having UDEV permission issues, if your application can see cameras only when run as the root user.

Modern Linux distro’s include UDEV, a system to manage device events and permissions. By default (at least on headless servers) USB devices are given only read permissions. This is insufficient for Phase One cameras, since we need write permission to send commands to the camera.

Therefore, to make USB camera work on Linux, you must add custom UDEV rules to your host machine, that allows writing to Phase One devices.

Adding the UDEV rule

Custom UDEV rules are located in /etc/udev/rules.d. These rules takes precedence over the default system rules. Which is what we want.

On your Linux machine create a file called 50-usb-phaseone-iqp-cameras.rules in the /etc/udev/rules.d directory. Now, add this content to the file:

# Standard IQP camera device
SUBSYSTEM=="usb", ATTR{idVendor}=="22db", ATTR{idProduct}=="0003", MODE="0666"

# IQP + Mass storage
SUBSYSTEM=="usb", ATTR{idVendor}=="22db", ATTR{idProduct}=="000B", MODE="0666"

# IQP + PTP
SUBSYSTEM=="usb", ATTR{idVendor}=="22db", ATTR{idProduct}=="000C", MODE="0666"

# IQP + PTP + Mass storage
SUBSYSTEM=="usb", ATTR{idVendor}=="22db", ATTR{idProduct}=="000D", MODE="0666"

This adds rules for all (current) Phase One USB devices. Depending on the camera settings it might use different USB Product Id’s.

To put these new rules into effect, to should reload UDEV:

$ sudo udevadm control -R
$ sudo udevadm trigger

Now, all application have write access to Phase One USB devices.

Debugging dynamic linking of libusb

If your Phase One camera still does not show up in the CameraSDK, you should check that libusb is loaded correctly. We can do that by using the LD_DEBUG environment variable. This puts the Linux dynamic linker / loader into debug mode.

Run your application as you normally would, but prepend this to the command line:

$ LD_DEBUG=libs ./CamTool

In the example we use the sample application from CamTool Sample.

The dynamic linker will output the libraries it tries to load:

3397:   find library=libusb-1.0.so.0 [0]; searching
3397:    search cache=/etc/ld.so.cache
3397:    search path=/lib/x86_64-linux-gnu/tls/haswell/x86_64:
        /lib/x86_64-linux-gnu/tls/haswell:/lib/x86_64-linux-gnu/tls/x86_64:
        /lib/x86_64-linux-gnu/tls:/lib/x86_64-linux-gnu/haswell/x86_64:
        /lib/x86_64-linux-gnu/haswell:/lib/x86_64-linux-gnu/x86_64:
        /lib/x86_64-linux-gnu:/usr/lib/x86_64-linux-gnu/tls/haswell/x86_64:
        /usr/lib/x86_64-linux-gnu/tls/haswell:
        /usr/lib/x86_64-linux-gnu/tls/x86_64:
        /usr/lib/x86_64-linux-gnu/tls:
        /usr/lib/x86_64-linux-gnu/haswell/x86_64:
        /usr/lib/x86_64-linux-gnu/haswell:/usr/lib/x86_64-linux-gnu/x86_64:
        /usr/lib/x86_64-linux-gnu:/lib/tls/haswell/x86_64:/lib/tls/haswell:
        /lib/tls/x86_64:/lib/tls:/lib/haswell/x86_64:/lib/haswell:
        /lib/x86_64:/lib:/usr/lib/tls/haswell/x86_64:/usr/lib/tls/haswell:
        /usr/lib/tls/x86_64:/usr/lib/tls:/usr/lib/haswell/x86_64:
        /usr/lib/haswell:/usr/lib/x86_64:/usr/lib   (system search path)
3397:     trying file=/lib/x86_64-linux-gnu/tls/haswell/x86_64/libusb-1.0.so.0
3397:     trying file=/lib/x86_64-linux-gnu/tls/haswell/libusb-1.0.so.0
3397:     trying file=/lib/x86_64-linux-gnu/tls/x86_64/libusb-1.0.so.0
3397:     trying file=/lib/x86_64-linux-gnu/tls/libusb-1.0.so.0
3397:     trying file=/lib/x86_64-linux-gnu/haswell/x86_64/libusb-1.0.so.0
3397:     trying file=/lib/x86_64-linux-gnu/haswell/libusb-1.0.so.0
3397:     trying file=/lib/x86_64-linux-gnu/x86_64/libusb-1.0.so.0
3397:     trying file=/lib/x86_64-linux-gnu/libusb-1.0.so.0

...

Here the dynamic linker cannot find the needed libusb shared object file: libusb-1.0.so.0, and it tries multiple search paths to locate it.

Overwrite libusb Search Path

In case your Linux distribution or root filesystem uses another filename or location for libusb, you can overwrite the search path that CameraSDK uses.

If CameraSDK sees the environment variable P1_LIBUSB_FILE, it will load libusb from that location instead of its default behaviour. The (string) value of P1_LIBUSB_FILE is directed into the dlopen call. Meaning you can either supply a filename, or the complete path.

Multiple USB Cameras

If you’re encountering issues with camera connectivity and image transfer on Linux, using 3 or more cameras, you might need to adjust the USB-FS buffer size. This buffer manages data flow between USB devices and the operating system. Here’s how you can manually configure the USB-FS buffer size to allow better performance, particularly when dealing with many USB cameras.

Acessing the Configuration

First, you will need to adjust the USB-FS buffer size. By default, it’s set to 16 MB, which can lead to problems when many USB devices are connected. (The buffer is shared between all connected USB devices.)

Recommended Buffer Size

Based on our testing, we recommend allocating between 6 and 8 MB of buffer size for each connected camera - this allows for some additional capacity.

Configuration Steps

Follow these steps to adjust the USB-FS buffer size:

1) Create the Configuration File

If you don’t have the /etc/rc.local file on your system, you’ll need to create it. Run the following commands in your terminal:

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

2) Edit the Configuration File

Open the /etc/rc.local file using a text editor:

$ sudo nano /etc/rc.local

If the file is newly created, add the following lines:

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

If the file already exists, insert the following lines before the exit 0 line:

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

3) Save and Apply Changes

Save your changes and close the text editor. Then restart your machine to apply the new USB-FS buffer configuration.

Verifying Configuration

After restarting, you can confirm that the memory limit has been updated by running the following command in your terminal:

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

If you’re unable to set the memory limit using the above command, you can temporarily adjust the USB-FS memory until the next restart with the following command:

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

If you continue to experience any issues or need further assistance, please don’t hesitate to contact us.