MATRIX VISION mvBlueFOX USB 2.0 Camera - Linux Access Libraries
===============================================================

Version 1.7.1 (Release 45)	October 20th 2006

System Requirements
-------------------

Kernel requirements:

Kernel 2.6.x (prefered) 
- or -
Kernel 2.4.x.

usbfs support (CONFIG_USB_DEVICEFS) N.B. 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).

N.B.
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 toolchain.

[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 Testprograms.
Optional: udev or hotplug subsystem (see also 6. 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 definately 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. framerate of 3 to 4 fps 
@640x480 only).

N.B. We have noticed problems with some USB Chipsets. 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.

- a different PC.
- a plug-in PCI/USB-2.0 card without any cables between the card and the USB connector.
- turning off the image footer property - this will ignore data errors.

IMPORTANT
=========
This version only contains libraries for Linux x86 (32 bit) or Liux 64-bit (x86_64).
There are separate package files for systems with toolchains 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
toolchain is, the lass likely it is that it will work. 
Toolchains based on GNU gcc 2.x.x are not supported at all.

See the instructions below for advice on deciding which package you should install.

This version for Linux does not include hot-plugging support at the application level.
i.e. a running application will not be informed of new mvBlueFOX 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.

This version (32-bit only) will also run in a VMware (http://www.vmware.com) virtual machine!

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

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

If the version number is 2.x.x then you cannot use the mvBlueFOX on your 
computer. Consider upgrading to a newer distribution.
If the version number is 3.2.x or 3.3.x then you will need the 
package using the C++ ABI 1. This package has ABI1 in its name.
If the version number is 3.4.x or 4.x.x or greater then you will need the package using 
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.

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

tar xvzf mvbluefox-x86-ABI1-1.7.1.45.tgz

-or-

tar xvzf mvbluefox-x86--ABI2-1.7.1.45.tgz

N.B.
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.

------------------------

4. 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
drwxr-xr-x    4 root     root         4096 Jan  5 15:08 wxPropGrid


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 
"wxPropGrid" directory contains source code for a library used by one of the 
test applications. 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 "LiveSnap":

cd my_mvbf_directory
LD_LIBRARY_PATH=`pwd`/lib/x86 apps/LiveSnap/x86/LiveSnap

For 64-bit it will look like this...
LD_LIBRARY_PATH=`pwd`/lib/x86_64 apps/LiveSnap/x86_64/LiveSnap

For ARM it will look like this...
LD_LIBRARY_PATH=`pwd`/lib/arm apps/LiveSnap/arm/LiveSnap
etc.

After installing the libraries and headers you may continue with "5." 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 "6." below.
------------------------


5. To build the test applications type "make". This will first attempt to build 
the library in "wxPropGrid" and then 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 2.6.x development files (headers etc.) supplied for your 
distribution. (See "Other requirements" above).
- fetch, compile and install the wxWidget 2.6.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 (or wx-config-2.6). The files you may need to alter are to be found 
here:

wxPropGrid/Src/Makefile.inc
apps/mvPropViewMakefile.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/SingleSnap, apps/LiveSnap, etc.
------------------------


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

6.1 For udev (e.g. Gentoo*, OpenSuSE 10.x):
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:

#mvBlueFOX - make USB node accessible to all users in the usb group
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. 
== DO NOT FORGET TO ADD YOUR USER TO THE usb group! You may have to create the group first. ==

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.

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

* 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 than either
of the two alternatives described above may be tried.  The udev method is better because hotplug is
likely to be removed eventually. 

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.
N.B. This is considered a security risk by some experts.

Note: 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.  
------------------------


7. == Note about 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. 

== IMPORTANT ==
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.
== IMPORTANT ==
------------------------


8. Power Down Mode
To try out the new power down mode you will need to update the firmware on the mvBlueFOX to at least version 39.
There is a simple text-based utility to do this in "apps/FirmwareUpgrade". Just build the application and start on the
platform of your choice giving the serial number of the connected mvBlueFOX as a parameter. e.g. on an Embedded ARM system...

$ ./arm/FirmwareUpgrade BF000188

 ++ Start FirmwareUpgrade: Sep 28 2006/11:48:19
 Have found 1 devices on this platform!
  0 Serial: BF000188
  Initialising the device: BF000188. This might take some time...
  The firmware of device BF000188 is currently 37.
  It will now be updated. During this time(approx. 30 sec.) the application will not react. Please be patient.
  Successfully performed firmware update
  Update successful.
  Please disconnect and reconnect the device now to activate the new firmware.
  Press any key to end the application

To test the power down mode use the test application in "apps/PowerDownTest". Take a look at the source code to see which
function is used to switch on power down mode. Here is an example of the output for an Embedded ARM system...

$ ./arm/PowerDownTest BF000188

 ++ Start PowerDownTest sample: Sep 28 2006/11:48:43
 Have found 1 devices on this platform!
  0 Serial: BF000188
  Initialising the device: BF000188. This might take some time...
  Ready to snap. Press 'p'<return> to power down, 'q'<return> to quit or <return> to snap an image..

  Request Nr.: 0. Snap took 0.76s.,
  Will save the file as:  SingCapt.pgm
  Ready to snap. Press 'p'<return> to power down, 'q'<return> to quit or <return> to snap an image..

  Request Nr.: 1. Snap took 0.41s.,
  Will save the file as:  SingCapt.pgm
  Ready to snap. Press 'p'<return> to power down, 'q'<return> to quit or <return> to snap an image..

  Request Nr.: 2. Snap took 0.4s.,
  Will save the file as:  SingCapt.pgm
  Ready to snap. Press 'p'<return> to power down, 'q'<return> to quit or <return> to snap an image..
  p
  Power off!
  Ready to snap. Press 'p'<return> to power down, 'q'<return> to quit or <return> to snap an image..

  Power On!. Power On took 2.24s.,
  Request Nr.: 3. Snap took 0.58s.,
  Will save the file as:  SingCapt.pgm
  Ready to snap. Press 'p'<return> to power down, 'q'<return> to quit or <return> to snap an image..

  Request Nr.: 0. Snap took 0.39s.,
  Will save the file as:  SingCapt.pgm
  Ready to snap. Press 'p'<return> to power down, 'q'<return> to quit or <return> to snap an image..
  q
------------------------


9. Please refer to the mvBlueFOX handbook for information on programming with 
the mvIMPACT_Acquire API. If the handbook makes references to Windows DLLs 
please use the equivalent Linux dynamic libraries that have been installed on 
your system.
------------------------



-
MATRIX VISION GmbH
support@matrix-vision.de

