CONTENTS
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.
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.
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.
Current and some past versions of the code, as well as a mailing list, are at
http://sourceforge.net/projects/stv0680-usb/
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.