
                            Bluetooth-alsa Project

   This project provides a way to use a bluetooth headset with Linux. We
   do this currently by making an alsa kernel driver which uses bluez to
   reach the headset. It works well enough now to get voice-quality audio
   to and from most headsets. We've had success with:
     * BlueTrek 1
     * Bluetake iPhono BT420 (using either sco or a2dp)
     * Canyon CN-BTH1 (must click headset's volume-up button after each
       connection)
     * Ericsson HBH-60
     * Ericsson HBH-35
     * Jabra BT200, BT250
     * Jabra BT110 (will turn off very soon after the last audio packets
       have been transmitted and btsco will quit with "RFCOMM channel
       lost")
     * Logitech HS01 (has a noisy microphone?)
     * Logitech Mobile F-0179A
     * Logitech Mobile F-0228A
     * Motorola HS801 (volume must be changed from headset?)
     * Motorola HS810/HS850 (may work "better" if you manually specify
       the handsfree channel, 8)
     * Plantronics M2500 (this headset has a surprising range >15 meters)
     * Siemens HHB-600

   We currently don't have any code to make the connection to an audio
   gateway (typically a cellphone). There's a [1]project associated with
   asterisk and a [2]standalone app for using a cellphone.

  Features

   We have code to make a headset connection (using the btsco daemon) to
   send audio through the alsa system and we have separate code to send
   stereo audio to the a2dp device using a userspace program (a2play).
   Only a couple of headsets can accept stereo audio so try the btsco
   stuff first.

  Build

    1. Install or update the required packages:
          + automake-1.7
          + libbluetooth-dev (aka libbluetooth-devel or bluetooth-devel)
          + libasound2-dev (aka alsa-devel)
          + a recent (2.6.11.7 or newer) kernel with *integrated* alsa
            enabled (it won't work with the "standalone" alsa drivers
            that are a separate download from the kernel)
    2. Check btsco out from cvs:
        cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/bluetooth-alsa login
        cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/bluetooth-alsa co btsco
    3. Compile:
        ./bootstrap
        ./configure
        make
        make install
        make maintainer-clean
    4. For SCO (two-way voice quality audio) you need a kernel with the
       emu10k1 driver selected (this is one of the drivers that forces
       the inclusion of the implementation of "snd_hwdep_new"). Build the
       kernel module:
        cd kernel
        make
        make install
        depmod -e
        make clean

  Using SCO audio

    1. insert the module (or better, set up the alsa configuration to
       load it)
        modprobe snd_bt_sco
    2. stop the esound controller if it's running via
        esdctl stop
    3. run
        hciconfig hci0 voice 0x0060
    4. turn on the headset (you may need to prepare the headset to be
       paired the computer, usually by turning on the headset and holding
       the on button until it beeps; make sure the headset has not
       connected to your cell--this would block the computer's
       connection.)
    5. run the handler (let it keep running if you run in the foreground)
        btsco bdaddress
    6. You probably need to enter the passkey if it's the first time
       'round
    7. send and receive audio from the headset (usually using /dev/dsp1)
       or via the alsa device with something like
        aplay -B 1000000 -D plughw:Headset sound.wav

   Right now the daemon interaction is somewhat limited:
     * Put alternating lines of regexes and shell commands in ~/.btscorc
       and when something that the headset sends matches these regexes,
       the shell command is run (with any back references \0 \1 etc
       replaced from the regexp, \s replaced by the link state and \p
       replaced by the daemon's pid). This, of course, is primarily
       intended to "do stuff" when the headset button(s) are pressed.
     * Send SIGHUP to the userspace program to make it re-read the config
       file.
     * Send SIGUSR1 to the userspace program to make the headset ring.
     * Send SIGUSR2 to the userspace program to force a headset
       reconnect.

  Stereo (A2DP) Streaming

   A2DP provides a way to send stereo high-quality audio to some of the
   newer headsets. On all the headsets I've seen so far, this is one-way
   audio, so if you were expecting to get something like a gaming headset
   (talking to other players, getting stereo sound back from the game),
   you should wait for the next generation of headsets to get 2-way A2DP.

   Right now A2DP transmission requires a helper app to bring in audio.
   Hopefully we can remove this requirement. From the btsco directory
   after a successful make:
        mpg123 --au - file.mp3 | ./a2play 00:0D:3C:30:32:AD

   Where you replace file.mp3 with a good mp3 file and bdaddr with the
   address of your headset. If you have trouble with using a2play, let us
   know on the mailing list if this works for you instead:
        mpg123 --au - file.mp3 | sbc/sbcenc - | ./sbc/rcplay 00:0D:3C:30:32:AD
-

   You can send live audio from line-in etc using a command like:
        ./a2play -s -d -r 44100 00:0D:3C:30:32:AD /dev/dsp

   Don't be surprised to get a delay. It's probably under 500ms but not
   much under that.

   Mayank Batra contributed a2dp sink code. This should allow you to
   receive a stream from another device. Run it with:
        hciconfig hci0 class 0x200404
        sdptool add A2SNK
        ./a2recv

   It will try to bind to the bluetooth adapter and send audio out to
   /dev/dsp.

  A2DP userspace plugin

   We're not being totally true to the project name at this point...
   there's not an ALSA connection yet with hifi.

   If you want to experiment with the early alsa userspace plugin work,
   go to the directory 'bt' in the cvs archive (yeah, great name but
   renames are a pain in cvs :) and have a look at the BUILD docs there.
   Or look in bluez/tools in cvs and you'll find an alsa driver there.

  Links

     * [3]Bug list at sourceforge
     * [4]Bluez main page

  Discussion

   This code is experimental, so the best place to talk about it and
   submit changes is on the bluez-devel mailing list.

   If things aren't working as you expect, some of the things that can
   help us track it down are:
     * Whether there is a hub between your computer and bluetooth adapter
       (you should avoid this [5]especially if it's a usb 2.0 hub)
     * Manufacturer and model of headset and bluetooth adapter
     * Output from hciconfig -a
     * Output from hciconfig hci0 revision (Run hciconfig as root)
       If it says "SCO mapping: PCM" then you need to get a different
       bluetooth adapter (or possibly to update the firmware using pskey
       from bluez-utils-cvs if you're ambitious)
       If it says the chip version is a broadcom chip, get a better
       adapter
       If it doesn't say anything at all about SCO mapping, you probably
       need a different bluetooth adapter (preferably "CSR" based)
     * Output from hcitool info bdaddr where bdaddr is the headset's
       address
     * Output from hcidump -X while running btsco or a2play if
       appropriate
     * The output btsco -v or a2play prints to the screen
     * Your kernel version and bluez userland versions or distro
     * Result when trying it with a recent kernel if possible (eg 2.6.11)
     * If you have a headset that can do a2dp, try both btsco and a2play
       (the significance is that the latter does not use SCO)
     * If you can try another bluetooth adapter or headset, let us know
       if that helps (the adapters are cheap now, eh? :)

  Credits

   Some instrumental people in this effort:
     * [6]Jonathan Paisley (retired from the project) started it up and
       wrote much of what we have now
     * [7]Niko Berger brought the patches forward to 2.6.7 and 2.6.8
     * [8]Lars Grunewaldt [largegreenwood (at) users.sourceforge.net]
       added some stuff to the userspace daemon and is working on mode
       change hooks
     * [9]Marcel Holtmann has always been the key developer for bluez and
       has recently jumped in and helped a lot with our project
       specifically
     * Henryk Ploetz donated SBC manipulation code and brings a
       significant understanding of this codec
     * [10]Brad Midgley is doing documentation, A2DP protocols, vendor
       relations, and project coordination
     * Fredrik Tolf has been fixing up daemon/userspace interactions
     * Mayank Batra contributed a2recv.c for A2DP sink support

  Our Sponsors

   [11][gumstix.gif] 

   Gumstix provides brilliant embedable xscale boards with bluetooth
   [12]SourceForge.net Logo 
     _________________________________________________________________

   The [13]bluetooth-alsa project pages

References

   1. http://www.crazygreek.co.uk/content/chan_bluetooth
   2. http://www.soft.uni-linz.ac.at/_wiki/tiki-index.php?page=ProjectBluezHandsfree
   3. http://sourceforge.net/tracker/?group_id=116589&atid=678258
   4. http://www.bluez.org/
   5. http://sourceforge.net/mailarchive/message.php?msg_id=11431438
   6. http://www.dcs.gla.ac.uk/~jp
   7. http://www.gargan.org/
   8. http://www.dark-reality.de/
   9. http://www.holtmann.org/linux/bluetooth/
  10. http://www.xmission.com/~bmidgley/
  11. http://www.gumstix.com/
  12. http://sourceforge.net/
  13. http://sourceforge.net/projects/bluetooth-alsa/
