Ensure you have the correct Pixelink SDK Variant
There are several variants of the Pixelink SDK (for Linux):
64-bit variant that is built for Intel x86 'PCs'. These systems may have an Intel, or an AMD processor.
v2.1 for PCs running Ubuntu 14.04
v2.2 for PCs running Ubuntu 16.04
v2.3 for PCs running Ubuntu 14.04/16.04
v2.4 for PCs running Ubuntu 14.04/16.04/18.04
v3.0 for PCs running Ubuntu 16.04/18.04/20.04
v3.2 for PCs running Ubuntu 16.04/18.04/20.04
v3.3 for PCs running Ubuntu 16.04/18.04/20.04/22.04
A 32-bit variant that is built for ARM7 platforms, including the Odroid XU3/4 and the NVIDIA Jetson-TK1.
v2.1 for Odroid XU3/4 running Ubuntu 14.04
v2.1 for Jetson TK1 running Ubuntu 14.04
v2.2 for Odroid XU3/4 running Ubuntu 16.04
v2.3 for ARM7 platforms running Ubuntu 14.04/16.04
v2.4 for ARM7 platforms running Ubuntu 14.04/16.04/18.04
v3.0 for ARM7 platforms running Ubuntu 16.04/18.04
v3.2 for ARM7 platforms running Ubuntu 16.04/18.04
v3.3 for ARM7 platforms running Ubuntu 16.04/18.04
A 64-bit variant that is built for ARM8 platforms, including Jetson TX1/TX2, Nano
v2.1 for Jetson TX1/TX2 running Ubuntu 14.04
v2.2 for Jetson TX1/TX2 running Ubuntu 16.04
v2.3 for ARM8 platforms running Ubuntu 14.04/16.04
v2.4 for ARM8 platforms running Ubuntu 14.04/16.04/18.04
v3.0 for ARM8 platforms running Ubuntu 16.04/18.04
v3.2 for ARM8 platforms running Ubuntu 16.04/18.04
v3.3 for ARM8 platforms running Ubuntu 16.04/18.04/20.04/22.04
A 64-bit variant that is built with a focus on the Raspberry Pi 4
v3.0 for Raspberry Pi 4 running Ubuntu 20.10
v3.2 for Raspberry Pi 4 running Ubuntu 20.10
v3.3 for ARM8 platforms running Ubuntu 22.04
The installation instructions for your SDK Variant are written in the INSTALL_INSTRUCTIONS.txt file, which is included with the downloaded SDK. For convenience, some of the required steps are listed below, but please refer to the install instructions file for a comprehensive list.
Install prerequisite libraries
The Pixelink SDK uses the libraries listed below. Please install the latest variant of these libraries on your system. Be sure to choose the 64-bit variant for PCs and ARMv8s, and the 32-bit variant for ARMv7s.
GNU C++ toolchain, including the G++ compiler/linker. For instance, you could use the following command to install the necessary tools to build basic applications (including the GNU C++ toolchain):
sudo apt-get install build-essential
If you intend to use the Pixelink API Python interface, then you will need to install Python package installer::
sudo apt-get install python3-pip
As explained in the READ.ME.txt file, there are two variants of the Pixelink API; the standard (default) version that is fully functional, and a 'Lite' version that has reduced dependencies and functionality. The standard version of the API has the following additional dependencies:
SDL2. Simple Directmedia Layer, used principally for video previewing capabilities. For instance, you can download the 2.0 version of this library with the following command:
sudo apt-get install libsdl2-2.0
Additionally, if you intend to develop (Gnome based) GUI applications, similar to the captureOEM sample application, you will need the development files for this library. That is:
sudo apt-get install libsdl2-dev
GTK+3 and Glade, used for the (Gnome-based) GUI applications captureOEM and simpleGui. GTK+3 is a dependent library of Glade, so installing Glade will also install GTK+3. Your version of Gnome will have software package management tool, it's usually easiest to use it to download the Glade tool. Alternatively, you can use the following command to get Glade:
[for Ubuntu 14.04] sudo apt-get install glade-gnome
[for Ubuntu 16.04 and above] sudo apt-get install glade
ffmpeg / libav. ffmpeg is an open source video compression library, while libav is a forked version of that library that was used with Ubuntu 14.04. You can install the latest variant of this library as follows:
[for Ubuntu 14.04] sudo apt-get install libav-tools
[for Ubuntu 16.04 and above] sudo apt-get install ffmpeg
NOTE: Some of these dependent libraries may not be part of 'official' distribution for your particular install, as they rely on open-source software. If your system cannot find the above libraries, then you can update the search repositories with commands such as:
sudo add-apt-repository universe
sudo add-apt-repository multiverse
sudo apt-get update
Install the Pixelink SDK files
The Pixelink SDK files have been archived into the compressed archive file PixeLINKSdk-for-zzzzz-vx.y, where 'zzzzz' identifies the target OS for the specific install (such as Ubuntu14.04-x86_64 for a 64-bit build of Ubuntu v14.04 on a PC platform), and 'x' and 'y' refer to the version and sub-version respectively. Before decompressing this archive, you should consider an 'appropriate' location for the Pixelink files. For example, a single user install may want to locate the files off of the directory ~/PixeLINKSdk, whereas a multi-user install would want the files located in a more central location. When decompressed (using a command like tar -xzvf PixeLINKSdk-for-Ubuntu20.04-x86_64-v3.2.tar.gz), the Pixelink SDK will be expanded into the following folders:
lib: This folder contains the shared libraries required to build (link) camera control applications. Your build process must be able to 'locate' these libraries (see step 4 of the INSTALL_INSTRUCTIONS.txt file). The file HOW.TO.USE.PxlApiLite.txt contains instructions on how to use the 'Lite' variant of the Pixelink API (as explained in the READ.ME.txt file).
include: This folder contains the 'C' header files describing the programmers interface to the Pixelink API.
samples: This folder contains a series of other folders which provide sample applications that use the Pixelink API. These folders contain all of the source and makefiles needed to build the application.
utilities: This folder contains any Pixelink utility programs, provided in binary form. See the READ.ME.txt file for a list of these utilities.
Create a PIXELINK_SDK_INC and PIXELINK_SDK_LIB environmental variables
These environmental variables identify the folder where the Pixelink SDK files have been installed (from the previous step). See the makefiles in the sample application to see how this variable can be used to build applications.
The easiest way to do this, is to create and export them within a startup script. One way of doing this is shown in the step below.
Configure your system so that the runtimes can find the Pixelink shared objects
You could do this by locating the shared objects in a common location (such as /lib) and using the ldconfig to create the necessary links to the shared libraries, however this requires super user privilege. Alternatively, you can add the path $PIXELINK_SDK_LIB (where PIXELINK_SDK was created in the step above) to the environmental variable LD_LIBRARY_PATH.
For example, assuming the Pixelink SDK files were installed to the ~/PixeLINKSdk folder, you could accommodate both this and the previous step by adding the following set of commands to a particular users ~/.bashrc file:
# +++++ PixeLINK cameras/SDK +++++
PIXELINK_SDK_INC=~/PixeLINKSdk/include
PIXELINK_SDK_LIB=~/PixeLINKSdk/lib
LD_LIBRARY_PATH=$PIXELINK_SDK_LIB
export PIXELINK_SDK_INC
export PIXELINK_SDK_LIB
export LD_LIBRARY_PATH
# ----- PixeLINK cameras/SDK -----
Note:
Starting with release 3.2 of Linux SDK, the SDK now includes two versions of the Pixelink API binary; the fully featured variant (used by default), and a reduced footprint / reduced functionality variant known as PxLApiLite. For more informaiton, see the PxLApiLite article.
Add read/write privilege to the camera device(s) (USB cameras only)
Pixelink API applications require read and write access to the USB device (the camera) in order to communicate with the device. On Ubuntu, this can be accomplished by creating a 'PixeLINK.rules' file in the 'etc/udev/rules.d' folder, that contains the following lines:
SUBSYSTEM=="usb",ATTRS{idVendor}=="1996",MODE="0666"
SUBSYSTEM=="usb_device",ATTRS{idVendor}=="1996",MODE="0666"
Note that you will need super user privilege to create this file in this folder, but once this is done, all users will be able to control all Pixelink cameras connected to the system. For instance, the following command will open/create this file:
sudo gedit /etc/udev/rules.d/PixeLINK.rules
Increase the amount of receive buffer space available to devices (if required)
USB cameras
By default, the Linux kernel will allocate as little as 16MB of buffer space for all USB devices. For larger, higher speed devices (such as the Pixelink USB3 cameras) this is not adequate. At 400 MB/s, 16MB of buffer space only amounts to 40 ms of buffer time before data loss occurs. Calling the API function PxLSetStreamState to turn on the camera stream, will return a warning return code of ApiSuccessLowMemory if your system is currently configured for very little buffer space. See the sample application lowLinkMemory for details.
To increase the amount of USB buffer space to a more appropriate value (in this case, 1GB), do the following on systems using GRUB based bootloader (such as Ubuntu running on a PC):
Edit the file ‘/etc/default/grub’ and look for the line ‘GRUB_CMDLINE_LINUX_DEFAULT=”{some_text}”
Append ”usbcore.usbfs_memory_mb=1000” to the end of some_text. For example:
GRUB_CMDLINE_LINUX_DEFAULT=”quiet splash”
becomes
GRUB_CMDLINE_LINUX_DEFAULT=”quiet splash usbcore.usbfs_memory_mb=1000”
Effect this change with the following command:
sudo update-grub
Manually set the memory limit (to 1GB) by entering the command:
‘sudo modprobe usbcore usbfs_memory_mb=1000’
Reboot your system for this change to take effect.
Gigabit Ethernet (including 10 GigE) cameras
Redefining the IP stack receive buffer space
By default, the Linux kernel will allocate as little as mere 256 bytes of receive buffer space for it's IP stack. For larger, higher speed devices (such as the Pixelink 10 GigE cameras) this is not adequate. Calling the API function PxLSetStreamState to turn on the camera stream, will return a warning return code of ApiSuccessLowMemory if your system is currently configured for very little buffer space. See the sample application lowLinkMemory for details.
Increasing the amount of receive buffer space to a more appropriate value (in this case, 25 MB) is outlined as follows. It's recommended that you allocate enough receive buffer space for at least 2 images. For instance, if you will be using your system to stream a 6 megapixel camera using a 16-bit pixel format, then you should have at least 24 MB of receive buffer.
Increasing the amount of receive buffer space to a more appropriate value (in this case, 25 MB) is outlined as follows. It's recommended that you allocate enough receive buffer space for at least 2 images. For instance, if you will be using your system to stream a 6 megapixel camera using a 16-bit pixel format, then you should have at least 24 MB of receive buffer.
Edit the file ‘/etc/sysctl.conf’ (requires super-user privilege)
Add the following to the file
# Allow 25MB of receive buffer memory
net.core.rmem_max=26214400
net.core.rmem_default=26214400
Effect this change with the following command:
sudo sysctl -p
Enabling 'Jumbo' Ethernet frames (packets)
The original Ethernet specification defined the maximum packet size as 1500 bytes. This packet size is too small to accommodate newer high capacity / throughout network devices such as Pixelink 10 GigE cameras. Fortunately, most current NICs and switches, can accommodate larger 'jumbo' frames.
To ensure maximum performance from your Pixelink 10 GigE camera, ensure that the systems NIC, and all intermediate Ethernet switches between the host system and the camera, have defined the maximum frame size of at least 9000 bytes.
Note that the Raspberry Pi 4 platform does not support jumbo frames without modifications to its kernel. See the 'Known Issues' in the READ.ME.txt file for more details.
For more instructions, please see the INSTALL_INSTRUCTIONS.txt file, included in the downloaded SDK.
If you run into any issues when installing the SDK, please contact Support at pixelink.support@ametek.com.