Android Bluetooth: A Pitfall

Developing BLE-enabled Android apps is fraught with challenges, especially when it comes to managing concurrent operations. One of the most common pitfalls developers face is the unexpected behavior that occurs when trying to execute BLE operations in rapid succession. In this blog post, we’ll delve into why this happens and how you can overcome it by implementing a custom queuing mechanism for BLE operations.

If you’ve worked with BLE on Android, you may have encountered a frustrating issue: when you attempt to execute multiple BLE operations one after another, like reading and writing characteristics or descriptors, only the first operation succeeds, while the others seem to disappear. This is more than just a minor inconvenience; it’s a serious problem because your app logic often depends on the successful completion of these operations. Without them, your UI can’t update with the fresh data from your connected device, leading to a poor user experience.

So, what’s going on under the hood? The core issue lies in how Android’s BLE stack handles operations. BLE operations are asynchronous, meaning they don’t complete instantaneously. When you execute the BLE stack with multiple requests in quick succession, the system struggles to keep up, leading to dropped operations and unpredictable behavior.

The Conventional Approach: Callback-Based Solutions

One way to mitigate this issue is by using callbacks to sequence your BLE operations.
For example, you might wait for the onCharacteristicWrite() callback to trigger before starting the next operation. This works for simple use cases where your BLE interactions are limited to a single screen or Activity.
However, this approach quickly becomes unmanageable as the complexity of your app grows. As you add more BLE operations—such as reading and writing descriptors, handling connections and disconnections, updating the MTU, and performing service discovery. You’ll find that a more scalable solution is needed.

The Scalable Solution: Implementing a Queuing Mechanism

To handle BLE operations more reliably, a custom queuing mechanism is essential. By queuing BLE operations, you ensure that each operation is executed sequentially, only after the previous operation has either succeeded or failed. This approach not only prevents operations from being dropped but also simplifies the management of BLE tasks across your app.

Here’s a basic outline of how you might implement such a mechanism:

• Create a Queue: Start by creating a queue (such as a LinkedList or Queue) to hold your BLE operations. Each operation can be represented as a task or command object that contains the details of the operation you want to perform.
• Operation Handler: Implement a handler or manager class responsible for processing the operations in the queue. This class should listen for the completion of each BLE operation, whether it succeeds or fails, before dequeuing and executing the next operation.
• Callback Integration: Modify your existing BLE callbacks (like onCharacteristicWrite(), onCharacteristicRead(), etc.) to trigger the dequeuing and execution of the next operation in the queue.
• Error Handling: Implement error handling to ensure that failed operations don’t block the queue. You might also want to perform retry logic for transient errors.
• UI Updates: Since your UI may depend on the outcome of BLE operations, ensure that your queue manager triggers appropriate UI updates once operations complete.

class BLEManager {
    ConcurrentLinkedQueue<BLEBaseCommand> commandQueue = new ConcurrentLinkedQueue<>(); // Note that we're using a ConcurrentLinkedQueue to prevent concurrency issues.

    private void terminateCommands() {
        commandQueue.clear();
        currentCommand = null;
    }

    private void enqueueCommand(BLEBaseCommand command) {
        commandQueue.offer(command);
        if (currentCommand == null) {
            executeNextCommand();
        }
    }

    private void signalCommandEnd() {
        currentCommand = null;
        if (!commandQueue.isEmpty()) { // Has remaining command?
            executeNextCommand();
        }
    }

    private void executeNextCommand() {
        BLEBaseCommand next = commandQueue.poll();
        if (next == null) {
            // All done
            return;
        }

        currentCommand = next;
        try {
            if (!currentCommand.execute()) {
                runOnUiThread(currentCommand.fallback); // Handle your error from `fallback` function depends on the command
                signalCommandEnd();
            }
        } catch (Exception ex) {
            signalCommandEnd();
        }
    }

    private void runOnUiThread(Runnable runnable) {
        new Handler(Looper.getMainLooper()).post(runnable);
    }
}

Somewhere from your BluetoothGattCallback class.

@Override
    public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) {
    // Your logic
    manager.signalCommandEnd();
}

@Override
public void onServiceChanged(@NonNull BluetoothGatt gatt) {
    // Your logic
    manager.signalCommandEnd();
}

@Override
public void onServicesDiscovered(BluetoothGatt gatt, int status) {
    // Your logic
    manager.signalCommandEnd();
}

@Override
public void onCharacteristicRead(BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, int status) {
    // Your logic
    manager.signalCommandEnd();
}

@Override
public void onCharacteristicWrite(BluetoothGatt gatt, BluetoothGattCharacteristic characteristic, int status) {
    // Your logic
    manager.signalCommandEnd();
}

@Override
public void onDescriptorRead(BluetoothGatt gatt, BluetoothGattDescriptor descriptor, int status) {
    // Your logic
    manager.signalCommandEnd();
}

@Override
public void onDescriptorWrite(BluetoothGatt gatt, BluetoothGattDescriptor descriptor, int status) {
    // Your logic
    manager.signalCommandEnd();
}

@Override
public void onReadRemoteRssi(BluetoothGatt gatt, int rssi, int status) {
    // Your logic
    manager.signalCommandEnd();
}

@Override
public void onMtuChanged(BluetoothGatt gatt, int mtu, int status) {
    // Your logic
    manager.signalCommandEnd();
}

Below is the basic class diagram

Why This Matters

Implementing a queuing mechanism for BLE operations isn’t just about avoiding dropped operations; it’s about creating a more reliable and scalable architecture for your app. As you expand your app’s BLE functionality, you’ll be thankful for the stability and predictability that a queuing system provides.

It’s worth mentioning that more modern paradigms like RxJava or Kotlin framework can offer even more elegant solutions to this problem. These tools can help you manage asynchronous operations with greater flexibility and less boilerplate code. However, for many developers, a custom queuing mechanism provides a solid foundation that can be easily understood and implemented without introducing additional dependencies. We might discuss this in another thread.

Conclusion

BLE on Android can be challenging, but with the right strategies, you can build robust applications that reliably communicate with BLE devices. By implementing a custom queuing mechanism, you can overcome many of the concurrency-related issues. Whether you’re just starting with BLE or looking to enhance your existing apps, adopting a queuing approach will make your development process smoother and your applications more reliable.
Happy Coding!