LINUX STV0680 USB SUPPORT


 
 

CONTENTS

  INTRODUCTION

  HISTORY & WHAT'S NEW

  NOTES

  DOWNLOAD

  THANKS

INTRODUCTION

    This site contains Linux programs which support the usb interface version of STV0680B chip based
cameras.  This chip (made by STMicroelectronics) comes in two versions: -001 and -003. The -003 version
offers the ability to record sounds, but is otherwise compatible with the -001 version.  Cameras based on
this chip include the Aiptek Pencam and the Nisis Quickpix 2.  The Vendor/Product ID is 0553/0202.  The
chip supports both 8 MB and 2 MB of memory.  With 8 MB, you can take 26 high res (VGA 640x480) or 107
low res (320x240) pictures.  The usb version also features a video interface, to act as a video or web cam.

NOTE: The chip supports both serial and usb interface versions.  Support for the serial version may be found
           at http://stv0680.sourceforge.net.  This program supports only the usb version.

    Currently, this support consists of several programs: PENCAM2, which combines a simple command line
program to download images (originally written by Bart Hartgers <bart@etpmod.phys.tue.nl>, and added to
by me (Kevin Sisson <kjsisson@bellsouth.net>)), and a program to automatically snap a picture and down-
load it to disk at regular intervals; and STV680, which makes a loadable module for video (webcam) support
for programs like gqcam and xawtv.  For the 2.4 kernels and above, the stv680.o module is part of the kernel
tree.  Pencam2 images are saved in the .ppm format, and can be enhanced with any image processing program
that understands this format (I use the GIMP).

    To run pencam2 you will need kernel usb support and usbdevfs support (any of the 2.4.x series should
work; the 2.2.x series may work if they have the necessary usb support).  You will also need the libusb
package to compile and run the program; the header files were included in the tarball package I downloaded
from the Internet.  If you use one of the Linux distributions (a rpm or deb package), you will probably also
need the libusb-devel package.  I have compiled the program with various versions, from libusb-0.1.3b to
libusb-0.16, and kernel versions 2.4.3 to 2.4.18.  NOTE: I strongly recommend you use the latest version of
libusb; for multiple camera support, version 0.16 or higher is necessary.

    The stv680 video driver is now part of the kernel tree, beginning with the later versions of 2.4.17, or 2.4.18,
depending upon where you got your kernel modules from.  I mantain a tarball for those people (like
me) who do not run the latest kernel.  This should work with 2.4.7 and up, and possibly back to 2.4.3 if you
make a few modifications.  If you have the code in your kernel source code or modules library, use that.  The
video driver will not work with the 2.2 kernel series.

    If you find these programs useful, you might drop Bart Hartgers a line thanking him, since he wrote the
original code that downloads the still pictures.
 
 

HISTORY & WHAT'S NEW


March 10, 2003.    I posted version 0.67 of pencam2 some time ago at the Sourceforge projects
                              page (see link below) but did not post a message here.  This version has an
                              'erase-all-pictures' function, and some support for multiple cameras.  Some
                              time soon I am going to start work on a simple GUI interface for pencam2.  I
                              am changing the downloads link to point to the Sourceforge project page, so
                              I don't have to maintain several copies of the files.  You should use the most
                              recent version of libusb (0.17 I believe, but 0.16 works) if you plan to use
                              multiple cameras.

May 30, 2002.       It seems there are several problems people have been encountering
                             recently, one old and one new.  The old problem is that of getting "cannot
                             claim interface" errors when trying to run pencam or pencam2.  This happens
                             when the stv680 driver is loaded.   YOU MUST REMOVE THE STV DRIVER
                             BEFORE TRYING TO RUN PENCAM.  The new problem is that pencam2
                             segfaults immediatley after starting.  I have seen this problem with Mandrake 8.2,
                             and the solution seems to be to recompile libusb and then pencam, and then it
                             works.  BTW, I recommend using libusb version 0.15 (or 0.1.5), which may not
                             be available yet as an RPM package.  I plan to release a new version of pencam2
                             soon, with some multiple camera support; this will require libusb version 0.16,
                             which has not yet been released but should be Real Soon Now.

                             Also, for those of you having performance problems with uhci controllers, there is
                             something you can do to improve performance, but it involves recompiling the
                             usb-uhci.o module.  The procedure is due to James McKenzie
                             <james@fishsoup.dhs.org>.  You will need the kernel sources for your kernel version,
                             plus all necessary support packages (figuring out whether you have everything is
                             YOUR problem).

                              1.  In the /usr/src/linux-<kernel number>/drivers/usb/usb-uhci.c file,  near the top,
                                   change #define CONFIG_USB_UHCI_HIGH_BANDWIDTH to
                                   #undef CONFIG_.....
                                   and a little bit further down, change both
                                   #define USE_CTRL_DEPTH_FIRST    and
                                   #define USE_BULK_DEPTH_FIRST
                                   from 0 to 1.  It might not hurt to make a copy of usb-uhci.c first, as well as
                                   the /lib/modules/<kernel version>/kernel/drivers/usb/usb-uhci.o.gz original
                                   module.

                              2.  Then recompile the usb-uhci.c file.  If you have all the dependency files built
                                   and have built all the modules before (done a "make modules"), you should be
                                   able to do "make modules SUBDIRS=drivers/usb" from the
                                   /usr/src/linux-<kernel number> directory.  If you have a freshly installed kernel
                                   source, you will probably have to do "make mrproper", "make menuconfig (or
                                   something similar)" to save the config file, "make dep", and then "make modules".
                                   The procedure may vary with your distribution. 

                              3.  Then move the new usb-uhci.o (you can gzip it or not, as you wish) from
                                   drivers/usb to /lib/modules/.../usb and run "depmod -a" to be sure there are no
                                    errors. rmmod the old usb-uhci (stop all usb activity first) and insmod the new one.

                               When I did this with an Intel uhci controller, I found that the frame rate for both
                                VGA and CIF cameras went up to the values I get for ohci controllers (~14 for
                                VGA, ~10 for CIF, instead of the old 6 for VGA and 1-2 for CIF).  Best of all, the
                                VIA KT133 uhci controller, which would freeze up after several minutes, worked
                                for several hours at the new higher frame rates.  The camera did hang after
                                several hours (running gqcam) but that was after the computer had gone into
                                sleep mode, so I suspect that the freeze up was due to that. Also, while xawtv
                                worked the first time I tried this, it would not work subsequently, even with the
                                the original usb-uhci.o module.  I think that is due to xawtv.  Try to use gqcam
                                or some other app if you can.

                                 I do not know what effect this may have on the performance of other usb devices,
                                 so that is why I suggested saving the original module.  The primary maintainer of
                                 the usb-uhci code, Georg Acher, has made these parameters loadable (i.e., you
                                 can set them when you load the module) for the new usb-uhci code in the 2.5
                                 series (there are a lot of changes going on there), and he intents to also make
                                 them loadable for the usb-uhci code in the 2.4 series, but I do not know when this
                                 will happen.
 

February 5, 2002.      I am releasing an updated version (0.25) of the stv driver; this allows VGA cameras
                                  to run in gnomemeeting and fixes a few other small errors.  I am also releasing
                                  pencam2-0.65 (version 0.60 is at the Sourceforge project site but I did not make a
                                  general announcement).  Pencam2 combines pencam and pensnap, reads and writes
                                  a config file, has a new auto select light filter, and has support for a simple command
                                  script file.  See the README.pencam2 for details.
 

January 17, 2002.     Some people have been having a problem with pencam-0.50: when they start
                                  pencam they get a message that the camera cannot be pinged, and pencam
                                  exits.  I found that I did make a small change between 0.42 and 0.50 which is
                                  apparently causing this problem, although I don't understand why is isn't a problem
                                  for everybody.  Anyway, if you are having this problem, try this:

                                 1. In pencam_vendor, at about line 368, just below 'case 0:' comment
                                    out the line 'ret = usb_control_msg (pc, (0x80 | USB_TYPE_VENDOR |
                                    USB_RECIP_ENDPOINT)...'

                                 2. Copy that line over and change just the '_USB_RECIP_ENDPOINT' to
                                     'USB_RECIP_DEVICE'. The new line should not be commented out. You are
                                     just changing one part of that line and saving the original as a comment.

                                 3. Do the same thing at about line 390, just below 'if ((ret < 0)) { to
                                     the line 'usb_control_msg(pc, ...

                                 4. rebuild pencam and see if that works.
 

January 14, 2002.     I have put a new version (0.24) of the stv driver here and at the sourceforge site.
                                 This has several small bug fixes: webcam no longer crashes after the second frame,
                                 a swapRGB override switch has been added, the green line aroung the frame is
                                 gone, and the brightness does not reset to default when changing image size.
                                 This version matches what is in the kernel tree, with two exceptions.  I have
                                 commented out the MODULE_LICENSE near the start of the program, and
                                 replaced the fill_bulk_...  routine with FILL_BULK.... I did this so that the modlule
                                 will compile on my system (kernel 2.4.8).  These two changes were implemented
                                 around 2.4.12 or later, so if you have a higher kernel version you may want to
                                 uncomment the MODULE_LICENSE, uncomment the fill_bulk and comment out
                                 the FILL_BULK (at around line 800).  The patch has been submitted to the 2.4.18
                                 kernel tree.
 

December 28, 2001.  I have decided to release the new pencam before Jan 1.  It has the saturate filter,
                                 and menu selection key presses no longer have to be followed by <enter>.  Also,
                                 I have released a minor update to pensnap; this allows the option of turning off the
                                 camera beep, and changes the stop picture key from 's' to 'x' (anybody notice that
                                 's' was in there for two different functions?).  The best place to get the files from is
                                 the sourceforge.net/projects/stv0680-usb page.
 

December 22, 2001.   A mailing list has been set up. To subscribe, goto the sourceforge project home
                                 page (http://sourceforge.net/projects/stv0680-usb) and follow the links under
                                 mailing list.  Also, I have set up the files sections so that you should be able
                                 to download the latest pencam and pensnap from there.  The stv680 webcam
                                 driver has been submitted to kernel 2.4.17.  The first version of this kernel has
                                 already been released, so the driver will probably not make it in until a later version
                                 is released, or possibly until 2.4.18.  Once it is in the kernel release, you should
                                 use that version.  I will continue to make available the current version, for use in
                                 kernels that do not yet have the driver.
 

December 20, 2001.   Release 0.20 of pensnap. This should work with all cameras.
 

December 18, 2001.   Good News: I have adapted the Gimp saturate filter to work with pencam.  This
                                 restores some of the color that seems to be taken out with the gamma-correction.
                                 I've also changed the menu selections so most things are toggles, and you don't
                                 have to hit the return key.  A new pencam release will occur around Jan 1.

                                 The stv680 driver is going to be included in the kernel code!  Greg Kroah-Hartman,
                                 the current linux-usb maintainer, has one of the cameras and is including the driver
                                 code in the 2.5 kernel tree.  It will also be in the 2.4 tree at some point, but I don't
                                 know exactly when.  This also means that the linux-usb kernel code guys will be
                                 looking at the driver code, so stability should improve.  There are also a number of
                                 enhancements planned, such as being able to use the pencam code with the stv
                                 driver loaded (you currently can't, as some of you know).  A simple gui for pencam
                                 may also be developed, although currently gtkam allows you to download pictures
                                 from the camera in X windows.  Much of the pencam image processing code has
                                 been imported to gphoto2 and will be in beta4. I have acquired a second camera
                                 (less memory, CIF format) so I can do more and better testing.  Still working on
                                 getting a mailing list at SourceForge.

                                 Bad News: After I got the second camera (and received some emails from people
                                 who had the same type of camera), I found that there is a bug in the pensnap code
                                 that basically makes it worthless for CIF formats.  A picture is automatically taken,
                                 but the software downloads from the wrong location in camera memory and you get
                                 nothing (well, colored horizontal lines).  I hope to have a fix in a few days; I want to
                                 test it thoroughly before posting it.
 

November 29, 2001.  New: Lots of stuff.  Pencam-0.42, with the sharpen filter.  Stv680-0.22, with the
                                 gamma correction-white balance and sharpen filter.  Pensnap-0.1 (first release).
                                 I have had a lot of trouble getting this to work with both ohci and uhci usb controllers,
                                 but this version seems to work with both on my systems (there seems to be a real
                                 problem with the usb-uhci software, at least for kernel versions 2.4.8 and less (maybe
                                 more)). I plan to upgrade to the latest (stable) kernel, probably 2.4.13, in a week or
                                 two, so then I'll know more).  Based on what I have seen working on pensnap, I
                                 would expect the stv680 driver to be more unstable on uhci than ohci.  Also, it seems
                                 that Beta 3 of gphoto2 (http://gphoto.org) has support for usb stv0680 cameras. You
                                 can download images, but it looks like just bayer->RGB and demosaic are working.
                                 If I turn off the filters in pencam, I get pictures that look identical to what gphoto2
                                 delivers.
 

November 15, 2001.   Pencam-0.41 released.  Lots of changes and enhancements.
 

November 6, 2001.     Second version of webcam driver released.
 

October 31, 2001.      First version of the webcam driver released.
 

September 9, 2001.   Pencam-0.3 released.
 

September 3, 2001.   Pencam-0.2 released, with the unsharp mask filter.
 

August 26, 2001.       Pencam-0.1 (first version) released.
 
 

NOTES

PENCAM2:

    As mentioned above, I have combined the pencam and pensnap programs into one, now called pencam2. 
The first version (0.60) was based on versions 0.50 of pencam and 0.21 of pensnap.  The next version adds
some new features (all covered in the Changelog and README.pencam2 files), such as read/write a config
file with your settings, read a command script file for automated picture taking, new auto-select light filter for
gamma correction - white balance, and a few other features.  The images can be processed with color
saturation filters, several sharpening filters, and a few manual light filters, or these can be turned off, and you
can use your own favorite program to process the images.
    The pensnap part of pencam2 will automatically take and download a single image at regular intervals.
This program eliminates the need to use the webcam driver for people who just want this type of application.
The picture size can be set for VGA (640x480) mode, if your camera supports it.  This program is NOT meant
as a replacement for the stv680 driver; at CIF/QVGA resolutions (352x288/320x240) the fastest frame rate is
about 1 frame/sec.  Pensnap can be used with cgi type of programs, that upload a picture to a browser at
regular intervals.
 

STV680:

    The stv680 driver works with xawtv (use the -noxv option)  and with gqcam (use -F to get the fastest
frame rate).  It also works with several cgi type of programs, such as webcam, that display regularly up-
dated  pictures to a browser, and with some video conferencing programs such as gnomemeeting (you
need version 0.25 if you have a VGA/QVGA camera).  The stv0680 cameras comes in two different type;
those that support CIF/QCIF and those that support VGA/QVGA.  As far as I know, no one camera
supports both modes.  The driver will try to set CIF (352x288) mode first if your camera supports it, and
if not it will set QVGA (320x240).  Half size (QCIF (176x144)  and QVGA/2 (160x120)) are available for
each type.  VGA is not supported; the frame rate would be too low (~ 3 frames/sec at best), and would
require special extra code in the driver if it worked at all.  The driver appears to be somewhat sensitive to
the version of xawtv being run; I have used 3.48 and 3.60, but had problems when I upgraded to 3.64 (I
am now using 3.72).  The kernel version you are running may also be a factor.
 

   NOTE: Pencam2 and the stv680 driver use completely different, incompatible methods to interface to the
              camera.  Pencam2 will not work if the stv680 driver is loaded (e.g., if you have it set up
              to load automatically when the camera is plugged in).  Do an "lsmod" and look for stv680 before
              trying to run pencam.  If the stv680 driver is loaded, unload it with "rmmod stv680".  In the future I
              hope to be able to fix this. 
 

DOWNLOAD

       Current and some past versions of the code, as well as a mailing list, are at

                              http://sourceforge.net/projects/stv0680-usb/ 



THANKS

This is not a complete list, but I would like to acknowledge the efforts and contributions of :

 * Bart Hartgers (<bart AT etpmod.phys.tue.nl>), for his work on the initial pencam program.

 * Adam Harrison (<adam AT antispin.org>), for his work on the serial version of stv680 based cameras,
   and for the bayer->RGB and demosaic programs.

 * Winston Chang (<winston AT  stdout.org>), for adapting his GIMP unsharp mask plugin for pencam.

 * Steve Miller ( <steve.miller AT st.com>), for sending me the usb command information, and for his
   encouragement while I was working on the webcam driver.

 * Alexander Schwartz (<alexander.schwartz AT gmx.net>), for the gamma correction - white balance
   software.

 * Kurt Garloff (<kurt AT garloff.de>) for the new and better gamma correction - white balance auto select
   filter.

  * To SourceForge.net for hosting this site.