BlueNIC - Bluetooth PAN profile implementation for BlueZ
Copyright (C) 2002 Sony Corporation

Written 2002 by Johannes Loebbert <loebbert@sony.de>

This package includes BNEP loadable module and tools for PAN profile.

Roles
--------
The PAN profile defines the following three roles:
PANU (Personal Area Network User)
- Device participating in a IP network over Bluetooth
- Support for all BNEP packet types (Includes all compression methods)
- Support for extension header compression
- Interpretation of 802.1p headers

GN (Group Ad-hoc Network)
- Full PANU support
- Enables slave-slave communication by forwarding packets between 
  connected PANUs.

NAP (Network Access Point)
- Full PANU support
- Full GN support
- Connects the Bluetooth network domain with the wired network.

BlueNIC supports all three roles according to the PAN profile v1.0
specification.


Architecture
---------------
The BlueNIC PANU implementation registers a Linux network devices
using one Bluetooth device. The MAC address of each BT/eth device pair
is the Bluetooth address of the associated Bluetooth device. The
functionality is implemented in a loadable module, which can be
controlled by a user space application.

The GN bridging functions are also included in the module, to enable
filtering and compression functionality, which are defined in the PAN
profile. Examples are filters for specific protocols, multicast
addresses and header compression when forwarding packets in the
Piconet.

The standard Linux bridging module, which can be controlled by the
brctl tool, implements the NAP functionality. The bridge module
bridges transparently between any Linux Ethernet device, like wired
Ethernet, 802.11 and also the Bluetooth BlueNIC module.


Control 
-----------------------
BNEP module is controlled with two programs
  pantool: PAN administration tool for device and connection control
  pantest: PAN testing tool for IoP/UPF
See manpages for more information.


Install
--------
See INSTALL.


Usage
--------
[Setup for NAP/PANU/GN]
0) Make the software
     ./configure
     ./make 
    ("./make install" if you want to install)

1) Setup BlueZ

2) Initiate the HCI devices with the right LM settings (NAP/GN: Master)
     e.g. "hciconfig hci0 lm master,accept" for NAP/GN

3) Insert the kernel module
     modprobe bnep (when installed)
       or
     insmod bnep.o

4) Create PAN Interface:
     pantool [-i ethX] insert [hciX|bdaddr] [-s <PANU|NAP|GN>]
                           (default values: ethX is eth1, role is PANU)
     e.g. "pantool -i eth0 insert hci0 -s NAP"
           when you use hci0 as eth0 in the role of GN.
   If you have only one BT device, you can do
     e.g. "pantool -i eth0 insert"

4') Setup/Change Role
     pantool [-i ethX] role -s <PANU|NAP|GN>
     e.g. "pantool -i eth0 role -s GN"
          when you'd like to change a role into GN.

5) Setup IP settings
     ifconfig <ethX> <ip_address>

[Setup for NAP bridging]
0) Download and install the bridge control program 
     For RedHat-i386, bridge-utils-0.9.3-1.i386.rpm
    (you can get it from http://bridge.sourceforge.net/)

1) Enable Linux bridging support 
     Switch: Networking options => 802.1d Ethernet Bridge
     modprobe bridge (when compiled as module)

2) Start the bridge
     brctl addbr bt

3) Add wired network interface to bridge
     brctl addif bt <ethX>

4) Add PAN interface to bridge
     brctl addif bt <ethY>

5) Start bridge
     ifconfig bt <ip_address> <ifconfig_parameter>

[Connect]
1) Create BNEP connection:
     pantool [-i ethX] cc <bdaddr> [-d <PANU|NAP|GN>]
                            (default destination service is NAP)

[Get Status]
1) Get PAN interfaces status:
     pantool status

[Disconnect]
1) Disconnect the connection:
     pantool [-i ethX] dc <bdaddr>


Architectural decision
---------------------------
The implementation as a kernel module was chosen, to make the usage as
simple as possible and provide the user a transparent transport medium
like any other network card.

The module uses a script language to build up packets in the kernel
with different extension header and payload specification and send
them over the Bluetooth link. The approach was chosen, because some
packets have to be resent, when the receiver does not send back a
notification after the timeout.

The GN implements an own code because the normal bridge code does not
support the following features:
- Header compression when forwarding packets 
- Network protocol filter
- Multicast filter
- BNEP extension header handling
- 802.1p  (required for the PAN)
Now, it supports all features.

The BNEP layer uses the L2CAP socket interface form within the kernel
by setting the fs to the kernel space. The socket calls are called by
kernel threads. Each connection has one thread to listen for incoming
data. For each device a thread is listening for new incoming
connection requests and for sending data over the physical device.


SDP
-----
Syntax: 
  sdpc -s <service_uuid> -f <first_attribute> -l <last_attribute> <remote_bdaddr>

The command issues a ServiceSearchAttribute query and decodes the answer. 

The folder also contains a XML file for the AXIS SDP - server port. 
It provides the records for all three PAN services. Before using the
file, some of the values have to be adopted to the system
(e.g. computer names).

Note: It will be updated for bluez-sdp in the future.


HCIDUMP
---------
PAN support patch is integrated into hcidump-1.2.tar.gz.
Please use HCIDump 1.2 or later version.


Information
-------------
You can download this package at 
  http://www.sony.co.jp/en/Products/Linux/Download/Bluetooth.html


Happy networking,

Johannes Loebbert <loebbert@sony.de>
Takashi Sasai <sasai@sm.sony.co.jp>


