MATRIX VISION - mvBlueFOX3 Technical Documentation
Quickstart

Driver concept

The driver supplied with the MATRIX VISION product represents the port between the programmer and the hardware. The driver concept of MATRIX VISION provides a standardized programming interface to all image processing products made by MATRIX VISION GmbH.
The advantage of this concept for the programmer is that a developed application runs without the need for any major modifications to the various image processing products made by MATRIX VISION GmbH. You can also incorporate new driver versions, which are available for download free of charge on our website: http://www.matrix-vision.com.

The following diagram shows a schematic structure of the driver concept:

Figure 1: Driver concept
  • 1 Part of any mvIMPACT Acquire driver installation package (Windows).
  • 2 Separately available for 32 bit and 64 bit. Requires at least one installed driver package.
  • 3 See 2, but requires an installed version of the mvBlueFOX driver.
  • 4 Part of the NeuroCheck installer but requires at least one installed frame grabber driver.
  • 5 Part of the mvIMPACT SDK installation. However, new designs should use the .NET libs that are now part of mvIMPACT Acquire ("mv.impact.acquire.dll"). The namespace "mv.impact.acquire" of "mv.impact.acquire.dll" provides a more natural and more efficient access to the same features as contained in the namespace "mvIMPACT_NET.acquire" of "mvIMPACT_NET.dll", which is why the latter one should only be used for backward compatibility but NOT when developing a new application.
  • 6 Part of Micro-Manager.

NeuroCheck support

A couple of devices are supported by NeuroCheck. However between NeuroCheck 5.x and NeuroCheck 6.x there has been a breaking change in the internal interfaces. Therefore also the list of supported devices differs from one version to another and some additional libraries might be required.

For NeuroCheck 5.x the following devices are supported:

DeviceAdditional software needed
mvTITAN-G1mvSDK driver for mvTITAN/mvGAMMA devices
mvTITAN-CLmvSDK driver for mvTITAN/mvGAMMA devices
mvGAMMA-CLmvSDK driver for mvTITAN/mvGAMMA devices
mvBlueFOXmvIMPACT Acquire driver for mvBlueFOX devices, "NCUSBmvBF.dll"

For NeuroCheck 6.0 the following devices are supported:

DeviceAdditional software needed
mvTITAN-G1mvIMPACT Acquire driver for mvTITAN/mvGAMMA devices
mvTITAN-CLmvIMPACT Acquire driver for mvTITAN/mvGAMMA devices
mvGAMMA-CLmvIMPACT Acquire driver for mvTITAN/mvGAMMA devices
mvHYPERION-CLbmvIMPACT Acquire driver for mvHYPERION devices
Every other mvIMPACT Acquire compliant devicemvIMPACT Acquire driver for the corresponding device family, "mv.impact.acquire.NeuroCheck6.dll" (comes with the driver package, but the driver package must be installed AFTER installing NeuroCheck 6

For NeuroCheck 6.1 the following devices are supported:

DeviceAdditional software needed
mvTITAN-G1mvIMPACT Acquire driver for mvTITAN/mvGAMMA devices
mvTITAN-CLmvIMPACT Acquire driver for mvTITAN/mvGAMMA devices
mvGAMMA-CLmvIMPACT Acquire driver for mvTITAN/mvGAMMA devices
mvHYPERION-CLbmvIMPACT Acquire driver for mvHYPERION devices
Every other mvIMPACT Acquire compliant devicemvIMPACT Acquire driver for the corresponding device family, "mv.impact.acquire.NeuroCheck6_1.dll" (comes with the driver package, but the driver package must be installed AFTER installing NeuroCheck 6.1

VisionPro support

Every mvIMPACT Acquire driver package on Windows comes with an adapter to VisionPro from Cognex. The installation order does not matter. After the driver package and VisionPro has been installed, the next time VisionPro is started it will allow selecting the mvIMPACT Acquire device. No additional steps are needed.

MATRIX VISION devices that also comply with the GigE Vision or USB3 Vision standard don't need any software at all, but can also use VisionPro's built-in GigE Vision or USB3 Vision support.

HALCON support

HALCON comes with built-in support for mvIMPACT Acquire compliant devices, so once a device driver has been installed for the mvIMPACT Acquire device, it can also be operated from a HALCON environment using the corresponding acquisition interface. No additional steps are needed.

MATRIX VISION devices that also comply with the GigE Vision standard don't need any software at all, but can also use HALCON's built-in GigE Vision support.

As some mvIMPACT Acquire device driver packages also come with a GenTL compliant interface, these can also be operated through HALCON's built-in GenTL acquisition interface.

LabVIEW support

Every mvIMPACT Acquire compliant device can be operated under LabVIEW through an additional set of VIs which is shipped by MATRIX VISION as a separate installation ("mvLabVIEW Acquire").

MATRIX VISION devices that also comply with the GigE Vision or USB3 Vision standard don't need any additional software at all, but can also be operated through LabVIEW's GigE Vision or USB3 Vision driver packages.

DirectShow support

Every mvIMPACT Acquire compliant device driver package comes with an interface to DirectShow. In order to be usable from a DirectShow compliant application, devices must first be registered for DirectShow support. How to this is explained here.

Micro-Manager support

Every mvIMPACT Acquire compliant device can be operated under https://micro-manager.org when using mvIMPACT Acquire 2.18.0 or later and at least Micro-Manager 1.4.23 build AFTER 15.12.2016. The adapter needed is part of the Micro-Manager release. Additional information can be found here: https://micro-manager.org/wiki/MatrixVision.

Windows

System requirements

Currently supported Windows versions are:

  • Microsoft Windows 7 (32-bit, 64-bit)
  • Microsoft Windows 8.1 (32-bit, 64-bit)
  • Microsoft Windows 10 (32-bit, 64-bit)

Other Windows version can be used at the user's own risk.

Note
Since mvIMPACT Acquire version 2.8.0 it could be possible that you have to update your Windows installer at least using Windows XP. The necessary packages are available from Microsoft's website: http://www.microsoft.com/en-US/download/details.aspx?id=8483

All necessary drivers are available from the MATRIX VISION website at www.matrix-vision.de, section "Products -> Cameras -> your interface -> your product -> Downloads".

Hardware

MATRIX VISION testet successfully several USB 3 extension cards or adapters for PCs and Notebooks. Please have a look here for a current listing:

See also
http://www.matrix-vision.com/faq-mvbluefox-en.html?show=824

Installing the mvGenTL-Acquire driver

By double clicking on

  • mvGenTL_Acquire-x86-n.n.n.msi (for 32-bit systems) or
  • mvGenTL_Acquire-x86_64-n.n.n.msi (for 64-bit systems), the installer will start automatically:
Figure 2: Driver installation - start window
  • Now, follow the instructions of installation program and use default settings:
Figure 3: Driver installation - select installation folder
Since
mvIMPACT Acquire 2.25.0

wxPropView is able to check if there are new driver version available on a weekly basis. Deactivate the check box if wxPropView should not check for updates. You can activate the checking in wxPropView via the help menu.

Figure 4: Driver installation - select features
  • After confirmation, the installation will start and copy the data. At the end, MATRIX VISION's USB3 Vision / GigE Vision capture filter driver will be installed. A "Windows Security" dialog will appear.
  • Click on Install (This however requires the system to be rebooted, thus the installer will ask the user to reboot the system).
Figure 5: Driver installation - Reboot request
  • After the system has been restarted, the filter driver installation will start automatically. If necessary, click "Ok" and ignore the compatibility testing of Windows by clicking on "Continue anyway" twice.
  • Now, the driver installation will be finished.

You will find all tools like

either on desktop as single icons or in Windows menu under "MATRIX VISION -> mvIMPACT Acquire".

Note
You can ignore the other tools mvIPConfigure and mvGigEConfigure, because they are only necessary in combination with GigE Vision devices like the mvBlueCOUGAR-X.

Afterwards, you can use mvDeviceConfigure to update the firmware. The latest firmware image is available on the web - please check for updates. The current firmware version can be read out using wxPropView (device section on top).

Linux

Please check our website for the availability of the Linux driver.

System requirements

  • Kernel 3.5.x or greater
Note
Linux kernels prior to 3.5.x do not inherently support USB 3!

In case the target system runs an older Linux kernel, it is absolutely necessary to update the kernel to at least version 3.5.0 . Please refer to the documentation of your Linux distribution for information on how to update your system's Linux kernel.

Following Kernels have been tested and verified by MATRIX VISION for seamless USB3 operation:

  • Kernel 3.8.0
  • Kernel 3.11.0
  • Kernel 3.14.0

Before installation on a Linux system (e.g. Ubuntu 12.04), the system has to provide at least following packages:

  • libwxbase3.0-0
  • libwxbase3.0-dev
  • libwxgtk3.0-0
  • libwxgtk3.0-dev
  • wx3.0-headers
  • build-essential (meta package)
  • libgtk2.0-dev
  • gcc 4.1 environment or newer

Hardware

MATRIX VISION testet successfully several USB 3 extension cards or adapters for PCs and Notebooks. Please have a look here for a current listing:

See also
http://www.matrix-vision.com/faq-mvbluefox-en.html?show=824

Installing the mvGenTL-Acquire driver

Note
If you are going to install the mvGenTL-Acquire driver on an embedded board, please read this section first.

To use the camera 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 camera, 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:

mvGenTL_Acquire-x86-n.n.n.tgz

  • Please start a console and change into a directory e.g. /home/username/workspace :
    cd /home/username/workspace 
  • Copy the install script and the hardware driver to the workspace directory (e.g. from the website):
    ~/workspace$ cp /home/Downloads/install_mvGenTL_Acquire.sh /home/Downloads/mvGenTL_Acquire-x86-2.3.2.tgz . 
  • Enable the execute flag with:
    chmod a+x install_mvGenTL_Acquire.sh 
  • Run the install script:
    ~/workspace$ ./install_mvGenTL_Acquire.sh

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

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

Note
The installation script (install_mvGenTL_Acquire.sh) and the archive (mvGenTL_Acquire-x86-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:

  • target directory name
  • 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.6.0 

If this argument is not specified, the driver will be placed in the default directory /opt .

The version argument is entirely optional. If no version is specified, the most recent

mvGenTL_Acquire-x86-n.n.n.tgz 

found in the current directory will be installed.

Defining udev rules

Most Linux system nowadays use the udev device manager, which is responsible for dynamically managing the /dev tree. In order to be able to use the MATRIX VISION mvBlueFOX3 USB3 Vision camera as non-root user, a special set of rules has to be handed to the udev device manager.

On older systems this could be done by directly editing the contents of a "/etc/udev/rules" file, however nowadays a "/etc/udev/rules.d" directory exists, which may contain several different files, each defining the behavior of a system device.

In the specific case of the mvBlueFOX3 camera, if the camera has been installed through the respective installation script install_mvGenTL_Acquire.sh , a suitable set of rules has been installed automatically. However if for some reason the rules have to be created manually it should be done according to the following steps:

  1. Create a file in the "/etc/udev/rules.d" directory with name 52-U3V.rules .
  2. Type the following content into the file:
    SUBSYSTEM!="usb|usb_device|plugdev", GOTO="u3v_rules_end"
    ACTION!="add", GOTO="u3v_rules_end"
    
    ATTRS{bDeviceClass}=="ef", ATTRS{bDeviceSubClass}=="02", ATTRS{bDeviceProtocol}=="01", ENV{ID_USB_INTERFACES}=="*:ef0500:*", MODE="0664", GROUP="plugdev"
    
    LABEL="u3v_rules_end"
    

  3. OPTIONAL: Create another file in the "/etc/udev/rules.d" directory with name 52-mvbf3.rules . This step is only necessary if a mvBlueFOX3 in the "mvbootloader" state should be recognised by the system.
  4. OPTIONAL: Type the following content into the file:
    SUBSYSTEM!="usb|usb_device|plugdev", GOTO="mvbf_rules_end"
    ACTION!="add", GOTO="mvbf_rules_end"
    
    ATTRS{idVendor}=="164c", ATTRS{idProduct}=="5531", MODE="0664", GROUP="plugdev"
    
    LABEL="mvbf_rules_end"
    

    This step is only necessary if a mvBlueFOX3 in the "mvbootloader" state should be recognised by the system.
  5. Save the file(s) and exit your editor
Note
The above 52-U3V.rules file provides the necessary access privileges not only for mvBlueFOX cameras, but also for U3V-compliant cameras of any other vendor.

As soon as this file is into place, each time the camera is plugged to the system it acquires the set of rights that allows the user to use it without having root privileges.

Optimizing USB performance

On most contemporary Linux systems, support for USB 3 functionality has moved from separate kernel modules to the kernel itself (usbcore). On such systems, the kernel memory which is allocated for use with USB is predefined and set to a relatively small value (e.g. 16 MB on a typical 32-bit Ubuntu 12.04 System). This value is usually enough for reading from an external HDD or similar applications, but in the case of machine vision applications, with Megapixel sensors and ultra-fast transfer speeds it is way too low.

Note
You may inquire the value (in Megabytes) on your system by typing:
cat /sys/module/usbcore/parameters/usbfs_memory_mb .

It is highly recommended to increase this value to at least 256 MB or even more depending on your application (number of cameras, number of request objects per camera etc.). For example, a 5 Mpix camera, capturing RGB data with a default request count of 10, needs about 5M * 3 * 10 ~= 150MB of the usbfs memory. Always bear in mind though, that mvIMPACT Acquire is probably not the only system component using usbcore memory, so you should always reserve several MB more than the number you get from the above calculation. As a general rule of thumb, for a single-camera application with a default request setting of 10, a value of 256 MB should be adequate.

To change the value of the usbfs_memory_mb system parameter, one has to invoke the kernel at boot time with an argument that sets the parameter to the desired value. Trying to modify this parameter after the system has booted (e.g. with modprobe ), will have no effect since usbcore is a system module integrated in the Linux kernel, and not a separate kernel module which can be loaded and unloaded on demand.

Passing parameters to the kernel at boot time is usually done by typing: systemModuleName.parameter=value . In our case this would be:

usbcore.usbfs_memory_mb=256 

How this can be done depends on the system bootloader. For systems using the GRUB2 bootloader the "/etc/default/grub" ( or in some distributions "/etc/default/grub/c.cfg" ) file has to be modified.

Warning
Always modify configuration files with extreme caution, since the slightest syntax error may render the file invalid, or even the computer not bootable!

After opening this file, the GRUB_CMDLINE_LINUX_DEFAULT entry must be located. It usually has the following value:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash" 

In order to invoke the Kernel with the usbfs_memory_mb parameter, it should be modified like:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash usbcore.usbfs_memory_mb=256" 

As a final step, GRUB has to be updated by executing the update-grub script:

sudo update-grub 

If all went well, after rebooting the system, the kernel will utilize the requested amount of memory for the usbcore subsystem.

Note
On systems with GRUB Legacy support the bootloader settings are controlled by other files ( e.g. "/boot/grub/menu/c.lst" etc.). In this case it is recommended to upgrade your bootloader to GRUB2 :
sudo apt-get install grub2 
If, for some reason, this is not an option, then the menu.lst itself could be directly modified as an absolutely last resort. Always keep in mind that it is strongly recommended not to tamper directly with files in the /boot/grub directory! The smallest typing error can render the system not bootable!

For Odroid-XU3 Users

To adapt the usbfs buffer size using Odroid-XU3, please follow these steps:

  1. Open the file /media/boot/boot.ini as root.
  2. Add or adapt the string "usbcore.usbfs_memory_mb=256" at the end of the boot arguments using a blank:
    setenv bootargs "... usbcore.usbfs_memory_mb=256" 
  3. Save the file.
  4. Reboot the Odroid-XU3 board.


For Odroid-U2 / -U3 Users

Although Odroid-U2 and Odroid-U3 do not have a USB 3 port, you can use the mvBlueFOX3 cameras with the USB 2.0. Jusst adapt the following settings:

  1. Locate the file boot.scr (by default: /media/boot).
  2. Export the strings from the file:
    strings boot.scr >> boot.txt 
  3. Add or adapt the string "usbcore.usbfs_memory_mb=256" at the end of the boot arguments using a blank:
    setenv bootargs "... usbcore.usbfs_memory_mb=256" 
  4. Create a new boot.scr from the modified boot.txt.
    mkimage -A arm -T script -C none -n "boot.scr for ODROID" -d boot.txt boot.scr 
  5. Reboot the board.
Note
The net bandwidth of USB 2.0 remains the same of course (30 MB/s).

For Raspberry Pi Users

Like Odroid-U2 and Odroid-U3, the Raspberry Pi only features a USB 2.0 port. However, it is also possible to use the mvBlueFOX3 with this port, just follow these steps:

  1. Open the file /boot/firmware/cmdline.txt as root.
  2. Add or adapt the string "usbcore.usbfs_memory_mb=256" at the end of the boot arguments using a blank:
    setenv bootargs "... usbcore.usbfs_memory_mb=256" 
  3. Save the file.
  4. Reboot the Raspberry Pi board.
Note
Likewise, the net bandwidth of USB 2.0 remains the same of course (30 MB/s).

For NVIDIA Tegra TK1 Users

To use the camera following modifications are necessary in the standard configuration of the NVIDIA Tegra TK1 board:

  1. Update the software to version 21.3. Please follow this descripion.
  2. Afterwards, you have to adapt the boot parameters in /boot/extlinux/extlinux.conf at the end of the "APPEND" line:
    1. Change "usb_port_owner_info=0" to "usb_port_owner_info=2" (this will change the USB port behavior from USB 2.0 to USB 3).
    2. Set "usbcore.autosuspend=-1" (power save mode is off now).
    3. Set "usbcore.usbfs_memory_mb=256" (this will increase the buffer of the USB bus)
    E.g.
    APPEND ${cbootargs} usb_port_owner_info=2 usbcore.autosuspend=-1 usbcore.usbfs_memory_mb=128 root=/dev/mmcblk0p1 
  3. Install the mvGenTL_Acquire driver.

Now, the camera should work.

Note
If you could not find the mvBlueFOX3 driver, you would add the current user to the plugdev group:
sudo usermod -a -G plugdev ubuntu 

For NVIDIA Jetson TX1/TX2 Users

To use the camera following modifications are necessary in the standard configuration of the NVIDIA Jetson TX1/TX2 board:

  1. Update the software to version 21.3. Please follow this descripion.
  2. Afterwards, you have to adapt the boot parameters in /boot/extlinux/extlinux.conf at the end of the "APPEND" line:
    1. Set "usbcore.autosuspend=-1" (power save mode is off now).
    2. Set "usbcore.usbfs_memory_mb=256" (this will increase the buffer of the USB bus)
    E.g.
    APPEND ${cbootargs} usbcore.autosuspend=-1 usbcore.usbfs_memory_mb=256 root=/dev/mmcblk0p1 
  3. Install the mvGenTL_Acquire driver.

Now, the camera should work.

Note
If you could not find the mvBlueFOX3 driver, you would add the current user to the plugdev group:
sudo usermod -a -G plugdev ubuntu 

Connecting the camera

After the driver installation you have to connect the mvBlueFOX3 using a USB 3 cable.

You can check connection by using tool mvDeviceConfigure. In the program's window, your camera should be listed:

Figure 6: Connected mvBlueFOX3

Afterwards, you can start wxPropView to configure the mvBlueFOX3.

Since driver version 2.11.3, starting wxPropView the first time, the Quick Setup Wizard , a tiny and powerful configuration tool, will be started.

Communicating with the camera

You can communicate with the camera the following way

  1. Via wxPropView :
    Since driver version 2.11.3, starting wxPropView the first time, the Quick Setup Wizard , a tiny and powerful configuration tool, will be started.

    If Quick Setup Wizard was disabled, wxPropView will start without wizard and you will see the serial number of the camera in the box "Serial No". After clicking "Use" the program connects to the camera. With "Acquire" you can see live images from the camera.

Setting up the camera

Besides wxPropView, there are further tools to set up the device:

With wxPropView it is possible to change e.g. the

  • image properties or
  • IP address.

mvDeviceConfigure is the program e.g.

For further information about the programs, please follow the link to the detailed description.

Settings behaviour 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. There is however an important difference in behaviour between different interface layouts. See here to find out how to modify the interface layout or check in the API documentation for the interfaceLayout property of the class Device. When working in DeviceSpecific interface layout, each frame will be captured with the settings as present when requesting the image. For GenICam interface layouts all device properties modified during a continuous acquisition will have immediate impact on the next frame transmitted by the device thus here when a precise moment to change settings is needed, continuous acquisition must be stopped and then restarted after modifying the features.

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

Figure 7 : 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). E.g. you have a device "VD000001" which belongs to the product group "VirtualDevice" with a setting exclusively for "VD000001". As soon as you store a product specific setting, the (device specific) setting for "VD000001" will be deleted. 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.

Relationship between driver, firmware, FPGA file and user settings

To operate a GenICam based device like mvBlueFOX3 apart from the physical hardware itself 2 pieces of software are needed:

  • A firmware running on the device. This firmware consists of
    • A GenICam compliant XML file exposing the features in a generic and standard compliant way
    • A FPGA file
    • The actual micro-code making the device operational
  • A device driver (this is the mvGenTLConsumer.dll and the mvGenTLProducer.cti on Windows and the libmvGenTLConsumer.so and the libmvGenTLProducer.so on Linux when using mvIMPACT Acquire, but can be any other USB3 Vision / GigE Vision compliant driver package from a third party vendor) running of the host system (provides control over the device from an application running on the host system).

The physical GenICam compliant device has a firmware programmed into the device's non-volatile memory, thus allowing the device to boot to a fully functional state without the need of any additional software running on the host. The firmware version that will be used when operating the device does NOT depend on the driver version that is used to communicate with the device. This will allow any piece of compliant third party software to operate the device without the need to have special knowledge about the firmware structure. This shall be illustrated by the following figure:

Figure 8 : The firmware is not a part of the device driver
Note
As it can be seen in the image the firmware file is NOT part of the device driver but comes as a separate archive. It is important to notice that a firmware file that may be present on the host system will not be used automatically but only when the user or an application explicitly updates the firmware on the device and will only become active after power-cycling the device.

The name of the firmware update archive (* in the figure above) is:

  • mvBlueFOX3_Update.mvu

Only during a firmware update the firmware file that has been selected from the file system of the host system will be downloaded permanently into the device's non-volatile memory.

Warning
Each firmware archive might contain more than one specific firmware version per device thus in order to select the one that is appropriate for the device appropriate tools such as mvDeviceConfigure should be used.

So assume a device with a certain firmware version is connected to a host system.

During an explicit firmware update, the firmware file will be downloaded onto the device. In order to become active the device must be power-cycled:

Figure 9 : Firmware file will be downloaded during an firmware update...

This can either be done by unplugging the device and then by plugging it back in or (for devices supporting this feature) by resetting/rebooting the device by a certain software command (DeviceControl/DeviceReset). When using mvDeviceConfigure to update devices the latter mechanism will be used by the tool thus it is NOT necessary to unplug the device.

When the device has completed rebooting the new firmware version will become active:

Figure 10 : ... after re-powering the device it will be active
  • The current firmware version of the device can be obtained either by using one of the applications which are part of the SDK such as mvDeviceConfigure or by reading the value of the property Device/FirmwareVersion or DeviceControl/DeviceFirmwareVersion using the API
  • The current FPGA file version used by the device can be obtained by reading the value of the property DeviceControl/mvDeviceFPGAVersion
Note
The FPGA file is a part of the firmware and cannot be updated independently thus reading it's version just provides some additional information.

Using wxPropView the same information is available as indicated by the following figure:

Figure 11 : wxPropView - FPGA and Firmware version numbers

Apart from the device driver and firmware relationship there are certain places where a device configuration can be stored when dealing with GenICam compliant devices:

  • There may be User Sets which are stored in the device's non-volatile memory. User Sets contain all the features, which affect the device's behaviour such as transfer pixel format, exposure time etc. User Sets are bound to major GenICam XML file releases, thus these settings will be lost whenever a firmware contains a different major version of a devices GenICam XML file
  • mvIMPACT Acquire settings which contain the state of all the features also stored in a User Set as well as other features added by the device driver. These settings will be stored on the host system either as a XML file or (on Windows only) in the Registry

Both methods can be used to pre-configure a device. Using the first method, the state of the features will travel with the physical device, using the mvIMPACT Acquire settings, feature states can be copied from host to host as a file.