Alan Cox | ab33d50 | 2006-02-27 00:09:05 -0300 | [diff] [blame] | 1 | $Id: README,v 1.7 2005/08/29 23:39:57 sbertin Exp $ |
| 2 | |
| 3 | 1. Introduction |
| 4 | |
| 5 | This is a driver for STMicroelectronics's CPiA2 (second generation |
| 6 | Colour Processor Interface ASIC) based cameras. This camera outputs an MJPEG |
| 7 | stream at up to vga size. It implements the Video4Linux interface as much as |
| 8 | possible. Since the V4L interface does not support compressed formats, only |
| 9 | an mjpeg enabled application can be used with the camera. We have modified the |
| 10 | gqcam application to view this stream. |
| 11 | |
| 12 | The driver is implemented as two kernel modules. The cpia2 module |
| 13 | contains the camera functions and the V4L interface. The cpia2_usb module |
| 14 | contains usb specific functions. The main reason for this was the size of the |
| 15 | module was getting out of hand, so I separted them. It is not likely that |
| 16 | there will be a parallel port version. |
| 17 | |
| 18 | FEATURES: |
| 19 | - Supports cameras with the Vision stv6410 (CIF) and stv6500 (VGA) cmos |
| 20 | sensors. I only have the vga sensor, so can't test the other. |
| 21 | - Image formats: VGA, QVGA, CIF, QCIF, and a number of sizes in between. |
| 22 | VGA and QVGA are the native image sizes for the VGA camera. CIF is done |
| 23 | in the coprocessor by scaling QVGA. All other sizes are done by clipping. |
| 24 | - Palette: YCrCb, compressed with MJPEG. |
| 25 | - Some compression parameters are settable. |
| 26 | - Sensor framerate is adjustable (up to 30 fps CIF, 15 fps VGA). |
| 27 | - Adjust brightness, color, contrast while streaming. |
| 28 | - Flicker control settable for 50 or 60 Hz mains frequency. |
| 29 | |
| 30 | 2. Making and installing the stv672 driver modules: |
| 31 | |
| 32 | Requirements: |
| 33 | ------------- |
| 34 | This should work with 2.4 (2.4.23 and later) and 2.6 kernels, but has |
| 35 | only been tested on 2.6. Video4Linux must be either compiled into the kernel or |
| 36 | available as a module. Video4Linux2 is automatically detected and made |
| 37 | available at compile time. |
| 38 | |
| 39 | Compiling: |
| 40 | ---------- |
| 41 | As root, do a make install. This will compile and install the modules |
| 42 | into the media/video directory in the module tree. For 2.4 kernels, use |
| 43 | Makefile_2.4 (aka do make -f Makefile_2.4 install). |
| 44 | |
| 45 | Setup: |
| 46 | ------ |
| 47 | Use 'modprobe cpia2' to load and 'modprobe -r cpia2' to unload. This |
| 48 | may be done automatically by your distribution. |
| 49 | |
| 50 | 3. Driver options |
| 51 | |
| 52 | Option Description |
| 53 | ------ ----------- |
| 54 | video_nr video device to register (0=/dev/video0, etc) |
| 55 | range -1 to 64. default is -1 (first available) |
| 56 | If you have more than 1 camera, this MUST be -1. |
| 57 | buffer_size Size for each frame buffer in bytes (default 68k) |
| 58 | num_buffers Number of frame buffers (1-32, default 3) |
| 59 | alternate USB Alternate (2-7, default 7) |
| 60 | flicker_freq Frequency for flicker reduction(50 or 60, default 60) |
| 61 | flicker_mode 0 to disable, or 1 to enable flicker reduction. |
| 62 | (default 0). This is only effective if the camera |
| 63 | uses a stv0672 coprocessor. |
| 64 | |
| 65 | Setting the options: |
| 66 | -------------------- |
| 67 | If you are using modules, edit /etc/modules.conf and add an options |
| 68 | line like this: |
| 69 | options cpia2 num_buffers=3 buffer_size=65535 |
| 70 | |
| 71 | If the driver is compiled into the kernel, at boot time specify them |
| 72 | like this: |
| 73 | cpia2=num_buffers:3,buffer_size:65535 |
| 74 | |
| 75 | What buffer size should I use? |
| 76 | ------------------------------ |
| 77 | The maximum image size depends on the alternate you choose, and the |
| 78 | frame rate achieved by the camera. If the compression engine is able to |
| 79 | keep up with the frame rate, the maximum image size is given by the table |
| 80 | below. |
| 81 | The compression engine starts out at maximum compression, and will |
| 82 | increase image quality until it is close to the size in the table. As long |
| 83 | as the compression engine can keep up with the frame rate, after a short time |
| 84 | the images will all be about the size in the table, regardless of resolution. |
| 85 | At low alternate settings, the compression engine may not be able to |
| 86 | compress the image enough and will reduce the frame rate by producing larger |
| 87 | images. |
| 88 | The default of 68k should be good for most users. This will handle |
| 89 | any alternate at frame rates down to 15fps. For lower frame rates, it may |
| 90 | be necessary to increase the buffer size to avoid having frames dropped due |
| 91 | to insufficient space. |
| 92 | |
| 93 | Image size(bytes) |
| 94 | Alternate bytes/ms 15fps 30fps |
| 95 | 2 128 8533 4267 |
| 96 | 3 384 25600 12800 |
| 97 | 4 640 42667 21333 |
| 98 | 5 768 51200 25600 |
| 99 | 6 896 59733 29867 |
| 100 | 7 1023 68200 34100 |
| 101 | |
| 102 | How many buffers should I use? |
| 103 | ------------------------------ |
| 104 | For normal streaming, 3 should give the best results. With only 2, |
| 105 | it is possible for the camera to finish sending one image just after a |
| 106 | program has started reading the other. If this happens, the driver must drop |
| 107 | a frame. The exception to this is if you have a heavily loaded machine. In |
| 108 | this case use 2 buffers. You are probably not reading at the full frame rate. |
| 109 | If the camera can send multiple images before a read finishes, it could |
| 110 | overwrite the third buffer before the read finishes, leading to a corrupt |
| 111 | image. Single and double buffering have extra checks to avoid overwriting. |
| 112 | |
| 113 | 4. Using the camera |
| 114 | |
| 115 | We are providing a modified gqcam application to view the output. In |
| 116 | order to avoid confusion, here it is called mview. There is also the qx5view |
| 117 | program which can also control the lights on the qx5 microscope. MJPEG Tools |
| 118 | (http://mjpeg.sourceforge.net) can also be used to record from the camera. |
| 119 | |
| 120 | 5. Notes to developers: |
| 121 | |
| 122 | - This is a driver version stripped of the 2.4 back compatibility |
| 123 | and old MJPEG ioctl API. See cpia2.sf.net for 2.4 support. |
| 124 | |
| 125 | 6. Thanks: |
| 126 | |
| 127 | - Peter Pregler <Peter_Pregler@email.com>, |
| 128 | Scott J. Bertin <scottbertin@yahoo.com>, and |
| 129 | Jarl Totland <Jarl.Totland@bdc.no> for the original cpia driver, which |
| 130 | this one was modelled from. |