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