Table of Contents

1. Introduction
2. Compiling the driver
	2.1 General
	2.2 Kernel 2.2
	2.3 Kernel 2.3
3. Installation
	3.1 Kernel 2.2 Parallel Port
	3.2 Kernel 2.3 Parallel Port
	3.3 Kernel 2.3 USB
4. Using the Camera
5. Tested Applications
6. Known Problems
7. Thanks


1. Introduction
	This is a driver for Vision's CPiA (Colour Processor Interface ASIC)
	based cameras.  Both USB and parallel port (PPC2) cameras are
	supported.
	
	Here is a list of cameras known to use Vision's CPiA:
		Creative Video Blaster WebCam II - PPC2 and USB 
		CVideo-Mail Express - PPC2 
		CU-SeeMe Cam Kit - PPC2 
		Digicom Galileo Plus/USB - PPC2 and USB 
		Ezonics EZCam - USB 
		Microtek EyeStar - USB 
		Pace Colour Video Camera - USB 
		SuperCam WonderEye - USB 
		Utopia USB Camera - USB 
		ZoomCam - PPC2 and USB 
	
	The driver is implemented as a kernel module.  It provides a
	Video 4 Linux (V4L) interface to applications, and a /proc interface
	to adjust camera settings.
	
	The latest information about this driver can be found at
	http://home.eunet.no/~jtotland/vision/

	FEATURES:

	- image formats: CIF/QCIF, SIF/QSIF, various others used by isabel;
	  note: all sizes except CIF/QCIF are implemented by clipping, i.e.
	  pixels are not uploaded from the camera
	- palettes: VIDEO_PALETTE_GRAY, VIDEO_PALETTE_RGB565, VIDEO_PALETTE_RGB555,
	  VIDEO_PALETTE_RGB24, VIDEO_PALETTE_RGB32, VIDEO_PALETTE_YUYV,
	  VIDEO_PALETTE_UYVY, VIDEO_PALETTE_YUV422
	- set compression while streaming: none, auto, manual
	- set targetting (quality,framerate)
	- set sensorfps
	- adjust brightness, color, contrast while streaming
	- state information (color balance, exposure) is preserved between
	  device opens
	- flicker control, backlight
	- proc-interface to all camera settings
	- works under SMP (make sure you use __SMP__ for compilation)

2. Compiling the driver

2.1 General
	Edit module/Makefile to set the compilation options you want.  In
	particular, uncomment SMP if you have a SMP system.
	
	Make sure that the kernel source is installed under /usr/src/linux,
	and that make config has been run.  Video for Linux support MUST
	be compiled into the kernel or available as a module.  Support for
	loadable modules is also required.  Compiling the driver into the
	kernel is possible, but is not covered by this document.
	
2.2 Kernel 2.2
	USB Cameras are not supported with a 2.2 kernel.
	
	Required kernel options: CONFIG_PARPORT,
	                         CONFIG_PARPORT_PC
	Recommended kernel options: CONFIG_PNP_PARPORT
	
	CONFIG_VIDEO_CPIA_PP_DMA is set by default in the Makefile.  This
	will use DMA, if available, to lower the CPU load when communicating
	with the camera.  It is not recommended that you disable this unless
	you are experiencing problems.
	
	Change to the module directory and type 'make'.  cpia_usb.c will
	fail to compile, just ignore it or remove cpia_usb.o from the
	OBJS line in the Makefile.
	
2.3 Kernel 2.3
	Do not enable USB CPiA Camera support in the kernel.  That will
	conflict with this driver.
	
	For PPC2:
	Required kernel options: CONFIG_PARPORT,
	                         CONFIG_PARPORT_PC,
				 CONFIG_PARPORT_1284
	Recommended kernel options: CONFIG_PARPORT_PC_FIFO
	
	For USB:
	Required kernel options: CONFIG_USB,
	                         CONFIG_USB_UHCI or CONFIG_USB_OHCI_HCD

	Change to the module directory and type 'make'.
	
3. Installation

3.1 Kernel 2.2 Parallel Port
 	Load the parport, parport_pc, and videodev modules (unless they
	are compiled into your kernel).  If you do not have kmod support
	in your kernel, you will may also want to load the parport_probe
	module.  insmod cpia.o. insmod cpia_pp.o.
	
	If you set CONFIG_PNP_PARPORT in your kernel, any ECP capable port
	with a camera will automatically be detected.  If you didn't, the
	driver will assume a camera on each ECP capable port.  You can
	explictly set which ECP ports have cameras by appending parport=X
	to the insmod cpia_pp.o command.  X can be either a single value (0),
	or a comma separated list of values (0,1).
	
	In order to use DMA, the parport device MUST have both a DMA and
	an IRQ.  To set the DMA, use dma=N when you load parport_pc.
	N is the DMA-channel (as set in BIOS or whereever you set it
        on your hardware).  To activate the IRQ, "echo N > /proc/parport/n/irq"
	where N is the correct IRQ number and n is the parport number.
	
	To check that everything is working properly, run dmesg.  It should
	show lines like this for each camera:
		Jan 26 21:33:16 roger kernel:   CPiA Version: 1.20 (2.0)
		Jan 26 21:33:16 roger kernel:   CPiA PnP-ID: 0553:0002:0100
		Jan 26 21:33:16 roger kernel:   VP-Version: 1.0 0100
	It should also report if DMA, FIFO, or PIO mode is used if you didn't
	disable DMA in the Makefile.
	
3.2 Kernel 2.3 Parallel Port
	Load the parport, parport_pc, and videodev modules (unless they
	are compiled into your kernel).  insmod cpia.o. insmod cpia_pp.o.

	Any ECP or TRISTATE capable port with a camera will automatically be
	detected.  If you want to limit the ports that are probed, append
	parport=X to the insmod cpia_pp.o command.  X can be either a single
	value (0), or a comma separated list of values (0,1).
	
	To check that everything is working properly, run dmesg.  It should
	show lines like this for each camera:
		Jan 26 21:33:16 roger kernel:   CPiA Version: 1.20 (2.0)
		Jan 26 21:33:16 roger kernel:   CPiA PnP-ID: 0553:0002:0100
		Jan 26 21:33:16 roger kernel:   VP-Version: 1.0 0100

3.3 Kernel 2.3 USB
	Load the usb driver(usb-uhci or usb-ohci), and videodev modules
	(unless they are compiled into your kernel).  insmod cpia.o.
	insmod cpia_usb.o.

	Cameras should be automatically detected.
	
	To check that everything is working properly, run dmesg.  It should
	show lines like this for each camera:
		Jan 26 21:33:16 roger kernel:   CPiA Version: 1.20 (2.0)
		Jan 26 21:33:16 roger kernel:   CPiA PnP-ID: 0553:0002:0100
		Jan 26 21:33:16 roger kernel:   VP-Version: 1.0 0100

4.Using the Camera
	There is an application (gqcam) available in the client directory that
	you can use, or try your favorite V4L application.
	
	To control the camera settings that the V4L interface doesn't
	allow changing, /proc/cpia/videoX is provided.  Peter Pregler has
	written a program to adjust these values that can be found at
	http://www.risc.uni-linz.ac.at/people/ppregler/cpia/
	You can also control these settings from the shell.  For example,
	to turn off compression:
	echo "compression_mode:none" >> /proc/cpia/video0
	
5. Tested Applications

- a simple test application based on Xt
- a test-application based on gqcam-0.4 (used GTK)
- xawtv-3.02 (also the webcam)
- xawtv-2.46
- w3cam (cgi-interface and vidcat, e.g. you may try out 'vidcat  |xv
  -maxpect -root -quit +noresetroot -rmode 5 -')
- vic, the MBONE video conferencing tool (version 2.8ucl4-1)
- isabel 3R4 (barely working, I swear it will work sometimes since this
  was the reason for me to write this driver :)

6. Known Problems

- Some applications do not handle the image format correctly, you will
  see strange horizontal stripes instead of a nice picture -> make sure
  your application does use a supported image size or queries the driver
  for the actually used size (reason behind this: the camera cannot
  provide any image format, so if size NxM is requested the driver will
  use a format to the closest fitting N1xM1, the application should now
  query for this granted size, most applications do not).
- If there is not enough light and the picture is too dark try to
  adjust the SetSensorFPS setting, automatic frame rate adjustment
  has its price
- Parallel port cameras will only work with an ECP (and TRISTATE for 2.3.x
  kernels) parallel port.

7. Thanks (in no particular order):

- Bas Huisman <bhuism@cs.utwente.nl> for writing the initial parport code
- Scott J. Bertin <sbertin@mindspring.com> for cleanups, the proc-filesystem
  and much more
- Peter Pregler <Peter_Pregler@email.com>
  http://www.risc.uni-linz.ac.at/people/ppregler
  for the V4L interface, low-level parallel port work, and much more
- Jarl Totland <Jarl.Totland@bdc.no> for setting up the mailing list 
  and maintaining the web-server
- Manuel J. Petit de Gabriel <mpetit@dit.upm.es> for providing help
  with Isabel (http://isabel.dit.upm.es/)
- Henry Bruce <whb@vvl.co.uk> for providing developers information about
  the CPiA chip, I wish all companies would treat Linux as seriously
- Chris Whiteford <Chris@informinteractive.com> for fixes related to
  the 1.02 firmware
- Jochen Scharrlach <Jochen.Scharrlach@schwaben.de> for USB support
- special kudos to all the tester whose machines crashed and/or
  will crash. :)
