  The BTTV Mini-HOWTO
  By Eric Sandeen, eric_sandeen@bigfoot.com
  v0.3, February 2000

  This document describes the hardware, software, and procedures needed
  to use a bt8x8 chipset based frame grabber or TV tuner card under
  Linux.
  ______________________________________________________________________

  Table of Contents


  1. Introduction

     1.1 Copyright of this document
     1.2 Where to get this document
     1.3 Acknowledgments
     1.4 Disclaimer

  2. Hardware Requirements

  3. Software Requirements

  4. System Configuration

     4.1 Hardware Installation
     4.2 Kernel Configuration
     4.3 Using the updated 0.6.x packages
     4.4 Special files in
     4.5 Loading the Modules
     4.6 Automating the process

  5. Applications

  6. Appendix - Arguments for All Modules



  ______________________________________________________________________

  1.  Introduction

  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 (), 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.


  1.1.  Copyright of this document

  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 linux-howto@metalab.unc.edu via email.


  1.2.  Where to get this document

  The most recent official version of this document can be obtained from
  the Linux Documentation Project  <http://metalab.unc.edu/LDP/>.


  1.3.  Acknowledgments

  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 after 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.


  1.4.  Disclaimer

  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.


  2.  Hardware Requirements


  From the bttv README:

  Bttv is a device driver for frame grabber cards using the Conexant (
  <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:

    AverMedia TV98

    <http://www.aver.com/products.html>


    AVerMedia TV-Phone

    <http://www.aver.com/lite/products/avertvphone.html>



    Diamond DTV2000

    <http://www.diamondmm.com/products/current/dtv-2000.cfm>



    Hauppauge Win/TV pci (and other Hauppauge cards)

    <http://www.hauppauge.com/>



    IDS Imaging FALCON

    <http://www.ids-imaging.de/>



    Lifeview Flyvideo II

    <http://www.lifeview.de/lifeview/html/produkte.htm#karte>



    Matrix Vision MV-Delta

    <http://www.matrix-vision.de/>



    miroVIDEO PCTV

    <http://www.pinnaclesys.com/>



    Osprey-100

    <http://www.mmac.com/products/osprey/osprey100.html>



    STB TV PCI

    <http://www.stb.com/products/multimedia/tvpci/tvpci.html>



    Terratec TERRA TV+

    <http://www.terratec.de/produkte/terratv/terratv_info.htm>



    Videologic Captivator PCI

    <http://www.videologic.com/Productinfo/capt_pci.htm>



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


  3.  Software Requirements

  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.

  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 , and an even more updated version is available from
  Gerd Knorr at These packages add support for more audio chips,
  including the TEA6300, TDA8425, and DPL3518.

  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 .

  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.



  4.  System Configuration


  4.1.  Hardware Installation

  (Thanks to William Burrow for this section.)

  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.

  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.

  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.)

  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.
  4.2.  Kernel Configuration


  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 videodev.o, bttv.o, and tuner.o under
  /lib/modules/2.x.x/misc, you should be ready to go.


  If not, you'll need to recompile your kernel with

  CONFIG_VIDEO_DEV

  and

  CONFIG_VIDEO_BT848

  enabled, preferably as loadable modules.  See the Linux Kernel HOWTO (
  <http://www.linuxdoc.org/HOWTO/Kernel-HOWTO.html>) for details on
  recompiling your kernel.



  4.3.  Using the updated 0.6.x packages

  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


  tar -xvzf bttv-0.6.x.tar.gz

  and change to the newly created directory.  su to root, and type

  make

  in the main directory to create the drivers.  (You can safely ignore
  the information in the INSTALL file about editing makefiles, and the
  like, since we will pass this information to the driver as module
  parameters.) Then, type

  make install

  to install them.  Finally, run

  /sbin/depmod -a

  to update your module dependency information.


  4.4.  Special files in /dev

  Next, you may need to make the special character files in the /dev
  directory.  Type ls /dev/video*; ls /dev/radio* 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 () for the
  programming-related details.



  There is a MAKEDEV script in the driver 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:
  mknod /dev/video0 c 81 0

  chmod 666 /dev/video0

  ln -s /dev/video0 /dev/video


  mknod /dev/radio0 c 81 64

  chmod 666 /dev/radio0

  ln -s /dev/radio0 /dev/radio



  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:

  mknod /dev/vtx0 c 81 192

  chmod 666 /dev/vtx0

  ln -s /dev/vtx0 /dev/vtx


  mknod /dev/vbi0 c 81 224

  chmod 666 /dev/vbi0

  ln -s /dev/vbi0 /dev/vbi



  4.5.  Loading the Modules

  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

  sync; sleep 1; sync

  to flush any dirty disk buffers before proceeding.  Then, using the
  insmod command as root, try loading up the modules.  The first two are
  easy, because they don't usually need any options:

  insmod videodev

  insmod i2c

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

  modprobe bttv

  By default, the bttv module attempts to autodetect your card type.
  Watch /var/log/messages to see what it finds.  If it doesn't
  autodetect properly, you can add the card=n option to the end of the
  previous command to force a card type, with n 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 radio=1 option if your card has FM tuner functionality.


  ______________________________________________________________________
  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
  ______________________________________________________________________



  Next, load the tuner module, with

  modprobe tuner type=n

  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 n from the following
  list (types 8 and 9 are included only in bttv-0.6.4h):


  ______________________________________________________________________
  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
  ______________________________________________________________________



  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.


  modprobe msp3400 or tea3600 or tda8425 or tda9855 or dpl3518(see the
  appendix for details and options)

  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.


  4.6.  Automating the process

  After you know which modules and options you need, you can automate
  the process by putting the information into /etc/conf.modules.  Then,
  running an application which needs the driver will cause it to be
  loaded automatically.  I use the following:


  ______________________________________________________________________
  # 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
  ______________________________________________________________________


  Be sure change this to reflect the proper modules and options for your
  particular card.  (Run an /sbin/depmod -a to make sure all your module
  dependency information is up to date, as well.)


  5.  Applications

  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:


    bttvgrab - Provides high-quality grabbing suitable for video
     recording

  


    Gnome-o-Vision - A viewer for the Gnome desktop environment
     (currently under development in the Gnome CVS)

  

    kwintv - Qt-based TV viewer for the KDE environment

  


    wmtune - window maker radio tuner applet for bttv based TV/radio
     cards

  


    wmtv - WindowMaker TV dock.app

  


    XawTV - a TV application and a few utilities

  


    XtTV - Simple TV/Video program for Linux/X Windows

  


  There is also a driver available for the FlyVideo98 Remote control
  card at

  Be sure to read the documentation 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 must take the time to read the
  documentation on most of these, as the application defaults will most
  likely not work for your card.


  6.  Appendix - Arguments for All Modules

  Items preceded with a "*" are only available in the 0.6.4h series
  driver



  ______________________________________________________________________

  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.
  ______________________________________________________________________



