Transport Drivers for BlueDrekar(TM) Middleware



1. UART Transport driver


I. INTRODUCTION

This transport driver for BlueDrekar*(TM) middleware is a reference 
implementation of the Bluetooth**(TM) Host Controller Interface (HCI) 
UART transport layer. 

Bluetooth wireless technology is expected to emerge as a key enabler 
of mobile and wireless Internet services, mostly extending Internet 
connectivity over next generation cellular technologies into a 
collection of locally-connected devices.

BlueDrekar protocol driver is IBM's new middleware based on the 
Bluetooth specifications. BlueDrekar middleware will allow Bluetooth  
wireless devices - from phones to household appliances - to reliably 
communicate with each other. IBM intends to seek certification from the 
Bluetooth Special Interest Group to demonstrate that the BlueDrekar  
middleware along with this transport driver are compliant with Bluetooth 
Specifications.



II. OVERVIEW

The Bluetooth wireless technology is a short-range wireless 
connectivity technology with particular focus on a specification that
lends itself to a low cost, low power and integrated implementation. 
The Bluetooth project team in IBM Research has been an active 
participant of the Bluetooth Special Interest Group (SIG) since its 
inception in early 1998 and has led IBM's involvement in the 
technical activities of the SIG. We have been developing a 
reference implementation of the protocol stack. We are making 
our reference implementation and interfaces available to the 
Bluetooth adopter members and promoters in order to enable them to 
develop exciting applications and paradigms around this technology. 

We anticipate that short-range wireless technologies such as the 
Bluetooth wireless technology will revolutionize mobile and pervasive
computing and wireless internet paradigms. Considering a wide range 
of computing and communication devices, including PDAs, notebook 
computers, pagers, cellular and cordless phones with different 
capabilities, a "smart" short-range wireless connectivity solution 
can be a major enabler for new and exciting usage scenarios. Our goal
is to develop a community based on our offering and foster pervasive 
computing and wireless internet services and applications based on 
the Bluetooth wireless technology. 

Our offering includes source code of the HCI UART transport driver 
for the BlueDrekar middleware. The Host Controller Interface (HCI) 
transport layer is defined in the Bluetooth standard specification. Currently, 
our offering only supports the HCI UART transport layer. This can be 
downloaded at IBM's developerWorks site under the GNU public license. 

This code can be referred to as a template to help one write 
a transport driver for other HCI transport layers such as for USB. 

This transport driver can be used with the BlueDrekar software package. This
package can be downloaded at IBM's alphaWorks site  under the alphaWorks 
license.



                      



III. SYSTEM REQUIREMENTS

We have developed and tested the code using IBM compatible PCs with
i486 or higher processors running Linux Kernel 2.2.12-20 (Red Hat***(TM)
6.1), 2.2.14-5.0 (Red Hat 6.2), 2.2.16-22 (Red Hat 7) and 2.2.18 (with
modutils upgraded to 2.3.11).
The Bluetooth hardware module we have used to test the code is
Ericsson's Bluetooth Hardware Module with HCI UART transport layer,
firmware version P7C (v1.0A) and P3E (v1.0B). We have developed a
big Endian version of the code on a power PC platform using MPC823
running embedded Linux (Kernel version 2.2.0-pre7) using
the iPengine****(TM) card from Bright Star Engineering Co..
We have also developed a big Endian version of the code on strongARM
processor using SA1110 running embedded Linux (Kernel version 2.4.1)
using the nanoengine*****(TM) card from Bright Start Engineering Co..

System requirements:

- i486 or higher processor with a free serial port.
- Linux with Kernel 2.2.12-20 or higher with a standard serial driver.
- Ericsson's Bluetooth Hardware Module with HCI UART transport layer 
or equivalent Bluetooth radio modules that is compliant to the 
Bluetooth standard version 1.0.


Note : *         BlueDrekar is a trademark of International Business Machine Co.
           **       The BLUETOOTH trademarks are owned by their proprietor
                      and used by IBM Corp. under license.
           ***      Red Hat is a trademark of Red Hat Software, Inc.
           ****    iPengine is a trademark of Bright Star Engineering Co.
           *****  nanoengine is a trademark of Bright Star Engineering Co.



IV. INSTALLATION

1) Initial Installation of the Package:

This installation requires root permissions. 

Step 1) Untar the source tar file using 
                  "tar xvf tp4bduart-xx.tar" 
                      where xx is the software version number. 

Step 2) Read README file in tp4bduart directory.

Step 3) Run "./install" without quotes in tp4bduart directory. 
                (This will compile the code and copy the binary files and 
                 script files to bin directory.)


2) Loading the Driver:

The driver must be loaded as root.

Step 1) Run "./start" without quotes in tp4bduart/bin/ directory.

Step 2) At this point, you may want to load a protocol driver. 
             The BlueDrekar protocol driver can be downloaded at IBM's 
             alphaWorks site  under the alphaWorks license.


3) Unloading the Driver:

Ensure to unload the protocol driver first if a protocol driver
was loaded in addition to the UART transport driver. 
Also, make sure the transport driver is not being used.

The driver must be unloaded as root.
Step 1) Run ./end in tp4bduart/bin/ directory.



V. DIRECTORY STRUCTURE

This package has the following tree structure --


                   - bin 
                   | 
                   |
tp4bduart --|
                   - man-----------man7 
                   | 
                   - src 

Individual directories -


(1) bin :

Binaries generated by compiling the source will be copied here at
the end of the build process.

This directory contains the "start" and "end" script files.
These script files are placed here after having run the "install"
(See Installation section above.)
 

(2) man :

man/man7: contains the manual page for the transport driver for
the HCI UART transport layer.
 

(3) src :

This contains the source code of the UART transport driver,
"Makefile", "start" and "end" scripts.



VI. PROGRAMMING INTERFACE ROUTINES

There is a manual page for all supported programming interface 
routines. The install process installs the man pages in the 
/usr/local/man directory.

Run "man tp4bduart" to see the details.



VII. HOW TO WRITE YOUR OWN TRANSPORT DRIVER

We have provided the source code of the line discipline driver that 
contains the HCI UART transport layer under the GNU license. This 
module may be used as a reference in order to write your own HCI 
transport driver.

This package also includes a manual page that describes about all 
supported programming interface routines that are being used to 
communicate with the BlueDrekar protocol driver.
Makefile for this driver is also available as a part of the package. 
Refer to the Bluetooth standard specification if additional details
of the HCI Transport layers are needed.



VIII. FREQUENTLY ASKED QUESTIONS (FAQ) 


1) What is Bluetooth?

The BLUETOOTH trademarks are owned by their proprietor and used
by IBM Corp. under license. The Bluetooth wireless technology has
been standardized by a consortium formed by five initial promoter
companies, IBM, Ericsson, Nokia, Intel and Toshiba and supported
by over 1800 companies as of June 2000. This technology uses
ISM band radio frequency with fast hopping spread spectrum and has
a range of 10 meters with a provision to increase it to 100m.
Within this range, one master device and up to seven active member
devices form a piconet. A provision to communicate between multiple
piconets is called a scatternet. The protocol stack includes,
the RF and baseband that is the physical layer, Link Manager,
Host Controller Interface (an optional layer in case there is
a split between the radio module and the host device),
Logical Link Control and Adaptation Protocol (L2CAP) layer,
RFComm layer, Telephony Control Protocol (TCS) layer, and
Service Discovery Protocol (SDP) layer.

The Bluetooth standard was named after Harald Blaatand 
"Bluetooth" II, a Viking king in Denmark during 940-981AD. 


2) What is included in this package?

The IBM reference implementation of the Bluetooth HCI UART transport 
driver can be downloaded at IBM's developerWorks site under the 
GNU public license. 

The IBM reference implementation of the higher layer protocol stack 
called BlueDrekar middleware can be downloaded at IBM's alphaWorks 
site under the alphaWorks license.

The UART transport driver can be used as a transport driver for the 
BlueDrekar protocol driver if you are using a Bluetooth wireless 
module with the HCI UART transport layer.


3) How compliant is it?

The code is written based on the Bluetooth wireless standard version 
1.0A and 1.0B. The reference implementation of the standard is an 
on-going project at IBM. The implementation could be enhanced with 
more features and functions and could be upgraded to a newer version 
of the standard without any notice as newer versions are available. 
IBM intends to seek certification from the Bluetooth Special Interest
Group (SIG) to demonstrate that the first version of the UART 
transport driver is compliant with Bluetooth Specifications.
At the time of release, this code was tested with the Ericsson's 
Bluetooth hardware module (UART version). 


4) How do I install the driver?

The transport driver package includes a step by step installation 
procedure. Please refer to the README file.
The package contains a script called "start" (without quotes) to 
load a loadable module, ldisc_bt.o. This will load the transport 
driver only. After loading the transport driver, the BlueDrekar
protocol driver could be loaded in order to provide support for 
the higher protocol layers. The BlueDrekar software package is 
available at IBM's alphaWorks site.

The source code for this UART transport driver is provided and
should be compiled using the provided "install" script.


5) How do I write my own transport driver?

This package includes source code and manual pages for interface 
routines as well as Makefile, include files and README document. 
One can use this as a template to write one's own transport driver 
that will work with the BlueDrekar protocol driver. If more detail 
information about the HCI transport layers of the Bluetooth wireless 
technology is necessary, you should refer to the Bluetooth standard 
specification. 


6) Will this transport driver work with 2.4.* kernels?

The transport driver source code provided here works fine for linux
kernels 2.2.12 through 2.2.18. For 2.4.* kernels, the following change
has to be made to the source code:

"tp4bduart/src/ldisc_bt.h" Line 87 of 209:
#define N_BT 14
                            must be changed to:
#define N_BT 15



IX. BLUEDREKAR TEAM

The BlueDrekar project team in IBM Research is a part of the 
Pervasive Security and Networking Department led by Mahmoud 
Naghshineh. The team has been an active participant of the Bluetooth
Special Interest Group (SIG) since its inception in early 1998 and it 
has led IBM's involvement in the technical activities of the SIG. It 
has contributed heavily to the development of the Bluetooth 1.0 
specification. Team members have served as editors for the HCI RS-232
transport and Service Discovery Application Profile (SDAP) parts of 
the specification. The team is a strong advocate of the Bluetooth 
wireless technology both inside and outside IBM, where they have been
invited to speak about the technology on several occasions.

The current members of the BlueDrekar team are: 

Stefan Berger                IBM Corporation          stefanb@us.ibm.com
Chatschik Bisdikian       IBM Corporation
Frank Janniello              IBM Corporation
Parviz Kermani              IBM Corporation
Nathan J. Lee                IBM Corporation         njlee@us.ibm.com
Mahmoud Naghshineh   IBM Corporation
Sumanth Reddy             IBM Corporation
Jim Rubas                     IBM Corporation          rubas@us.ibm.com