DEV Community

Ble Advertiser
Ble Advertiser

Posted on

Mastering Reliable BLE Characteristic Notifications on Android (Kotlin): Avoiding Missed Updates and Connection Drops

#android #kotlin #bluetooth #ble

Ever built an Android BLE app that seems to get characteristic notifications perfectly, only for updates to mysteriously stop flowing after a disconnect/reconnect cycle, or for data to arrive sporadically? You're not alone. Building reliable BLE applications, especially those requiring persistent characteristic notifications, is a non-trivial task that demands a deep understanding of the Android Bluetooth stack and the GATT profile. Missed notifications lead to stale data, broken UI, and ultimately, a poor user experience—a critical issue in IoT applications where data integrity is paramount.

This article cuts through the noise, providing you with the hard-won knowledge needed to implement rock-solid BLE characteristic notifications in your Android (Kotlin) applications. We'll move beyond basic setCharacteristicNotification calls, diving into the critical role of the Client Characteristic Configuration Descriptor (CCCD), robust connection management, and essential optimizations like MTU negotiation, ensuring your app receives every update, every time.

Core Concepts: The Pillars of Reliable Notifications

Before diving into code, let's solidify the foundational concepts that underpin reliable BLE notifications.

Notifications vs. Indications

While often used interchangeably in casual conversation, BLE Notifications and Indications have a crucial technical difference:

  • Notifications: The peripheral sends data to the central without requiring an acknowledgment from the central. This is faster but offers no guarantee of delivery. Think of it as UDP for BLE.
  • Indications: The peripheral sends data and requires an acknowledgment from the central. If no acknowledgment is received, the peripheral can retransmit. This provides guaranteed delivery but introduces overhead due to the handshake. Think of it as TCP for BLE.

For most real-time data streams where some loss can be tolerated for higher throughput (e.g., sensor data updates), Notifications are preferred. For critical, infrequent events (e.g., firmware update progress, device alarms), Indications are safer. This article primarily focuses on Notifications due to their prevalence and the common pitfalls associated with their reliability.

The GATT Profile and the CCCD

The Generic Attribute Profile (GATT) defines how BLE devices exchange data. Data is organized into Services, which contain Characteristics. Each Characteristic has properties (read, write, notify, indicate) and can have Descriptors.

One specific descriptor is absolutely vital for notifications and indications: the Client Characteristic Configuration Descriptor (CCCD).

The CCCD is a standard 16-bit descriptor (UUID: 00002902-0000-1000-8000-00805f9b34fb). It acts as a switch, allowing the central device (your Android phone) to tell the peripheral whether it wants to receive notifications or indications for a specific characteristic.

  • To enable Notifications, you write 0x0100 (hex) or BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE to the CCCD.
  • To enable Indications, you write 0x0200 (hex) or BluetoothGattDescriptor.ENABLE_INDICATION_VALUE to the CCCD.
  • To disable both, you write 0x0000 (hex) or BluetoothGattDescriptor.DISABLE_NOTIFICATION_VALUE to the CCCD.

Crucially, enabling notifications is a two-step process on Android:

  1. Call BluetoothGatt.setCharacteristicNotification(characteristic, true) on your local BluetoothGatt object. This prepares the Android stack to receive notifications.
  2. Then, you must write the appropriate value (ENABLE_NOTIFICATION_VALUE) to the characteristic's CCCD on the remote peripheral device. This tells the peripheral to start sending notifications.

Many developers miss step 2, leading to the "notifications sometimes work, sometimes don't" phenomenon.

Android's BLE Stack & Lifecycle

Your primary interface for GATT operations is the BluetoothGatt class and its BluetoothGattCallback. All BLE operations—connection state changes, service discovery, characteristic reads/writes, and descriptor writes—are asynchronous and reported back via the BluetoothGattCallback methods. Understanding this asynchronous nature and the sequence of callbacks is fundamental to building a robust BLE client.

MTU (Maximum Transmission Unit) Negotiation

The default MTU for BLE is 23 bytes. This means each packet can carry only 20 bytes of actual data (3 bytes are used for GATT overhead). If your characteristic notifications contain more than 20 bytes of data, the data will be fragmented into multiple 23-byte packets. This fragmentation introduces overhead and can impact throughput and reliability.

By requesting a larger MTU (up to 517 bytes on most modern devices), you can send more data per packet, reducing overhead and improving notification efficiency. This is vital for high-throughput applications.

Implementation: The Step-by-Step Guide

Let's walk through the process of reliably enabling and receiving characteristic notifications.

Prerequisites & Permissions

  • Android API Level: Android 5.0 (API 21) or higher.
  • Kotlin: All code examples will be in Kotlin.

  • Permissions (in AndroidManifest.xml):

    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
<!-- Android 11 and below needed coarse/fine location for BLE scanning -->
<!-- For background scanning post-Android 12, BLUETOOTH_SCAN without neverForLocation might implicitly require location if your app logic uses it. -->

    For Android 12+, BLUETOOTH_SCAN and BLUETOOTH_CONNECT are the primary permissions. For older APIs (API 30 and below), ACCESS_FINE_LOCATION is also required for BLE scanning.

Core Steps to Enable Notifications

Let's assume you've already scanned for a device and successfully established a GATT connection via device.connectGatt(context, autoConnect, bluetoothGattCallback).

  1. Discover Services: After a successful connection (onConnectionStateChange with newState == BluetoothProfile.STATE_CONNECTED and status == BluetoothGatt.GATT_SUCCESS), you must call gatt.discoverServices(). Wait for onServicesDiscovered callback.

  2. Find the Target Characteristic and its CCCD: Once services are discovered, iterate through them to find your target service and then your target characteristic. Every characteristic that supports notifications or indications must have a CCCD.

    val service = gatt?.getService(SERVICE_UUID)
val characteristic = service?.getCharacteristic(CHARACTERISTIC_UUID)
if (characteristic == null) {
    Log.e(TAG, "Characteristic $CHARACTERISTIC_UUID not found!")
    return
}
// Retrieve the CCCD descriptor
val cccdDescriptor = characteristic.getDescriptor(UUID.fromString(CCC_DESCRIPTOR_UUID))
if (cccdDescriptor == null) {
    Log.e(TAG, "CCCD descriptor not found for characteristic ${characteristic.uuid}!")
    return
}

  3. Enable Notifications on the Local BluetoothGatt Object: This is the first of the two critical steps. It tells the Android BLE stack to be ready to receive data for this characteristic.

    val success = gatt?.setCharacteristicNotification(characteristic, true)
if (success == false) {
    Log.w(TAG, "Failed to set characteristic notification locally for ${characteristic.uuid}")
    return
}

  4. Write to the CCCD Descriptor on the Remote Device: This is the second and most crucial step. It informs the peripheral device to start sending notifications.

    cccdDescriptor.value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE // For Notifications
// cccdDescriptor.value = BluetoothGattDescriptor.ENABLE_INDICATION_VALUE // For Indications

val writeSuccess = gatt?.writeDescriptor(cccdDescriptor)
if (writeSuccess == false) {
    Log.e(TAG, "Failed to write CCCD descriptor for ${characteristic.uuid}")
    return
}

    You must wait for the onDescriptorWrite callback to confirm this operation.

  5. Handle Incoming Notifications: Once the CCCD is successfully written, the peripheral will start sending notifications. These will be received in your onCharacteristicChanged callback.

    override fun onCharacteristicChanged(gatt: BluetoothGatt?, characteristic: BluetoothGattCharacteristic?) {
    super.onCharacteristicChanged(gatt, characteristic)
    characteristic?.let { char ->
        val value = char.value // The byte array containing the notification data
        Log.d(TAG, "Received notification from ${char.uuid}: ${value.toHexString()}")
        // Process the received data here
    }
}

MTU Negotiation

It's highly recommended to request a larger MTU early in the connection lifecycle, ideally after a successful connection but before performing heavy data transfers or enabling notifications.

// In your onConnectionStateChange after STATE_CONNECTED and GATT_SUCCESS
override fun onConnectionStateChange(gatt: BluetoothGatt?, status: Int, newState: Int) {
    super.onConnectionStateChange(gatt, status, newState)
    if (newState == BluetoothProfile.STATE_CONNECTED && status == BluetoothGatt.GATT_SUCCESS) {
        Log.i(TAG, "Device connected. Requesting MTU...")
        gatt?.requestMtu(512) // Request up to 512 bytes, Android will negotiate to max supported.
    }
    // ... rest of your connection state handling
}

override fun onMtuChanged(gatt: BluetoothGatt?, mtu: Int, status: Int) {
    super.onMtuChanged(gatt, mtu, status)
    if (status == BluetoothGatt.GATT_SUCCESS) {
        Log.i(TAG, "MTU changed to $mtu bytes.")
        // Now you can proceed with service discovery and notification setup
        gatt?.discoverServices()
    } else {
        Log.e(TAG, "Failed to change MTU, status: $status. Proceeding with default MTU.")
        gatt?.discoverServices() // Still discover services
    }
}
Enter fullscreen mode Exit fullscreen mode

Code Examples

Here’s a simplified BleManager class demonstrating the core logic for reliable characteristic notifications. Note that a full-featured manager would include robust state handling, error recovery, and threading considerations.

import android.bluetooth.*
import android.content.Context
import android.util.Log
import java.util.*

// UUIDs for example (replace with your device's actual UUIDs)
private val SERVICE_UUID: UUID = UUID.fromString("0000FE59-0000-1000-8000-00805f9b34fb") // Example Nordic UART Service
private val CHARACTERISTIC_UUID: UUID = UUID.fromString("00008888-0000-1000-8000-00805f9b34fb") // Example Notify Characteristic
private val CCC_DESCRIPTOR_UUID: UUID = UUID.fromString("00002902-0000-1000-8000-00805f9b34fb") // Standard CCCD UUID

class BleNotificationManager(private val context: Context) : BluetoothGattCallback() {

    private val TAG = "BleNotificationManager"
    private var bluetoothGatt: BluetoothGatt? = null
    private val notificationListeners = mutableMapOf<UUID, (ByteArray) -> Unit>()
    private val characteristicsToEnableNotificationsOnReconnect = mutableSetOf<UUID>()

    //region Connection and Setup
    fun connect(device: BluetoothDevice) {
        // autoConnect = false for direct connection, autoConnect = true for background/persistent
        bluetoothGatt = device.connectGatt(context, false, this)
        Log.i(TAG, "Attempting to connect to device: ${device.address}")
    }

    fun disconnect() {
        bluetoothGatt?.apply {
            close()
            Log.i(TAG, "Disconnected and closed GATT.")
        }
        bluetoothGatt = null
        notificationListeners.clear()
        // Keep characteristicsToEnableNotificationsOnReconnect for potential future auto-reconnect
    }
    //endregion

    //region BluetoothGattCallback Overrides
    override fun onConnectionStateChange(gatt: BluetoothGatt?, status: Int, newState: Int) {
        super.onConnectionStateChange(gatt, status, newState)
        if (status == BluetoothGatt.GATT_SUCCESS) {
            when (newState) {
                BluetoothProfile.STATE_CONNECTED -> {
                    Log.i(TAG, "Device CONNECTED. Requesting MTU...")
                    bluetoothGatt = gatt // Store reference to actual gatt object
                    gatt?.requestMtu(512) // Request MTU after successful connection
                }
                BluetoothProfile.STATE_DISCONNECTED -> {
                    Log.w(TAG, "Device DISCONNECTED.")
                    // Crucial: Clear listeners or handle reconnection attempts
                    notificationListeners.clear()
                    gatt?.close() // Close GATT resources
                    bluetoothGatt = null
                    // Implement reconnection logic here if autoConnect=false
                }
            }
        } else {
            Log.e(TAG, "Connection failed with status: $status, new state: $newState")
            gatt?.close()
            bluetoothGatt = null
            notificationListeners.clear()
        }
    }

    override fun onMtuChanged(gatt: BluetoothGatt?, mtu: Int, status: Int) {
        super.onMtuChanged(gatt, mtu, status)
        if (status == BluetoothGatt.GATT_SUCCESS) {
            Log.i(TAG, "MTU changed to $mtu bytes. Discovering services...")
        } else {
            Log.e(TAG, "Failed to change MTU, status: $status. Proceeding with default MTU.")
        }
        // Always discover services after MTU negotiation (or failed negotiation)
        gatt?.discoverServices()
    }

    override fun onServicesDiscovered(gatt: BluetoothGatt?, status: Int) {
        super.onServicesDiscovered(gatt, status)
        if (status == BluetoothGatt.GATT_SUCCESS) {
            Log.i(TAG, "Services discovered. Attempting to enable notifications for stored characteristics.")
            // This is where you'd re-enable notifications after a reconnect or initial connection
            characteristicsToEnableNotificationsOnReconnect.forEach { uuid ->
                val characteristic = gatt?.getService(SERVICE_UUID)?.getCharacteristic(uuid)
                if (characteristic != null) {
                    // Re-register any listeners that were set up before
                    val listener = notificationListeners[uuid] ?: { data ->
                        Log.d(TAG, "Reconnected: Received data for $uuid: ${data.toHexString()}")
                    }
                    enableCharacteristicNotifications(characteristic, listener)
                }
            }
        } else {
            Log.e(TAG, "Service discovery failed with status: $status")
        }
    }

    override fun onDescriptorWrite(gatt: BluetoothGatt?, descriptor: BluetoothGattDescriptor?, status: Int) {
        super.onDescriptorWrite(gatt, descriptor, status)
        if (status == BluetoothGatt.GATT_SUCCESS) {
            Log.i(TAG, "Successfully wrote CCCD for ${descriptor?.characteristic?.uuid}")
            // Now notifications are truly enabled on the remote device
            // You might want to notify your app layer here that notifications are active.
        } else {
            Log.e(TAG, "Failed to write CCCD for ${descriptor?.characteristic?.uuid}, status: $status")
            // Handle error: perhaps retry or disable local notification if it was previously set.
            descriptor?.characteristic?.let { char ->
                bluetoothGatt?.setCharacteristicNotification(char, false) // Disable local if remote failed
                notificationListeners.remove(char.uuid)
                characteristicsToEnableNotificationsOnReconnect.remove(char.uuid)
            }
        }
    }

    override fun onCharacteristicChanged(gatt: BluetoothGatt?, characteristic: BluetoothGattCharacteristic?) {
        super.onCharacteristicChanged(gatt, characteristic)
        characteristic?.let { char ->
            val value = char.value
            notificationListeners[char.uuid]?.invoke(value)
            // Log.d(TAG, "Received notification from ${char.uuid}: ${value.toHexString()}") // Often too noisy
        }
    }
    //endregion

    //region Public API for enabling notifications
    fun enableCharacteristicNotifications(
        characteristic: BluetoothGattCharacteristic,
        listener: (ByteArray) -> Unit
    ) {
        if (bluetoothGatt == null) {
            Log.e(TAG, "GATT not connected. Cannot enable notifications.")
            return
        }

        // Step 1: Enable local notifications
        val success = bluetoothGatt?.setCharacteristicNotification(characteristic, true)
        if (success == false) {
            Log.w(TAG, "Failed to set characteristic notification locally for ${characteristic.uuid}")
            return
        }

        // Step 2: Write to the CCCD descriptor
        val descriptor = characteristic.getDescriptor(UUID.fromString(CCC_DESCRIPTOR_UUID))
            ?: run {
                Log.e(TAG, "CCCD descriptor not found for characteristic ${characteristic.uuid}")
                bluetoothGatt?.setCharacteristicNotification(characteristic, false) // Cleanup local state
                return
            }

        // Configure descriptor value for notifications
        descriptor.value = BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE

        val writeSuccess = bluetoothGatt?.writeDescriptor(descriptor)
        if (writeSuccess == false) {
            Log.e(TAG, "Failed to write CCCD descriptor for ${characteristic.uuid}")
            bluetoothGatt?.setCharacteristicNotification(characteristic, false) // Cleanup local state
            return
        }
        notificationListeners[characteristic.uuid] = listener
        characteristicsToEnableNotificationsOnReconnect.add(characteristic.uuid) // Store for reconnects
    }

    fun disableCharacteristicNotifications(characteristic: BluetoothGattCharacteristic) {
        if (bluetoothGatt == null) {
            Log.e(TAG, "GATT not connected. Cannot disable notifications.")
            return
        }

        bluetoothGatt?.setCharacteristicNotification(characteristic, false) // Disable locally

        val descriptor = characteristic.getDescriptor(UUID.fromString(CCC_DESCRIPTOR_UUID))
        if (descriptor == null) {
            Log.e(TAG, "CCCD descriptor not found for characteristic ${characteristic.uuid}. Cannot disable remotely.")
            return
        }

        descriptor.value = BluetoothGattDescriptor.DISABLE_NOTIFICATION_VALUE
        bluetoothGatt?.writeDescriptor(descriptor) // Write to remote to disable

        notificationListeners.remove(characteristic.uuid)
        characteristicsToEnableNotificationsOnReconnect.remove(characteristic.uuid)
        Log.i(TAG, "Attempting to disable notifications for ${characteristic.uuid}")
    }
    //endregion

    // Helper extension for logging byte arrays
    private fun ByteArray.toHexString(): String =
        joinToString(separator = " ", prefix = "[", postfix = "]") { String.format("%02X", it) }
}
Enter fullscreen mode Exit fullscreen mode

Usage Example 

// In your Activity or ViewModel
class MainActivity : AppCompatActivity() {
    private lateinit var bleManager: BleNotificationManager
    private var targetDevice: BluetoothDevice? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        bleManager = BleNotificationManager(this)
        // ... set up UI, permissions, scanning ...

        // Example: once a device is found (e.g., from a scan result)
        // targetDevice = // ... your scanned BluetoothDevice ...
        // bleManager.connect(targetDevice!!)

        // After connection and services discovered (simulated here for demonstration)
        // In a real app, you'd call this after onServicesDiscovered
        findViewById<Button>(R.id.enable_notifications_button).setOnClickListener {
            val gattCharacteristic = bleManager.bluetoothGatt // Access internal gatt for example
                ?.getService(SERVICE_UUID)
                ?.getCharacteristic(CHARACTERISTIC_UUID)

            if (gattCharacteristic != null) {
                bleManager.enableCharacteristicNotifications(gattCharacteristic) { data ->
                    runOnUiThread {
                        // Update UI with received data
                        findViewById<TextView>(R.id.data_display).text = "Data: ${data.toHexString()}"
                    }
                }
            } else {
                Log.e("MainActivity", "Target characteristic not found!")
            }
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        bleManager.disconnect()
    }
}
Enter fullscreen mode Exit fullscreen mode

Best Practices for Unshakeable Reliability

Achieving true reliability in BLE notifications requires more than just enabling the CCCD. Here are critical best practices forged in the fires of real-world IoT deployments:

  1. Always Re-enable Notifications on Reconnection: This is arguably the most critical and often overlooked point. When a BLE device disconnects, its GATT state, including any characteristic notification/indication subscriptions, is reset on the peripheral. Upon reconnection, you must re-execute the two-step process: setCharacteristicNotification(characteristic, true) and then writeDescriptor(cccdDescriptor) for every characteristic you wish to receive updates from.

    • Fix: Maintain a persistent list of UUIDs for all characteristics for which notifications were enabled. In your onServicesDiscovered callback (which is triggered after every successful connection, including reconnections), iterate through this list and re-enable notifications for each. The provided BleNotificationManager includes characteristicsToEnableNotificationsOnReconnect for this purpose.

  2. Implement a Robust Connection Management State Machine: Relying solely on onConnectionStateChange is insufficient. Your application should actively manage the connection lifecycle. This includes:

    • Connection Attempts: Handle connection failures and implement exponential backoff for retries.
    • Disconnection Handling: Distinguish between intentional disconnections (e.g., user-initiated) and unintentional ones (e.g., device out of range). For unintentional disconnects, trigger an automatic reconnection attempt.
    • GATT Resource Management: Always call gatt.close() when you're done with a device or after an unexpected disconnection. This releases system resources. Failure to do so can lead to resource leaks and prevent future connections. Nullify your BluetoothGatt instance after closing.
    • autoConnect Nuances: Using device.connectGatt(context, true, this) (autoConnect = true) is excellent for background, persistent connections as the Android system will attempt to reconnect in the background if the device comes back into range. However, it's slower for initial connections. For foreground-driven, immediate connections, autoConnect = false is generally preferred. Understand the trade-offs and use the appropriate one for your scenario.

  3. Error Handling for CCCD Write and Other Operations: Don't assume writeDescriptor or any other GATT operation will always succeed. Network interference, remote device issues, or timing problems can cause failures.

    • Fix: Always check the status parameter in callbacks like onDescriptorWrite, onCharacteristicWrite, etc. If status != BluetoothGatt.GATT_SUCCESS, log the error, inform the user if necessary, and implement a retry mechanism or gracefully disable the corresponding functionality. In the example, if onDescriptorWrite fails, we disable the local notification setting.

  4. Prioritize MTU Negotiation for Performance: As discussed, the default 23-byte MTU can be a bottleneck.

    • Fix: Request a larger MTU using gatt.requestMtu(desiredMtu) immediately after a successful connection (in onConnectionStateChange). Wait for the onMtuChanged callback before proceeding with service discovery or notification setup to ensure the MTU has been negotiated. This optimizes data transfer from the start.

  5. Debounce or Throttle Rapid onCharacteristicChanged Events: If your peripheral sends notifications at a very high frequency (e.g., hundreds of updates per second), directly processing every single onCharacteristicChanged event on the main thread can lead to UI freezes or ANRs.

    • Fix: Implement a debounce or throttle mechanism. For UI updates, consider using LiveData or Kotlin Flow with debounce() operators. For background processing, aggregate data or process it on a dedicated background thread with rate limiting. This ensures your app remains responsive and stable under heavy data loads.

Conclusion

Mastering reliable BLE characteristic notifications on Android is about more than just calling setCharacteristicNotification. It demands a thorough understanding of the GATT profile, particularly the critical two-step process involving the CCCD. You've learned that persistently re-enabling notifications upon reconnection, implementing robust connection state management, proactively negotiating a larger MTU, and meticulously handling errors are non-negotiable for building truly stable IoT applications. By applying these principles, you will significantly reduce missed updates and connection drops, delivering a superior user experience.

Your next step should be to refactor your BLE communication layer into a dedicated, stateful BleManager class that encapsulates these best practices, providing a clean and reliable API for the rest of your application.

Top comments (0)