Installation Guide for Basler pylon 2.3.x for Linux

Transcription

1 Installation Guide for Basler pylon 2.3.x for Linux Version 2.3.x Document ID Number: AW Revision Date: May 27, 2011 Subject to Change Without Notice Basler Vision Technologies

2 Installation of the Basler pylon for Linux Software for Use with Basler Gigabit Ethernet (GigE) Cameras This installation guide relates to Basler pylon 2.3.x for Linux software. You can download the software free of charge from the Basler website at You can also download the Readme for Basler pylon 2.3.x for Linux (AW001003xx000) from the same website. The pylon-2.3.c.dddd-<zz>.tar.gz binary package contains the following files: doc/* # HTML documentation Samples/* # sample files pylon-bininst-<zz>.tar.gz # where <zz> indicates the platform (32 or 64 bit) README INSTALL Extract pylon-bininst-<zz>.tar.gz to the /opt/pylon directory or any directory of your choice. This installation guide assumes you are installing in the /opt/pylon directory. If you choose to install in a different directory you'll have to modify the directory name accordingly. Note: Root permissions are needed to get write access to /opt. Change to the directory where you extracted the package. To install the pylon runtime libraries to /opt/pylon use the following commands: If you want to install the 32 bit version: sudo md /opt/pylon sudo tar -C /opt/pylon -xzf pylon-bininst-32.tar.gz If you want to install the 64 bit version: sudo md /opt/pylon sudo tar -C /opt/pylon -xzf pylon-bininst-64.tar.gz 1

3 Environment Variables For developing and running pylon based applications, the following environment variables must be exported (the following commands assume you have pylon installed in /opt/pylon): export PYLON_ROOT=/opt/pylon export GENICAM_ROOT_V2_1=${PYLON_ROOT}/genicam The runtime linker must be able to find the GenICam libraries during runtime. An easy way to do this is to add the directories to the LD_LIBRARY_PATH variable. The values for the LD_LIBRARY_PATH variable differ depending on the platform you are using. # (for 32 bit Linux) ${PYLON_ROOT}/lib ${GENICAM_ROOT_V2_1}/bin/Linux32_i86 Example command for adding the library directories to the LD_LIBRARY_PATH variable for 32 bit platforms: export LD_LIBRARY_PATH=${PYLON_ROOT}/lib:${GENICAM_ROOT_V2_1}/bin/Linux32_i86:$LD_LI BRARY_PATH # (for 64 bit Linux) ${PYLON_ROOT}/lib64 ${GENICAM_ROOT_V2_1}/bin/Linux64_x64 Example command for adding the library directories to the LD_LIBRARY_PATH variable for 64 bit platforms: export LD_LIBRARY_PATH=${PYLON_ROOT}/lib64:${GENICAM_ROOT_V2_1}/bin/Linux64_x64:$LD_ LIBRARY_PATH To increase runtime performance activate the GenICam cache. To do this the GENICAM_CACHE_V2_1 environment variable must point to a folder where the application can write, e.g., mkdir -p $HOME/genicam_xml_cache export GENICAM_CACHE_V2_1=$HOME/genicam_xml_cache The directory to which the GENICAM_CACHE_V2_1 variable is pointing must exist. The setpylonenv.sh script in the Samples directory provides an example of how to set up the environment variables. 2

4 Version Infos The pylon libraries have been built using the following tools. 32 bit: OpenSuse 10.0 g++ (GCC) (prerelease) (SUSE Linux) GNU ld (GNU Binutils) libstdc _ glibc bit: OpenSuse bit g++ (GCC) (prerelease) (SUSE Linux) GNU ld (GNU Binutils) libstdc _ glibc Network Adapter Configuration This section describes the correct configuration of the network adapter to which a camera is connected. To configure your network adapter use the tools supplied with your operating system. You can use the Basler pylon IP Configuration Tool to configure the IP settings of the camera (see the 'Camera IP Configuration section below). IP address An easy way to establish a connection to a camera is to assign a fixed IP address to the network adapter to which the camera will be connected. When using only one camera or when using multiple cameras connected to only one network adapter via a switch, we recommend that you use Auto IP (also known as Automatic Private IP Addressing, LLA or Zeroconf). Because Basler GigE cameras support the Auto IP feature, a Basler GigE camera will be detected automatically when it is connected to a network adapter configured for Auto IP. When Auto IP is used, both the camera and the network adapter will automatically choose an unassigned IP address within the subnet. It is essential that the network adapter is configured to use Auto IP. Sometimes, automatic IP addressing is called Local-Link, dynamic address assignment, Zeroconf or LLA. If none of these 3

5 settings is available choose DHCP. Most implementations will fall back to Auto IP if they don't receive an DHCP answer. If for any reason, the network adapter cannot be configured to use Auto IP, assign a fixed, static IP address within the subnet. Make sure the address is not already used. If you don't use a DHCP server for IP address configuration we recommend to turn off the DHCP option on the camera to shorten the camera's startup time. Attention: When multiple cameras are to be connected to different network adapters either by using multiple network adapters or by using a multiport network adapter, Auto IP won't work. The network address for each network adapter must be in a different subnet. Assign a fixed IP address from a different subnet to each adapter that has a camera connected. Example: A computer has two network adapters - eth1 and eth2. One camera is to be connected to each network adapter. Assign the address to eth1 and to eth2, and use the subnet mask for both adapters. Use the IP Configurator Tool (see below) to assign a persistent IP address from the subnet to the camera connected to eth1 and a persistent IP address from the subnet to the camera connected to eth2. An alternative to assigning fixed IP addresses to network adapters and cameras is to run a DHCP server. In that case, DHCP must be activated for the cameras. DHCP can be activated by using the Basler pylon IP Configuration Tool. See the 'Camera IP Configuration' section below for more details about changing a camera's IP configuration. Jumbo Frames If your network adapter supports jumbo frames, they should be enabled by setting the Maximum Transfer Unit (MTU) size to Firewall The firewall must be disabled for network adapters to which cameras are connected. Otherwise, device discovery and receiving streaming data may not work. In some cases Reverse Path Filtering may prevent the discovery of devices. See the Readme for Basler pylon 2.3.x for Linux for more details on this. 4

6 Recommended Network Adapters The recommended GigE network adapters for use with Basler GigE cameras are the adapters in the Intel PRO 1000 series. Although the pylon software will run with any GigE network adapter, we observed a significantly higher CPU load when grabbing image data with network adapters other than the recommended Intel PRO 1000 series. Permissions for Real-time Thread Priorities In pylon based applications, the network packets are processed by a receive thread started by the pylongige library. To minimize jitter and network packet losses, the pylon implementation tries to set the receive thread's priority to real-time thread priority. Therefore, applications based on pylon require the necessary privileges to be allowed to change the receive thread's scheduling policy. However, for systems with a Linux kernel or newer, it is possible to allow processes without root privileges to set the realtime scheduling policy. When the Linux PAM module is installed (which is normally the case for OpenSuse 10.3) you can control on a per user or group basis the maximum real-time priority for non-privileged processes via the /etc/securitiy/limits.conf file. For example, adding the line * - rtprio 99 to /etc/security/limits.conf allows all users to launch applications that will set thread priorities to real-time priority. Changing /etc/security/limits.conf requires root privileges. After changing the /etc/security/limits.conf file, logging off and on again is required. For more details about the /etc/security/limits.conf file, see the limits.conf man page. We recommend that for all users who will launch a pylon based application, a maximum realtime priority >=1 be specified. For kernel or older, or when the PAM module is not installed, we recommend either starting pylon based applications with root privileges or setting the SUID bit of pylon based applications. Example: Setting the SUID bit of the PylonViewer program (to be performed by the root user): chown root /opt/pylon/bin/.pylonviewerapp chmod u+s /opt/pylon/bin/.pylonviewerapp Note: When the SUID bit of an application is set, the runtime linker ignores the value for the LD_LIBRARY_PATH variable when launching that application. Thus when using pylon based SUID applications, ensure that the directories where pylon libraries are located are added to the /etc/ld.so.conf file as described above in the 'Runtime Linker Configuration' section. 5

7 You can use the Basler pylon Viewer application (see below) to check if the pylon GigE library has the required permissions for setting real-time thread priorities. After starting the pylon Viewer, select a camera device from the list of devices. In the Features pane expand the Stream Parameters node and select the Guru entry from the User Level drop down list below the Features pane. The 'ReceiveThreadPriority' parameter indicates the thread priority for the receive thread. If the value is zero, the library didn't have the required permissions for setting real-time thread priorities. A value greater than zero indicates that the thread is scheduled with real-time thread priorities. Basler Pylon Viewer The Basler pylon Viewer lets you parameterize cameras and display acquired images. The Basler pylon Viewer program is installed in: /opt/pylon/bin/pylonviewerapp Camera IP Configuration The Basler IP Configuration Tool lets you change a camera's IP configuration (e.g., the IP address). As the IP Configuration Tool needs exclusive access to the camera, we recommend to close all other programs (e.g. the pylon Viewer) before running the IP Configuration Tool. After the IP Configuration Tool is started, it will list all connected cameras. Select the camera to configure from the list of detected devices and click the Change Configuration button. If the camera's current IP address is not within the subnet assigned to the PC's network adapter, a dialog box will pop up requesting that you assign a temporary IP address which matches the PC's subnet. You must do this before proceeding with the IP configuration. There are three methods that a camera can use to obtain an IP address: The user can assign a fixed, persistent IP address. The camera can retrieve an IP address from a DHCP server. The camera can try to automatically negotiate an IP address with the PC to which it is connected (known as AutoIP, Automatic Private IP Addressing, LLA or Zeroconf). Chose the appropriate method by enabling/disabling the corresponding checkboxes in the IP Configuration Protocol pane. When enabling fixed IP addressing, enter the IP address and subnet mask in the input fields of the Persistent IP address pane. Enter a value of for the Default Gateway. Refer to the 'Network Adapter Configuration' section above for more information about assigning IP addresses to the PC's network adapters. Press the Write Configuration button to write the changes into the camera. After the new settings have been written the camera will be reset and the new settings will take effect. 6

8 You can use the Assign Temporary IP address button to assign a temporary static IP address to the camera. The temporary address will remain valid until the camera is powered down or the network plug is removed either from the camera or the PC, but the saved configuration will not be changed. This is useful if you want to connect the camera to a different PC or network adapter to modify some settings, but want to keep the current one untouched. Optimizing Packet Size If your network adapter supports jumbo frames, you set the adapter's MTU to 8192 as described in the 'Network Adapter Configuration' section above. In order to take advantage of the adapter's jumbo frame capability, you must also set the packet size used by the camera to If you are working with the pylon Viewer application, you can set the packet size by first selecting a camera from the tree in the Device pane. In the Features pane, expand the features group that shows the camera's name, expand the Transport Layer parameters group, and set the Packet Size parameter to If you write your own application, use the camera API to set the PacketSize parameter to Building Applications Please refer to the HTML documentation shipped with the Basler pylon package for instructions about building your pylon based applications. Basler Support Worldwide Americas: bc.support.usa@baslerweb.com Europe: bc.support.europe@baslerweb.com Asia: bc.support.asia@baslerweb.com 7

9 8