LDP/LDP/howto/linuxdoc/BTTV.sgml

<!doctype linuxdoc system>
<article>
<title>The BTTV Mini-HOWTO 
<author>By Eric Sandeen, <tt/eric_sandeen@bigfoot.com/ 
<date>v0.3, February 2000
<abstract>
This document describes the hardware, software, and procedures needed to
use a bt8x8 chipset based frame grabber or TV tuner card under Linux.
</abstract>

<toc>
<sect>Introduction
<p>
The ability to capture and view  video sources is one of the more interesting multimedia
features of Linux.  Many different types of video devices are supported via the 
video4linux API (<htmlurl url="http://roadrunner.swansea.uk.linux.org/v4l.shtml">),
including several TV tuner cards based on the Conexant bt848 and bt878 chipsets.  
This document explains how to use these cards on a Linux system.

<sect1>Copyright of this document
<p>
This HOWTO is copyrighted 1999 Eric Sandeen.

Unless otherwise stated, Linux HOWTO documents are copyrighted by their
respective authors. Linux HOWTO documents may be reproduced and distributed
in whole or in part, in any medium physical or electronic, as long as this
copyright notice is retained on all copies. Commercial redistribution is
allowed and encouraged; however, the author would like to be notified of any
such distributions.

All translations, derivative works, or aggregate works incorporating any
Linux HOWTO documents must be covered under this copyright notice. That is,
you may not produce a derivative work from a HOWTO and impose additional
restrictions on its distribution. Exceptions to these rules may be granted
under certain conditions; please contact the Linux HOWTO co-ordinator at the
address given below.

In short, we wish to promote dissemination of this information through as
many channels as possible. However, we do wish to retain copyright on the
HOWTO documents, and would like to be notified of any plans to redistribute
the HOWTOs.

If you have questions, please contact Tim Bynum, the Linux HOWTO
co-ordinator, at <em/linux-howto@metalab.unc.edu/ via email.

<sect1>Where to get this document
<p>
The most recent official version of this document can be obtained from the
Linux Documentation Project <url url="http://metalab.unc.edu/LDP/">.

<sect1>Acknowledgments
<p>
Thanks to Ralph Metzler and Marcus Metzler for writing the original bttv driver.
Also, Alan Cox for creating the Video4Linux API, Gerd Knorr for his 
work on the radio cards, subsequent bttv releases, and xawtv.  And everyone else 
who contributed to Linux support for these cards.  Thanks to
William Burrow, who also wrote a BTTV Howto (which I learned about <em>after</em>
I wrote this document...)  I have improved this guide, thanks to his work.

In writing this HOWTO I have drawn heavily on the bttv and xawtv documentation.

<sect1>Disclaimer
<p>
Use the information in this document at your own risk. I disavow any
potential liability for the contents of this document. Use of the concepts,
examples, and/or other content of this document is entirely at your own
risk.

All copyrights are owned by their owners, unless specifically noted
otherwise.  Use of a term in this document should not be regarded as
affecting the validity of any trademark or service mark.

Naming of particular products or brands should not be seen as endorsements.
You are strongly recommended to take a backup of your system before major
installation and backups at regular intervals.

<sect>Hardware Requirements
<p>

From the bttv <tt>README</tt>:

Bttv is a device driver for frame grabber cards using the Conexant 
(<url url="http://www.conexant.com">) Bt848 family
of video decoder chips.
Among those are the Bt848, Bt848A, Bt849, Bt878 and Bt879.
The only major differences between the cards by different manufacturers 
are the types of tuners and extra components on the boards.
E.g., some cards by Hauppauge have an additional Videotext decoder 
and/or sound decoder chip.
Only some of these additional components are supported by bttv.
Also, type (Composite or S-Video) and number of inputs differ.

The following cards should work:
<itemize>

	<item><bf>AverMedia TV98</bf> 
	<itemize>
	<item><url url="http://www.aver.com/products.html">
	</itemize>
	
	<item><bf>AVerMedia TV-Phone</bf> 
	<itemize>
	<item><url url="http://www.aver.com/lite/products/avertvphone.html">
	</itemize>
	
	<item><bf>Diamond DTV2000</bf> 
	<itemize>
	<item><url url="http://www.diamondmm.com/products/current/dtv-2000.cfm">
	</itemize>
	
	<item><bf>Hauppauge Win/TV pci</bf> (and other Hauppauge cards)
	<itemize>
	<item><url url="http://www.hauppauge.com/">
	</itemize>
	
	<item><bf>IDS Imaging FALCON</bf>
	<itemize>
	<item><url url="http://www.ids-imaging.de/">
	</itemize>
	
	<item><bf>Lifeview Flyvideo II</bf>
	<itemize>
	<item><url url="http://www.lifeview.de/lifeview/html/produkte.htm#karte">
	</itemize>
	
	<item><bf>Matrix Vision MV-Delta</bf>
	<itemize>
	<item><url url="http://www.matrix-vision.de/">
	</itemize>
	
	<item><bf>miroVIDEO PCTV</bf>
	<itemize>
	<item><url url="http://www.pinnaclesys.com/">
	</itemize>
	
	<item><bf>Osprey-100</bf> 
	<itemize>
	<item><url url="http://www.mmac.com/products/osprey/osprey100.html">
	</itemize>
	
	<item><bf>STB TV PCI</bf> 
	<itemize>
	<item><url url="http://www.stb.com/products/multimedia/tvpci/tvpci.html">
	</itemize>
	
	<item><bf>Terratec TERRA TV+</bf> 
	<itemize>
	<item><url url="http://www.terratec.de/produkte/terratv/terratv_info.htm">
	</itemize>
	
	<item><bf>Videologic Captivator PCI</bf> 
	<itemize>
	<item><url url="http://www.videologic.com/Productinfo/capt_pci.htm">
	</itemize>
	
</itemize>

If you know of other cards which work, please email me and I'll add them
in the next revision of this document.

<sect>Software Requirements

<p>
To use these TV tuner cards under Linux, you will need the appropriate kernel 
drivers.  The bttv drivers have been a part of the kernel distribution since 
version 2.2.0.
<p>
Alternately, you can get the latest version of tbe driver package and use it 
with 2.0.35 or newer kernels.  However, it's not guaranteed to work with the 
older 2.0.x series kernels.  The updated bttv package is available from
<htmlurl url="http://www.thp.uni-koeln.de/~rjkm/linux/bttv.html">, and an
even more updated version is available from Gerd Knorr at
<htmlurl url="http://www.in-berlin.de/User/kraxel/xawtv.html">  These packages
add support for more audio chips, including the TEA6300, TDA8425, and DPL3518.
<p>If you're
new to the world of the bttv driver, I would suggest starting with the version
included with the latest kernel.  If you find that you have trouble with it, or that
it does not support your card, then venture out to the updated 0.6 series
drivers at the locations shown above.  If you're feeling really adventurous,
you can try Gerd Knorr's 0.7 series drivers, due to be incorporated in the 2.4
kernel.  The 0.7 series drivers are also available at
<htmlurl url="http://www.in-berlin.de/User/kraxel/xawtv.html">.
<p>
This document is based primarily on the 2.2.14 kernel drivers, with some mention
of the features available in the updated 0.6 series driver packages.  The 0.7
series is currently not covered, as it is in heavy development at the time of
this writing.

<!-- newer 7.x series drivers will not work with 2.0.x kernels... -->

<sect>System Configuration
<p>
<sect1>Hardware Installation
<p>
<em>(Thanks to William Burrow for this section.)</em>
<p>
If you are afraid to open the case of your computer, be sure to read over this 
entire HOWTO first and make notes about the card, such as its tuner
type, integrated circuit numbers, the frequencies of the crystal(s) and so on. 
Then get someone competent to install the card for you. 
<p>
Otherwise, open the case and install the card in an available slot. Pick one 
that supports PCI bus transfers and PCI bus mastering, if your mainboard
is picky about this (see your mainboard's manual). You will want this for 
overlay mode. 
<p>
For sound, there are two different ways to connect your video grabber card 
and your sound card. One way is internal routing. Connect your CD-ROM
audio cable to the video card sound input and the video card output to the 
sound card CD-ROM or Tuner audio input. Another way is to connect the external
1/8'' audio jack on the video card to the audio card's 1/8'' line audio in 
jack. You can also just plug amplified speakers into the grabber card audio out
if you do not have an audio card or don't want to route through the sound card. 
(A few of the newer bt878 cards don't have any sound connector, because they
send digital audio data across the PCI bus.  There is no support for this at
the time of this writing.)
<p>
A video source is also handy, especially for determining if the card is 
working or not. Many cards handle composite video in, S-Video in and, if
equipped with a tuner, RF in. There is a separate connector for each 
of these inputs.
<p>
<sect1>Kernel Configuration
<p>

Your kernel will need to be correctly configured to support your card.
Most newer Linux distributions come with the necessary
modules already compiled, so if you can find the <tt>videodev.o</tt>, 
<tt>bttv.o</tt>, and <tt>tuner.o</tt> under <tt>/lib/modules/2.x.x/misc</tt>, 
you should be ready to go.
<p>
<!-- Is there a better way to tell if it's configured properly? -->

If not, you'll need to recompile your kernel with
<P>
<tt>CONFIG_VIDEO_DEV</tt><P>
and<P>
<tt>CONFIG_VIDEO_BT848</tt><P>
enabled, preferably as loadable modules.  See the Linux Kernel HOWTO (<url url="http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html">) for details on recompiling your kernel.

<!-- what about i2c... does it come with the CONFIG_VIDEO_BT848? -->

<sect1>Using the updated 0.6.x packages
<p>
If you want to use the updated 0.6.x package, you should first retrieve 
the archive from one of the sites mentioned above.  Extract it with
<p> 
<tt>tar -xvzf bttv-0.6.x.tar.gz</tt>
<p>
and change to the newly created 
directory.  <tt>su</tt> to root, and type 
<p>
<tt>make</tt>
<p>
in the main 
directory to create the drivers.  (You can safely ignore the information 
in the <tt>INSTALL</tt> file about editing makefiles, and the like, since
we will pass this information to the driver as module parameters.) Then, type 
<p>
<tt>make install</tt>
<p>
to install them.  Finally, run 
<p>
<tt>/sbin/depmod -a</tt>
<p>
to update your module dependency information.

<sect1>Special files in <tt>/dev</tt>
<p>
Next, you may need to make the special character files in the <tt>/dev</tt>
directory.  Type <tt>ls /dev/video*; ls /dev/radio*</tt> to see if these
devices already exist.  If not, you'll need to create them.  All of the 
files have major device number 81, and the minor device numbers depend
on the specific device (video, radio, etc.) as well as multiple instances
of these files.  See the Video4Linux API 
(<htmlurl url="http://roadrunner.swansea.uk.linux.org/v4lapi.shtml">) 
for the programming-related details.
 
<!-- Make sure they're the right major and minor char numbers? -->
<!-- Also, what about "old" names - necessary? -->

<p>
There is a <tt>MAKEDEV</tt> script in the <tt>driver</tt> directory 
of the bttv driver package which will create four video devices for 
you.  You can also do it yourself fairly easily if you only have one video
capture card.
As root, type:

<tt>mknod /dev/video0 c 81 0</tt><p>
<tt>chmod 666 /dev/video0</tt><p>
<tt>ln -s /dev/video0 /dev/video</tt><p>

<tt>mknod /dev/radio0 c 81 64</tt><p>
<tt>chmod 666 /dev/radio0</tt><p>
<tt>ln -s /dev/radio0 /dev/radio</tt><p>

<!-- says this is for compatibility.... needed?
<tt>mknod /dev/bttv0 c 81 0</tt><p>
<tt>chmod 666 /dev/bttv0</tt><p>
<tt>ln -s /dev/bttv0 /dev/bttv</tt><p>
-->

There are also videotext and VBI devices which can be created if you have an
application which needs them.  (Currently, there are only a few.)  Type:

<tt>mknod /dev/vtx0 c 81 192</tt><p>
<tt>chmod 666 /dev/vtx0</tt><p>
<tt>ln -s /dev/vtx0 /dev/vtx</tt><p>

<tt>mknod /dev/vbi0 c 81 224</tt><p>
<tt>chmod 666 /dev/vbi0</tt><p>
<tt>ln -s /dev/vbi0 /dev/vbi</tt><p>


<sect1>Loading the Modules
<p>
The bttv driver provides many different modules, with many different options,
as described in the appendix of this document.  With so many modules 
and options, you may wish to do this by hand until
you get everything working.   On the off chance that this causes your box
to crash, it wouldn't hurt to type
<p>
<tt>sync; sleep 1; sync</tt>
<p>
to flush any dirty disk buffers before proceeding.  Then, using the 
<tt>insmod</tt> command as root, try
loading up the modules.  The first two are easy, because they don't usually need
any options:

<tt>insmod videodev</tt>

<tt>insmod i2c</tt>
<!-- is this just for bttv...? any guarantees that it's available? -->
<!-- What about the new I2C? -->

Now you're ready to load the bttv module itself:

<tt>modprobe bttv</tt>

By default, the <tt>bttv</tt> module attempts to autodetect your card type.
Watch <tt>/var/log/messages</tt> to see what it finds.  If it doesn't
autodetect properly,
you can add the <tt>card=<em/n/</tt> option to the end of the previous command
to force a card type, with 
<tt><em/n/</tt> chosen from the following list.  (Types 0 through 19 are provided
in the kernel series driver, bttv-0.6.4h contains support for types 20 through 27)
You can also add the 
<tt>radio=1</tt> option if your card has FM tuner functionality.
<p>
<code>
card=n		card type
		0:  Auto-Detect
		1:  Miro
		2:  Hauppauge (old bt848 boards)
		3:  STB
		4:  Intel
		5:  Diamond
		6:  AVerMedia
		7:  MATRIX Vision MV-Delta
		8:  FlyVideo
		9:  TurboTV
		10: Hauppauge (new bt878 boards)
		11: MIRO PCTV pro
		12: Terratec/Vobis TV-Boostar
		13: Newer Hauppauge WinCam (bt878)
		14: MAXI TV Video PCI2
		15: Terratec TerraTV+
		16: Aimslab VHX
		17: PXC200
		18: AVermedia98
		19: FlyVideo98 (newer FlyVideo cards)
		20: Zoltrix TV-Max
		21: iProTV
		22: ADS Technologies Channel Surfer TV
		23: Pixelview PlayTV (bt878)
		24: Leadtek WinView 601
		25: AVEC Intercapture
		26: LifeView FlyKit w/o Tuner
		27: Intel Create and Share PCI

</code>

Next, load the tuner module, with

<tt>modprobe tuner type=<em/n/</tt>

You will probably need to dig into your case to see which tuner you have.  Some
cards (Miro and Hauppauge) allow the tuner to be automatically detected, but 
you may need to specify it.  The tuner should be marked with the brand name,
and you can look at the crystals (little aluminum cans) on the board to see if
you have an NTSC or a PAL tuner.  For PAL, the crystal is marked 28.xxxMHz 
(where xxx are three digits). For NTSC, the canister should say 35.xxxMHz.
Once you have identified your tuner, select the value of <tt><em/n/</tt> from 
the following list (types 8 and 9 are included only in bttv-0.6.4h):
<p>
<code>
type=n		type of the tuner chip. n as follows:
		0: Temic PAL tuner
		1: Philips PAL_I tuner
		2: Philips NTSC tuner
		3: Philips SECAM tuner
		4: no tuner
		5: Philips PAL tuner
		6: Temic NTSC tuner
		7: Temic PAL tuner
		8: Alps TSBH1 NTSC tuner
		9: Alps TSBE1 PAL tuner
</code>

<!-- Add info about NTSC vs PAL vs SECAM and world regions? -->

Finally, insert any sound modules you may need.  Again, you will probably
need to take a very close look at the card to see what you've got.  
Note that drivers for TEA6300, TDA8425, TDA9855, and DPL3518 chips are 
only included in the 0.6.4h series driver, and are not included with 
the current (2.2.14) kernel drivers.

<!-- Create table of cards and their sound chips? -->

<tt>modprobe msp3400</tt> or <tt>tea3600</tt> or <tt>tda8425</tt> or
<tt>tda9855</tt> or <tt>dpl3518</tt>(see the appendix for details and options)
<p>
Fire up your favorite video4linux program, and see if it works.  If you
can't change the channel, make sure you have inserted the correct tuner
module.  If you can't hear any sound, double check the sound module, and
make sure that the channel is not muted, if you're running the audio through
your sound card.
<p>
<Sect1>Automating the process 
<p>
After you know which modules and options you need, you can automate the 
process by putting the information into <tt>/etc/conf.modules</tt>.  Then, running an 
application which needs the driver will cause it to be loaded automatically. 
I use the following:

<code>
# TV
alias	char-major-81	bttv
pre-install bttv	modprobe -k tuner; modprobe -k msp3400
options	bttv		radio=1 card=3
options tuner		type=2
</code>
Be sure change this to reflect the proper modules and options for your particular card.
(Run an <tt>/sbin/depmod -a</tt> to make sure all your module dependency information
is up to date, as well.)

<sect>Applications
<p>
Now that your kernel is configured, your devices have been configured, and your
modules are inserted, you will also need an application to actually view or 
capture the images from  your card.  There are many available:

<itemize>

	<item><bf>bttvgrab</bf> - Provides high-quality grabbing suitable for video 
	recording
	<itemize>
	<item><htmlurl url="http://moes.pmnet.uni-oldenburg.de/bttvgrab/">
	</itemize>
	
	<item><bf>Gnome-o-Vision</bf> - A viewer for the Gnome desktop environment 
	(currently under development in the Gnome CVS)
	<itemize>
	<item><htmlurl url="http://cvs.gnome.org/lxr/source/gnomovision/">
	</itemize>

	<item><bf>kwintv</bf> - Qt-based TV viewer for the KDE environment
	<itemize>
	<item><htmlurl url="http://www.mathematik.uni-kl.de/~wenk/kwintv/">
	</itemize>
	
	<item><bf>wmtune</bf> - window maker radio tuner applet for bttv based 
	TV/radio cards
	<itemize>
	<htmlurl url="http://home.pages.de/~fionn/archive/wmtune-1.0_bttv.tar.bz2">
	</itemize>
	
	<item><bf>wmtv</bf> - WindowMaker TV dock.app
	<itemize>
	<item><htmlurl url="http://www.student.uwa.edu.au/~wliang/">
	</itemize>
	
	<item><bf>XawTV</bf> - a TV application and a few utilities
	<itemize>
	<item><htmlurl url="http://www.in-berlin.de/User/kraxel/xawtv.html">
	</itemize>
	
	<item><bf>XtTV</bf> - Simple TV/Video program for Linux/X Windows
	<itemize>
	<item><htmlurl url="http://home.pages.de/~rasca/xttv/">
	</itemize>
	
</itemize>

There is also a driver available for the FlyVideo98 Remote control card at
<htmlurl url="http://wolf.ifj.edu.pl/~jochym/FlyVideo98/">

<bf>Be sure to read the documentation</bf> for any applications you plan to use.
Many of them require detailed configuration files to be edited before
the application will work properly!  Due to the many different types of cards
out there, you <em>must</em> take the time to read the documentation on
most of these, as the application defaults will most likely <em>not</em>
work for your card.

<sect>Appendix - Arguments for All Modules

<!-- Style guide says that the code tag is not the way to go - options? -->

<p>
Items preceded with a "*" are only available in the 0.6.4h series driver
<p>    
<code>

videodev.o
	this is the basic video4linux module, all video 
	drivers (incl. bttv) register themselves here.

i2c.o
	the generic i2c module. It does much of the i2c bus
	management, all other modules (except videodev.o)
	use this one

	insmod args:
		scan=1		scan the bus for i2c devices
		verbose=0	shut up i2c
		i2c_debug=1	for debugging, it sticks the 
				whole (software) i2c bus 
				traffic to the syslog

bttv.o
	the bt848 (grabber chip) driver

	insmod args:
		remap=adr       remap Bt848 memory to adr<<20		
		vidmem=base	frame buffer address>>20 (of graphic card)
		triton1=0/1     for Triton1 compatibility
                                Triton1 is automatically recognized
                                but this might also help with other chipsets
		pll=0/1/2	pll settings
				0: don't use PLL
				1: 28 MHz crystal installed
				2: 35 MHz crystal installed
		radio=0/1	card supports radio
		card=n		card type
				0:  Auto-Detect
				1:  Miro
				2:  Hauppauge (old bt848 boards)
				3:  STB
				4:  Intel
				5:  Diamond
				6:  AVerMedia
				7:  MATRIX Vision MV-Delta
				8:  FlyVideo
				9:  TurboTV
 				10: Hauppauge (new bt878 boards)
				11: MIRO PCTV pro
				12: Terratec/Vobis TV-Boostar
				13: Newer Hauppauge WinCam (bt878)
				14: MAXI TV Video PCI2
				15: Terratec TerraTV+
				16: Aimslab VHX
				17: PXC200
				18: AVermedia98
				19: FlyVideo98 (newer FlyVideo cards)
				*20: Zoltrix TV-Max
				*21: iProTV
				*22: ADS Technologies Channel Surfer TV
				*23: Pixelview PlayTV (bt878)
				*24: Leadtek WinView 601
				*25: AVEC Intercapture
				*26: LifeView FlyKit w/o Tuner
				*27: Intel Create and Share PCI

	remap, card, radio and pll accept up to four comma-separted arguments
	(for multiple boards).  The CARD and PLL defines from the Makefile
	are used as defaults.

msp3400.o
	The driver for the msp34xx sound processor chips. If you have a
	stereo card, you probably want to insmod this one.

	insmod args:
		debug=1/2	print some debug info to the syslog,
				2 is more verbose.

*tea6300.o
	The driver for the tea6300 fader chip.  If you have a stereo
	card and the msp3400.o doesn't work, you might want to try this
	one.  This chip is seen on most STB TV/FM cards (usually from
	Gateway OEM sold surplus on auction sites).

	insmod args:
		debug=1		print some debug info to the syslog.

*tda8425.o
	The driver for the tda8425 fader chip.  This driver used to be
	part of bttv.c, so if your sound used to work but does not
	anymore, try loading this module.

	insmod args:
		debug=1		print some debug info to the syslog.

*tda9855.o
	The driver for the tda9855 stereo decoder / audio processor chip.
	
	insmod args:
		debug=1		print some debug info to the syslog.

*dpl3518.o
	Driver for the dpl3518a Dolby Pro Logic Processor
	
	insmod args:
		debug=1		print some debug info to the syslog.

tuner.o
	The tuner driver.  You need this unless you want to use only
	with a camera or external tuner ...

	insmod args:
		debug=1		print some debug info to the syslog
		type=n		type of the tuner chip. n as follows:
				0: Temic PAL tuner
				1: Philips PAL_I tuner
				2: Philips NTSC tuner
				3: Philips SECAM tuner
				4: no tuner
				5: Philips PAL tuner
				6: Temic NTSC tuner
				7: Temic PAL tuner
				*8: Alps TSBH1 NTSC tuner
				*9: Alps TSBE1 PAL tuner

i2c_chardev.o
	provides a character device for i2c bus access.  Works for 2.1.x
	only, not compiled by default.
</code>


</article>