
Bluetooth Driver for Linux Kernel v.2.2.x
------------------------------------------

These files are work in progress. For more information on Bluetooth 
on Linux see http://developer.axis.com where you can find newer 
versions of the software.

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

What's happened lately ?

14 Aug 2000
 
- Fixed inquiry command

- Added connection of SCO link

- Remade the way configuration are done, added functions 
  l2ca_local_conf_done() and l2ca_remote_conf_done() used by 
  upper layers to know whether they need to resend a config 
  message.

- Now send config_cfm only when entering OPEN state

- Fixed MTU reconfiguration

- If l2cap_send_data cannot send a data chunk for some 
  reason, it sets the buffer as flushed and returns error. 
  Next time someone tries to subscribe a buffer in btmem 
  the chunk is unsubscribed

- Added support for dialup profile

- Fixed bug with sending MSC command during connection

4 Aug 2000

- Added fix in bt_tty_close (bluetooth.c) which notifies upper application 
  on ttyBT0 when lower driver got hungup. (Mark Douglas Corner)
- Added l2cap ping 
- Added test interface for unplug fest
- Updated test.c

3 Aug 2000

- Added possibility to run btd with stack in usermode, now you can 
  run gdb on the stack and really see what's going on... 
  We are working on getting pppd to work with the user stack aswell
  
- Bug fixes in several files from people on the list, thanks !

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

July 25, 2000 

- Added /proc file support, (/proc/bt, still more to do...)

- Cleanup and added automatic restart of btd after setting bd address

- Fixed bugs in blueooth.c regarding interface up to user level
  when using N_TTY line discipline i.e using ttyBT0 as a virtual 
  serial port.

- Fixed bug in l2ca_disconnect_req that actually removed the l2cap connections
  and shutdown baseband when no more was left
  
- Fixed bug when inserting new connections over the same hci handle. 
  Forgot to add BD address, link_up, initiator in new l2cap_con

- Added checks after each subscribe_bt_buf to return error if subscribe failed
  After failing to subscribe a buffer in l2cap_cmdrej we tried to use a NULL 
  pointer, not very nice...

- Added debug printouts when issuing a l2cap_cmdrej packet

- Forgot to include l2cap header when comparing received len with mtu 

- Added status struct to store bytes received/sent etc

- Skeleton for TCS, feel free to dig in :)

- Lots of cleanup, however still lots more...

- Added version tags in each file to make it easier to match files
  against each other

- Added btconfig.h which contains all defines necessary for different
  setups of the stack (HCI emulation etc)

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


Previous releases:

- Fixed bug in memory handler (didn't handle full buffers correctly)
- Added some new commands in bluetooth daemon
- !!! MAJOR number for BT driver has changed to 124 (previous : 62) !!!
  Please update device node (see below *** NEW ***)
- Kernel support v 2.2
- Tested client functionality
- Bug fixes from unplug fest 
- HCI emulation
- Better support for multipoint (untested)
- More general parsing in SDP
- Added client functionality (untested)
- More fault detection
- Support for initialization of BT hardware (Ericsson module/
  Digianswer rs-dongle)

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

Currently the following problems with the BT stack kernel 
integration have been found. If you manage to repeat/fix a problem, 
please post to bluetooth-dev@axis.com

* Lost sync in hci_receive_data()

  The setup here is a standard pc linux machine running the stack
  and is connected to a digianswer rs232 dongle using a null modem 
  serial cable.
  
  The problem is that we sometimes get erroneous data fed into the 
  hci state machine when transferring a lot of data on the link. 
  If we get a byte that is not understood (e.g wrong uart header 
  on a hci packet) we loose sync and must reset the state machine 
  to find the start of a new hci packet. We think this is caused by 
  overwriting of the flip buffers in the serial driver but we're 
  not sure. However, it doesn't happen too often...


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

Things to do :

* TCS
* Make SDP more general i.e no static entries
* More control from user mode application
* Better documentation

If you are interested in helping us by any of these things, please post to
bluetooth-dev@axis.com

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


Best regards 
Bluetooth team at Axis Communications.


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

- Docs 

How do I install AXIS bluetooth stack ?
---------------------------------------------

# Unpack the tarball :

tar xvzf <file>

# Make the bluetooth stack module

cd bluetooth
cd src
make

# Make the bluetooth application

cd ..
cd apps
make

# Insert the module:

insmod bt.o

# To get debug messages in kernel start another window and issue :

tail -f /var/log/messages 
(or whatever file your kernel logger is set to use)

# Then you have to create the file node (as root) for the 
  bluetooth driver in user mode (this will be done from a script 
  later on)

*** NEW ***
mknod /dev/ttyBT0 c 124 0


For now only use a single tty (ttyBT0) since multipoint functionality 
still is untested !


APPLICATION 
-----------

syntax:  ./btd [options]
     
     options: 
              -u <uart device>
              sets which uart device that will be used by the stack
              default: ttyS2

              -b <bluetooth device>
              sets which bluetooth device that will be used from application
              default: ttyBT0
 
              -s <speed>
              sets uart speed
              9600, 19200, 38400, 57600, 115200, 230400, 460800
              default: 115200 baud
                 
              -r <role>
              sets application role (server or client)
              default: server
              
              -i <HW initialisation> 
              hw specific initialization
              ericsson, digi (digianswer rs232 dongle)
              default: ericsson

              -l
              use the IP number of eth0 as local address

              -m
              enters command line mode
              default: skip command line mode

              -R
              reset bluetooth hardware before use
              default: no reset

              -e <0/1>
              Modem emulation on/off (used to emulate modem when using dialup
	      in windows) 
              default: on

     e.g if using ericsson module at 115200 baud and acting server
     ./btd -s 115200 -i ericsson

     if using HW that req no init and acting client with command line interface
     ./btd -r client

     if using non default devices
     ./btd -u /dev/ttyS2 -b /dev/ttyBT3 [options...]




How do I setup a session between two units ?
---------------------------------------------

Server side:

1. btd -R -s 115200 -i ericsson

Client side:

1. btd -R -s 115200 - i ericsson -r client
2. Connect to the other unit by doing
   connect <bd address> 0


What do the menu options do?
----------------------------

con <xx:xx:xx:xx:xx:xx> <profile>
 
 Connect to BT device with BD_ADDR <xx:xx:xx:xx:xx:xx> using <profile>
 profile is one of: 
  0 - Serial profile
  1 - Lan profile

disc <handle>

  Disconnect from the connection with handle nbr <handle>, 
  <handle> is the number you previously got when connecting.  
  Currently <handle> isn't used at all due to lack of multipoint support in HW. 

send <nbr bytes> <nbr repeats>
 
 Just send chunks of data. <nbr bytes> are sent <nbr repeats> 
 times. Data is sent using the RFCOMM protocol layer

me <1/0>
 
  Turn modem emulation on/off. Modem emulation is used on the 
  server side to fool a windows client that it is talking to a 
  modem. The emulation answers OK to all AT*\r\n sequences. 
  When it receives ATD*\r\n it quits and starts ppp instead.

setbd <xx:xx:xx:xx:xx:xx>
 
  Set the BT device BD_ADDR to <xx:xx:xx:xx:xx:xx>

readbd
 
  Get the BT device BD_ADDR
  
reset

  Reset the BT device.

ppp
 
  Quit btd and start ppp to the peer instead.
  
quit

  Just quit.


How do I setup a session if I don't have any bluetooth hardware ?
-----------------------------------------------------------------

Compile the module with the define HCI_EMULATION (btconfig.h) defined. 
Then connect 2 Linux PC with a null modem cabel, and start the btd application
as server as one side and btd as client on the other side.

Server side:

1. start btd with the option
   btd -e 0 -i no_hw

Client side:

1. start btd with the option
   btd -r client -e 0 -i no_hw
2. Connect to the serverside by doing
   connect 11:22:33:44:55:66 0 (actually the bd address does not matter in
   this case)


How do I use the stack in user mode instead of the kernel ?
---------------------------------------------------------

See README.userstack


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

   
Short description of stack integration in kernel
----------------------------------------------------


1) PPP over serial (standard way): 

  user app (pppd)
       / \
-------| |------------------
       \ /
  -------------
  |   tty      |
  |           <----> line discipline (PPP)
  -------------
  | tty driver | (serial driver)
  -------------
       / \
-------| |------------------
       \ /
       UART



2) PPP over bluetooth:

  user app (pppd)
       / \
-------| |------------------
       \ / ttyBT0
   --------------
   | tty | ldisc-> PPP ldisc
-----------------------------------------------
   | tty driver | (bluetooth driver)
   -------------
   |            | <-------        
   |  BT STACK  | <-----  |            ADDED
   |            | <---  | | 
   -------------      | | |
   |   ttyS0    |     V V V
   |       ldisc->  BT ldisc 
-----------------------------------------------
   | tty driver | (serial driver)
   -------------
        / \
--------| |------------------
        \ /
       UART

ttySx is a standard serial port tty.
ttyBTx has a separate major nbr and has been registered to 
use bt driver as tty driver.

ttySx is opened initially from a bluetooth control-application
which sets the bt line discipline and keeps the tty open.

When ttyBT is opened from pppd it is set to use ppp discipline 
which in turn uses the driver registered in its tty i.e the bt 
driver.

At the stack top it acts like a serial driver for ppp
At the bottom the stack acts like any line discipline used from 
the standard serial tty.


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


             - Glue Layers for stack - 

                "APPLICATION" (here:ttyBT)
       ---------------------------------------------
 TOP   | bt_recieve_top()  |    bt_write_top()     |
       ---------------------------------------------
                ^                       |
                |                       V
  
 
                     T H E  S T A C K 
     
                                     
                ^                       |
                |                       V
        ----------------------------------------------------
 BOTTOM | bt_receive_lower_stack()| bt_write_lower_driver()|
        ----------------------------------------------------
              "PHYSICAL DRIVER" (here:serial driver)


- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -