MATRIX VISION mvHYPERION Framegrabber - Linux Access Libraries
===============================================================

IMPORTANT
***************************************************************************************
=======================================================================================
The easiest way to install the necessary software for the mvHYPERION Framegrabber is to
use the install_mvHYPERION.sh installation script, which can be downloaded from the
MATRIX VISION GmbH website(www.matrix-vision.com) along with the latest drivers.
Place the install_mvHYPERION.sh script and the mvHYPERION-x86_64_ABI2-x.x.x.tgz file
in the same directory, and make the script executable:

    chmod a+x install_mvHYPERION.sh    

if this fails, try:

    sudo chmod a+x install_mvHYPERION.sh

and proceed with the installation:

    ./install_mvHYPERION.sh

If for some reason you cannot use this script then proceed manually according to the steps
described below.

=======================================================================================
***************************************************************************************



This version only contains libraries for Linux x86 (32 bit) or Linux 64-bit (x86_64).
Version 1.9.12 (Release 72)  Oct 15th 2007
System Requirements
-------------------

Kernel requirements:
Kernel later than 2.6.x 

N.B. Kernel 2.2.x or 2.4.x cannot be used with the mvHYPERION.

Software requirements:
Linux x86 (32-bit).
- The 32 bit version will run on a 64-bit Linux system if the other library requirements are met
with 32-bit libraries. i.e. you cannot mix 64 and 32-bit libraries and applications.
- Versions for Linux on x86-64 (64-bit), PowerPC, ARM or MIPS may be possible on request.

GNU compiler version GCC 3.2.x or greater and associated toolchain.

Other requirements:
libexpat (http://expat.sourceforge.net)
Optional: wxWidgets 2.6.x (Unicode or ANSI) for the wxWidget Testprograms.
Optional: udev or hotplug subsystem (see also 6. below).

As an example of which packets need to be installed, consider OpenSuSE 10.1:
- The compiler used is gcc 4.1.0 and may need to be installed. Use the "gcc" und "gcc-c++" RPMs.
Other RPMs may be installed automatically due to dependencies (e.g. make).
- libexpat will almost definately be installed already in any software configuration. The RPM is called ¨expat¨.
- Install the wxWidgets "wxGTK" and "wxGTK-develop" RPMs. Others that will be automatically installed due to
dependencies include "wxGTK-compat" and "wxGTK-gl". Although the MATRIX VISION software does not use
the ODBC database API the SuSE version of wxWidgets has been compiled with ODBC support and the RPM
does not contain a dependency to automatically install ODBC. For this reason you must also
install the "unixODBC-devel" RPM.
- OpenSuSE 10.1 uses the udev system so a separate hotplug installation is not needed.

Hardware requirements:
PC with PCIe Single Lane.
mvHYPERION framegrabber from MATRIX VISION.

IMPORTANT
=========
This version only contains libraries for Linux x86 (32 bit) or Linux 64-bit (x86_64).
There are separate package files for systems with toolchains based on GNU gcc 3.2.x - 3.3.x and 
those based on GNU gcc >= 3.4.x. gcc 3.1.x may work but, in general, the older your
toolchain is, the less likely it is that it will work. 
Toolchains based on GNU gcc 2.x.x are not supported at all.

See the instructions below for advice on deciding which package you should install.

Introduction
------------
The mvHYPERION is controlled by a number of user-space libraries. It is also necessary to compile and install
a kernel module.

Installation
------------
1. Logon to the PC as the "root" user or start a super user session with "su". 
Start a console with "root" privileges .
------------------------

2. Determine which package you need by issuing the following command in a 
terminal window:

gcc -v

This will display a lot of information about the GNU gcc compiler being used on 
your system. 

If the version number is 2.x.x then you cannot use the mvHYPERION on your 
computer. Consider upgrading to a newer distribution.
If the version number is 3.2.x or 3.3.x then you will need the 
package using the C++ ABI 1. This package has ABI1 in its name.
If the version number is 3.4.x or 4.x.x or greater then you will need the package using 
the C++ ABI 2. This package has ABI2 in its name.
------------------------


3. You can now install the mvIMPACT_acquire and mvHYPERION libraries as follows:

- create a new directory somewhere on your system.
- copy the correct package file to this directory and change into 
this directory with "cd".

The libraries are supplied as a "tgz" archive with the extension ".tgz".

Unpack the archive using "tar" e.g.:

tar xvzf mvhyperion-x86-ABI1-1.9.12.72.tgz

-or-

tar xvzf mvhyperion-x86_ABI2-1.9.12.72.tgz

N.B.
Current versions of the ABI1 libraries were compiled using a SuSE 8.1 system for maximum 
compatibility with older Linux distributions. These libraries should work with all SuSE 8.x
and SuSE 9.x versions as well as with Debian Sarge and older Red Hat / Fedora variants.

Current versions of the ABI2 libraries were compiled using a SuSE 10.1 or Debian 'etch' 4.0r1 system
for maximum compatibility with newer Linux distributions. These libraries should work with SuSE 10.x
as well as with Ubuntu 6.06 or newer, with up-to-date Gentoo or Fedora FC5.

------------------------

4. After installing the access libraries you will see something like 
the following directory structure in your directory (dates and file sizes will differ
from the list below):

drwxr-xr-x   10 root     root         4096 Jan  5 15:08 .
drwxr-xr-x   23 root     root         4096 Jan  4 16:33 ..
drwxr-xr-x    3 root     root         4096 Jan  5 15:08 DriverBase
-rw-r--r--    1 root     root         1079 Jan  5 15:08 Makefile
drwxr-xr-x    7 root     root         4096 Jan  5 15:08 apps
drwxr-xr-x    4 root     root         4096 Jan  5 15:08 common
drwxr-xr-x    3 root     root         4096 Jan  5 15:08 lib
drwxr-xr-x    3 root     root         4096 Jan  5 15:08 mvDeviceManager
drwxr-xr-x    2 root     root         4096 Jan  5 15:08 mvIMPACT_CPP
drwxr-xr-x    3 root     root         4096 Jan  5 15:08 mvPropHandling
drwxr-xr-x    1 root     root         4096 Jan  5 15:08 Scripts

The directory "lib/x86" contains the pre-compiled 32-bit libraries for accessing the 
device.  If 64-bit libraries are supplied they will be found in "lib/x86_64".
The "apps" directory contains test applications (source code).
The other directories contain headers needed to write 
applications for the device.

Since the libraries are not installed to a directory known to the system i.e. 
not in the "ldconfig" cache you will need to tell the system where to find them 
by...

- using the "LD_LIBRARY_PATH" environment variable,
- or copying the libraries by hand to a system directory like "/usr/lib" (or 
using some symbolic links), 
- or entering the directory in "/etc/ld.so.conf" and running "ldconfig".

e.g. to start the application called "LiveSnap":

cd my_mvbf_directory
LD_LIBRARY_PATH=`pwd`/lib/x86 apps/LiveSnap/x86/LiveSnap

For 64-bit it will look like this...
LD_LIBRARY_PATH=`pwd`/lib/x86_64 apps/LiveSnap/x86_64/LiveSnap

For ARM it will look like this...
LD_LIBRARY_PATH=`pwd`/lib/arm apps/LiveSnap/arm/LiveSnap
etc.

After installing the libraries and headers you may continue with "5." below
as a normal user i.e. you do not need to be "root" in order to compile the
test applications. See also the note "6." below.
------------------------


5. To build the test applications type "make". This will attempt to build 
all the test applications contained in "apps". If you have problems compiling
the wxWidget library or application you may need to do one or more of the following:

- install the wxWidget 3.x development files (headers etc.) supplied for your 
distribution. (See "Other requirements" above).
- fetch, compile and install the wxWidget 3.x packet from source downloaded 
from the website (http://www.wxwidgets.org).
- alter the Makefiles so as to find the wxWidget configuration script called 
wx-config. The files you may need to alter are to be found here:

apps/mvPropViewMakefile.inc

You will find the compiled test programs in the subdirectories "apps/.../x86".
For 64 bit systems it will be "apps/.../x86_64".
For ARM systems it will be "apps/.../arm".

If you cannot build the wxWidget test program you should, at least, be able to 
compile the text-based test programs in apps/SingleSnap, apps/LiveSnap, etc.

The Makefile will also attempt to configure itself so that the mvHYPERION kernel module
can be built. You should see the following message at the end of the compile block:

=============================================================
To install the mvHYPERION kernel module now make sure that you are root and type:
make install
=============================================================

If you are not already logged in as the "root" user you must now use "su" to change users
and type "make install". On an Ubuntu system you might try "sudo make install". The kernel
module will now be built and installed.

Now you will have to tell your system to use this kernel module and to associate it with a 
device node. To do this you need to edit the file "/etc/modprobe.conf". Depending on your
system you may have a directory called "/etc/modules.d/", where you can put files that
are included automatically in "/etc/modprobe.conf". Other systems (e.g. older SuSE) use a
file called "/etc/modprobe.conf.local" which the user may alter. Which ever way you do it, you
need to add some lines like this:

alias char-major-64     hyperion
options hyperion major_dev_num=64

Afterwards, please use "depmod -a" to tell the system about this change. The lines above
tell the system to use a device called "/dev/hyperion" with a major number of 64.

------------------------


6. If you are using a system with an up-to-date version of udev you might be interested in the file
"Scripts/50-udev-hyperion.rules". By including this file in your udev rules directory you can tell
your system to create a device node for the mvHYPERION automatically when loading the kernel module.
You will need to edit the file to fit your system. As delivered, all entries are commented out.

If you do not use udev then you will have to create a device node yourself by hand. For example, you
could do the following to use major device number 64:

mknod /dev/hyperion c 64 0

If you have more than one mvHYPERION in your PC you will need a device node per card:

mknod /dev/hyperion0 c 64 0
mknod /dev/hyperion1 c 64 1
mknod /dev/hyperion2 c 64 2
mknod /dev/hyperion3 c 64 3

------------------------

7. The mvIMPACT_acquire libraries look for camera definition files in the directory
"/etc/matrix-vision/mvimpact-acquire/camerafiles" so you will need to create these
directories as the "root" user using "mkdir -p /etc/matrix-vision/mvimpact-acquire/camerafiles".

You should download the camera definitions for your camera from the MATRIX VISION website and copy them
to this directory.


8. Please refer to the mvHYPERION handbook for information on programming with 
the mvIMPACT_Acquire API. If the handbook makes references to Windows DLLs 
please use the equivalent Linux dynamic libraries that have been installed on 
your system.
------------------------



-
MATRIX VISION GmbH
support@matrix-vision.de

