Android Bluetooth Hacking using the NDK

Many people lamented the omission of the Bluetooth APIs from Android 1.1 and 1.5 firmware builds. This post will detail a method of writing bluetooth-enabled apps for Android using nothing more than the recently released Native Development Kit (NDK). You will not have to root your phone. However, since the NDK is available for firmwares 1.5 onwards only, this method will unfortunately NOT work on 1.1 firmwares. Full source for an Eclipse demo project can be found at the bottom of this article. This article builds on my earlier post (Android Hello NDK).

Obtaining the C Headers and Bluetooth System Libraries

The bad news is that you will have to recompile the 1.5 (CupCake) sources with bluetooth support enabled. The somewhat good news is that you can find ready-built binaries and header files for download at the end of this article. If you prefer to build your own library though:

1. Follow the build instructions which can be found in the Android Bluetooth FAQ.
2. Copy the libraries libbluetooth.so and libbluedroid.so into $NDK_HOME/build/platforms/android-1.5/arch-arm/usr/lib/
3. Copy the bluetooth folder from $SDK_SOURCE/external/bluez/libs/include/bluetooth/ to $NDK_HOME/build/platforms/android-1.5/arch-arm/usr/include/

You are now ready to start building bluetooth-enabled apps. Please note that we only need to place the ARM bluetooth binaries in the NDK to resolve link-time dependencies. We DO NOT actually have to deploy/add the bluetooth libraries to our phones using our .apk file, since the very same bluetooth libraries you built from the are already available on the Android device.

Android and Bluez

Bluetooth support on the Android is provided by the excellent Bluez library. There is however a dearth of good information/documentation on Bluez programming. What documentation there is on Bluez programming seems to mostly cover the Python bindings. There is only one resource that I could find which does a decent job of covering C programming using Bluez (See Resources).

The Android Project

This demo application will do a simple scan for bluetooth devices, and populate an Android ListView control with the results. Let us now create an Activity that includes a ListView, declares a native JNI method, and loads a shared library inside a static initializer.

"<project_home>/src/net/bruary/bluescan/BlueScan.java"

 public class BlueScan extends Activity {

  ListView lvDevices;
  private ArrayList deviceArray;
  private ArrayAdapter listAdapter;
  
  /** Called when the activity is first created. */
     @Override
     public void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);

         setContentView(R.layout.main);
    
         lvDevices = (ListView) findViewById(R.id.lvDevices);
         deviceArray = new ArrayList();
         listAdapter = new ArrayAdapter(this, android.R.layout.simple_list_item_1, deviceArray);
         lvDevices.setAdapter(listAdapter);

         String[] devices = btDeviceScan();
    
         for (String device: devices){
          deviceArray.add(device);
         }
    
         listAdapter.notifyDataSetChanged();
    
     }

     /*Our native method which receives an array of Strings back from
      * the C++ shared library
      * */
     public native String[] btDeviceScan();

     static {
         System.loadLibrary("bluescan");
     }

 }

Setting up our NDK Project

Our NDK project is setup as per usual. The notable difference is in our library's Android.mk file, where we now must include the libbluetooth.so library. In the following listing please pay special attention to line #5. Due to a bug in the current NDK, we must explicitly set our library path to $(SYSROOT)/usr/lib. If you omit this, the linker won't find libbluetooth(or libc, libm etc. for that matter)

 LOCAL_PATH := $(call my-dir)
 
 include $(CLEAR_VARS)

 LOCAL_LDLIBS := -L$(SYSROOT)/usr/lib -lbluetooth
 LOCAL_DEFAULT_CPP_EXTENSION := cpp
 
 LOCAL_MODULE    := bluescan
 LOCAL_SRC_FILES := bluescan.cpp

 include $(BUILD_SHARED_LIBRARY)

Shared Library Sources

The following listing shows our C++ implementation of the Bluez code for scanning for some nearby bluetooth devices. I don't want this to devolve into a Bluez programming tutorial, so I will keep my comments brief.
This sourcecode is adapted from the "simplescan" application in the "Bluetooth Programming in C with Bluez" tutorial. Therefore some of the code is a bit redundant (e.g. perror() is redundant in our NDK app). I also don't do any error/exception handling, so please don't deploy this source to production. You've been warned :)

The two bluez API methods we call are hci_get_route() on line 30, which gives us the deviceID of our Phone's bluetooth device. The other method is hci_inquiry() on line 40, which does the actual scanning. Notice that we pass an array of inquiry_info structs to hci_inquiry().
Please do read the article linked to in the Resources section for more details on Bluez programming.

 #include <string.h>
 #include <jni.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <unistd.h>
 #include <sys/socket.h>
 #include <arpa/inet.h>
 #include <bluetooth/bluetooth.h>
 #include <bluetooth/rfcomm.h>
 #include <bluetooth/hci.h>
 #include <bluetooth/hci_lib.h>
 #include <bluescan.h>


 JNIEXPORT jobjectArray JNICALL Java_net_bruary_bluescan_BlueScan_btDeviceScan(JNIEnv *env, jobject obj)
 {
     int max_rsp = 255;
     inquiry_info* infoArray = new inquiry_info[max_rsp];
     inquiry_info **ii = NULL;
     int num_rsp;
     int dev_id, len, flags;
     int i;
     char addr[19] = {0};
     char name[248] = {0};
     bool bHasError =false;
     jstring errMsg; 

     jobjectArray btDevices;

     dev_id = hci_get_route(NULL);
     if (dev_id < 0 ){
         bHasError = true;
         errMsg = env->NewStringUTF("Error obtaining device ID");
     }

     len  = 15;
     flags = IREQ_CACHE_FLUSH;
     infoArray = new inquiry_info[max_rsp];

     num_rsp = hci_inquiry(dev_id, len, max_rsp, NULL, &infoArray, flags);
     if (num_rsp < 0)
         perror("hci_inquiry");

     btDevices = env->NewObjectArray(num_rsp, env->FindClass("java/lang/String"), env->NewStringUTF(""));

     for (i = 0; i < num_rsp; i++){
         ba2str(&(infoArray[i].bdaddr), addr);
         memset(name, 0, sizeof(name));

         env->SetObjectArrayElement(btDevices, i, env->NewStringUTF(addr));

     }

     delete(infoArray);

     return btDevices;
 }

Running the Application

When running the application, please note that I set the len parameter above to 15 (fifteen). The total scanning time will therefore be (1.28 * 15)seconds. I don't know where the 1.28 comes from, much of Bluez is still a mystery to me.

Resources

Blueooth Programming in C with Bluez
You can download the Eclipse project files here: Eclipse Project Files
You can download the NDK project files here: NDK Project Files
You can download my pre-built libbluetooth binaries for ARM NDK here: Bluetooth NDK Binaries