Package de.avetana.bluetooth

Package de.avetana.bluetooth Description

This package provides an implementation of the JSR 82 specification from Sun Microsystems (c). The aim of this specification is to easily develop Bluetooth-based applications in java. It does not exist (as I am writing these comments) any universal implementation of the Sun Specification.
The Avetana Bluetooth package is available under three operating systems: Linux (GPL version), Windows and Mac OS X (commercial versions) and is NOT a 100 % pure Java implementation. The use of JNI technologies allows to communicate with the hardware and system-specific bluetooth stack.
Under Linux you must have a kernel version > 2.4.20 or at least you must have the BlueZ kernel modules installed AND loaded.

Package Specification

For JSR82-Specification, please see

• The Java Community Process - JSR 82
• Article - The Java API s for Bluetooth Wireless Technology

Related Documentation

For overviews, examples, guides, and tool documentation, please see the API documentation and the documents stored in the directory named "doku".
The class de.avetana.bluetooth.JSRTest2 gives an overview of the possibilities offered by this implementation.
Please refer to the following tutorial, too.

Quick Tutorial

Management of the local Device

The JSR82 Specification allows to work only with one Local Device, which is accessible with the help of the static method:

LocalDevice m_local=LocalDevice.getLocalDevice();



You can now retrieve some properties of your local device:

//retrieves the BT address of the local device
LocalDevice.getBluetoothAdress()

//retrieves the name of the local device
LocalDevice.getFriendlyName()

// retrieves the discoverable mode. Beware, this method often requires root privileges
LocalDevice.getDiscoverableMode()


The method getRecord(ConnectionNotifier) and updateRecord(ServiceRecord) cannot be directly used here.
They suppose that you have already created a service waiting for incoming connections.

Device/Service Search

With your LocalDevice you can retrieve the DiscoveryAgent which will help you to perform an HCI inquiry (Device search) or a service Search.

//retrieves the DiscoveryAgent
DiscoveryAgent m_agent=LocalDevice.getDiscoveryAgent()

Whatever the search you want to perforn you need beside your DiscoveryAgent a DiscoveryListener.
The DiscoveryListener will set the way your application react each time a new device or a new service is found, but also when the searches terminate normally or abnormally.

Example of a device search

DiscoveryListener myListener=new DiscoveryListener() {
  public void servicesDiscovered(int transID, ServiceRecord[] servRecord) {
    //does nothing
  }

  public void deviceDiscovered(RemoteDevice btDevice, DeviceClass cod) {
    try {
      System.out.println("New Device "+btDevice.getBluetoothAddress()+" found!");
      System.out.println("Remote Name of the device is "+btDevice.getFriendlyName(true));
    }catch(Exception ex) {}
  }

  public void inquiryCompleted(int discType) {
    System.out.println("Device Search completed!");
  }

  public void serviceSearchCompleted(int transID, int respCode) {
    // does nothing
  }
};

try {
   m_agent.startInquiry(DiscoveryAgent.GIAC, myListener);
}
catch(Exception ex) {ex.printStackTrace();}

This example does not implement the part of the DiscoveryListener class used to manage the result of a service search. In this case this does not have any influence, since this little code-fragment is only performing a device search.
A more complete example performing a service search as soon as the device search is completed can be found in the de.avetana.bluetooth.util.ServiceFinderPane class.

I strongly recommand to refer to this class for a pratical example.

Client connection and data exchange

After a service search and the choice of the service you want to connect to, you know the connection URL used to perform a client connection (this URL is given by the method javax.bluetooth.ServiceRecord#getConnectionURL(...)).

Let's suppose that the choosen service waits for RFCOMM protocol based-connections. The form of the URL is:

String connectionURL="btspp://123456123456:1;encrypt=false;authenticate=false;master=true"

To connect to this service, assuming that running is a class variable set to false, when the user presses an UI button labelled Close:

  Connection con=Connector.open(connectionURL);
  Runnable r=new Runnable() {
    public void run() {
      byte b[] = new byte[200];
         try {
            while (running) {
               dataReceived.setText("Received " + received);
               int a = is.read(b);
               received += a;
            }
         } catch (Exception e) {e.printStackTrace();running=false; }
    }
  //Starts the thread used to read data
  new Thread(r).run();

  //Write some data
  ((StreamConnection)streamCon).openDataOutputStream().writeChars("Try to write");

License

In each file related to this project, you will find the following header:

COPYRIGHT:
(c) Copyright 2004 Avetana GmbH ALL RIGHTS RESERVED.

This file is part of the Avetana bluetooth API for Linux.

The Avetana bluetooth API for Linux is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

The Avetana bluetooth API is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

The development of the Avetana bluetooth API is based on the work of Christian Lorenz (see the Javabluetooth Stack at http://www.javabluetooth.org) for some classes, on the work of the jbluez team (see http://jbluez.sourceforge.net/) and on the work of the bluez team (see the BlueZ linux Stack at http://www.bluez.org) for the C code. Classes, part of classes, C functions or part of C functions programmed by these teams and/or persons are explicitly mentioned.

Please RESPECT the terms of this license and commit any changes!!!.

Conclusion

The JSR82 specification is really an easy-to-use development tool for Bluetooth. Moreover the use of the Avetana Bluetooth implementation is transparent for the end-programmer.

This quick tutorial has made a short presentation of the possibilities offered by the Avetana Bluetooth implementation but a look at the JSRTest class could complete this HOWTO.

Several turorials are available on the internet and I strongly suggest to consult them if you are not familiar with Bluetooth, Java or the use of JSR82.
But please keep two things in mind:

• Only RFCOMM and L2CAP protocols are currently supported.
• The linux implementation is free under the terms of the GPL. So if you want to modify some files, please do it and commit any modifications with our CVS Server.