MATRIX VISION - mvBlueCOUGAR-X/-XD Technical Documentation
Quickstart

Table of Contents

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 successfully tested several network interface cards, which are summarized in the following document: http://www.matrix-vision.com/tl_files/mv11/support/Manuals/mvBlueCOUGAR-X_-_Recommended_NICs_en.pdf.

Additional hardware requirements for mvBlueCOUGAR-XD

The mvBlueCOUGAR-XD is a high-performance camera containing latest top-notch technology which requires

  • a high data throughput on the host system,

for example, when processing large amount of image data and

  • high CPU resources if processing color images on the host PC.

This means that you will need

  • the latest PC architectures, preferably multi core Intel CPUs and chipsets
  • sufficient RAM (4 GB in 32-bit OS; 8 GB in 64-bit OS), and
  • appropriate and recommended network cards with PCI-E x1 or x4 interface and with the latest "Link Aggregate Group" (LAG) capable drivers.

Please ask your system vendor for further advice and consult our technical documentation.

Beside the host system requirements, you have to fine-tune

  • the network settings,
  • the camera settings, and
  • the host system settings (e.g. disabling the sleep mode)

to achieve the specified frame rates possible from the camera's perspective.

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

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

Optimizing the network configuration

This chapter explains, how to achieve optimal performance by setting up the NIC (network interface card) and the devices network controller in the best possible way with respect to the limitations imposed by the surrounding network. To check, if the camera is available via the network, you can use the tool mvIPConfigure.

Attention
Only network experts should change settings in this section.

The camera sets the MTU to the maximum value automatically given by the NIC or switch and supports a maximum MTU of 16K. You can change the MTU of the camera manually under "Setting -> Base -> Camera -> GenICam -> Transport Layer Control -> Gev Stream Channel Selector -> Gev SCPS Packet Size".

In the system settings of the camera, you can set up the overall network behaviour of the device in the "Transport Layer Control" section e.g. by assigning a persistent IP address, a persistent default gateway and a persistent subnet mask in "Transport Layer Control" section according to your needs. However IP configuration related settings should be done by using the tool mvIPConfigure as this will provide a more convenient access to these parameters.

Network performance related parameters however can be controlled from the "Driver -> GenTL" section as well:

Figure 6: wxPropView - System settings

By default 1500 is used as MTU ("Driver -> GenTL -> Interfaces -> Interface0 -> mv Gev Interface MTU"). You can change this according to your network. As a general rule of thumb it can be said, that the higher the MTU, the better the overall performance, as less network packets are needed to transmit a full image, which results in less overhead that arises from the handling of each arriving network packet in the device driver etc. However every component involved in the data transmission (that includes every switch, router and other network component, that is installed in between the device and the system receiving the packets) must support the MTU or packet size, as otherwise the first component not supporting the packet size will silently discard all packets, that are larger than the component can handle.

Note
If you modify the interface MTU of the device, it will take up to 5 seconds until these settings are saved in the non-volatile memory. During this time do not remove the power supply! Afterwards you have to reboot the device for the changed settings to take effect.

Adjusting the network controller

If you have interplay problems between mvBlueCOUGAR and a network controller (NIC) please check following settings in the driver settings:

Note
There is no need to set the transfer packet size manually. Whenever the device is initialised, the driver will determine the maximum possible packet size for the current network settings automatically.
The screenshots below are examples for how a dialog for a feature described here might look like. Not every NIC/NIC driver will support every feature discussed here and different drivers might use different names for the features presented. The hints are just meant to give an idea for what to look for.
  1. Is the NIC a "1000MBit Full Duplex Controller" and is this mode activated (via properties of network settings)?
  2. Is the driver of the NIC up-to-date?
    Some manufacturers have optimized their drivers referring to higher data throughput.
  3. Is the "GigE Vision Capture driver" installed as described in Install GigE Vision capture filter ?
  4. Does the MTU of the NIC correspond the setting of the mvBlueCOUGAR?
    Using a peer-to-peer connection leads to a better performance and normally you can use values higher than 1500. Here, values between 4k and 12k make sense, whereas some network controllers only allow maximum of 9k which is enough for sensors up to 4 megapixels.

    Figure 7: Setting "Jumbo Packet" using an Intel PRO/1000 network interface

  5. Is the NIC parameter "Interrupt Moderation" switched on?

    Figure 8: Setting "Interrupt Moderation" using an Intel PRO/1000 network interface

  6. Some multi-port network cards might also offer to configure the number of "RSS (Receive Side Scaling) Queues". When dealing with high data rates, increasing the number of queues might also improve the overall stability of the system in terms of the possibility of packet losses etc.

    Figure 9: Setting "RSS Queues" using an Intel Ethernet Adapter I340-T4

  7. Is the amount of the "Receive Descriptors" (RxDesc) of the NIC set to the maximum (generally 2048)?
    This amount depends on the MTU. You can get a feeling about values with following formula:

    Note
    The formula is per camera and per network port.
    RxDesc >= 1.1 * PixelPerImg * BytesPerPixel
          ---------------------------------
                       MTU

    "Example 1: 1500 at 1.3MPixel" 

    RxDesc >= 1.1 * 1.3M * 1
          --------------
              1500
       >= 950

    "Example 2: 8k at 1.3MPixel" 

    RxDesc >= 1.1 * 1.3M * 1
          --------------
              8192
       >= 175
    Note

    Both examples are showing the RxDesc values based on packages per image per second. Now, if you increase the images per second you will see that you reach the amount of "Receive Descriptors" very soon. Usually, the default values of the system are between 64 and 256 and as a general rule too low. Also each use of a "Receive Descriptor" will result in a certain amount of CPU time needed, which is why larger packets result in a better overall performance.

    If you are using small MTU values or if there is only a small value of "Receive Descriptors" possible, you have to enable "Interrupt Throttling". Interrupt throttling enables the NIC to combine packets thus lowering the amount of interrupts.

    The "Receive Descriptors" a.k.a. "Receive Buffers" (Intel PRO/1000 network interface) can be found under "Performance Options":

    Figure 10: "Performance Options"
    Figure 11: Setting "Receive Buffers"

Additional network configuration for mvBlueCOUGAR-XD

The mvBlueCOUGAR-XD Dual-GigE camera needs a network interface card with two network interfaces which support so-called Link Aggregation, teaming, or "bonding". Normally, Windows installs a standard driver which does not support link aggregation. For this, you have to install and download a driver from the manufacturer's website. When e.g. using a "Intel Ethernet Server Adapter I350-T2" network controller this will be

See also
List of Intel network controllers supporting teaming with Windows 10: https://www.intel.com/content/www/us/en/support/articles/000020905/network-and-i-o/ethernet-products.html

After installation you have to combine the two interfaces which are used by the mvBlueCOUGAR-XD. For this, open the driver settings of the network controller via the "Device Manager" of Windows:

Link Aggregation / Teaming with Windows 7

  1. Open the tab "Teaming" and
  2. create a new team.

    Figure 12: Create an aggregation group

  3. Then enter a name for this group e.g. "mvBlueCOUGAR-XD" and
  4. click on "Next".

    Figure 13: Enter an aggregation group name

  5. Select the two interfaces which where used for the mvBlueCOUGAR-XD.

    Figure 14: Select the used interfaces

  6. Finally, select the connection type "Static Link Aggregation".

    Figure 15: Select the connection type

After closing the group assistant, you can connect the camera using the two network interfaces. There is no special connection necessary between camera and network controller interfaces.

It is also possible to use the camera with one network interface. This of course will result in a reduced data rate. For this use the right (primary) network interface of the camera only (the label on the back can be read normally).

Link Aggregation / Teaming with Windows 10

  1. Click Start (Windows Icon in the taskbar) and type in Powershell.
  2. Right-click the Powershell icon and choose "Run as Administrator".
  3. If you are prompted to allow the action by User Account Control, click Yes .
  4. Enter the command (e.g. for Intel NIC) 

    Import-Module -Name "C:\Program Files\Intel\Wired Networking\IntelNetCmdlets\IntelNetCmdlets"
  5. Afterwards, execute the command: 

    New-IntelNetTeam -TeamName "HDR Camera" -TeamMemberNames "Intel(R) Ethernet Server Adapter I350-T2","Intel(R) Ethernet Server Adapter I350-T2 #2" -TeamMode StaticLinkAggregation
    Replace "HDR Camera" with your preferred teaming name and also "Intel(R) Ethernet Server Adapter I350-T2" with the name of your used NIC.

Linux

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

System requirements

  • Kernel 3.5.x or greater

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

Additional hardware requirements for mvBlueCOUGAR-XD

The mvBlueCOUGAR-XD is a high-performance camera containing latest top-notch technology which requires

  • a high data throughput on the host system,

for example, when processing large amount of image data and

  • high CPU resources if processing color images on the host PC.

This means that you will need

  • the latest PC architectures, preferably multi core Intel CPUs and chipsets
  • sufficient RAM (4 GB in 32-bit OS; 8 GB in 64-bit OS), and
  • appropriate and recommended network cards with PCI-E x1 or x4 interface and with the latest "Link Aggregate Group" (LAG) capable drivers.

Please ask your system vendor for further advice and consult our technical documentation.

Beside the host system requirements, you have to fine-tune

  • the network settings,
  • the camera settings, and
  • the host system settings (e.g. disabling the sleep mode)

to achieve the specified frame rates possible from the camera's perspective.

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.

For more information and if you want to install only the mvBlueCOUGAR remote driver on Linux. Please have a look at Installing the mvBlueCOUGAR Remote Driver.

Optimizing the network configuration

This chapter explains, how to achieve optimal performance by setting up the NIC (network interface card) and the devices network controller in the best possible way with respect to the limitations imposed by the surrounding network. To check, if the camera is available via the network, you can use the tool mvIPConfigure.

Attention
Only network experts should change settings in this section.

The camera sets the MTU to the maximum value automatically given by the NIC or switch and supports a maximum MTU of 16K. You can change the MTU of the camera manually under "TransportLayer" -> "GevSCPSPacketSize".

In the system settings of the camera, you can set up the overall network behaviour of the device in the "TransportLayer" section e.g. by assigning a persistent IP address, a persistent default gateway and a persistent subnet mask in "TransportLayer" section according to your needs. However IP configuration related settings should be done by using the tool mvIPConfigure as this will provide a more convenient access to these parameters.

Network performance related parameters however can be controlled from the "TransportLayer" section as well:

Figure 16: wxPropView - System settings

By default 1500 is used as MTU ("DeviceInterfaceMTU"). You can change this according to your network. As a general rule of thumb it can be said, that the higher the MTU, the better the overall performance, as less network packets are needed to transmit a full image, which results in less overhead that arises from the handling of each arriving network packet in the device driver etc. However every component involved in the data transmission (that includes every switch, router and other network component, that is installed in between the device and the system receiving the packets) must support the MTU or packet size, as otherwise the first component not supporting the packet size will silently discard all packets, that are larger than the component can handle.

Note
If you modify the interface MTU of the device, it will take up to 5 seconds until these settings are saved in the non-volatile memory. During this time do not remove the power supply! Afterwards you have to reboot the device for the changed settings to take effect.

Adjusting the network controller

If you have interplay problems between mvBlueCOUGAR and a network controller (NIC) please check following settings in the driver settings:

Note
There is no need to set the transfer packet size manually. Whenever the device is initialised, the driver will determine the maximum possible packet size for the current network settings automatically.

  1. Is the amount of the "Receive Buffers" of the NIC set to the maximum? If you want to set the "Receive Buffers", you have to

    1. create a new file 62-buffers-performance.conf in "/etc/sysctl.d/" (/etc/sysctl.d/62-buffers-performance.conf) and
    2. add the following lines to this file: 
      net.core.wmem_max=16777216
net.core.rmem_max=16777216
net.core.netdev_max_backlog=10000
    3. Afterwards, reboot the system or enter "sudo sysctl -p".
    See also
    For more information about Linux network tuning, please have a look at http://www.cyberciti.biz/faq/linux-tcp-tuning/.

Additional network configuration for mvBlueCOUGAR-XD

The mvBlueCOUGAR-XD Dual-GigE camera needs a network interface card with two network interfaces which support so-called "Link Aggregation" or "bonding".

To bond the network interface, the following description assumes that your system has three interfaces eth0, eth1, and eth2,

  • eth0 is the standard system interface (e.g. connected to the Internet or intranet) and
  • the mvBlueCOUGAR-XD is connected to eth1 and eth2 (these interfaces will be bonded).

Furthermore, it is assumed that the

  • Class C subnet 192.168.10.1 is used for bonding, that the
  • receive buffers value was raised, and
  • Intel network interface controller (NIC) is used and the Intel e1000e Kernel module is available.
Note
If your system uses an active network manager, which assigns IP automatically, you should stop the network manager as follows:
sudo service network-manager stop

To bond the network interfaces, please follow these steps:

  1. Install the package ifenslave: 
    sudo apt-get install ifenslave
  2. Turn the network interfaces down, which you want to bond: 
    sudo ifconfig eth1 down 
sudo ifconfig eth2 down
  3. Afterwards, load the bonding Kernel module: 
    sudo modprobe bonding mode=0 miimon=100

    "mode=0" means "round robin" mode which corresponds to the "static link aggregation" on Windows systems
    "miimon=100" means that it will be checked every 100 ms if there are link failures in the bonding. 100 is the recommended value.
  4. Now you have to define the parameters of the bonding: 
    sudo ifconfig bond0 192.168.10.1 netmask 255.255.255.0 mtu 8000
  5. You have to link the physical network interface controllers to the bonding and turn them on: 
    sudo ifenslave bond0 eth1 eth2
sudo ifconfig eth1 up
sudo ifconfig eth2 up
  6. Finally, you have to restart the Linux networking services: 
    sudo /etc/init.d/networking restart

Now, you can check if you can ping the mvBlueCOUGAR-XD via the bonding.

Connecting the camera

To start the device please accomplish following steps:

  1. Connect the mvBlueCOUGAR with a
    • CAT5e/CAT6 Peer-to-Peer-cable to a network (e.g. a switch) or PC directly
      Note
      With mvBlueCOUGAR-XD you can either connect both LAN connectors (RJ 45) using Link Aggregation or one LAN connector, which requires to use the connector LAN 1 only.
  2. Power the mvBlueCOUGAR via power supply.
    The mvBlueCOUGAR will boot immediately.
Note
If you're using Power over Ethernet (PoE) connecting and powering are one step.
If both power possibilities are connected (local power supply and Power over Ethernet (PoE)), the camera will use the local power supply.
If you change from one supply to the other, the camera will reset and reboot.

After energizing mvBlueCOUGAR via power supply or Power over Ethernet (PoE) the camera will start to boot.

Depending on the configuration of the network or the mvBlueCOUGAR (more precisely: if DHCP is used or not), following IP addresses are assigned:

  • If the mvBlueCOUGAR is configured to use a static IP address, the mvBlueCOUGAR will use this one. In this case, the mvBlueCOUGAR will only be accessible, if the IP address is valid for the current network.
  • With DHCP, the mvBlueCOUGAR will get an IP address from the DHCP server (default setting).
  • Without DHCP, the mvBlueCOUGAR will start with a logical link address (LLA) / zero configuration class B IP address ("169.254.X.X", netmask 255.255.0.0).
Note
Please have a look at LLA in the Glossary when using Linux and LLA.
Warning
If you are using a static IP address, please be sure that this IP address
  • does exist
  • is not used by anyone else in the same network
  • is a valid one
Note
If you have two NICs in your PC, please be sure that they are using different subnets, otherwise the systems does not know which Ethernet interface is used to exchange the data. 
Working example:

 192.168.0.1: PC Port1
 172.16.1.1:  PC Port2
 192.168.0.3: Cam1
 172.16.1.4:  Cam2

You can change settings like the static IP address to your needs (please have a look at: mvIPConfigure).

Further the mvBlueCOUGAR starts the GigE Vision control server making the device actually discoverable using standard GigE Vision mechanism.

Figure 17: Boot sequence of mvBlueCOUGAR

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.
    Note
    The current IP address can be found in the "Device" properties under "DeviceIPAddress".

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.

With mvGigEConfigure it is possible to install the

  • GigE capture filter of the network controller.

With mvIPConfigure it is possible to configure the

  • network behavior of GigE devices.

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 18: 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 19: 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:

  • mvBlueCOUGAR-X_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 20: 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 21: ... 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 22: 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.