Installing the mvGenTL-Acquire Driver

Introduction

To use a GenICam/GenTL compliant camera (grab images from it and change its settings), a driver is needed, consisting of a few libraries and a dozen or so configuration files. These files are run time required.

To develop applications that can use a GenICam/GenTL compliant camera, a source tree is needed, containing header files, makefiles, samples, and a few libraries. These files are compile time required.

Both file collections are distributed in a single package : mvGenTL_Acquire-x86-n.n.n.n.tgz.

To install this package, a shell script must be run : install_mvGenTL_Acquire.sh.
You may need to enable the execute flag with chmod a+x install_mvGenTL_Acquire.sh.

This document describes what this script does and how it should be invoked.

Invoking the Installation Script

The installation script (install_mvGenTL_Acquire.sh) and the archive (mvGenTL_Acquire-x86-n.n.n.n.tgz) must reside in the same directory.
Nothing is written to this directory during script execution, so no write access to the directory is needed in order to execute the script. It could even be executed from a partition that was mounted read-only (e.g. from a CD-ROM).

You should run the script as a normal user, and will be asked for the superuser password when needed (unless you did a sudo shortly before invoking the script).

The script takes two arguments, both of which are optional:

  1. target directory name
  2. version

The arguments must be specified in this order.
Invoke with argument -h to see a help message.

Target Directory Name

The target directory name specifies where to place the driver.
If the directory does not yet exist, it will be created.
The path can be either absolute or relative; i.e. the name may but need not start with /.
Write access to this directory, or the directory above, is not needed, as the archive will be unpacked using sudo.
It is therefore ok to specify e.g. /usr/local.

This directory is only used for the files that are run time required.

The files required at compile time are always installed in $HOME/mvimpact-acquire-x86-n.n.n.n.
The script also creates a convenient softlink to this directory:

    mvimpact-acquire -> mvimpact_acquire-x86-1.10.30.108
Use $HOME/mvimpact-acquire in all your scripts and makefiles, and nothing needs to be changed after an update.

If this argument is not specified, or is ., the driver will be placed in the current working directory.

Version

The version argument is entirely optional.
If no version is specified, the most recent mvGenTL_Acquire-n.n.n.n.tgz found in the current directory will be installed.
Often there will be only one mvGenTL_Acquire-n.n.n.n.tgz file in that directory. It is then pointless to specify a version.

A note on terminology. Suppose the archive file is called mvGenTL_Acquire-1.10.30.108.tgz. The driver in this archive will have major version number 1, minor version number 10, build number 30 and release number 108.

Now suppose that install_mvGenTL_Acquire.sh resides in /tmp (as will often be the case), and that /tmp also contains mvGenTL_Acquire-1.10.30.108.tgz and mvGenTL_Acquire-1.10.28.102.tgz. Then both

    ./install_mvGenTL_Acquire.sh  $HOME/mvGTLA  1.10.30.108
and
    ./install_mvGenTL_Acquire.sh  $HOME/mvGTLA
will install version 1.10.30.108 in directory $HOME/mvGTLA, as that is the most recent version.
To install version 1.10.28.102, you must be explicit:
    ./install_mvGenTL_Acquire.sh  $HOME/mvGTLA  1.10.28.102

What the Script Does

The script not only copies files to their respective target directories, but also patches a few config files.

Prerequisites

The mvGenTL-Acquire driver implements the GenICam™ standard.
As such, it rests on a handful of GenICam™ libraries, which the installer will also install.

Not automatically installed is the wxWidgets development package.
Its manual installation prior to running the install script, though not strictly required, is strongly recommended, as without it, wxPropView cannot be built.
On SuSE, the package is called wxGTK-devel, on Ubuntu libwxgtk3.0-dev.

Dynamic Linking

The driver consists of a number of shared libraries.
Where on the hard disk these libraries will end up depends on the first argument passed to the install script.
Suppose the script was called like so:

    ./install_mvGenTL_Acquire.sh  /usr/local
The libraries will then be installed in
    /usr/local/lib
    /usr/local/lib/genapi/generic
    $HOME/mvimpact-acquire/lib/x86
This is relevant to ld at compile time, and to ld.so at run time.

So that ld can find libmvDeviceManager.so at compile time, add a line like this to your makefile:

    LDFLAGS+=-L$(HOME)/mvimpact-acquire/lib/x86 -lmvDeviceManager

So that ld.so can find all the required libs at run time, the script writes

    $GENICAM_ROOT/lib
    $GENICAM_ROOT/lib/genapi/generic
    $HOME/mvimpact-acquire/lib/x86
to either /etc/ld.so.conf.d/genicam.conf and /etc/ld.so.conf.d/acquire.conf or /etc/ld.so.conf, expanding the environment variables in the process.
On systems where /etc/ld.so.conf sources all files found in directory /etc/ld.so.conf.d/ (like Ubuntu and SuSE), the paths are written to /etc/ld.so.conf.d/genicam.conf and /etc/ld.so.conf.d/acquire.conf.
Else, they are written to /etc/ld.so.conf.
The script then adds the libraries to the ld.so cache by calling ldconfig.
Obviously all of this is done as superuser, but that will go by unnoticed, as the superuser password was already requested earlier in the script, when installing the prerequisites.

If you ever need to edit /etc/ld.so.conf.d/genicam.conf by hand, you must write out the paths in full, and not include any environment variables. So you should write e.g.
    /usr/local/lib
    /usr/local/lib/genapi/generic
    /home/john/mvimpact-acquire/lib/x86
rather than
    $GENICAM_ROOT/lib
    $GENICAM_ROOT/lib/genapi/generic
    $HOME/mvimpact-acquire/lib/x86
(where /usr/local and /home/john are obviously just examples).

This is so because ldconfig does not expand environment variables when reading the configuration files.

Environment Variables

The GenICam™ libraries expect to find three environment variables.
The install script will write the corresponding export commands to either /etc/profile.d/genicam.sh or /etc/profile.
On systems where /etc/profile sources all files found in directory /etc/profile.d/*.sh (like Ubuntu and SuSE), the export commands are written to /etc/profile.d/genicam.sh.
Else, they are written to /etc/profile.

In addition, an export line is written to either /etc/profile.d/acquire.sh or /etc/profile.

Note that these environment variables will not be set after completion of the install script.

The shell level of a script is always one deeper than the level of the shell from where the script is called. Any environment variable set at this deeper level is lost as soon as the script terminates, i.e. as soon as control returns to the higher level. It is therefore impossible to set environment variables from within a script (or the script must be sourced, which is not foreseen for install_mvGenTL_Acquire.sh).

The solution is to source /etc/profile by hand after the script is done:

    ./install_mvGenTL_Acquire.sh  /usr/local
    . /etc/profile

There is space between . and / in the last command.

The same effect as sourcing /etc/profile can be achieved by logging out and then logging in again, e.g. by restarting X11 (Ctrl-Alt-Delete).

As of the next boot, the environment variables will always be set properly and you can forget about them.

Building the Tools and Samples

When it has written all settings to their respective config files, the script asks the user whether the tools and samples should be built.
If the answer is anything other than n, all tools and samples will be built.
If the answer is n (no), the script will exit without building the tools and samples.
The user can build them at some later point like so:

    cd $HOME/mvimpact-acquire
    make x86
    sudo ldconfig
The sudo ldconfig must only be run once, after the first make.
It ensures that the applications built in directory $HOME/mvimpact-acquire/apps can find three shared libraries built in $HOME/mvimpact-acquire/lib/x86:
    libmvDeviceManager.so
    libmvPropHandling.so

Optimizing the Ethernet connection

Be sure to set the MTU for the used Ethernet port to as high a value as possible.

    sudo /sbin/ifconfig eth0 mtu 9200

If this returns

    SIOCSIFMTU: Invalid argument

the port (here eth0) does not support packets this large (here 9200), and you must try some lower value. In this case, try a smaller value until no error is returned.
To see the current MTU for a given port (let's say eth0), type

    /sbin/ifconfig eth0

Note that the connection is only as fast as the slowest link in the chain, meaning that in many cases you cannot get anything higher than 1500. In such cases, the network is a limiting factor, and the camera cannot deliver its optimal performance.
If you cannot use ifconfig with any value higher than 1500, try to rearrange your connection, perhaps by taking out a slow switch or so.
In addition, be sure to use CAT5E cables.