Installing the mvBlueCOUGAR Remote Driver

Introduction

To use the mvBlueCOUGAR 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 the mvBlueCOUGAR 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 : mvBlueCOUGAR-n.n.n.n.tar.gz.

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

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

Invoking the Installation Script

The installation script (install_mvBlueCOUGAR.sh) and the archive (mvBlueCOUGAR-n.n.n.n.tar.gz) 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 (not when you did a sudo shortly before invoking the script).

You need internet access in case one or more of the packages on which the GenICam™ libs depend are not yet installed on your system. In this case, the script will install these pacakages, and for that, internet access is required.

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

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 mvBlueCOUGAR-n.n.n.n.tar.gz found in the current directory will be installed.
Often there will be only one mvBlueCOUGAR-n.n.n.n.tar.gz file in that directory. It is then pointless to specify a version.

A note on terminology. Suppose the archive file is called mvBlueCOUGAR-1.10.30.108.tar.gz. 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_mvBlueCOUGAR.sh resides in /tmp (as will often be the case), and that /tmp also contains mvBlueCOUGAR-1.10.30.108.tar.gz and mvBlueCOUGAR-1.10.28.102.tar.gz. Then both

    ./install_mvBlueCOUGAR.sh  $HOME/mvBC  1.10.30.108

    ./install_mvBlueCOUGAR.sh  $HOME/mvBC

    ./install_mvBlueCOUGAR.sh  $HOME/mvBC  1.10.28.102

What the Script Does

The script not only copies files to their respective target directories, but also takes care of a few dependencies and patches a few config files.

Prerequisites

The mvBlueCOUGAR 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, though not strictly required, is strongly recommended, as without it, wxPropView cannot be built.

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_mvBlueCOUGAR.sh  /usr/local

    /usr/local/lib
    /usr/local/lib/genapi/generic
    $HOME/mvimpact-acquire/lib/x86

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

If you ever need to edit /etc/ld.so.conf.d/genicam.conf by hand, you must write out the pathes 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_mvBlueCOUGAR.sh).

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

    ./install_mvBlueCOUGAR.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.

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

    libmvDeviceManager.so
    libmvPropHandling.so
    libwxPropGrid.so

If you choose not to build the samples and would like to build e.g. wxPropView or any other wxWidgets based sample later on, you have to compile wxPropGrid first.