eBUS SDK for Linux - ftp.elvitec.frftp.elvitec.fr/Pleora/SDK-LOGICIEL/eBUS SDK for Linux Quick...

Installing, Uninstalling, and Starting the Software Applications a

PLEORA TECHNOLOGIES INC.

eBUS SDK for LinuxeBUS SDK Version 5.0

Quick Start Guide

Copyright © 2017 Pleora Technologies Inc.

These products are not intended for use in life support appliances, devices, or systems where malfunction of these products can reasonably be expected to result in personal injury. Pleora Technologies Inc. (Pleora) customers using or selling these products for use in such applications do so at their own risk and agree to indemnify Pleora for any damages resulting from such improper use or sale.

Trademarks

PureGEV, eBUS, iPORT, vDisplay, AutoGEV, AutoGen, and all product logos are trademarks of Pleora Technologies. Third party copyrights and trademarks are the property of their respective owners.

Notice of Rights

All information provided in this manual is believed to be accurate and reliable. No responsibility is assumed by Pleora for its use. Pleora reserves the right to make changes to this information without notice. Redistribution of this manual in whole or in part, by any means, is prohibited without obtaining prior permission from Pleora.

Document Number

EX001-017-0013, Version 7.0 2/3/17

Table of Contents
About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
What this Guide Provides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

Introducing the eBUS SDK for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3About the eBUS SDK for Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4eBUS SDK Licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Installing the eBUS SDK for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Installing the eBUS SDK for Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Optimizing Operation with GigE Vision Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Loading the eBUS Universal Pro for Ethernet Filter Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Enabling Jumbo Ethernet Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Increasing the Socket Buffer Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Additional Optimization Steps for the x86 for Linux Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Using eBUS Player to Configure Devices and Stream Images on the x86 for Linux Platform . . . . . 15

Compiling and Running Sample Applications for the x86 for Linux Platform . . . . . . . . . . . . . . . . . . 17

Cross-Compiling and Running Sample Applications on an Embedded ARM Board . . . . . . . . . . . . . 19Cross-Compiling the Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Running the Samples on the Embedded ARM Board. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Troubleshooting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

i

Chapter 1

About this GuideThis chapter describes the purpose and scope of this guide, and provides a list of complimentary guides.

The following topics are covered in this chapter:

• “What this Guide Provides” on page 2

• “Related Documents” on page 2

About this Guide 1

What this Guide Provides

This guide provides you with the steps to use the eBUS SDK on the Linux operating system, on a Linux x86 or x86_64 or Linux ARM platform. This guide is intended for novice Linux users, although advanced Linux users may be interested in some of the eBUS SDK-specific elements of this guide.

The installation, configuration, and usage instructions contained in this guide are based on the CentOS Linux distribution (for the Linux x86 platform) and Ubuntu 12.04 LTS (for the Linux ARM platform).

Related Documents

The eBUS SDK for Linux Quick Start Guide is complemented by the following guides, available on the Pleora Support Center at www.pleora.com.

• eBUS Player Quick Start Guide for Windows, eBUS Player Quick Start Guide for OS X

• eBUS Player User Guide for Windows, eBUS Player User Guide for OS X

• eBUS SDK C++ API Quick Start Guide

• Configuring Your Computer and Network Adapters for Best Performance knowledge base article

• eBUS SDK Licensing knowledge base article

• eBUS SDK C++ API documentation. Navigate to <installation_directory>/share/doc/sdk/index.html

2 eBUS SDK for Linux Quick Start Guide

http://www.pleora.com

Chapter 2

Introducing the eBUS SDK for LinuxThis chapter describes the eBUS SDK for Linux, which is an application development toolset that allows you to develop custom vision systems to acquire and transmit images and data using the Linux operating system.


• “About the eBUS SDK for Linux” on page 4

• “eBUS SDK Licenses” on page 5

Introducing the eBUS SDK for Linux 3

About the eBUS SDK for Linux

Designed for use in high-performance digital video systems and cameras, Pleora’s eBUS™ Software Development Kit (SDK) is a feature-rich toolkit that allows Windows, Linux and Mac developers to produce video applications in short timeframes, while reducing risk and lowering design and support costs.

The eBUS SDK is based on a clean, modular architecture that uses a single set of functions to receive video over GigE, 10 GigE, USB, and IEEE 802.11 wireless. This helps “future-proof” application software because it can be modified quickly and easily for different media. It also helps developers work efficiently, and reduces support for portfolios with multiple interface offerings.

Pleora’s eBUS SDK features a huge library of sample code, which serves as a quick-start platform for each development project. It also includes the eBUS Universal Pro driver, which helps developers achieve high-performance results by maximizing end-to-end throughput and ensuring video is delivered with low, consistent latency.

The eBUS SDK complies fully with the GigE Vision®, USB3 Vision™ and GenICam™ standards, and is compatible with every version of each. It interoperates seamlessly with Pleora’s extensive portfolio of video interface products, as well as with standards-compliant products from other manufacturers.


eBUS SDK Licenses

While the eBUS SDK is a licensed product, you can trial it without purchasing a license. However, the following limitations apply:

• Received images (received from third-party GigE Vision or USB3 Vision devices, such as non-Pleora enabled cameras) have an embossed watermark.

• Raw data is only received from Pleora enabled cameras.

Understanding Licensing

Each license is associated to the MAC address of a network interface card (NIC). When you purchase a transmit or receive license, your Pleora representative will request the MAC address of a NIC in the workstation. Pleora includes the MAC address in the license file that your representative provides you with, which allows the eBUS SDK to accept the license. The MAC address is used to identify the workstation, and is required regardless of the protocol (GigE Vision or USB3 Vision).

Activating an eBUS SDK License

For detailed information about licensing, including details on activating a license, see the eBUS SDK Licensing knowledge base article, available on the Pleora Technologies Support Center.

5Introducing the eBUS SDK for Linux

Chapter 3

Installing the eBUS SDK for LinuxThis chapter provides system requirements and installation steps that you will use to install the eBUS SDK for Linux.


• “System Requirements” on page 8

• “Installing the eBUS SDK for Linux” on page 9

Installing the eBUS SDK for Linux 7

System Requirements

Ensure the computer or embedded ARM target meets the following recommended requirements:

• At least one Gigabit Ethernet NIC (if you are using GigE Vision devices) or at least one USB 3.0 port (if you are using USB3 Vision devices).

For the x86 Linux platform:

• Appropriate development toolchains or integrated development environment (IDE):

• gcc 4.4.7 (or later) to compile non-GUI samples

• QMake version 2.01a, with Qt version 4.6.2 to compile GUI-based samples

• Kernel-devel package for your specific kernel version to compile the eBUS Universal Pro for Ethernet filter driver

• One of the following operating systems:

• Red Hat Enterprise Linux 7, 64-bit

• CentOS 7, 64-bit

• Ubuntu 14.04 LTS and 16.04 LTS, 32-bit or 64-bit

Note: If you plan on using H.264 encoding on the x86 Linux operating system, you must install some external libraries, enable the H.264 encoding functionality, and recompile the eBUS Player sample application. For more information, see the eBUS SDK C++ API Quick Start Guide, which is available on the Pleora Support Center (www.pleora.com).

For the Linux for ARM platform:

• Appropriate cross-compile development toolchains:

• ARM gnu cross-compile toolchain 4.8 (or later)

• Glibc version 2.19 or later. Please note that other C library implementations, such as uClibc and eglibc, are not supported.

• Linux kernel version 3.1 or later. Netfilter kernel configuration must be enabled before you compile the eBUS Universal Pro for Ethernet filter driver.

• Linux Ubuntu 14.04 LTS development host (or later) is recommended for manual installation of the eBUS SDK on your ARM board.

• It may be possible to use the eBUS SDK with other distributions or development toolchains, however usage information may vary.

• On the Linux ARM platform, it is important that you have the correct toolchain, which is often provided by the board manufacturer. Ensure that the development board is configured, loads Linux, and the user can transfer files from the development computer to the target board. See the eBUS SDK release notes for tested configurations.

Linux distributions other than Ubuntu may require manual steps when running the installer for the Linux ARM platform. For more information, see “Manually installing non-Ubuntu distributions on ARM targets” on page 10.



Tool Requirements for the x86 for Linux Platform

If you have a receive license, install it before you begin. For more information, see “Activating an eBUS SDK License” on page 5.

For Linux ARM platform users, we recommend that before you begin, you take note of the gnu eabi toolchain that is used to compile objects. You will be required to select the proper .run file for your toolchain during installation.

For example, eBUS_SDK-<version>-linux-gnueabi-arm.run is for soft-float targets and eBUS_SDK-<version>-linux-gnueabihf-arm.run is for hard-float targets.

The eBUS SDK uses the standard development tools available for the supported Linux distributions. The eBUS Universal Pro for Ethernet filter driver requires the kernel development package and gcc to compile. These can be installed using the Yum package updater, by executing yum install gcc and yum install kernel-devel, respectively. The sample applications require the gcc-c++ package for compilation, which can be obtained by executing yum install gcc-c++. Sample applications with GUI elements require Qt version 4.6.2 for compilation, which can be installed using yum install qt-devel.

Installing the eBUS SDK for Linux

Step 1. Installing the eBUS SDK

For the x86 or x64 for Linux platform

1. Log in as superuser.

2. Execute one of the following commands, depending on the operating system:• For Ubuntu: sudo dpkg -i eBUS_SDK_Ubuntu-<version>.deb

• For x64 CentOS or Red Hat Enterprise Linux: sudo rpm -i eBUS_SDK_CentOS-RHEL-7-x86_64-<version>.rpm

The SDK installs to the /opt/pleora/ebus_sdk/<platform> directory.

3. Follow the installation prompts, as outlined below.

For supported USB 3.0 host controller chipsets, consult the eBUS SDK Release Notes, available on the Pleora Support Center.

You must install the SDK as superuser.

9Installing the eBUS SDK for Linux

For the Linux for ARM platform

1. Execute sudo dpkg -i eBUS_SDK_<version>_linux-<architecture>-arm.deb

Where <architecture> is either gnueabihf for hard-float targets or gnueabi for soft-float targets.

The SDK installs to the /opt/pleora/ebus_sdk/linux-<architecture>-arm directory.

2. Follow the installation prompts, as outlined below.

Installation prompts (all platforms)

• During installation, the script will ask if you would like to:

• Add the eBUS SDK and GenICam libraries to the list of shared libraries available on the system using the ldconfig utility. The default answer is yes.

• Compile the eBUS Universal Pro for Ethernet filter driver, which is used to optimize the operation of GigE Vision devices. If the kernel development and gcc packages have been installed, the driver can be compiled. If not, the script fails.

If you skip the prompt to compile the driver or if the script fails, you can build it later by running the <installation_directory>/module/build.sh script.

Note: If the eBUS Universal Pro for Ethernet driver is not loaded, you can still work with GigE Vision devices. However, until you load the driver, the operation of these devices is not optimized.

The steps for loading the driver after it has been compiled are provided in “Loading the eBUS Universal Pro for Ethernet Filter Driver” on page 14.

Important: You must compile the eBUS Universal Pro for Ethernet driver for each different kernel version.

• Disable strict Reverse Path Forwarding filtering. Disable this setting if you want to detect GigE Vision compliant devices that are configured with a different subnet than your computer’s NIC (for example, if the computer uses a static IP address but the GigE Vision device uses an LLA address). For more information, see https://access.redhat.com/site/solutions/53031. The script makes the change, optionally resets the network stack, and then persists this change across reboots. To change this setting later, execute the <installation_directory>/bin/set_rp_filter.sh script as superuser, and choose option 0.

At this point, the installation script is complete and the eBUS SDK is fully installed (with the exception of the eBUS Universal Pro for Ethernet driver, which is loaded in “Loading the eBUS Universal Pro for Ethernet Filter Driver” on page 14).

Manually installing non-Ubuntu distributions on ARM targets

1. On a Ubuntu-16.0.4 development host, execute ./eBUS_SDK_<version>_linux-<architecture>-arm.run

2. Execute "tar -cvf ~/pleora.tar /opt/pleora" to zip the installed files.

3. Copy the pleora.tar file from the host to the ARM target in the /opt directory.

4. Execute cd/opt on the target to move to the /opt directory.

5. Unzip the .tar file by executing sudo tar -xvf ./pleora.tar.


https://access.redhat.com/site/solutions/53031

Step 2: Installing Licenses and Setting Up Access for USB3 Vision Devices

To use a license (either a transmitter or third-party runtime license) or access devices that support the USB3 Vision standard, you must install and run the eBUS SDK daemon (eBUSd).

To install and run eBUSd

• As superuser, execute the <installation_directory>/bin/install_daemon.sh script and follow the prompts.

You can manually control the state of the daemon by issuing commands.

• For x86 for Linux: service eBUSd <command> (where <command> can be start, stop, restart, or status) as superuser.

- Or -

• For non-Ubuntu Linux distributions for ARM: sudo ./eBUSd <command> (where <command> can be start, stop, restart, or status) as superuser.

To set up access for USB3 Vision devices that are not enabled with Pleora’s technology

1. As superuser, execute the <installation_directory>/bin/set_udev_rules.sh script and follow the prompts.

2. When prompted, enter the vendor ID assigned to the device’s manufacturer. This number often appears on the device’s label.

For x86 for Linux platforms, Kernel version 2.6.32-431 (or later) is required for USB 3.0 support on either CentOS or Red Hat Enterprise Linux.

To uninstall the eBUS SDK, execute the <installation_directory>/bin/uninstall.sh script as superuser.

To increase memory size for high bandwidth applications (Ubuntu distribution only)

For high bandwidth applications on the Ubuntu distribution, you can increase the USB 3.0 memory size.

• As superuser, execute the <installation_directory>/bin/set_usbfs_memory_size.sh script and follow the prompts.

11Installing the eBUS SDK for Linux

Chapter 4

Optimizing Operation with GigE Vision DevicesThis chapter provides some steps you can take to optimize operation when using GigE Vision devices with the eBUS SDK.


• “Loading the eBUS Universal Pro for Ethernet Filter Driver” on page 14

• “Enabling Jumbo Ethernet Frames” on page 14

• “Increasing the Socket Buffer Size” on page 14

• “Additional Optimization Steps for the x86 for Linux Platform” on page 14

Optimizing Operation with GigE Vision Devices 13

Loading the eBUS Universal Pro for Ethernet Filter Driver

To optimize operation with GigE Vision devices, we strongly recommend that you use the eBUS Universal Pro for Ethernet filter driver. This filter driver enhances the performance of your system by allowing GigE Vision Stream Protocol (GVSP) data to bypass some (or all) of the operating system’s network stack, delivering the data directly to the eBUS SDK.

After the filter driver has been compiled (as outlined in “Step 1. Installing the eBUS SDK” on page 9), you can load it using the <installation_directory>/module/load.sh script. To unload it, use the module/unload.sh script.

Enabling Jumbo Ethernet Frames

If supported by your network card, GigE Vision device, and switch (if applicable), we recommend that you enable jumbo Ethernet frames when using GigE Vision devices. The use of jumbo frames reduces the amount of Ethernet, IP, UDP, and GVSP packet overhead when transmitting images, which reduces the CPU load and memory requirements.

To enable jumbo packets

• As superuser, execute the following command:/sbin/ifconfig eth[INDEX] mtu [SIZE]

where, [INDEX] = 0,1,2,…,n (depending on the number of NICs present)

[SIZE] = desired frame size

For example,

/sbin/ipconfig eth0 mtu 8000

Increasing the Socket Buffer Size

To further improve performance, you can also increase the size of the socket buffer.

To increase the socket buffer size

• As superuser, execute the <installation_directory>/bin/set_socket_buffer_size.sh script.

Additional Optimization Steps for the x86 for Linux Platform

If you are using an Intel Pro/1000-based network interface when working with the x86 for Linux platform, there are additional configuration settings that can yield performance improvements. If you have an Intel Pro/1000 NIC, refer to the Configuring Network Adapters for Best Performance knowledge base article (available on the Pleora Support Center) for more information. For other NICs, see the documentation accompanying the NIC.


Chapter 5

Using eBUS Player to Configure Devices and Stream Images on the x86 for Linux Platform

When you are working with the x86 for Linux platform, you can use eBUS Player (which is precompiled and installed with the release in the bin folder) to connect to, configure, and stream images from GigE Vision and USB3 Vision devices.

You must disable the firewall before using GigE Vision devices. Some optimization may be desirable before using GigE Vision or USB3 Vision devices with the eBUS SDK in a production environment, as was discussed in “Optimizing Operation with GigE Vision Devices” on page 13.

Using eBUS Player to Configure Devices and Stream Images on the x86 for Linux Platform 15

Note: In the bin folder, you will find both an eBUSPlayer script and an eBUSPlayer.bin executable. You should always execute the eBUSPlayer script, which sets the proper environment variables, and then automatically executes the eBUSPlayer.bin executable.


Chapter 6

Compiling and Running Sample Applications for the x86 for Linux Platform

We strongly recommend that you copy the sample applications from the share/samples directory to your personal development workspace before modifying or compiling them. A list of samples, with a description of each, can be found in the index.html file in that directory.

The sample applications require the gcc-c++ package for compilation, which can be obtained by executing yum install gcc-c++.

To build all of the samples, execute the build.sh script in the <installation_directory>/share/samples directory. To compile specific samples, navigate to the folder for the sample within share/samples and execute the make command.

Environment variables must be properly set before any of the compiled samples are executed. To do this, source the bin/set_puregev_env script by executing source set_puregev_env or . set_puregev_env.

For information about building the sample applications and creating your own applications, see the eBUS SDK C++ API Quick Start Guide.

Compilation will fail for GUI-based samples if the Qt development package is not installed. For Qt version information, see “System Requirements” on page 8.

Compiling and Running Sample Applications for the x86 for Linux Platform 17

Chapter 7

Cross-Compiling and Running Sample Applications on an Embedded ARM Board

This chapter explains how to cross-compile eBUS SDK applications for an embedded ARM board.

Before you begin, ensure you have installed the correct toolchain, which is often provided by the board manufacturer. Ensure that the development board is configured, loads Linux, and the user can transfer files from the development computer to the target board.


• “Cross-Compiling the Sample Applications” on page 20• “Running the Samples on the Embedded ARM Board” on page 20

Cross-Compiling and Running Sample Applications on an Embedded ARM Board 19

Cross-Compiling the Sample Applications

Use the provided sample.Makefile to cross-compile the sample applications for the embedded ARM board.

To cross-compile the sample applications

1. Open a terminal.

2. In the sample.Makefile in the share/samples directory, replace the variable CC and CXX with the cross-compile toolchain path, based on your setup. For example, if you are using a hard-float board, you could change the variables to:CC = /usr/bin/arm-linux-gnueabihf-gccCXX = /usr/bin/arm-linux-gnueabihf-g++

3. Set the environment variables required by the eBUS SDK.source /opt/pleora/ebus_sdk/linux-<architecture>-arm /bin/ set_puregev_env

4. Copy the samples from the /opt folder to your home directory.cp -rf /opt/pleora/ebus_sdk/linux-<architecture>-arm/share/samples ~/ samples

5. Compile the samples.cd ~/samplesbash ./build.sh

Running the Samples on the Embedded ARM Board

After you have cross-compiled the samples, you can copy them to your target board and run the samples.

To run the samples on the board

1. Copy the /opt/pleora/ebus_sdk/linux-<architecture>-arm/ folder from your host computer to the target board using the same path (or adjust the set_puregev_env script accordingly).

You can remove unused files at the same time, according to dependencies.

2. Copy the compiled sample executables to the target board.

3. On the target board, run the set_puregev_env script.source /opt/pleora/ebus_sdk/linux-<architecture>-arm/bin/set_puregev_env

4. Run the samples from the same terminal.


Chapter 8

Troubleshooting

Cannot detect or connect to GigE Vision devices.

In the Device Selection dialog box, select the Show unreachable Network Devices check box.

If the device still does not appear, do one of the following:

• Disable the firewall.

- And/or - • As superuser, execute the <installation_directory>/bin/set_rp_filter.sh script and then

choose option 0 (to disable strict Reverse Path Forwarding filtering).

Cannot detect or connect to USB3 Vision devices.

As superuser, ensure that the eBUSd daemon is started by executing service eBUSd status. If it is not started, execute service eBUSd start. If it is not installed, run the <installation_directory>/bin/install_daemon.sh module and follow the prompts.

On Linux for x86, a high number of GTK errors or warnings appear when running an application.

It is likely that you are running the sample application as superuser, but are logged on as a standard user.

The sample applications compiled successfully, but they will not run.

As superuser, execute the <installation_directory>/bin/install_libraries.sh script to ensure that the required libraries have been added to the system. Also, ensure that you source the bin/set_puregev_env script.

A watermark appears on received images.

You require a receive license. For more information, see the eBUS SDK Licensing knowledge base article, available on the Pleora Support Center (www.pleora.com).

Troubleshooting 21


Chapter 9

Technical SupportOn the Pleora Support Center, you can:

• Download the latest software.

• Log a support issue.

• View documentation for current and past releases.

• Browse for solutions to problems other customers have encountered.

• Get presentations and application notes.

• Get the latest news and information about our products.

• Decide which of Pleora’s products work best for you.

To visit the Pleora Support Center

• Go to www.pleora.com and click Support Center.

If you have not registered yet, you are prompted to register.

Accounts are usually validated within one business day.

Technical Support 23


eBUS SDK for Linux - ftp.elvitec.frftp.elvitec.fr/Pleora/SDK-LOGICIEL/eBUS SDK for Linux Quick...

Documents

Transcript of eBUS SDK for Linux - ftp.elvitec.frftp.elvitec.fr/Pleora/SDK-LOGICIEL/eBUS SDK for Linux Quick...