Balluff - mvBlueCOUGAR-X/-XD Technical Documentation
Installing The mvGenTL-Acquire Package

Table of Contents

All necessary drivers are available from the Balluff website at https://www.balluff.com/en-de/downloads/software.

Windows

Starting the installer application

  • mvGenTL_Acquire-x86-3.0.0.exe (for 32-bit systems) or
  • mvGenTL_Acquire-x86_64-3.0.0.exe (for 64-bit systems): will display the following dialog:
Figure 1: Driver installation - Start Window
  • Now, follow the instructions of the installation program and adjust the settings to your needs:
Figure 2: Driver installation - Select Installation Folder
Since
Version 2.25.0 of this driver package

ImpactControlCenter is able to check if a new driver version became available on a weekly basis. Deactivate the check box if ImpactControlCenter should not check for updates. You can activate this again in ImpactControlCenter via the help menu.

Figure 3: Driver installation - Select Features
  • After confirmation, the installation will start and copy files and install device drivers.
Figure 4: Driver installation - Installation Completed

You will find all tools like

either as shortcuts on the desktop or in the Windows start menu under MATRIX VISION -> Impact Acquire.

Afterwards, you can use DeviceConfigure to update the firmware if needed. The latest firmware image is available on the web - please check for updates. The current firmware version can be read out using ImpactControlCenter.

Linux

Additional packages will be needed to use all features of Impact Acquire.

Compiler etc. for building applications:

  • build-essential (meta package)
  • gcc 5.5.0 environment or newer

wxWidget release 3.0 or 3.2 packages, e.g.

  • libwxbase3.0-0v5
  • libwxbase3.0-dev
  • libwxgtk3.0-gtk3-0v5
  • libwxgtk3.0-gtk3-dev
  • libwxgtk-webview3.0-gtk3-0v5
  • libwxgtk-webview3.0-gtk3-dev
  • wx3.0-headers
  • libgtk2.0-dev
Note
The names of the packages mentioned above are Debian / Ubuntu specific. Other distributions (e.g. SuSE, Arch, Redhat, ...) will use different names.

The installation script will ask if the packages should be downloaded during the installation process. If some of the packages are not installed some features might not be available. If the e.g. wxWidgets related packages are missing on the target system then all GUI application coming as part of the Impact Acquire installation won't be available.

Note
If you are going to install the mvGenTL-Acquire package on an ARM device, please read this section first.

To use a (camera) device in Linux (capture 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 device an API 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 which is available in the Download section of the Balluff website. In addition to that an installation script is provided which can be downloaded from the same location. Using this script makes installing the driver package a lot easier.

Note
The following table shows the supported platforms and the corresponding package and installation script name:
ArchitecturePackageInstallation Script
ARM64mvGenTL_Acquire-ARM64_gnu-3.0.0.tgzinstall_mvGenTL_Acquire_ARM.sh
ARMhfmvGenTL_Acquire-ARMhf_gnueabi-3.0.0.tgzinstall_mvGenTL_Acquire_ARM.sh
x86_64mvGenTL_Acquire-x86_64_ABI2-3.0.0.tgzinstall_mvGenTL_Acquire.sh

The following example explains the installation process for the x86_64 package. The installation process for other packages will work almost identical except different names as mentioned in the previous table.

  • Please start a console and change into the directory where the installation script and the installation package are located e.g. /home/username/Downloads : 
    cd /home/username/Downloads
    Note
    If root permissions are needed, the script will ask for the permissions. There is no need to call it with root permissions.
  • You might need to enable the execute flag with: 
    chmod a+x install_mvGenTL_Acquire.sh
  • Run the install script: 
    ./install_mvGenTL_Acquire.sh

During installation, the script will ask if it should build all tools and samples.

Note
The installation script is developed for Ubuntu/Debian, SUSE Linux and Red Hat Linux based distributions. On other distributions some features of the installation script may or may not work. Get in touch with us if you encounter any problems!

The installation script checks for package dependencies described above and installs them with the respective standard package manager (e.g. apt-get) if necessary. So an Internet connection is recommended.

Note
The installation script (install_mvGenTL_Acquire.sh) and the archive (mvGenTL_Acquire-x86_64_ABI2-3.0.0.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 supports various arguments, which allow to customize the installation, the desired functionalities and the installation process itself. All arguments are optional:

ArgumentFunction
-h or --help Display the help.
-p or --path Define a custom installation directory.
-gev or --gev_support Install the GigE Vision related features of the driver. Default: yes
-u3v or --u3v_support Install the USB3 Vision related features of the driver. Default: yes
-pcie or --pcie_support Install the PCI Express related features of the driver. Default: yes
-ogev or --only_gev Install only the GigE Vision related features of the driver (deprecated, favor flavors without the 'only' instead). Default: no
-ou3v or --only_u3v Install only the USB3 Vision related features of the driver (deprecated, favor flavors without the 'only' instead). Default: no
-onaos or --only_naos Install only the PCI Express related features of the driver (deprecated, favor flavors without the 'only' instead). Default: no
-u or --unattended Unattended installation with default settings. By using this parameter you explicitly accept the EULA.
-m or --minimal Minimal installation. No tools or samples will be built, and no automatic configuration and/or optimizations will be done. By using this parameter you explicitly accept the EULA.

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

If no path is specified, the package will be installed to /opt/mvIMPACT_Acquire.

MacOS

Since
Version 2.50.0 of this driver package

Impact Acquire is available as a dmg (Apple disk image) for macOS 12 (Monterey) on ARM architectures like the Mac mini. This disk image contains files for working with Balluff GigEVision™ devices, but does not contain a full installer.

Quickstart

  • With a double-click on mvIMPACT_Acquire_ARM64-3.0.0.dmg , the disk image is mounted like an external disk to the folder /Volumes, and a window opens displaying the end-user license agreement.
  • After agreeing, the contained folders and files are displayed in a Finder window.
  • Open a Terminal window
  • In the Terminal, enter
    cd /Volumes/<NameOfTheDmgWithoutExtension> (e.g. cd /Volumes/mvIMPACT_Acquire_ARM64-2.50.0)
  • Now, the three GUI tools can be started like this:
    ./startImpactControlCenter.sh
    ./startIPConfigure.sh
    ./startDeviceConfigure.sh
    For more information about these tools, see https://www.balluff.com/en-de/documentation-for-your-balluff-product/SDK_GUI_Tools/index.html
  • If the tools don't work properly, you might have to install additional software. See chapter Initial Operation
  • For unmounting the disk image, find the mounted disk icon on the desktop and eject it. Closing the window showing the contents of Impact Acquire does not unmount the disk image.

Package Contents

The package contains:

  • Basically the same structure and contents as for Linux, but only support for GigEVision™ devices.
    • apps
    • bin
    • CMake
    • common
    • doc
    • DriverBase
    • FirmwareUpdates
    • lib
    • mvDeviceManager
    • mvIMPACT_CPP
    • mvPropHandling
    • runtime
    • Toolkits
  • An installation script install_local_mvGenTL_Acquire.sh for creating a local copy of mvGenTL_Acquire.
  • Bash scripts for starting the three applications provided: startImpactControlCenter.sh, startIPConfigure.sh and startDeviceConfigure.sh

Installation

For using mvGenTL_Acquire without prior mounting of the disk image, script install_local_mvGenTL_Acquire.sh can be used. This script copies all files into a new folder in the user's home folder(~/mvIMPACT_Acquire), and then the .bashrc file is extended by setting all necessary environment variables. These changes will automatically become available after the next start.

Initial Operation

Be aware that:

  • For this version, homebrew must be installed as well as a few packages that can be installed using homebrew:
  • All scripts available with Impact Acquire are for the Bourne-Again Shell (bash), and not for the in-built Z shell.
  • The following environment variables have to be set:
    • MVIMPACT_ACQUIRE_DIR pointing to the folder where all mvGenTL_Acquire folders reside
    • GENICAM_GENTL64_PATH pointing to $MVIMPACT_ACQUIRE_DIR/lib/arm64
    • GENICAM_ROOT pointing to $MVIMPACT_ACQUIRE_DIR/runtime/bin/Mac64_Universal
  • Environment variable MVIMPACT_ACQUIRE_DATA_DIR is assumed to be pointing to a folder containing the following subfolders:
    • logs (a folder that contains the camera log files. Copying file $MVIMPACT_ACQUIRE_DIR/apps/mvDebugFlags.mvd here allows logging to be configured)
    • GenICam (a folder for storing GenICam files of cameras)
    • GenICam/Cache_V3_4 (A folder for caching GenICam xml files of cameras for saving time when opening them)
  • ImpactControlCenter, IPConfigure or DeviceConfigure can be started like this:
    • $MVIMPACT_ACQUIRE_DIR/bin/ImpactControlCenter.app/Contents/MacOS/ImpactControlCenter
    • $MVIMPACT_ACQUIRE_DIR/bin/IPConfigure.app/Contents/MacOS/IPConfigure
    • $MVIMPACT_ACQUIRE_DIR/bin/DeviceConfigure.app/Contents/MacOS/DeviceConfigure
  • When compiling the shipped example programs from source code, CMake has to be available on the system. If the installed wxWidgets version does not allow starting the GUI tools, re-compiling might be necessary. CMake usage is described here

Balluff cameras should now be usable.

Optimization of Network Parameters

To improve performance, some system parameters may have to be adapted. Using the script bin/tuneNetwork.sh , they are set provided you have administrator privileges (the MTU is set only for interface "Ethernet")

  • An MTU of 9000 is set up (at least 8000 should be used)
    networksetup -setMTU <adapter name (e.g. en1)> 9000
  • Via sysctl, some more optimizations may be made:
    sudo sysctl -w kern.ipc.maxsockbuf=8388608 // or more if possible
    sudo sysctl -w net.inet.udp.maxdgram=9216
    sudo sysctl -w net.inet.raw.recvspace=16777216 // or more if possible
    sudo sysctl -w net.inet.udp.recvspace=7454720 // or more if possible
    Note
    These changes are only valid for the running session and have to be set after each start of the system