#########################################################
IDS - Imaging Development Systems GmbH
uEye Driver installation
#########################################################
2004 - 2007, Imaging Development Systems GmbH
------------------
SUMMARY
------------------
1 - REQUIREMENTS
2 - INSTALLED FILE STRUCTURE
3 - QUICK START (FOR ADVANCED USERS)
4 - DETAILED INSTALLATION
5 - THE DEMONSTRATION PROGRAM
6 - EVENT HANDLING UNDER LINUX
7 - CURRENT API STATUS
8 - UEYE LINUX DRIVER FAQ
9 - COMPATIBILITY LIST
1 - REQUIREMENTS
----------------
SOFTWARE REQUIREMENTS
- 2.6.xx LINUX kernel (min. 2.6.9)
- libc/glibc, the standard C Library (min. v2)
- gcc, the GNU Compiler Collection (min. v3.4)
- POSIX threads library (POSIX threads enabled libc)
- bash (Bourne again shell) or sh to run the script
- QT and KDE (including sources) for the demo program
HARDWARE REQUIREMENTS
- USB 2.0 support for the kernel
- a connected uEye camera
OTHER REQUIREMENTS
- You will need ROOT rights in order to install, and load
the kernel module. You will also need these rights in
order to modify system wide scripts to automatically
load the kernel module on startup and specify the shared
library location in /etc/ld.so.conf.
- You must copy the files on a read/write enabled support.
For example, into /usr/local/src. The install scripts
needs a writable place to compile the driver.
The requirements are also automatically checked by the
install script, when the installation process is started.
NOTE 1:
Compiling the kernel driver is needed because the Linux
kernel does not provide a binary driver interface. Different
dependencies (compiler version and kernel version) do not
allow to distribute a binary driver that can be loaded by
all Linux kernels.
NOTE 2:
The compiler used to compile the kernel module has to be of
the same version as the compiler that has been used to
compile the running kernel.
If you installed a new compiler and removed the old one,
then you certainly will have to recompile the kernel before
installing the uEye driver.
2 - INSTALLED FILE STRUCTURE
----------------------------
The created files will be installed in following directories:
/lib/modules/.../kernel/media/video/ueye_usb-driver.ko The Linux kernel module
/usr/lib/libueye_api.so The uEye shared library
/usr/src/ids/uEye/ sources for the demo program
/usr/include/uEye.h The development header file
/usr/share/doc/uEye/ PATH to the documentation files
3 - QUICK START (FOR ADVANCED USERS)
------------------------------------
1 - copy all the files in a directory on the hard disk
(you need write access to it in order to decompress
and compile the driver)
2 - go to the directory you copied the files into and
run the setup program script by typing
$> sh ./ueye-setup*.run
3 - if any problems occurred, the common problems section
below or the generated report.log file may include a
hint to solve them.
If not contact your local distributors support and
submit the report.log file (in the uEye setup
directory).
4 - If you are not using hotplug modify the start scripts
to load the kernel module automatically (insmod
ueye_usb-driver.ko) on startup.
You may also have to modify your udev config if used.
Eventually you will also need to setup the path to
the header file and the path to the shared library.
4 - DETAILED INSTALLATION
-------------------------
1 - copy all the files in a directory on the hard disk
(you need write access to it in order to decompress
and compile the driver) for example into /usr/local/src.
2 - If you are in a graphical environment, open a console by
using the appropriate menus.
3 - Get the superuser rights by typing: (you will of course
also need the password)
$> su --login
4 - Change to the directory where you copied the files into:
$> cd /usr/local/src
5 - Run the setup program script by typing:
$> sh ./ueye-setup*.run
6 - Now the installation starts. Respond to the questions
that may appear on the screen. The installation process
may take some time. At the end, you will be informed if
the installation was successful or not.
7 - If the installation was unsuccessful, have a look to the
generated report.log file /usr/local/src/report.log as
well as the faqs section in this document, which may help
you solving the problem.
If you dont succeed please send the log file to your local
distributor or the ids support (support@ids-imaging.de).
8 - If the installation was successful, then you may want to
change your start scripts to automatically load the kernel
module on startup. Refer to the documentation coming with
your LINUX distribution in order to make this change.
"insmod ueye_usb-driver.ko" -> loads the kernel module into the kernel
"rmmod ueye_usb-driver.ko" -> removes the kernel module from the kernel
"lsmod" -> dumps a list of all modules currently loaded
5 - THE DEMONSTRATION PROGRAM
-----------------------------
The demonstration program is there to show how to use the API in
order to make following actions:
- Board detection and initialization
- Setup memory for capturing
- Setup the camera video mode
- Modify the image parameters
- Making snapshots
- Making snapshots using the optional MemoryBoard
- Using Events
- Display the video in a QT based application
6 - EVENT HANDLING UNDER LINUX
------------------------------
Events currently not supported:
IS_SET_EVENT_DEVICE_RECONNECTED
IS_SET_EVENT_REMOVE
Event functions are using internal conditional variables under Linux.
To use a event it must be first enabled using the EnableEvent.
To wait for an event is_WaitEvent is added, which doesn't exist under
Windows OS.
InitEvent resets while ExitEvent signals a given event, this can be used for manual
setting and reseting an event.
e.g.:
is_EnableEvent (hCam, IS_SET_EVENT_FRAME); // enable frame event
is_InitEvent (hCam, IS_SET_EVENT_FRAME); // reset the frame event
is_FreezeVideo (hCam, IS_DONT_WAIT); // start a capture with don't wait
is_WaitEvent (hCam, IS_SET_EVENT_FRAME, 1000); // wait for a new frame with timeout of 1000ms
7 - CURRENT API STATUS
----------------------
The current api version shipped with this setup package is 2.40.0003.
The functional range is described in the sdk documentation and is much the same as in
windows version with folowing exceptions:
7.1 - Functions currently not available for linux
-------------------------------------------------
There are a few functions (mainly gui related ones) that are not accessible in the linux
version of this uEye sdk release.
Api functions not implemented in this version:
User Interface: (currently not supported)
---------------
IDSEXP is_RenderBitmap (HIDS hf, INT nMemID, HWND hwnd, INT nMode);
IDSEXP is_GetDC (HIDS hf, HDC* phDC);
IDSEXP is_ReleaseDC (HIDS hf, HDC hDC);
IDSEXP is_UpdateDisplay (HIDS hf);
IDSEXP is_SetDisplayMode (HIDS hf, INT Mode);
IDSEXP is_SetDisplaySize (HIDS hf, INT x, INT y);
IDSEXP is_SetDisplayPos (HIDS hf, INT x, INT y);
IDSEXP is_SetHwnd (HIDS hf, HWND hwnd);
IDSEXP is_SetParentHwnd (HIDS hf, HWND hwnd);
IDSEXP is_SetUpdateMode (HIDS hf, INT mode);
IDSEXP is_GetColorDepth (HIDS hf, INT* pnCol, INT* pnColMode);
IDSEXP is_LoadParameters (HIDS hf, char* fileName);
IDSEXP is_SaveParameters (HIDS hf, char* fileName);
DirectDraw: (not supported)
8 - UEYE LINUX DRIVER FAQ
-------------------------
8.1 Compiling the kernel module
-------------------------------
Q: Installation aborts whith failure "*** No rule to make target `modules'. Stop."
A: You need the headers of the installed kernel in order to compile the kernel driver module.
Install the kernel headers and try again.
8.2 Loading the kernel module
-----------------------------
Q: Using FC5 Linux, insmod as well as modprobe failes with error "unknown symbol".
A: There is a known issue in the FC5 2054 kernel, which prevents loading nongpl drivers.
Please update your kernel to a build newer than 2054.
Q: Using FC6 Linux, loading the module failed because of mismatching version magic.
A: The FC6 installer may have installed the i586 kernel on i686 hardware in error.
Replace this kernel with the i686 version: yum remove kernel-'uname -r'.i586
yum install kernel-'uname -r'.i686
yum install kernel-devel-'uname -r'.i686
Q: When loading the module several warnings are sysloged, like "Symbol usb_register_driver
is being used by a non-GPL module, which will not be allowed in the future".
A: With kernel 2.6.17, the use of some usb core functions was scheduled to be exclusivly
allowed for drivers under GPL licence. Unfortunatly our driver is closed source and
therefore non-GPL (which is claimed by MODULE_LICENSE() macro in uEye_usb.c). Unless
we cant change this without make it open source, please use a kernel allowing access
to these symbols (like prior 2.6.17 ones does).
8.3 Camera PnP
--------------
Q: Great, I've succeeded in compiling and loading the kernel module at last, but as soon as I
plug in a uEye camera, I get a kernel 'Oops'. The EIP points to "uEye_HandleStartDevice".
A: Take a look back to the report.log file created during installation. If you find an entry
saying "Warning: Could not retrieve CONFIG_REGPARM settings!" the installation program may
have linked the wrong object file! The installation program tries to determine the current
kernel configuration by looking to a "config-'uname -r'" file in your "/boot" directory or
alternatively for a ".config" or "config.gz" file in your kernel source directory
(/usr/src/'uname-r' or /usr/src/kernels/'uname -r' for fedora).
Please ensure one of this files exist (maybe you have to call 'make cloneconfig'), in the
specified directory (place a symlink if necessary).
Q: Ok, all things are working fine, but there is still an error message from the driver. It says
"probe of x-x:x.x failed with error" at syslog level, every time a camera is plugged in.
A: Dont worry. We are using a two stage initialisation process. Failing the probe function causes
the usb subsystem to recall our driver at second stage.
8.4 Camera operation
--------------------
Q: The LED on the camera flashes green and a call to is_GetNumberOfCameras or is_GetCameraList
returns a value greater than zero. But when I try to open a camera is_InitCamera returns
IS_ALL_DEVICES_BUSY (Code: 120).
A: Most likely the device file nodes, named "/dev/uEye_usb0" to "/dev/uEye_usb'X'", are missing
or the rights for them are misset. During installation these files are created with a call to
mknod. If you are using udev they will be gone after reboot. In this case the directory
"/etc/udev/rules.d" should contain a file that provides a rule to create the correct device
nodes.
9 - COMPATIBILITY LIST
----------------------
The Linux operation system is one of the most widely ported, running on a wide range of architectures
and provided over many distributions.
Although we are trying to be compatible among the whole range of kernel versions and distributions
there is no guarantee that the uEye driver is working on a specific untested combination.
Below there's a list of tested and succeeded platforms and distributions:
Distribution Kernel Architecture /Processor uEye driver
/etc/<distr>-release 'uname -r' 'uname -i' / 'uname -m' (/proc/cpuinfo)
Ubuntu 7.04 2.6.20-15-386 unknown / i686 (Intel Pentium 4 2.80GHz) 2.40.03.5
Knoppix 5.2 2.6.19.5 unknown / i686 (Intel Pentium 4 2.80GHz) 2.40.03.5
Fedora Core release 6 2.6.19-1.2895.fc6 i386 / i686 (Intel Pentium 4 2.80GHz) 2.40.03.5
Fedora Core release 6 2.6.18-1.2798.fc6 i386 / i686 (Intel Pentium 4 2.80GHz) 2.40.03.5
openSUSE 10.2 (i586) 2.6.18.8-0.1-default i386 / i686 (Intel Celeron 2.00GHz) 2.40.03.5
Ubuntu 6.10 2.6.17-11-386 i386 / i686 (Intel Pentium 4 2.80GHz) 2.21.02.4
Fedora Core release 5 2.6.17-1.2174_FC5 i386 / i686 (Intel Pentium 4 2.80GHz) 2.21.02.4
SUSE LINUX 10.1 (i586) 2.6.16.27-0.6-default i386 / i686 (Intel Pentium 4 2.80GHz) 2.21.02.2
Ubuntu 6.06.1 LTS 2.6.15-27-k7 unknown / i686 (AMD Athlon XP 1800+) 2.21.02.2
Ubuntu 6.06.1 LTS 2.6.15-26-386 unknown / i686 (Intel Pentium 4 2.80GHz) 2.21.02.2
SUSE LINUX 10.0 (i586) 2.6.13-15.11-default i386 / i686 (Intel Celeron 2.00GHz) 2.40.03.1
The uEye driver could also be ported to other platforms than the common x86 PC. If you want to use the
uEye on such a system, please ask for a special version.
Till now we succeed in porting to following systems:
ADS Debian 2.6.17.9-ep93xx-pxa-ads1 arm / arm (Cirrus EP9315) 2.21.02.arm
DENX ELDK 4.0 2.6.15 ppc / ppc (G2_LE) 2.21.02.ppc
Download Driver Pack
After your driver has been downloaded, follow these simple steps to install it.
Expand the archive file (if the download file is in zip or rar format).
If the expanded file has an .exe extension, double click it and follow the installation instructions.
Otherwise, open Device Manager by right-clicking the Start menu and selecting Device Manager.
Find the device and model you want to update in the device list.
Double-click on it to open the Properties dialog box.
From the Properties dialog box, select the Driver tab.
Click the Update Driver button, then follow the instructions.
Very important: You must reboot your system to ensure that any driver updates have taken effect.
For more help, visit our Driver Support section for step-by-step videos on how to install drivers for every file type.