Debugging bluetooth app on android.

Android is leading market share in the mobile phone space and with the rapid growing of IoT/connected devices, we are seeing more and more innovative applications using Bluetooth technology show up in Google Play. With even more teams building Bluetooth apps on Android, some basic knowledge about the Bluetooth stack and APIs will be essential to developers.

Understanding the SDK and the Stack
With just a few lines of high-level API calls, you can quickly scan around and connect to the target device using Bluetooth (If you want to understand where to start using Bluetooth with low energy in your app or simply want a boilerplate skeleton code, you can always get those from our App Accelerator Kit).

To move your app’s performance to the next level, a good understanding of Bluetooth APIs will be helpful. From the first introduction of Bluetooth with low energy features in version 4.3 (JELLY_BEAN_MR2) API Level: 18, the SDK and the Bluetooth Stack on Android have evolved…a lot. A new package of android.bluetooth.le was added from API Level: 21. For some Bluetooth operations you may have more than one way of doing it. With that, you always want to check the user’s OS version/API level to better understand the capabilities from the Bluetooth SDK.

The feature set on different physical handsets may also vary. One example is BluetoothLeAdvertiser class. It is one of the “HAL-enabled features” not available on all Android phones. You need to specifically call BluetoothAdapter.isMultipleAdvertisementSupported() to determine its availability on that very device
Enable the Bluetooth HCI log on the device via Developer Options—also from the SDK, there is a helpful tool called the “Bluetooth HCI snoop log” (available after version 4.4)
HCI Snoop LogIt works like a hook in the stack to capture all the HCI packets in a file. For most Android devices, the log file is at /sdcard/btsnoop_hci.log. This article details the steps on how to set up the tool and retrieve the information.

Third party tools on Android—similar to the popular Bluetooth GATT/GAP tool “Lightblue” on iOS, a very useful tool called “nRF Master Control Panel” by Nordic Semiconductor is a powerful Android tool. This tool can get you a lot of information as a GAP/GATT client. It can also emulate an Android GATT server. Even better, it can show you the real-time RSSI graph of the advertisers in the range. You can find the tool on Google Play.
RSSI GraphUnderstanding Connection Intervals
Connection intervals for Bluetooth are a group of important parameters for your app. To balance power efficiency and performance, you need to fine-tune those parameters for your specific use case.

At the GAP (Generic Access Profile) layer, the peripheral advertises and the central listens. Then the central device initiates the connection and the peripheral accepts the connection request. When initiating the Bluetooth connection, the central device sends out a connection request (connect_req) which contains a set of connection parameters:

Connection interval
Slave latency
Management Timeout
In the initial request, the connection interval should be set to initial_conn-interval and slave latency should be set to zero. On Android devices, the initial_conn_interval (the initial value for connection interval when the connection is set up) is set to 7.5ms, which is the minimum that the spec allows. With the 7.5ms interval, we can get the highest throughput but it’s very power hungry (the smaller interval means more frequent connection event, which will result in more data being transmitted, at the cost of more power). Once the connection is set up and all the initial actions on the central side are complete, either the central or peripheral can request a connection parameter update. This request is a new proposal of the parameters for the counterpart to consider. Once the proposal is accepted, the central will start the connection parameter update procedure. On Android, this procedure is implemented in the BluetoothGatt class. A method called requestConnectionPriority will be called to update the connection parameters. As of now in API Level: 23, the update method supports three sets of parameters:

CONNECTION_PRIORITY_BALANCED
CONNECTION_PRIORITY_HIGH
CONNECTION_PRIORITY_LOW
You can see the process here:

Connection Process

The target device may also send requests to Android in the hope of changing the intervals to its preference. But it’s always the decision of the master role (the device who initiate the connection at the link layer level) on the intervals they will be settled on.

Understanding the Packet and Procedure
Another powerful tool for a Bluetooth developer is the protocol analyzer (“the sniffer”). I used the ComProbe BPA Low Energy Bluetooth Protocol Analyzer for this article. It can easily tell me how the wireless communication works or what went wrong.

When I am unsure if the Android stack and the API passed me the correct data, I will start the analyzer and check the details from different levels. The following capture shows the details of “Read by type” operation. I can go to the “Handle value pair” and debug step-by-step on that very handle.

Debug step by stepDebugging an Invisible Activity or a Background Service
It’s not always guaranteed that your app will be running in the foreground. Any higher priority tasks can move activity into invisible mode. Sometimes Bluetooth operations are implemented in a service running in the background. Most of the time, Bluetooth may operate differently when not in the foreground. The scenario of running in the background or a service needs to be tested and verified. Almost all Android debuggers support the feature of attaching to a specific process. All you need to do is to find out the process ID of your app and attach your debugger to this specific process.

Android studioEver since the first introduction of Bluetooth (with low energy features) support on Android, both the Bluetooth Stack and the APIs improved in each new version. With those improvements and developer friendly APIs/tools, Android is becoming a very powerful platform for the IoT ecosystem. I am looking forward to more innovative apps on Android soon.

Happy programming!