MATRIX VISION - mvBlueFOX Technical Documentation
Quickstart

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

Note
For Windows XP Embedded
As mvBlueFOX cameras will register as an 'imaging device' in the systems device manager please make sure that your Windows XP Embedded (XPe) distribution is shipped/build with support for the corresponding device class ("Class GUID {6bdd1fc6-810f-11d0-bec7-08002be2092f}") before installing the mvBlueFOX device driver. Otherwise, an installing of the driver when connecting a camera will fail with an error message like "a required section in the INF file could not be found". The camera will not be accessible then.

The mvBlueFOX is a USB 2.0 compliant camera device and needs therefore a functioning USB 2.0 port. If you are not sure about this, please follow these steps:

  1. Press "Start" and click on "Run"
  2. Enter
    msinfo32 
  3. Click on "Components" and look after "USB"
  4. If there is a entry like "USB 2.0 Root Hub" or "ROOT_HUB20", your system has USB 2.0.

Please be sure that your system has at least one free USB port.

Installing the mvIMPACT Acquire driver

Warning
Before connecting the mvBlueFOX, please install the software and driver first!

All necessary drivers are available from the MATRIX VISION website: https://www.matrix-vision.com "Products -> Hardware -> mvBlueFOX -> Downloads Tab".

By double clicking on "mvBlueFOX-x86-n.n.n.msi" (for 32-bit systems) or "mvBlueFOX-x86_64-n.n.n.msi" (for 64-bit systems), the mvBlueFOX installer will start automatically.

Figure 1: mvBlueFOX installer - Start window

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

Figure 2: mvBlueFOX installer - Select folder

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

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

Confirm the installation by clicking "Next".

Figure 4: mvBlueFOX installer - Confirm installation

The installation is finished now you can close the window.

Figure 5: mvBlueFOX installer - Finished installation

Installing the hardware

Warning
Before connecting the mvBlueFOX, please install the software and driver first!

It is not necessary to shutdown your system. On an USB port, it is possible to hot plug any USB device (hot plug lets you plug in new devices and use them immediately).

Warning
If using the Binder connector first connect the cable to the camera, then connect the camera to the PC.

Plug the mvBlueFOX to an USB 2.0 Port. After plugging the mvBlueFOX Windows® shows "Found New Hardware" and starts the Windows Hardware Wizard.

Figure 6: Windows - Found new hardware

The Wizard asks you for the driver. The installation doesn't need any Windows® automatic at this step and it is recommended to type the driver directory by hand. Choose "No, not this time" and press "Next".

Figure 7: Windows Hardware Wizard - Driver Installation

Choose "Install the software automatically" and press "Next".

Figure 8: Windows Hardware Wizard - Driver location

The Hardware Wizard installs the driver.

Figure 9: Windows Hardware Wizard - Driver location

The Hardware Wizard will search the registry for the device identification and after a while the Wizard prompts you to continue the installation or to abort it. Also Windows® will display the following message to inform the user that this driver digitally signed by Microsoft. You have to select 'Continue anyway' otherwise, the driver can't be installed. If you don't want to install a driver that is not signed you must stop the installation but can't work with the mvBlueFOX camera then.

Press "Continue Anyway" and finish the driver installation.

Figure 10: Windows Hardware Wizard - Windows logo testing

After the Windows® Logo testing, you have to click "Finish" to complete the installation.

Figure 11: Windows Hardware Wizard - Complete the installation

Now, you can find the installed mvBlueFOX in the Windows® "Device Manager" under image devices.

Figure 12: Windows Device Manager - Installed mvBlueFOX

After this installation, you can acquire images with the mvBlueFOX. Simply start the application wxPropView (wxPropView.exe) from

mvBlueFOX/bin. 
See also
wxPropView

Linux

System Requirements

Kernel requirements

Kernel 2.6.x .. Kernel 3.x.x.

  • usbfs support (CONFIG_USB_DEVICEFS)
    Note
    This is different from devfs! support. The USB device file system should, of course, be mounted at /proc/bus/usb.
  • SysV IPC support (CONFIG_SYSVIPC).
    Note
    Most distributions will have these kernel options turned on by default.

Software requirements

  • Linux x86 (32-bit)
    • The 32 bit version will run on a 64-bit Linux system if the other library requirements are met with 32-bit libraries. I.e. you cannot mix 64 and 32-bit libraries and applications.
    • Versions for Linux on x86-64 (64-bit), PowerPC, ARM or MIPS may be possible on request.
  • GNU compiler version GCC 3.2.x or greater and associated tool chain.
    Note
    Our own modified version of libusb has been statically linked to our library and is therefore included, so libusb is not a requirement.

Other requirements

  • libexpat (http://expat.sourceforge.net)
  • Optional: wxWidgets 2.6.x (non Unicode) for the wxWidget test programs.
  • Optional: udev or hotplug subsystem (see also 4. below).

As an example of which packets need to be installed, consider OpenSuSE 10.1:

  • The compiler used is gcc 4.1.0 and may need to be installed. Use the "gcc" und "gcc-c++" RPMs. Other RPMs may be installed automatically due to dependencies (e.g. make).
  • libexpat will almost definitely be installed already in any software configuration. The RPM is called "expat".
  • Install the wxWidgets "wxGTK" and "wxGTK-develop" RPMs. Others that will be automatically installed due to dependencies include "wxGTK-compat" and "wxGTK-gl". Although the MATRIX VISION software does not use the ODBC database API the SuSE version of wxWidgets has been compiled with ODBC support and the RPM does not contain a dependency to automatically install ODBC. For this reason you must also install the "unixODBC-devel" RPM.
  • OpenSuSE 10.1 uses the udev system so a separate hotplug installation is not needed.

Hardware requirements

USB 2.0 Host controller (Hi-Speed) or USB 1.1 Host controller will also work (with a max. frame rate of 3 to 4 fps at 640x480 only).

Note
We have noticed problems with some USB chip sets. At high data rates sometimes the image data appears to be corrupted. If you experience this you could try one or more of the following things.
  • Use a different PC.
  • Use a plug-in PCI/USB-2.0 card without any cables between the card and the USB connector.
  • Turn off the image footer property - this will ignore data errors.
  • Use an up-to-date firmware version.
Note
The driver contains libraries for Linux x86 (32 bit) or Linux 64-bit (x86_64). There are separate package files for systems with tool chains based on GNU gcc 3.2.x - 3.3.x and those based on GNU gcc >= 3.4.x. gcc 3.1.x may work but, in general, the older your tool chain is, the lass likely it is that it will work. Tool chains based on GNU gcc 2.x.x are not supported at all.
GCC 4.x (4.1.0) has been tested on OpenSuSE 10.1 and should work on other platforms.
This version (32-bit only) will also run in a VMware (http://www.vmware.com) virtual machine!

Installing the mvIMPACT Acquire driver

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

mvBlueFOX-x86_ABI2-n.n.n.tgz
  1. Please start a console and change into a directory e.g. /home/username/workspace
    cd /home/username/workspace
    
  2. Copy the install script (available as download from https://www.matrix-vision.com) and the hardware driver to the workspace directory (e.g. from a driver CD or from the website):
    ~/workspace$ cp /media/cdrom/drv/Linux/install_mvBlueFOX.sh /
     . && cp /media/cdrom/drv/Linux/mvBlueFOX-x86_ABI2-1.12.45.tgz -t ./
    
  3. Run the install script:

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

    You may need to enable the execute flag with

    chmod a+x install_mvBlueFOX.sh.
    

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

Note
The installation script ("install_mvBlueFOX.sh") and the archive ("mvBlueFOX-x86_ABI2-n.n.n.tgz") must reside in the same directory. Nothing is written to this directory during script execution, so no write access to the directory is needed in order to execute the script.

You need Internet access in case one or more of the packages on which the GenICam™ libs depend are not yet installed on your system. In this case, the script will install these packages, and for that, Internet access is required.

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

  1. target directory name
  2. version

The target directory name specifies where to place the driver. If the directory does not yet exist, it will be created. The path can be either absolute or relative; i.e. the name may but need not start with "/.".

Note
This directory is only used for the files that are run time required.

The files required at compile time are always installed in "$HOME/mvimpact-acquire-n.n.n". The script also creates a convenient softlink to this directory:

mvimpact-acquire -> mvIMPACT_acquire-1.12.45

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

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

You can now start wxPropView, after installing the hardware like

wxPropView

because the installer script added the needed symbolic links.

Note
If you want to install the mvBlueFOX Linux driver without installer script manually, please have a look at the following chapter:

Installing the mvIMPACT Acquire driver manually

Note
We recommend to use the installer script to install the mvBlueFOX driver.

The mvBlueFOX is controlled by a number of user-space libraries. It is not necessary to compile kernel modules for the mvBlueFOX.

  1. Logon to the PC as the "root" user or start a super user session with "su". Start a console with "root" privileges.
  2. Determine which package you need by issuing the following command in a terminal window:

    gcc -v
    

    This will display a lot of information about the GNU gcc compiler being used on your system. In case of the version number you have to do following:

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

  3. You can now install the mvBlueFOX libraries as follows:

    • create a new directory somewhere on your system.
    • copy the correct mvbluefox package file to this directory and change into this directory with "cd".

    The mvBlueFOX libraries are supplied as a "tgz" archive with the extension ".tgz". The older "autopackage" format is now deprecated since it cannot handle 64-bit libraries.

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

      tar xvzf mvBlueFOX-x86_ABI2-1.12.45.tgz
      
      Note
      Current versions of the ABI1 libraries were compiled using a SuSE 8.1 system for maximum compatibility with older Linux distributions. These libraries should work with all SuSE 8.x and SuSE 9.x versions as well as with Debian Sarge and older Red Hat / Fedora variants.
      Current versions of the ABI2 libraries were compiled using a SuSE 10.1 system for maximum compatibility with newer Linux distributions. These libraries should work with SuSE 10.x as well as with Ubuntu 6.06 or newer, with up-to-date Gentoo or Fedora FC5.
    2. After installing the mvBlueFOX access libraries you will see something like the following directory structure in your directory (dates and file sizes will differ from the list below):

      drwxr-xr-x   10 root     root         4096 Jan  5 15:08 .
      drwxr-xr-x   23 root     root         4096 Jan  4 16:33 ..
      drwxr-xr-x    3 root     root         4096 Jan  5 15:08 DriverBase
      -rw-r--r--    1 root     root         1079 Jan  5 15:08 Makefile
      drwxr-xr-x    7 root     root         4096 Jan  5 15:08 apps
      drwxr-xr-x    4 root     root         4096 Jan  5 15:08 common
      drwxr-xr-x    3 root     root         4096 Jan  5 15:08 lib
      drwxr-xr-x    3 root     root         4096 Jan  5 15:08 mvDeviceManager
      drwxr-xr-x    2 root     root         4096 Jan  5 15:08 mvIMPACT_CPP
      drwxr-xr-x    3 root     root         4096 Jan  5 15:08 mvPropHandling
      drwxr-xr-x    1 root     root         4096 Jan  5 15:08 scripts
      

      The directory "lib/x86" contains the pre-compiled 32-bit libraries for accessing the mvBlueFOX. If 64-bit libraries are supplied, they will be found in "lib/x86_64". The "apps" directory contains test applications (source code). The other directories contain headers needed to write applications for the mvBlueFOX.

      Since the libraries are not installed to a directory known to the system i.e. not in the "ldconfig" cache you will need to tell the system where to find them by...

      • using the "LD_LIBRARY_PATH" environment variable,
      • or copying the libraries by hand to a system directory like "/usr/lib" (or using some symbolic links),
      • or entering the directory in "/etc/ld.so.conf" and running "ldconfig".

      e.g. to start the application called "SingleCapture":

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

      etc.

      After installing the libraries and headers you may continue with "3." below as a normal user i.e. you do not need to be "root" in order to compile the test applications. See also the note "4." below.

    3. To build the test applications type "make". This will attempt to build all the test applications contained in "apps". If you have problems compiling the wxWidget library or application you may need to do one or more of the following:

      • install the wxWidget 3.x development files (headers etc.) supplied for your distribution. (See "Other requirements" above).
      • fetch, compile and install the wxWidget 3.x packet from source downloaded from the website (http://www.wxwidgets.org).
      • alter the Makefiles so as to find the wxWidget configuration script called wx-config.

      The files you may need to alter are to be found here:

      apps/mvPropView/Makefile.inc
      

      You will find the compiled test programs in the subdirectories "apps/.../x86". For 64 bit systems it will be "apps/.../x86_64". For ARM systems it will be "apps/.../arm".

      If you cannot build the wxWidget test program you should, at least, be able to compile the text-based test programs in apps/SingleCapture, apps/SingleCapture, etc.

    4. It may be possible to run applications as a non-root user on your system if you are using the udev system or a fairly recent version of hotplug.

For udev (e.g. Gentoo*, OpenSuSE 10.0 - 10.1)

Add the following 2 rules to one of the files in the directory "/etc/udev/rules.d" or make a new file in this directory (e.g. "/etc/udev/rules.d/20-mvbf.rules") containing the lines below:

ENV{UDEVD_EVENT}=="1", ACTION=="add", BUS=="usb", ENV{PRODUCT}=="164c/101/0", /
RUN+="/bin/sh -c 'chmod 0664 $env{DEVICE}; chgrp usb $env{DEVICE}'"
ENV{UDEVD_EVENT}=="1", ACTION=="add", BUS=="usb", ENV{PRODUCT}=="164c/103/0", /
RUN+="/bin/sh -c 'chmod 0664 $env{DEVICE}; chgrp usb $env{DEVICE}'"

You will find an example file "20-mvbf.rules" in the scripts directory after installation.

Note
Do not forget to add your user to the usb group! You may have to create the group first.

Current Gentoo systems support udev with a minimal, legacy hotplug system. It is usually sufficient to add any usernames that are to be used for the mvBlueFOX to the group "usb" because there is already a udev rule giving write permission to all USB devices to members of this group. If this does not work then try the other alternatives described here. The udev method is better because hotplug is likely to be removed eventually.

For udev (OpenSuSE 10.2 - 10.x)

In "/etc/fstab" in the line starting with usbfs change noauto to defaults

Afterwards either restart the system or execute "mount -a"

In "/etc/udev/rules.d/50-udev-default.rules" (or similar) change the line after a comment regarding libusb. Change 'MODE="0644"' in 'MODE="0664", GROUP="users"'

Connect the camera to the system now or re-connect it if it has been connected already

In case the environment variable USB_DEVFS_PATH is not set, it needs to be set to "/dev/bus/usb" ('export USB_DEVFS_PATH="/dev/bus/usb"'.

For udev on Ubuntu 06.10

Edit the file /etc/udev/rules.d/40-permissions.rules. Search for the entry for usbfs. It should look like this:

# USB devices (usbfs replacement)
SUBSYSTEM="usb_device" MODE="0664" 

Now change it to read like this:

# USB devices (usbfs replacement)
SUBSYSTEM="usb_device" GROUP="plugdev", MODE="0664"

udev on some other systems

Some very up-to-date systems also set the environment variable $USB_DEVFS_PATH to point to "/dev/bus/usb" instead of the older (default) value of "/proc/bus/usb". This may cause the mvBlueFOX libraries to attempt to access device nodes in "dev/bus/usb" but the rules described above will not change the permissions on these files. Normally you will find a rule in "/etc/udev/rules.d/50-udev.rules" which will already cure this problem. You might like to slightly modify this rule to give write permission to a specific group e.g. the group "usb". A patch is supplied in the scripts directory to do this.

Alternatively, for a system with full hotplugging (e.g. older SuSE systems)

Copy the files named below from the scripts directory into the directory "/etc/hotplug/usb":

matrixvision.usermap
matrixvision_config

The file "matrixvision.usermap" contains the vendor and product IDs for the mvBlueFOX cameras and specifies that the script "matrixvision_config" should be run when a MATRIX VISION mvBluefOX camera is plugged in or out. This script attempts to write some information to the system log and then changes the permissions for the newly-created device node so that non-root users can access the camera.

This feature has not yet been extensively tested. If you find that the applications start but appear to hang or to wait for a long time before continuing (and normally crashing) then changing the file permissions on your system does not appear to be sufficient. We have observed this on a 32 bit SuSE 9.1 system. In this case you may have more success if you change the owner of the application to "root" and set the suid bit to allow it to run with "root" permissions.

Note
This is considered a security risk by some experts.
If you have been using the mvBlueFOX with one user (e.g. root) and want to try it as another user you should remove the complete directory "/tmp/mv/", which may contain several files of zero length. These files are used to control mutexes within the software and will be owned by the first user. The new user will probably not be able to write to these files and the mvBlueFOX will not work.

Using CMOS versions of the mvBlueFOX and mvBlueFOX-M especially with USB 1.1

Version 1.4.5 contains initial support for CMOS mvBlueFOX on USB 1.1 . In order to conform to the rigid timing specifications of the CMOS sensor, onboard RAM is used. This RAM is available only on mvBlueFOX-M boards at the moment. Therefore you cannot use the mvBlueFOX-102x with USB 1.1 . It will work with USB 2.0.

Note
If you want to capture continuous live images from mvBlueFOX-102 or mvBlueFOX-M102x you should switch the trigger mode from "Continuous" to "OnDemand" for best reliable results. For single snaps the default values should work correctly.

Installing the hardware

Warning
If using the Binder connector first connect the cable to the camera, then connect the camera to the PC.

The driver for Linux does not include hot-plugging support at the application level. I.e. a running application will not be informed of new mvBlueFOX2 devices that have been plugged in and will probably crash if an mvBlueFOX camera is unplugged whilst it is being used. You need to stop the application, plug in the new camera and then restart the application. This will change in a later version.

Relationship between driver, firmware and FPGA file

To operate a mvBlueFOX device apart from the physical hardware itself 3 pieces of software are needed:

  • a firmware running on the device (provides low-level functionality like allowing the device to act as a USB device, support for multiple power states etc.)
  • an FPGA file loaded into the FPGA inside the device (provides access features to control the behaviour of the image sensor, the digital I/Os etc.)
  • a device driver (this is the mvBlueFOX.dll on Windows® and the libmvBlueFOX.so on Linux) running on the host system (provides control over the device from an application running on the host system)

The physical mvBlueFOX device has a firmware programmed into the device's non-volatile memory, thus allowing the device to act as a USB device by just connecting the device to a free USB port. So 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.

On the contrary the FPGA file version that will be used will be downloaded in volatile memory (RAM) when accessing the device through the device driver thus the API. One or more FPGA files are a binary part of the device driver. This shall be illustrated by the following figure:

Figure 13: The firmware file is a binary part of the device driver
Note
As it can be seen in the image one or multiple firmware files are also a binary part of the device driver. However it is important to notice that this firmware file 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. Since mvIMPACT Acquire version 2.28.0 every firmware starting from version 49 is available within a single driver library and can be selected for updating! mvDeviceConfigure however will always update the device firmware to the latest version. If you need to downgrade the firmware for any reason please get into contact with the MATRIX VISION support to get detailed instructions on how to do that.

FPGA

Until the device gets initialized using the API no FPGA file is loaded in the FPGA on the device. Only by opening the device through the API the FPGA file gets downloaded and only then the device will be fully operational:

Figure 14: The FPGA file gets downloaded when the device will be opened through the API

As the FPGA file will be stored in RAM, disconnecting or closing the device will cause the FPGA file to be lost. The firmware however will remain:

Figure 15: The FPGA file will be lost if the device is disconnected or closed

In case multiple FPGA files are available for a certain device the FPGA file that shall be downloaded can be selected by an application by changing the value of the property Device/CustomFPGAFileSelector. However the value of this property is only evaluated when the device is either initialized using the corresponding API function OR if a device has been unplugged or power-cycled while the driver connection remains open and the device is then plugged back in.

Note
There is just a limited set of devices that offer more than one FPGA file and these additional FPGA files serve very special purposes so in almost every situation the default FPGA file will be the one used by an application. Before using custom FPGA files, please check with MATRIX VISION about why and if this makes sense for your application.

So assuming the value of the property Device/CustomFPGAFileSelector has been modified while the device has been unplugged, a different FPGA file will be downloaded once the device is plugged back into the host system:

Figure 16: A different FPGA file can be downloaded

Firmware

Only during a firmware update the firmware file that is a binary part of the device driver will be downloaded permanently into the device's non-volatile memory.

Warning
Until mvIMPACT Acquire 2.27.0 each device driver just contained one specific firmware version thus once a device's firmware has been updated using a specific device driver the only way to change the firmware version will be using another device driver version for upgrading/downgrading the firmware again. Since mvIMPACT Acquire version 2.28.0 every firmware starting from version 49 is available within a single driver library and can be selected for updating! mvDeviceConfigure however will always update the device firmware to the latest version. If you need to downgrade the firmware for any reason please get into contact with the MATRIX VISION support to get detailed instructions on how to do that.

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

Figure 17: A certain firmware version is connected to a host system

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

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

When then re-attaching the device to the host system, the new firmware version will become active:

Figure 19: ... after repowering 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 Info/FirmwareVersion using the API
  • The current FPGA file version used by the device can be obtained by reading the value of the property Info/Camera/SensorFPGAVersion

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

Figure 20: wxPropView - FPGA and Firmware version numbers

Settings behaviour during startup

A setting contains 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 analogue to digital conversion process for analogue video sources or
  • the AOI to be captured from the incoming image data.

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

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

Figure 21: 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.