MATRIX VISION - mvHYPERION Technical Documentation
Quickstart

Hardware installation

Attention
"Electro Static Discharge (ESD)"

Please take all proper Electro Static Discharge (ESD) precautions during the installation of your new hardware!

Before starting the installation, turn off your computer and all peripheral devices. Disconnect the computer from the power supply and all necessary components.

Note
To avoid doing damage to the hardware, discharge yourself of static charge by touching e.g. the casing. Beware of touching contacts of the frame grabber or of the computer.
  • Select a free busmaster slot (PCI Express). Remove the slot's cover at the back of the computer and keep the screw.
  • Carefully insert the board into the slot by holding the board at the top and gently pushing both ends into the slot at the same time. Press onto the upper edge of the board to make sure it is seated in the slot firmly.
  • Do not force the board into the slot! You run the risk of bending the contacts. If the board does not fit easily, pull it back out, and try again.
  • Fasten the board's bracket at the back of the computer using the screws you saved from the shield.
  • Put the cover back on the computer and reconnect the peripheral devices.
  • Start the computer.
Attention
"Short-circuit"

According to the construction, if you want to connect or disconnect a PoCL camera, please be sure that the PC or the mvHYPERION frame grabber is switched off! Otherwise, during the connection, the camera or the frame grabber could be short-circuited and possibly destroyed!

→ Switch off the PC or the mvHYPERION frame grabber if you want to connect or disconnect a PoCL camera.

Windows

System Requirements

Currently supported Windows versions are:

  • Microsoft Windows 7 (32-bit, 64-bit) (requires min. 2 GB main memory)
  • Microsoft Windows 8.1 (32-bit, 64-bit) (requires min. 2 GB main memory)

Consecutively the installation for Windows will be described. The description for the Linux installation can be found here: Linux.

Note
For a correct installation of the frame grabber please install the MSI package before connecting any board to the system. Afterwards you can install the physical board(s) and when the system starts again everything else is done automatically.

Software installation

All necessary drivers for Windows and Linux are contained in the mvIMPACT CD-ROM or DVD-ROM. For newer driver versions we recommend to visit the MATRIX VISION website at www.matrix-vision.de, section Support/Download/Hardware.

After the Hardware installation the boot sequence shows "Found New Hardware" and starts the Windows Hardware Wizard. Closed this windows and insert the mvIMPACT CD-ROM or DVD-ROM into your drive and select "Driver installation ..." and the needed mvIMPACT Acquire driver (e.g. "mvTITAN / mvGAMMA").

Figure 1: Start window

After the click on the needed driver the installation process starts.

Figure 2: mvHYPERION installer - Start window

Select the folder, where you want to install the software.

Figure 3: mvHYPERION installer - Select folder

Select the features, which you want to install. Following features exist:

  • "Base Libraries"
    This feature contains all necessary files for property handling and display. Therefore, it is not selectable.
  • "mvHYPERION driver"
    This is also not selectable.
  • "Tools"
    This feature contains tools for the frame grabber (e.g. to acquire images (wxPropView)).
  • "mvIMPACT acquire API"
    The "mvIMPACT acquire API" contains the header for own programming. Additionally you can choose the examples, which installs the sources of wxPropView, mvIPConfigure and various small examples. The project files shipped with the examples have been generated with Visual Studio 2013. However projects and makefiles for other compilers can be generated using CMake fairly easy. See CMake section in the C++ manual for additional details.
  • "Documentation"
    This will install this manual as single HTML help file (.chm).
Figure 4: mvHYPERION installer - Select features

Confirm the installation by clicking "Next".

Figure 5: mvHYPERION installer - Confirm installation

The installation process copies the files to Windows. Then Windows shows a message to signal that this driver is not checked through Microsoft. This is only an attempt to make insecure and it is recommended to ignore it.

Press "Continue Anyway" and finish the driver installation.

Figure 6: mvHYPERION installer - Windows logo testing
Figure 7: mvHYPERION installer - Driver successfully installed
Figure 8: mvHYPERION installer -Installation complete

After this, you have to restart the system. Afterwards, you can acquire images with the frame grabber. Simply start the application wxPropView (wxPropView.exe).

See also
wxPropView

Linux

System Requirements

Kernel requirements

Kernel 2.6.x.

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 (non Unicode) for the wxWidget test programs.
  • 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 definitely 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 PCI Express Single lane

Note
The driver 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 lass likely it is that it will work. Toolchainss based on GNU gcc 2.x.x are not supported at all.

Installing the mvIMPACT Acquire driver

Using the installer script

To use the mvHYPERION frame grabber within Linux (grab images from it and change its settings), a driver is needed, consisting of several libraries and several configuration files. These files are required during run time.

To develop applications that can use the mvHYPERION frame grabber, a source tree is needed, containing header files, makefiles, samples, and a few libraries. These files are required at compile time.

Both file collections are distributed in a single package:

mvHYPERION-x86_ABI2-n.n.n.tgz
  1. Please start a console and change into a directory e.g. /home/username/workspace
    cd /home/username/workspace
    
  2. Copy the install script and the hardware driver to the workspace directory (e.g. from a driver CD or from the website):
    ~/workspace$ cp /media/cdrom/drv/Linux/install_mvHYPERION.sh /
     . && cp /media/cdrom/drv/Linux/mvHYPERION-x86_ABI2-2.14.0.tgz -t ./
    
  3. Run the install script:

    ~/workspace$ ./install_mvHYPERION.sh
    
    Note
    The install script has to be executable. So please check the rights of the file.
    During installation, the script will ask, if it should build all tools and samples.

    You may need to enable the execute flag with

    chmod a+x install_mvHYPERION.sh
    

The installation script checks the different packages and installs them with the respective standard packages manager (apt-get) if necessary.

Note
The installation script ("install_mvHYPERION.sh") and the archive ("mvHYPERION-x86_ABI2-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.

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 packages, and for that, Internet access is required.

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

  1. target directory name
  2. version

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

Note
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-n.n.n". The script also creates a convenient softlink to this directory:

mvimpact-acquire -> mvIMPACT_acquire-2.3.2

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

The version argument is entirely optional. If no version is specified, the most recent mvHYPERION-x86_ABI2-n.n.n.tgz found in the current directory will be installed.

If you have also installed tools and samples, you will find them in apps. Just change into the subdirectory, for example, "apps/mvPropView/x86" you can find the camera setup tool wxPropView. You can find it in subdirectory "/opt/mvIMPACT_Acquire/apps/mvPropView/x86". However, you do not always have to start the tool from this folder. The installer script has created symbolic links so that it is enough to type in wxPropView throughout the system to start wxPropView.

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

Doing it manually

The mvHYPERION is controlled by a number of user-space libraries. It is not necessary to compile a kernel module.

  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. In case of the version number you have to do following:

    Version Description
    2.x.x You cannot use the mvHYPERION on your computer. Upgrade to a newer distribution.
    3.2.x - 3.3.x Use the C++ ABI 1. This package has ABI1 in its name.
    greater or equal 3.4.x Use the C++ ABI 2. This package has ABI2 in its name.

  3. You can now install the 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".

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

      tar xvzf mvhyperion-x86-ABI1-1.8.4.55.tgz
      

      or

      tar xvzf mvhyperion-x86-ABI2-1.8.4.55.tgz
      
      Note
      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 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.
    2. 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 mvBlueFOX. If 64-bit libraries are supplied they will be found in "lib/x86_64". The "apps" directory contains test applications (source code). The 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 "SingleCapture":

      Note
      Please declare the device e.g. HC* or HC000000001
      cd my_directory
      LD_LIBRARY_PATH=`pwd`/lib/x86 apps/SingleCapture/x86/SingleCapture HC*
      
      For 64-bit it will look like this...
      LD_LIBRARY_PATH=`pwd`/lib/x86_64 apps/SingleCapture/x86_64/SingleCapture HC*
      
      For ARM it will look like this...
      LD_LIBRARY_PATH=`pwd`/lib/arm apps/SingleCapture/arm/SingleCapture HC*
      

      etc.

      After installing the libraries and headers you may continue with "3." 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 "4." below.

    3. 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/mvPropView/Makefile.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/SingleCapture, apps/SingleCapture, 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.

    4. 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
      
    5. 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.

Connecting a camera

To connect a camera, for example via CameraLink cable to the mvHYPERION-CLx frame grabber, please do the following:

  • Connect the cable from the camera (labeled with e.g. Data channel 1) to the first connector J1 of the mvHYPERION frame grabber.
  • Optionally, if you are using a Medium or Full, connect the cable from the camera (labeled with e.g. Data channel 2) to the second connector J2 of the mvHYPERION.
  • Optionally, use the connector J3 to power the camera.

Make sure that you do not mix up the channels. For this, please have a look at chapter Technical Data, where to find the specific connectors.

  • Afterwards, start wxPropView and choose the "Generic" camera definition.
  • Now, press the Live button - at this point you should see something from the camera.
  • Then, create a new camera definition.
  • Finally, export the new camera definition and choose it in "wxPropView -> ImageSetting -> Camera -> Type".

Settings behavior during startup

Settings contain all the parameters that are needed to prepare and program the device for the image capture. Every image can be captured with completely different set of parameters. In almost every case, these parameters are accessible via a property offered by the device driver. A setting e.g. might contain

  • the gain to be applied to the analog to digital conversion process for analog video sources or
  • the AOI to be captured from the incoming image data.

So for the user a setting is the one an only place where all the necessary modifications can be applied to achieve the desired form of data acquisition.

Now, whenever a device is opened, the driver will execute following procedure:

Figure 9: wxPropView - Device setting start procedure
  • Please note that each setting location step in the figure from above internally contains two search steps. First the framework will try to locate a setting with user scope and if this can't be located, the same setting will be searched with global (system-wide) scope. On Windows® this e.g. will access either the HKEY_CURRENT_USER or (in the second step) the HKEY_LOCAL_MACHINE branch in the Registry.
  • Whenever storing a product specific setting, the device specific setting of the device used for storing will be deleted (if existing). So when the user is currently working with a device 'VD000001' belonging to the product group 'VirtualDevice' and there is a setting exclusively for this device storing a product specific setting now will automatically delete the setting for 'VD000001'. Otherwise a product specific setting would never be loaded as a device specific setting will always be found first.
  • The very same thing will also happen when opening a device from any other application! wxPropView does not behave in a special way but only acts as an arbitrary user application.
  • Whenever storing a device family specific setting, the device specific or product specific setting of the device used for storing will be deleted (if existing). See above to find out why.
  • On Windows® the driver will not look for a matching XML file during start-up automatically as the native storage location for settings is the Windows® Registry. This must be loaded explicitly by the user by using the appropriate API function offered by the SDK. However, under Linux XML files are the only setting formats understood by the driver framework thus here the driver will also look for them at start-up. The device specific setting will be an XML file with the serial number of the device as the file name, the product specific setting will be an XML file with the product string as the filename, the device family specific setting will be an XML file with the device family name as the file name. All other XML files containing settings will be ignored!
  • Only the data contained in the lists displayed as "Image Setting", "Digital I/O" and "Device Specific Data" under wxPropView will be stored in these settings!
  • Restoring of settings previously stored works in a similar way. After a device has been opened the settings will be loaded automatically as described above.
  • A detailed description of the individual properties offered by a device will not be provided here but can be found in the C++ API reference, where descriptions for all properties relevant for the user (grouped together in classes sorted by topic) can be found. As wxPropView doesn't introduce new functionality but simply evaluates the list of features offered by the device driver and lists them any modification made using the GUI controls just calls the underlying function needed to write to the selected component. wxPropView also doesn't know about the type of component or e.g. the list of allowed values for a property. This again is information delivered by the driver and therefore can be queried by the user as well without the need to have special inside information. One version of the tool will always be delivered in source so it can be used as a reference to find out how to get the desired information from the device driver.