.. _linux-trouble-label:

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:

.. code:: sh

    $ 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:

.. code:: sh

    $ LD_DEBUG=libs ./CamTool

In the example we use the sample application from :ref:`cam-tool-label`.

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.