Based on kernel version 4.7.2. Page generated on 2016-08-22 22:48 EST.
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 separated 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 cpia2.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.