------------------------------------------------------------------------------------------
Readme for kernel 2.6.x Linux device driver for the Zoran/Nogatech USBVision Video Grabber
------------------------------------------------------------------------------------------

Author: Joerg Heckenbach <joerg@heckenbach-aw.de>
Homepage: http://www.emuit.com/webcam.html (Dwaine Garden)



INTRODUCTION:
-------------

This is a driver for the USB video bridge USBVision from Zoran/Nogatech, a USB-only cable used in many "webcam" devices.
It supports streaming and capture of color or monochrome video via the Video4Linux
API. Most V4L apps are compatible with it, but a few video-conferencing programs
do not work yet.

If you need more information, please visit the Zoran/Nogatech homepage at the above URL.

usbvision-0.9.6 is the first prerelease of the 1.0 driver. I did many changes in the code and I hope I 
didn't break working features on different devices. The decompression is completed. Just from time to 
time there are some black or white error pixels in the image on slower machines. Maybe it is a timing problem 
in the isoc interrupt routine. We stay a third of the time in interrupt and so it is likely, that the parser 
is called twice. Let me cleanup the routine for performance, move the parser to user-context and add a lock.

For 2.6x kernels we can use the saa7111 from the kernel tree, so the make will not compile the saa7111-new 
for these kernels.  The bt819-new.c is not coded to 2.6. kernel yet.
I have tested the driver with kernel 2.6.1, 2.6.2 to 2.6.7 with devices "Hauppauge WinTV USB FM 1" and 
"Pixelview PlayTV USB Pro FM" on a 600MHz PII system.



WHAT YOU NEED:
--------------

- If you want to help with the development, get the chip's specification docs at
  http://www.emuit.com/webcam.html

- A Video4Linux compatible frame grabber program (I recommend xawtv or Kwintv)
  xawtv is available at:  http://www.in-berlin.de/User/kraxel/xawtv.html
  
- Radio Application to take advantage of the radio tuner. (some of the devices)
  GQradio is available at:  http://gqmpeg.sourceforge.net/radio.html



HOW TO INSTALL THE DEVICE DRIVER:
---------------------------------


First way (The easy one)
---------

It works with most modern standard installations.

a) In the usbvision directory do
   make; make install; modprobe usbvision

b) Start your video application.

c) Enjoy.

If c) doesn't work, something went wrong ;-)




Second way (Not as easy as the first one)
----------

You need this, if either usb-, i2c-, tuner- or v4l-support is missing in your kernel.

a) cp the following files into the directory /usr/src/linux/drivers/usb/media

	usbvision.c
	usbvision.h
	saa7113.c
	saa7113.h
	i2c-algo-usb.c
	i2c-algo-usb.h
	usbvision_ioctl.h


c) In the makefile of the dir /usr/src/linux/drivers/usb, look for the line "obj-$(CONFIG_USB_IBMCAM)	+=media/", 
insert an additional line then added the line for the usbvision driver 

   obj-$(CONFIG_USB_USBVISION)	+= media/

e) Add the line to the makefile in /usr/src/linux/driver/usb/media/
  obj-$(CONFIG_USB_USBVISION)     += usbvision.o saa7113.o i2c-algo-usb.o

f) Edit file /usr/src/linux/drivers/usb/media/Kconfig   
   Paste the following lines below after the entry for the IBMCAM.

---------------------------- Begin Paste ------------------------------
config USB_USBVISION
	tristate "USB Zoran/Nogatech USBVision Video Grabber Support"
	depends on USB && VIDEO_DEV && I2C && VIDEO_BT848 && VIDEO_DPC
	---help---
  	  Say Y here if you want to connect a Nogatech NT100x, or a Zoran
  	  ZR36504/ZR36505 chipset based video/tv/radio grabber, to your
  	  computer's USB port.

  	  For more information, read <file:Documentation/usb/usbvision.txt>.
	  
  	  This driver needs the following support: Please enable (Y or M in config)
	  	Video For Linux API 
		I2C API.  
		BT484 Device Support
		DPC7146 demonstration board Device Support
	  	  
  	  This code is also available as a module ( = code which can be
  	  inserted in and removed from the running kernel whenever you want).
  	  The module will be called usbvision.o.  If you want to compile it as a
  	  module, say M here and read <file:Documentation/modules.txt>. This
  	  video grabber has several configuration options which can be specified
  	  when you load the module.  Read <file:Documentation/usb/usbvision.txt> to
  	  learn more.
---------------------------- End of Paste -----------------------------


h) If it is not already there (it usually is), create the video device:

	mknod /dev/video c 81 0

i) Sometimes /dev/video is a symlink to /dev/video0

You will have to set permissions on this device to allow you to read/write
from it:

	chmod 666 /dev/video
	chmod 666 /dev/video0 (if necessary)

When configuring the kernel choose Zoran/Nogatech USBVISION video support as
module. You are going to need also to select i2c and v4l, and if your
device have tuner you need to compile also BT848 support or other modules
that compile the tuner.o module.

	a) Do a make modules, make modules_install.

	b) If the USB Support and the Video4Linux was compiled as modules.

	   modprobe usbcore.o
           modprobe usb-uhci.o  <OR>  modprobe ohci-hcd.o
	   modprobe videodev.o

	b) Install the modules:

   	   modprobe usbvision- For a great radio application, try GQradio.

       The usbvision module will also load the i2c-algo-usb, i2c-core, saa7111, saa7113.


 VIDEO PLAYERS FOR PLAYING VIDEO OUPUT
-------------------------------------
 
 Here is the setting to get the TV tuner working with mplayer.  It does software video scaling, so you can have full screen mode with the USBVision driver.
 
 	mplayer tv:// -tv channel=43:driver=v4l:input=0:outfmt=rgb24:norm=ntsc:height=240:width=320 -flip
 
 Here is the setting to get the TV tuner working with xawtv.
 
 	xawtv -c /dev/video0



USBVISION MODULE PARAMETERS:
----------------------------

  NAME: isocMode
  TYPE: integer (0x03, 0x14, 0x60)
  DEFAULT: 0x60
  DESC:  The isocMode is the format mode of the data that is transmitted on the isocronous
  pipe via USB. It is not depending on the connected video-hardware. Default is 0x14.

        YUV422          0x03
        YUV420          0x14
        COMPRESSION     0x60    Enable compression for full framerate.


  NAME: debug
  TYPE: bitmask
  DEFAULT: 0
  DESC: You don't need this option unless you are a developer. If you are a developer then
  you will see in the code what values do what. This is a bit mask, and you can combine any
  number of bits to produce what you want:

       bit 2    debug procfs
       bit 3    debug video ioctl
       bit 4    debug video io
       bit 5    debug radio io
       bit 7    debug usb frame header
       bit 8    debug probe and disconnect
       bit 9    debug irq
       bit 10   debug handling of isochronus transfer
       bit 11   debug parsing of usb data
       bit 12   debug handling of scratch
       bit 13   debug utility functions
       bit 14   debug i2c stuff


  NAME: flags
  TYPE: bitmask
  DEFAULT: 0
  DESC: This is a bit mask, and you can combine any number of bits to produce what you want.
  Usually you don't want any of extra features this option provides:

       bit 0    FLAGS_RETRY_VIDIOCSYNC     This bit allows to retry failed
                                           VIDIOCSYNC ioctls without failing.
                                           Will work with xawtv, will not
                                           with xrealproducer. Default is
                                           not set.
       bit 1    FLAGS_MONOCHROME           Activates monochrome (b/w) mode.
       bit 2    FLAGS_DISPLAY_HINTS        Shows colored pixels which have
                                           magic meaning to developers.
       bit 3    FLAGS_OVERLAY_STATS        Shows tiny numbers on screen,
                                           useful only for debugging.
       bit 4    FLAGS_FORCE_TESTPATTERN    Shows blue screen with numbers.
       bit 5    FLAGS_SEPARATE_FRAMES      Shows each frame separately, as
                                           it was received from the camera.
                                           Default (not set) is to mix the
                                           preceding frame in to compensate
                                           for occasional loss of Isoc data
                                           on high frame rates.
       bit 6    FLAGS_CLEAN_FRAMES         Forces "cleanup" of each frame
                                           prior to use; relevant only if
                                           FLAGS_SEPARATE_FRAMES is set.
                                           Default is not to clean frames,
                                           this is a little faster but may
                                           produce flicker if frame rate is
                                           too high and Isoc data gets lost.


  NAME: dga
  TYPE: integer (0-1) boolean
  DEFAULT: 1
  DESC: This will set the option for DGA video to either Yes or No.  Default is 1.


  NAME: PowerOnAtOpen
  TYPE: integer (0-1) boolean
  DEFAULT: 1
  DESC: This will set the device to power on automatically when opened.  Default is 1.


  NAME: CustomDevice
  TYPE: string
  DEFAULT: NULL
  DESC: This will set a new Custom device
  EXAMPLE: "0x0573 0x4D31 0 7113 3 PAL 1 1 1 5 -1 -1 -1 -1 -1"
  FORMAT: "idVendor idProduct Interface Codec	VideoChannels VideoNorm AudioChannels Radio
             Tuner TunerType Vin_Reg1 Vin_Reg2 X_Offset Y_Offset Dvi_yuv"
        Codec:
			7111
			7113
			819

		VideoNorm:
			P or PAL
			S or SECAM
			N or NTSC

		TunerType: (!!!use the NUMBER not the name)  see latest in "/usr/src/linux/drivers/media/video/tuner.h"
			TUNER_TEMIC_PAL     0        /* 4002 FH5 (3X 7756, 9483) */
			TUNER_PHILIPS_PAL_I 1
			TUNER_PHILIPS_NTSC  2
			TUNER_PHILIPS_SECAM 3		/* you must actively select B/G, L, L` */
			TUNER_ABSENT        4
			TUNER_PHILIPS_PAL   5
			TUNER_TEMIC_NTSC    6        /* 4032 FY5 (3X 7004, 9498, 9789)  */
			TUNER_TEMIC_PAL_I   7        /* 4062 FY5 (3X 8501, 9957)        */
			TUNER_TEMIC_4036FY5_NTSC 8   /* 4036 FY5 (3X 1223, 1981, 7686)  */
			TUNER_ALPS_TSBH1_NTSC 	 9
			TUNER_ALPS_TSBE1_PAL 	10
			TUNER_ALPS_TSBB5_PAL_I 	11
			TUNER_ALPS_TSBE5_PAL 	12
			TUNER_ALPS_TSBC5_PAL 	13
			TUNER_TEMIC_4006FH5_PAL	14   /* 4006 FH5 (3X 9500, 9501, 7291)     */
			TUNER_ALPS_TSHC6_NTSC 	15
			TUNER_TEMIC_PAL_DK	16   /* 4016 FY5 (3X 1392, 1393)     */
			TUNER_PHILIPS_NTSC_M	17
			TUNER_TEMIC_4066FY5_PAL_I       18  /* 4066 FY5 (3X 7032, 7035) */
			TUNER_TEMIC_4006FN5_MULTI_PAL   19  /* B/G, I and D/K autodetected (3X 7595, 7606, 7657)*/
			TUNER_TEMIC_4009FR5_PAL         20  /* incl. FM radio (3X 7607, 7488, 7711)*/
			TUNER_TEMIC_4039FR5_NTSC        21  /* incl. FM radio (3X 7246, 7578, 7732)*/
			TUNER_TEMIC_4046FM5             22  /* you must actively select B/G, D/K, I, L, L` !  (3X 7804, 7806, 8103, 8104)*/
			TUNER_PHILIPS_PAL_DK		23
			TUNER_PHILIPS_FQ1216ME		24  /* you must actively select B/G/D/K, I, L, L` */
			TUNER_LG_PAL_I_FM	25
			TUNER_LG_PAL_I		26
			TUNER_LG_NTSC_FM	27
			TUNER_LG_PAL_FM		28
			TUNER_LG_PAL		29
			TUNER_TEMIC_4009FN5_MULTI_PAL_FM	30  /* B/G, I and D/K autodetected (3X 8155, 8160, 8163)*/
			TUNER_SHARP_2U5JF5540_NTSC  31
			TUNER_Samsung_PAL_TCPM9091PD27 32
			TUNER_MT2032 33
			TUNER_TEMIC_4106FH5 	34	/* 4106 FH5 (3X 7808, 7865)*/
			TUNER_TEMIC_4012FY5	35	/* 4012 FY5 (3X 0971, 1099)*/
			TUNER_TEMIC_4136FY5	36	/* 4136 FY5 (3X 7708, 7746)*/
			TUNER_LG_PAL_NEW_TAPC   37
			TUNER_PHILIPS_FM1216ME_MK3  38
			TUNER_LG_NTSC_NEW_TAPC   39
			TUNER_HITACHI_NTSC       40
			TUNER_PHILIPS_PAL_MK     41
			TUNER_PHILIPS_ATSC       42
			TUNER_PHILIPS_FM1236_MK3 43
			TUNER_PHILIPS_4IN1       44	/* ATI TV Wonder Pro - Conexant */
			TUNER_MICROTUNE_4049FM5  45


================================================================================================

FINAL NOTE:
-----------

If your device isn't known, add it to usbvision_device_data and usbvision_table in usbvision.h.

You can speed up tuner detection, when adding "options tuner addr=your_addr" to /etc/modules.conf.

If your device isn't known, edit line (modprobe usbvision CustomDevice="0x0573 0x4D31 0 7113 3 PAL 1 1 1 5 -1 -1 -1 -1 -1")
in 'usbvision.rc' file then 'usbvision.rc start'
also edit "etc/rc.d/init.d/usbvision" if you use it

Please tell me your experience (joerg@heckenbach-aw.de), or contact (dwainegarden@rogers.com).


