Impact Acquire SDK C
Non-MSI Based Setup Routines
Attention
Other setup routines should NOT include the driver files if this can be avoided, as this might cause version conflicts when the original installation package is installed as well and might also confuse the MSI engine when removing the original installation package, which might cause an incomplete package removal operation. However if this approach is desired this section provides a brief list of things that must be done of the target machine.
Note
Deprecated product families will NOT be described here!

Locating Runtime Libraries

The following table shows where to find files belonging to the Impact Acquire framework on a target machine where the framework has been installed.

Library 32-bit system - 32-bit library 32-bit system - 64-bit library 64-bit system - 32-bit library 64-bit system - 64-bit library
BVS_CA-BN.[some letter].[0-3].dll - - - "%windir%\system32"
mvBlueFOX.dll "%windir%\system32" - "%windir%\SysWOW64" "%windir%\system32"
mvDeviceManager.dll "%windir%\system32" - "%windir%\SysWOW64" "%windir%\system32"
mvDisplay.dll "%windir%\system32" - "%windir%\SysWOW64" "%windir%\system32"
mvGenTLConsumer.dll "%windir%\system32" - "%windir%\SysWOW64" "%windir%\system32"
mvGenTLProducer.cti "%MVIMPACT_ACQUIRE_DIR%\bin" - "%MVIMPACT_ACQUIRE_DIR%\bin" "%MVIMPACT_ACQUIRE_DIR%\bin\x64"
mvGenTLProducer.PCIe.cti - - - "%MVIMPACT_ACQUIRE_DIR%\bin\x64"
mvImageProcessing.dll "%windir%\system32" - "%windir%\SysWOW64" "%windir%\system32"
mvIMPACT_Acquire.jar "%MVIMPACT_ACQUIRE_DIR%\bin" - "%MVIMPACT_ACQUIRE_DIR%\bin" "%MVIMPACT_ACQUIRE_DIR%\bin\x64"
mvIMPACT_Acquire.java.dll "%MVIMPACT_ACQUIRE_DIR%\bin" - "%MVIMPACT_ACQUIRE_DIR%\bin" "%MVIMPACT_ACQUIRE_DIR%\bin\x64"
mvPropHandling.dll "%windir%\system32" - "%windir%\SysWOW64" "%windir%\system32"
mvVirtualDevice.dll "%windir%\system32" - "%windir%\SysWOW64" "%windir%\system32"
mv.impact.acquire.dll (.NET) "%MVIMPACT_ACQUIRE_DIR%\bin\.NET"
mv.impact.acquire.display.dll (.NET) "%MVIMPACT_ACQUIRE_DIR%\bin\.NET"
mv.impact.acquire.display.extensions.dll (.NET) "%MVIMPACT_ACQUIRE_DIR%\bin\.NET"
mv.impact.acquire.examples.helper.dll (.NET) "%MVIMPACT_ACQUIRE_DIR%\bin\.NET"
mv.impact.acquire.dll (.NET Standard) "%MVIMPACT_ACQUIRE_DIR%\bin\netstandard2.0"
mv.impact.acquire.display.dll (.NET Standard) "%MVIMPACT_ACQUIRE_DIR%\bin\netstandard2.0"
mv.impact.acquire.display.extensions.dll (.NET Standard) "%MVIMPACT_ACQUIRE_DIR%\bin\netstandard2.0"
mv.impact.acquire.examples.helper.dll (.NET Standard) "%MVIMPACT_ACQUIRE_DIR%\bin\netstandard2.0"

Common Files Needed For Every Device Family

To operate a Balluff imaging or image capture device with the Impact Acquire framework some common files are needed for every device on the target system:

  • mvDeviceManager.dll
  • mvImageProcessing.dll
  • mvPropHandling.dll

As the user-mode part of this SDK internally make use of Open MP (http://openmp.org/) on Windows® a matching version of the Open MP runtime must be installed on the target system as well. Current versions of the libraries are linked against the Microsoft Visual Studio® 2019 version of the Open MP runtime. The corresponding merge modules or redistributables can be obtained from Microsoft. See here as well: Windows®

Note
Since release 1.8.0 of this framework the file libexpat.dll is no longer shipped with the installation package, as it is no longer needed by any of the modules belonging to the Impact Acquire interface. This might force you to modify your installer.

All these files can be either be copied somewhere in the systems path or into the applications directory.

With these files the device can be used and configured from an application. Some features however require some additional installation work:

General Considerations When Shipping Kernel Drivers

In general any version of Windows® requires you to install properly signed kernel/device drivers. Unfortunately the signature requirements did change over the years and therefore different Windows version require differently signed drivers. The actual kernel driver is always the same in almost every scenario however the signature attached to the file is NOT and therefore the full file is different. When working with the *.msm-files for the driver installation the merge modules internal logic will detect the version of Windows the installation is running on and will then install the matching version of the device driver. Internally this is achieved by putting EVERY version of the kernel driver into the merge module and then only the correct version gets installed. When not using the merge modules this has to be implemented as well. If just a single version of Windows is targeted the easiest approach is to install the Impact Acquire package on that system and get the related driver files from the full installation. Which files are needed for which device is described further down in this chapter. Right now Impact Acquire usually comes with drivers for the following versions of Windows:

Windows versionUsed Signature
Vista, 7, 8, 8.1, 10(smaller than release 1607) and Server 2008SHA256
Windows 10 greater or equal version 1607 and Windows 11SHA256 EV

See Windows® as well!

Displaying Image Data

In case an application makes use of the mvDisplay.dll library this must be deployed on the target system as well. The same restrictions, path information, etc. as in the previous section apply.

Note
More information about locations of libraries within the standard installation is summarized at Locating Runtime Libraries.

Load/Store Settings

In order to allow the application to load and store settings in the registry these keys must be created during the installation:

  • HKEY_LOCAL_MACHINE/Software/Balluff/Settings
  • HKEY_CURRENT_USER/Software/Balluff/Settings

If the keys are missing settings can still be loaded and stored in the platform independent XML format by using the appropriate functions discussed in the chapters describing the software interface.

Log-file Support

If your application shall be able to generate log output the following directory must be created on the target system:

  • "%PUBLIC%/Documents/Balluff/ImpactAcquire/Logs"

Apart from that these files must be installed into "%PUBLIC%/Documents/Balluff/ImpactAcquire/Logs":

  • mvDebugFlags.mvd
  • logo.png
  • mvIMPACT_acquireLogFile.xsl
  • mvLogFileViewer.html
  • sarissa.js
  • Apache.txt (this must be shipped with mvLogFileViewer.html and sarissa.js for legal reasons as part of the file make use of code under the Apache 2.0 license)

The first file is discussed in detail in the logging chapter of this manual, the latter files are only needed if the standard Balluff Impact Acquire log-file style shall be used(XML with stylesheet transformation). To find out how to embed your own log-file stylesheet please refer to the chapter about the logging mechanism. Here it also explained how to create plain XML log files and XML files that can be viewed using mvLogFileViewer.html.

Camera Description Files Support (Frame Grabbers)

Note
The last minor release containing frame grabber related Impact Acquire packages was version 2.47.0. If frame grabber boards are part of the application the last released package for these boards can be mixed with newer releases of other Impact Acquire up to version 3.0.0. Mixing 2.x installations with 3.x and higher installations will not be supported. See Migrating Applications To Impact Acquire 3.0.0 And Higher as well! Frame grabber board packages have entered maintenance mode!

If your application shall be able to work with camera description files and does NOT modify the property Device/customDataDirectory before initialising the device the following directory must be created on the target system:

  • "%PUBLIC%/Documents/Balluff/ImpactAcquire/CameraFiles"

All camera description files that shall be used by the application must be installed into the folder CameraFiles in order to be recognized by the driver.

.NET Support

In case an application makes use of the Impact Acquire .NET interface the corresponding libraries must be deployed on the target system as well. Were and what version of these libraries must be shipped is explained in the Building, Linking And Running Applications Using Impact Acquire chapter of the .NET API manual.

Depending on the used functionalities the following libraries might be necessary:

  • mv.impact.acquire.dll (always needed)
  • mv.impact.acquire.display.dll (needed if the display module shall be used)
  • mv.impact.acquire.display.extensions.dll (needed if special features of the display module shall be used)
  • mv.impact.acquire.examples.helper.dll (needed if features from this module have been used)
Attention
Even if the listed files have the same names as the ones for the .NET Standard interface the files are NOT identical. Please have a look at chapter Locating Runtime Libraries to get some information where they are located in the default installation.

.NET Standard Support

In case an application makes use of the Impact Acquire .NET Standard interface the corresponding libraries must be deployed on the target system as well. Were and what version of these libraries must be shipped is explained in the Building, Linking And Running Applications Using Impact Acquire chapter of the .NET API manual.

Depending on the used functionalities the following libraries are necessary:

  • mv.impact.acquire.dll (always needed)
  • mv.impact.acquire.display.dll (needed if the display module shall be used)
  • mv.impact.acquire.display.extensions.dll (needed if special features of the display module shall be used)
  • mv.impact.acquire.examples.helper.dll (needed if features from this module have been used)
Attention
Even if the listed files have the same names as the ones for the .NET interface the files are NOT identical. Please have a look at chapter Locating Runtime Libraries to get some information where they are located in the default installation.

Java Support

In case an application makes use of the Java to Impact Acquire native interface the mvIMPACT_Acquire.java.dll library must be deployed on the target system as well. The same restrictions, path information, etc. as in the Common Files Needed For Every Device Family section apply.

Note
More information about locations of libraries within the standard installation is summarized at Locating Runtime Libraries.

Python Support

Distributing the Impact Acquire Python API requires some additional work as the Python interface has to be compiled for the specific target platform first. The same restrictions, path information, etc. as in the Common Files Needed For Every Device Family section apply.

Please refer to the to Impact Acquire SDK Python → Building And Running Applications Using Impact Acquire → Building → Windows for more details.

The resulting package will be located at %MVIMPACT_ACQUIRE_DIR%\LanguageBindings\Python\Output. Depending on the Python version which should be used the resulting directory might be named according to the Python version it has been built for, e.g.:

  • lib.win32-3.8 for Python 3.8
  • (Only for Impact Acquire < 3.0.1) lib.win32-2.7 for Python 2.7
Note
More information about locations of libraries within the standard installation is summarized at Locating Runtime Libraries.

FreeImage Support

The mvVirtualDevice library as well as the load/save image API of Impact Acquire make use of the FreeImage project.

FFmpeg Support

The load/save video stream API makes use of the FFmpeg project. In order to use these features have a good look at the legal notice section and the video stream related API documentation. All details can be found there.

GenICam™ GenTL Device Specific

Note
This section applies to all GigE Vision™ as well as all USB3 Vision™ devices and all BVS CA-GT, BVS CA-GX (mvBlueCOUGAR-X), BVS CA-SF (mvBlueFOX3), BVS CA-BN and mvBlueCOUGAR-S devices in particular.

For all GenICam™ based devices the following files will be necessary:

  • mvGenTLConsumer.dll can be copied somewhere in the systems path or into the applications directory

In case of mvUSB3Vision or GigE Vision™ devices:

  • mvGenTLProducer.cti can be copied somewhere in the systems path or into a directory the corresponding GENICAM_GENTL environment variable is pointing to.

In case of BVS CA-BN devices:

  • mvGenTLProducer.PCIe.cti can be copied somewhere in the systems path or into a directory the corresponding GENICAM_GENTL environment variable is pointing to.
  • BVS_CA-BN.[some letter].[0-3].dll can be copied somewhere in the systems path or into the directory mvGenTLProducer.PCIe.cti resides in.

For the GenICam cache it is necessary to make use of the environment variable MVIMPACT_ACQUIRE_DATA_DIR which will be used to store data like the log files generated by Impact Acquire, firmware update files or the GenICam cache. The variable has to be defined to a directory with the following structure:

%MVIMPACT_ACQUIRE_DATA_DIR%
|- FirmwareUpdates (optional)
|- GenICam
|- logs (optional)
Note
More information about locations of libraries within the standard installation is summarized at Locating Runtime Libraries.
Attention
Regarding all the kernel driver related information discussed in the technology specific sections from here onwards it is essential to understand the impact of what is described here as well! Not doing so will result in a corrupted system (e.g. in problems like this)!

GigE Vision™ Device Specific (Windows 7 And Smaller)

If the GigE Vision™ capture filter kernel-mode driver shall be used the following files must be shipped as well:

For 32-bit support:

  • mvGigECapture.inf (matching the target platform)
  • mvGigECapturem.inf (matching the target platform)
  • mvGigECapture_x86.cat
  • mvGigECapturem_x86.cat
  • mvGigECapture.sys (matching the target platform)

For 64-bit support:

  • mvGigECapture.inf (matching the target platform)
  • mvGigECapturem.inf (matching the target platform)
  • mvGigECapture_amd64.cat
  • mvGigECapturem_amd64.cat
  • mvGigECapture.sys (matching the target platform)
Note
Please note that the file mvGigECapture.sys that is installed on the target system will differ from Windows® version to Windows® version. Currently Windows 2000 will need a different version of this file than newer versions of Windows. To obtain the correct file needed for the target platform the original installer must be installed on the system in question. Thus to build an installer for Windows 2000 the *.sys-file must be obtained from a Windows 2000 system. When working with the merge modules this will be done automatically.

GigE Vision™ Device Specific (Windows 8 And Newer)

If the GigE Vision™ capture filter kernel-mode driver shall be used the following files must be shipped as well:

For 32-bit support:

  • mvGigECapture2.inf
  • mvGigECapture2_x86.cat
  • mvGigECapture2.sys

For 64-bit support:

  • mvGigECapture2.inf
  • mvGigECapture2_amd64.cat
  • mvGigECapture2.sys

GigE Vision™ Device Specific (Common Installation)

To actually install the filter driver on the system there are 3 ways to go: Either the tool GigEConfigure or the built-in mechanism of Windows® to install a filter driver can be used.

Using GigEConfigure there are 2 possibilities:

  1. By using the command line options available for the tool. For details please have a look into the GigEConfigure section in the Impact Acquire SDK GUI Applications-manual, chapter "Command-line Interface".
  2. The user interactive version by simply starting the tool and then clicking Install driver or Remove driver and/or by right-clicking on a network connection entry to enable/disable the filter driver.
Note
More details regarding the usage of GigEConfigure can be found at the corresponding chapter within the Impact Acquire SDK GUI Applications-manual (here).

Using the built-in mechanism of Windows® works like this:

First navigate to any of the network connections available to the system and open the properties dialog of that connection.

Network connection properties

Here click on Install...

In the next Windows® select Service and click on Add....

Network component type selection

Now click on Have Disk....

Network service selection

Click on Browse... and navigate to the folder containing the GigE Vision™ capture filter kernel-mode driver files mentioned above.

Install from disc

Select the file mvGigECapture.inf and click on Open

Locate file

Click on OK

Select network service
Note
Depending on the amount of network connections installed in your system and depending on the version of Windows® you are working with a couple of warnings might appear that must be confirmed with something like Continue anyway.

Afterwards the filter driver will installed and active on EVERY network connection of the system. If that is not desired, it can be enable and disabled from the properties dialog of the network connection that shall be modified by checking or unchecking the box in from of the Balluff Impact Acquire filter driver entry.

Software installation

GigE Vision™ Device Specific (Registry Based Installation)

The third approach is a possibility provided by the functionality of the mvGenTLProducer.cti which allows to install the filter driver using the Impact Acquire API. At first there are some values which have to be written to the Registry of Windows® to specify the GigE Vision™ support and the path to the GigE Vision™ filter driver which shall be installed

The entry HKEY_LOCAL_MACHINE/SOFTWARE/Balluff/Settings has to be generated and afterwards the keys from the following table have to be created.

Name Type Value
GEV_SUPPORT DWORD 1
GEV_DRIVER_SOURCE_PATH String MVIMPACT_ACQUIRE_DIR%\KernelDrivers\mvGigECaptureDriver(x64)(SHA256.EV)\mvGigECapture2.inf
Note
The GEV_DRIVER_SOURCE_PATH might differ depending on the source of the kernel driver files. See General Considerations When Shipping Kernel Drivers as well. Afterwards some small application needs to load the required TLIMV_InstallDriverFromRegistry function from mvGenTLProducer.cti. The following code shows how this would work:
#include <windows.h>
int main( void )
{
typedef void ( *TLIMV_InstallDriverFromRegistry )( void );
HINSTANCE hDLL = LoadLibrary( "<path to mvGenTLProducer.cti>" );
TLIMV_InstallDriverFromRegistry installDriverFromRegistry = ( TLIMV_InstallDriverFromRegistry ) GetProcAddress( ( HMODULE ) hDLL, "TLIMV_InstallDriverFromRegistry" );
installDriverFromRegistry();
};
Note
As the function will install the GigE Vision™ filter driver and access the HKEY_LOCAL_MACHINE entries, the application utilizing this functionality needs to be called with administrator permissions. Of course this cannot only be done using a C/C++ application as shown here but also by any other mechanism that can write to the Registry and can call a DLL function that doesn't require parameters. So this can also be done from within a WiX installation package or some C# application for example.

USB3 Vision™ Device Specific

For USB3 Vision™ device support the following files correctly signed for the target platform must be shipped as well:

For 32-bit support:

  • mvUSB3Vision.inf
  • mvUSB3Vision.cat
  • x86/libusbK_x86.dll
  • x86/libusb0_x86.dll
  • x86/libusbK.sys
  • x86/WdfCoInstaller01009.dll

For 64-bit support:

  • mvUSB3Vision.inf
  • mvUSB3Vision.cat
  • x86/libusbK_x86.dll
  • x86/libusb0_x86.dll
  • amd64/libusbK.sys
  • amd64/libusbK.dll
  • amd64/libusb0.dll
  • amd64/WdfCoInstaller01009.dll
Attention
The relative folder structure is vital! Installation of the kernel module will fail if this does not match!

Experienced users are encouraged to use the Microsoft Driver Install Framework for applications to deploy this driver on the target system (http://msdn.microsoft.com/en-us/library/ms790295.aspx). This is the recommended way for installing device drivers.

BVS CA-BN Device Specific

For BVS CA-BN device support the following files correctly signed for the target platform must be shipped as well:

For 32-bit support:

Attention
There is no support for 32-bit operating systems.

For 64-bit support:

  • mvBlueNAOS.inf
  • mvBlueNAOS.cat
  • mvBlueNAOS.sys

Experienced users are encouraged to use the Microsoft Driver Install Framework for applications to deploy this driver on the target system (http://msdn.microsoft.com/en-us/library/ms790295.aspx). This is the recommended way for installing device drivers.

GenICam™ Runtime

Apart from that, the GenICam™ runtime this framework has been linked with must be installed on the target system. The runtime modules are contained in the merge modules belonging to this installation package.

The framework will try to locate the GenICam™ runtime in %MVIMPACT_ACQUIRE_DIR%/Toolkits/GenICam_v<major>_<minor> thus if you plan to distribute the runtime in a different way you need to setup you environment accordingly as described by the GenICam™ standard.

USB2 Devices

Note
This section applies to all BVS CA-MLC, BVS CA-IGC and mvBlueFOX devices.
  • mvBlueFOX.dll can be copied somewhere in the systems path or into the applications directory
Note
More information about locations of libraries within the standard installation is summarized at Locating Runtime Libraries.

The files belonging to the kernel driver correctly signed for the target platform:

  • amvBlueFOX2.inf must be copied into the Windows® inf folder
  • mvBlueFOX2.sys must be copied into the Windows® drivers folder
  • mvBlueFOX2.cat (signed catalog file for the mvBlueFOX2.sys module)
Note
The leading 'a' in the file name amvBlueFOX2.inf is NOT a mistake. The reason for this strange file name is that Windows 2000 by default uses the first *.inf-file in an alphabetical search that matches the detected device. As previous versions of this driver package contained 2 versions of the kernel driver, the 'older' versions *.inf-files name was mvBlueFOX.inf and in order to install the newer version of the kernel driver as a default driver the new *.inf-file must be found before the old one as Windows does not list all available drivers but only the first one detected.

The kernel driver files should be installed BEFORE connecting the device to the target system the first time as then Windows automatically detects the driver.

*.cat files can't just be copied into some system specific directory. Please refer to the corresponding documentation by Microsoft.

In addition to this a Windows® driver framework co-installer is needed. This file must be copied into the Windows® system (system32) folder. Both the 32-bit and the 64-bit version of the driver need 'WdfCoinstaller01009.dll' for the driver installation. If the co-installer is not present on the target system they must be copied as well.

Experienced users are encouraged to use the Microsoft Driver Install Framework for applications to deploy this driver on the target system (http://msdn.microsoft.com/en-us/library/ms790295.aspx). This is the recommended way for installing device drivers.

These files alone will correctly install the mvBlueFOX as a recognized device on the target system. However to access the device from any kind of application the base libraries for the Impact Acquire interface will be needed as well.

Virtual Devices

  • mvVirtualDevice.dll can be copied somewhere in the systems path or into the applications directory

mvVirtualDevice is able to connect to the FreeImage library for loading JPEG, PNG and TIFF images from hard disk. See FreeImage Support for details. The libary will try to load the FreeImage libraries from %MVIMPACT_ACQUIRE_DIR%/Toolkits//FreeImage3160/bin/Release/FreeImage/<platform> so this is where the library needs to be to make this work.

Note
More information about locations of libraries within the standard installation is summarized at Locating Runtime Libraries.