Forem: Ble Advertiser

Navigating Android 12+ BLE Permissions: A Kotlin Developer's Checklist for BLUETOOTH_SCAN, CONNECT, and ADVERTISE

Ble Advertiser — Sun, 26 Apr 2026 11:04:18 +0000

Did your rock-solid BLE app suddenly stop discovering devices, connecting, or advertising services on Android 12 (API 31) or later? You're not alone. Google's ongoing commitment to user privacy and granular control introduced a significant overhaul to how Bluetooth permissions are handled, moving away from the broad strokes of BLUETOOTH_ADMIN and ACCESS_FINE_LOCATION to a much more precise model. This change is mandatory, not optional, and understanding it is critical to delivering a reliable BLE experience.

This article cuts through the noise, providing a direct, actionable guide for Android developers using Kotlin. We’ll break down the new BLUETOOTH_SCAN, BLUETOOTH_CONNECT, and BLUETOOTH_ADVERTISE permissions, show you exactly how to implement them, and arm you with best practices to avoid common pitfalls.

Core Concepts: The Shift in Android 12+ BLE Permissions

Before Android 12 (API 31), BLE operations primarily relied on two install-time permissions: BLUETOOTH and BLUETOOTH_ADMIN. While BLUETOOTH_ADMIN granted broad control over Bluetooth functions like scanning and connecting, the critical piece for scanning nearby devices was the runtime permission ACCESS_FINE_LOCATION. This was a point of frequent user friction; many users questioned why a flashlight app needed their precise location, simply because it also wanted to scan for a nearby BLE lightbulb.

With Android 12, Google addressed this by decoupling location from fundamental BLE operations. The new model introduces three distinct runtime permissions, giving users more granular control over what specific Bluetooth capabilities your app can access.

Here's the breakdown of the new permissions introduced in API 31+:

`BLUETOOTH_SCAN`

Purpose: This permission is required if your app needs to discover nearby Bluetooth devices, including BLE peripherals, or determine their non-identifying information (e.g., device name, service UUIDs in advertisement data).
Operations: Any operation that initiates a scan for Bluetooth devices, such as calling BluetoothAdapter.startLeScan() or BluetoothLeScanner.startScan().
Crucial Distinction: On Android 12 (API 31) and higher, BLUETOOTH_SCAN does NOT inherently require ACCESS_FINE_LOCATION just to discover devices. If your app uses scan results only to find a device for connection and doesn't derive physical location from these results, you do not need to request ACCESS_FINE_LOCATION alongside BLUETOOTH_SCAN. This is a significant privacy improvement. You should also include android:usesPermissionFlags="neverForLocation" in your manifest for BLUETOOTH_SCAN to explicitly signal this intent to the OS.

`BLUETOOTH_CONNECT`

Purpose: This permission is required if your app needs to communicate with already-paired Bluetooth devices, initiate connections, or accept incoming connections.
Operations:
- Connecting to a GATT server (BluetoothDevice.connectGatt()).
- Reading/writing characteristics or descriptors.
- Communicating with a remote device after a connection has been established.
- Accepting incoming connections (BluetoothAdapter.listenUsingRfcommWithServiceRecord(), BluetoothGattServer.accept()).
- Accessing the local Bluetooth adapter's profile (e.g., BluetoothAdapter.getProfileProxy()).

`BLUETOOTH_ADVERTISE`

Purpose: This permission is required if your app needs to make its device discoverable to other Bluetooth devices and broadcast advertisement packets.
Operations: Starting a BLE advertisement session (BluetoothLeAdvertiser.startAdvertising()).

The Location Conundrum (Revisited for API 31+)

While BLUETOOTH_SCAN now largely stands alone for discovery, there are specific scenarios where ACCESS_FINE_LOCATION is still required for BLE operations, even on Android 12+:

Location Inference: If your app uses the BLE scan results (e.g., RSSI values from multiple beacons, or specific beacon types like iBeacons/Eddystones whose profiles are often associated with location) to infer the physical location of the user or a device, then ACCESS_FINE_LOCATION is still necessary. The system needs to ensure the user is aware their location is being derived.
Compatibility (Pre-API 31 logic): If you target API 30 or lower, and your app runs on an Android 12+ device, the system might grant the new Bluetooth permissions if BLUETOOTH_ADMIN and ACCESS_FINE_LOCATION were granted. However, this is a compatibility bridge, and you must update your targetSdkVersion to 31 or higher and request the new permissions directly.
Global Bluetooth/Wi-Fi scanning setting: Prior to API 31, if the user globally disabled "Wi-Fi and Bluetooth scanning" in their device settings (a system setting separate from app permissions), apps could not perform BLE scans even with ACCESS_FINE_LOCATION. On API 31+, BLUETOOTH_SCAN (especially with neverForLocation) allows an app to bypass this global setting for app-initiated scans if the app doesn't derive location from scan results.

Summary Table: Permissions Pre- vs. Post-API 31

Operation	Android 11 (API 30) & Lower	Android 12 (API 31) & Higher	Notes
Scanning	`BLUETOOTH_ADMIN` + `ACCESS_FINE_LOCATION` (runtime)	`BLUETOOTH_SCAN` (runtime)	`ACCESS_FINE_LOCATION` no longer required for mere discovery on API 31+ if not inferring location.
Connecting	`BLUETOOTH_ADMIN`	`BLUETOOTH_CONNECT` (runtime)	No runtime permission for connection prior to API 31.
Advertising	`BLUETOOTH_ADMIN`	`BLUETOOTH_ADVERTISE` (runtime)	No runtime permission for advertising prior to API 31.
Location Use	`ACCESS_FINE_LOCATION` (runtime)	`ACCESS_FINE_LOCATION` (runtime)	Still required if your app uses scan results to derive physical location.

Implementation: A Step-by-Step Guide for Kotlin

Implementing the new BLE permissions correctly involves two main steps: declaring them in your AndroidManifest.xml and then requesting them at runtime using modern Activity Result APIs.

Step 1: Update Your `AndroidManifest.xml`

You need to declare the new Bluetooth permissions in your AndroidManifest.xml. It's crucial to also include maxSdkVersion for older permissions if you still need to support pre-API 31 devices, ensuring the system selects the correct permissions based on the device's OS version.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- REQUIRED for devices running Android 12 (API level 31) or higher -->
    <!-- For discovering nearby BLE devices -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
        android:usesPermissionFlags="neverForLocation"
        tools:targetApi="s" />
    <!-- For connecting to already-paired BLE devices and communicating -->
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT"
        tools:targetApi="s" />
    <!-- For making your device discoverable as a BLE peripheral -->
    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE"
        tools:targetApi="s" />

    <!-- REQUIRED for devices running Android 11 (API level 30) or lower -->
    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />

    <!--
        REQUIRED if your app still needs to derive physical location from BLE scan results,
        OR if targeting API 30 or lower and performing BLE scans.
        For API 31+, BLUETOOTH_SCAN with "neverForLocation" flag covers most scan use cases.
    -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <!-- Declares that your app uses BLE and should only be installed on devices that support it. -->
    <uses-feature android:name="android.hardware.bluetooth_le" android:required="true"/>

    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.BlePermissionsGuide"
        tools:targetApi="31">
        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>
    </application>
</manifest>

Key Points in Manifest:

android:usesPermissionFlags="neverForLocation": Crucial for BLUETOOTH_SCAN. This flag explicitly tells the system that your app does not intend to use Bluetooth scan results to derive physical location. This can help prevent unnecessary location permission prompts and streamline the user experience.
tools:targetApi="s": The tools:targetApi attribute (from xmlns:tools) helps lint and other build tools understand that these permissions are specific to certain API levels, preventing warnings if your minSdkVersion is lower than 31.
android:maxSdkVersion="30": This ensures that older permissions like BLUETOOTH and BLUETOOTH_ADMIN are only requested on devices running Android 11 or lower, preventing redundant or incorrect permission requests on newer OS versions.
ACCESS_FINE_LOCATION: Keep this if you truly need location for other features or if you are inferring location from BLE scans. Otherwise, consider removing it for maximum privacy.

Step 2: Request Permissions at Runtime (Kotlin & Activity Result API)

For modern Android development, you should use the registerForActivityResult API (part of the Activity Result APIs) to handle runtime permission requests. This replaces the deprecated onRequestPermissionsResult callback, leading to cleaner and more lifecycle-aware code.

First, define a launcher for requesting multiple permissions in your Activity or Fragment:

import android.Manifest
import android.bluetooth.BluetoothAdapter
import android.bluetooth.BluetoothManager
import android.content.Context
import android.content.Intent
import android.content.pm.PackageManager
import android.net.Uri
import android.os.Build
import android.os.Bundle
import android.provider.Settings
import android.util.Log
import android.widget.Button
import android.widget.Toast
import androidx.activity.result.ActivityResultLauncher
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AlertDialog
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat

class MainActivity : AppCompatActivity() {

    private val TAG = "BLEPermissionsGuide"
    private var bluetoothAdapter: BluetoothAdapter? = null

    // Register ActivityResultLauncher for requesting multiple permissions
    private val requestBlePermissions: ActivityResultLauncher<Array<String>> =
        registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { permissions ->
            val allGranted = permissions.entries.all { it.value }
            if (allGranted) {
                // All required BLE permissions are granted. Proceed with BLE operations.
                Log.d(TAG, "All required BLE permissions granted.")
                ensureBluetoothEnabled()
            } else {
                // At least one BLE permission was denied.
                Log.w(TAG, "One or more BLE permissions denied.")
                showPermissionDeniedDialog()
            }
        }

    // Register ActivityResultLauncher for enabling Bluetooth
    private val enableBluetoothLauncher: ActivityResultLauncher<Intent> =
        registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result ->
            if (result.resultCode == RESULT_OK) {
                Log.d(TAG, "Bluetooth enabled by user.")
                startBleOperationsIfReady()
            } else {
                Log.w(TAG, "Bluetooth not enabled by user.")
                Toast.makeText(this, "Bluetooth is required for this app.", Toast.LENGTH_SHORT).show()
            }
        }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Initialize BluetoothAdapter
        val bluetoothManager = getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
        bluetoothAdapter = bluetoothManager.adapter

        findViewById<Button>(R.id.start_scan_button).setOnClickListener {
            // Initiate the permission check and request flow
            checkAndRequestBlePermissions()
        }
    }

    private fun checkAndRequestBlePermissions() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { // Android 12 (API 31) and higher
            val permissionsToRequest = mutableListOf<String>()

            // Check BLUETOOTH_SCAN
            if (ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_SCAN) != PackageManager.PERMISSION_GRANTED) {
                permissionsToRequest.add(Manifest.permission.BLUETOOTH_SCAN)
            }
            // Check BLUETOOTH_CONNECT
            if (ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_CONNECT) != PackageManager.PERMISSION_GRANTED) {
                permissionsToRequest.add(Manifest.permission.BLUETOOTH_CONNECT)
            }
            // Check BLUETOOTH_ADVERTISE (only add if your app needs to advertise)
            if (ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_ADVERTISE) != PackageManager.PERMISSION_GRANTED) {
                // If you need advertising, uncomment the line below:
                // permissionsToRequest.add(Manifest.permission.BLUETOOTH_ADVERTISE)
            }

            // If ACCESS_FINE_LOCATION is truly needed for location inference from BLE scans (not just discovery)
            // if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
            //     permissionsToRequest.add(Manifest.permission.ACCESS_FINE_LOCATION)
            // }

            if (permissionsToRequest.isNotEmpty()) {
                // Request the missing permissions
                requestBlePermissions.launch(permissionsToRequest.toTypedArray())
            } else {
                // All necessary permissions already granted for API 31+
                Log.d(TAG, "All API 31+ BLE permissions already granted.")
                ensureBluetoothEnabled()
            }
        } else { // Android 11 (API 30) and lower
            // For older Android versions, we primarily need ACCESS_FINE_LOCATION for scanning.
            // BLUETOOTH and BLUETOOTH_ADMIN are install-time permissions.
            if (ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
                // Request ACCESS_FINE_LOCATION using the same ActivityResultLauncher
                requestBlePermissions.launch(arrayOf(Manifest.permission.ACCESS_FINE_LOCATION))
            } else {
                Log.d(TAG, "ACCESS_FINE_LOCATION permission already granted for older API.")
                ensureBluetoothEnabled()
            }
        }
    }

    private fun ensureBluetoothEnabled() {
        bluetoothAdapter?.let {
            if (!it.isEnabled) {
                Log.d(TAG, "Bluetooth is disabled. Requesting user to enable it.")
                val enableBtIntent = Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE)
                enableBluetoothLauncher.launch(enableBtIntent)
            } else {
                Log.d(TAG, "Bluetooth is already enabled.")
                startBleOperationsIfReady()
            }
        } ?: run {
            Log.e(TAG, "Bluetooth not supported on this device.")
            Toast.makeText(this, "Bluetooth not supported on this device.", Toast.LENGTH_LONG).show()
        }
    }

    private fun startBleOperationsIfReady() {
        // Double-check if all conditions (permissions, Bluetooth enabled) are met.
        // This method can be called after permissions are granted or Bluetooth is enabled.
        if (bluetoothAdapter?.isEnabled == true && hasRequiredBlePermissions()) {
            Toast.makeText(this, "Starting BLE scan...", Toast.LENGTH_SHORT).show()
            Log.d(TAG, "BLE scan initiated.")
            // --- Your BLE scanning or connection logic goes here ---
            // Example:
            // val scanner = bluetoothAdapter?.bluetoothLeScanner
            // scanner?.startScan( /* Scan Filters and Settings */ )
        } else {
            Log.w(TAG, "Cannot start BLE operations: Permissions or Bluetooth not ready.")
        }
    }

    private fun hasRequiredBlePermissions(): Boolean {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_SCAN) == PackageManager.PERMISSION_GRANTED &&
            ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_CONNECT) == PackageManager.PERMISSION_GRANTED
            // Add BLUETOOTH_ADVERTISE if required for your app
            // && ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_ADVERTISE) == PackageManager.PERMISSION_GRANTED
            // Add ACCESS_FINE_LOCATION if required
            // && ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
        } else {
            // For API < 31, ensure ACCESS_FINE_LOCATION (if scanning)
            ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
        }
    }

    private fun showPermissionDeniedDialog() {
        AlertDialog.Builder(this)
            .setTitle("Permissions Required")
            .setMessage("BLE operations require Bluetooth permissions. Please grant them in your device settings.")
            .setPositiveButton("Go to Settings") { dialog, _ ->
                val intent = Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS)
                val uri = Uri.fromParts("package", packageName, null)
                intent.data = uri
                startActivity(intent)
                dialog.dismiss()
            }
            .setNegativeButton("Cancel") { dialog, _ ->
                dialog.dismiss()
            }
            .show()
    }
}

Explanation of the Code:

requestBlePermissions Launcher: This ActivityResultLauncher is initialized once. When requestBlePermissions.launch() is called with an array of permissions, it triggers the system permission dialog. The lambda then receives a map of permission names to boolean (granted/denied) results.
enableBluetoothLauncher Launcher: Separate launcher to handle the result of ACTION_REQUEST_ENABLE which prompts the user to turn on Bluetooth.
checkAndRequestBlePermissions():
- It uses Build.VERSION.SDK_INT to conditionally handle permissions based on the Android version.
- For API 31+, it explicitly checks BLUETOOTH_SCAN, BLUETOOTH_CONNECT, and optionally BLUETOOTH_ADVERTISE and ACCESS_FINE_LOCATION.
- For API 30 and lower, it primarily checks ACCESS_FINE_LOCATION (since BLUETOOTH and BLUETOOTH_ADMIN are install-time).
- If any required permission is missing, it adds it to permissionsToRequest and then launches the requestBlePermissions launcher.
ensureBluetoothEnabled(): Permissions are just one part. You must also ensure the Bluetooth adapter is actually enabled. This function checks bluetoothAdapter.isEnabled and, if necessary, launches an ACTION_REQUEST_ENABLE intent.
startBleOperationsIfReady(): This is your entry point for BLE functionality. It's called only after permissions are granted AND Bluetooth is enabled.
showPermissionDeniedDialog(): A critical UX component. If permissions are permanently denied (user checks "Don't ask again"), you cannot re-request them programmatically. This dialog informs the user and provides a direct link to your app's settings page, where they can manually grant permissions.
hasRequiredBlePermissions(): A utility function to quickly check the current state of necessary permissions.

Best Practices: Avoiding Common BLE Permission Headaches

Even with the correct code, nuanced issues can arise. Here are crucial best practices derived from real-world BLE development.

Request Permissions Contextually, Not All at Once:

Pitfall: Dumping all three new Bluetooth permissions (BLUETOOTH_SCAN, BLUETOOTH_CONNECT, BLUETOOTH_ADVERTISE) to the user at app launch can be overwhelming and lead to denials. If your app only scans occasionally, asking for BLUETOOTH_CONNECT and BLUETOOTH_ADVERTISE upfront is unnecessary and bad UX.
Fix: Request permissions just before the operation that requires them. For instance, request BLUETOOTH_SCAN when the user taps a "Start Scan" button. Request BLUETOOTH_CONNECT when they select a device to connect to. This provides clear rationale and increases the likelihood of permission grants.

// Example: Only request BLUETOOTH_ADVERTISE when user explicitly enables advertising
fun enableAdvertisingClicked() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        if (ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_ADVERTISE) != PackageManager.PERMISSION_GRANTED) {
            requestBlePermissions.launch(arrayOf(Manifest.permission.BLUETOOTH_ADVERTISE))
        } else {
            startAdvertising() // Proceed with advertising
        }
    } else {
        startAdvertising() // For older APIs, BLUETOOTH_ADMIN handles this
    }
}

Understand and Utilize android:usesPermissionFlags="neverForLocation":
- Pitfall: Omitting android:usesPermissionFlags="neverForLocation" with BLUETOOTH_SCAN can inadvertently prompt the user for location permission, even if your app doesn't need it for location inference. This happens if ACCESS_FINE_LOCATION is also declared in your manifest for other purposes.
- Fix: Always include android:usesPermissionFlags="neverForLocation" when declaring BLUETOOTH_SCAN in your AndroidManifest.xml if your app does not derive physical location from BLE scan results. This tells the OS to handle BLUETOOTH_SCAN independently of ACCESS_FINE_LOCATION. Double-check your app's logic; if you're truly not inferring location, this flag is your friend.
Provide Clear Rationale and Handle Persistent Denials Gracefully:
- Pitfall: Simply showing the system permission dialog, and then crashing or failing silently if the user denies it, leads to a poor user experience. Users need to understand why you need these permissions. If they deny persistently (checking "Don't ask again"), your app might get stuck.
- Fix:
  - shouldShowRequestPermissionRationale(): Before requesting a permission, check shouldShowRequestPermissionRationale(). If it returns true, it means the user has denied the permission at least once, and you should show a custom UI (like an AlertDialog) explaining why the permission is needed before re-requesting it.
  - Direct to Settings: For persistent denials (when shouldShowRequestPermissionRationale() returns false after multiple denials), your app cannot request the permission again. Your only recourse is to guide the user to your app's settings page, where they can manually enable the permission. The showPermissionDeniedDialog() in the example code demonstrates this.
Manage Bluetooth State Independently:
- Pitfall: Assuming that granting permissions is enough to start BLE operations. Bluetooth can be disabled by the user even if permissions are granted.
- Fix: Always check BluetoothAdapter.isEnabled() before initiating any BLE operation (scan, connect, advertise). If it's disabled, prompt the user to enable it using an Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE). Your enableBluetoothLauncher example covers this.
Backward Compatibility for Older Devices:
- Pitfall: Only implementing the API 31+ permission model and breaking functionality for users on Android 11 or lower.
- Fix: Use Build.VERSION.SDK_INT checks, as shown in the checkAndRequestBlePermissions() example. Ensure your AndroidManifest.xml correctly uses maxSdkVersion for older permissions and includes ACCESS_FINE_LOCATION for scanning on pre-API 31 devices if necessary. The system will then handle the permission model appropriate for the device's OS version.

Conclusion

Navigating Android 12+ BLE permissions might seem daunting at first glance, but it's a critical step towards building more secure and privacy-respecting applications. By understanding the distinct roles of BLUETOOTH_SCAN, BLUETOOTH_CONNECT, and BLUETOOTH_ADVERTISE, correctly declaring them in your manifest, and requesting them at runtime with the Activity Result APIs, you empower your users with granular control while ensuring your app functions reliably. Remember to prioritize user experience by requesting permissions contextually, clarifying their necessity, and providing clear paths to resolution if permissions are denied. Now, go forth and refactor your BLE apps with confidence. Review your existing BLE applications today and update their permission handling to embrace the modern Android permission model.

Solving Elusive Android BLE Background Reconnection Issues: A Deep Dive into OS Restrictions and Robust Strategies

Ble Advertiser — Sun, 26 Apr 2026 11:03:12 +0000

Your Android IoT device randomly loses its BLE connection in the background, refusing to reconnect until the app is foregrounded or the device is rebooted. Sound familiar? You've likely spent hours debugging GATT_FAILURE errors or complete silence from your peripheral, only to find it magically works when your app is actively in use. This isn't a bug in your peripheral firmware; it's Android's aggressive battery optimizations and evolving background execution limits at play, compounded by often misunderstood BLE APIs.

As a senior Android developer, you know the frustration of chasing these elusive background BLE issues across multiple OS versions. This article dives deep into why these problems occur and, more importantly, provides battle-tested strategies to build reliable, persistent BLE connections that stand up to Android's stringent rules. We'll cut through the noise, equipping you with the knowledge to maintain robust background BLE communication, even when the OS is trying its best to shut you down.

Core Concepts: Understanding Android's BLE Landscape

Before we architect solutions, we must internalize the "why" behind Android's often counter-intuitive BLE behavior. The primary adversaries here are the operating system's power management features and evolving execution context rules.

OS Restrictions: The Silent Killers of Background BLE

Doze Mode & App Standby: Introduced in Android 6.0 (API 23), Doze mode puts your device into a deep sleep state when it's stationary, unplugged, and has had its screen off for a while. It defers app background CPU, network, and BLE scan activities. App Standby restricts background network and CPU access for apps that haven't been used recently. These modes are often the culprits behind "random" disconnections or failed reconnections. Your BluetoothLeScanner might simply not be granted CPU time to advertise or initiate a connection attempt.
Background Execution Limits (API 26+): Android 8.0 (API 26) introduced stricter limits on background services. Apps in the background can no longer create background services. When an app goes into the background, any running background services are stopped within a few minutes. To perform continuous background work, including persistent BLE operations, you must use a Foreground Service.
Location Permissions (API 23+): BLE scanning is inherently tied to location services. Prior to Android 12 (API 31), ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION were required for any BLE scanning. For background scanning on Android 10 (API 29) and above, you additionally need ACCESS_BACKGROUND_LOCATION. Without these, your app simply cannot discover peripherals, making reconnection attempts impossible if the peripheral's address isn't cached or if a new scan is required. Android 12+ introduces BLUETOOTH_SCAN and BLUETOOTH_CONNECT which largely replace the location requirement for scanning and connecting specifically for BLE, but ACCESS_FINE_LOCATION may still be needed for deriving location from scan results or if you target older APIs.
BluetoothGatt.connectGatt(..., autoConnect: Boolean) Nuances:
- autoConnect = false: Instructs the system to immediately connect to the remote device. This is suitable for foreground connections where the peripheral is known to be advertising, and you need a swift connection. If the device isn't advertising, it will fail quickly. It does not automatically reconnect on disconnect.
- autoConnect = true: This is your critical tool for background reconnection. It tells the system to scan for the peripheral and connect when it's advertising. If the peripheral disconnects (e.g., moves out of range), the system will continue to scan periodically in the background and automatically reconnect when it detects the peripheral again.
  - The Catch: While autoConnect = true sounds like a complete solution, its efficacy is subject to OS power management. When your app is in the background and not running a Foreground Service, the system's scanning interval for autoConnect can become very infrequent or stop entirely to conserve battery. This is why a Foreground Service is paramount.

Robust Reconnection Strategies: Your Toolkit

Foreground Services: This is your primary mechanism for continuous, uninterrupted BLE operations in the background. By declaring a Foreground Service, you explicitly inform the OS that your app is performing important, user-visible work, thus exempting it from many background execution limits. The notification associated with a Foreground Service makes this transparent to the user.
- API 34+: FOREGROUND_SERVICE_CONNECTED_DEVICE permission is specifically for services that connect to external devices, further solidifying the intent.
autoConnect: true as the Foundation: Always use autoConnect: true for persistent connections where the peripheral may go in and out of range. This offloads the reconnection logic to the system, which is generally more reliable and power-efficient than your app constantly initiating new connectGatt calls.
Persistent Scan with PendingIntent (API 26+): For scenarios where you need to discover a peripheral (e.g., initial connection or after a long-term unpairing), BluetoothLeScanner.startScan() with a PendingIntent is the most robust background scanning method. Instead of your app running continuously, the system wakes up your BroadcastReceiver or Service only when a scan result matches your ScanFilter. This is significantly more power-efficient and reliable in the background compared to ScanCallback variants.
Strategic BluetoothGatt Management: Maintain a strong reference to your BluetoothGatt instance. Do not call gatt.close() unless you intend to permanently disconnect and release resources. Calling close() too often will force you to restart the entire discovery/connection process. Instead, rely on autoConnect: true to handle range-based disconnects gracefully.
Robust onConnectionStateChange Handling: This callback is central to your reconnection logic. Monitor BluetoothGatt.GATT_DISCONNECTED and BluetoothGatt.GATT_FAILURE.
- GATT_DISCONNECTED (status 0 or 8 typically): The device was connected and then disconnected. If autoConnect: true was used, the system should attempt reconnection.
- GATT_FAILURE (status 133, 19, 22, etc.): A connection attempt failed. This is where you might need to manually retry connectGatt or initiate a new scan if the peripheral's address is unknown or unreliable. Implement exponential backoff for retries to avoid hammering the BLE stack.

Implementation: Building a Resilient BLE Stack

Let's put these concepts into practice. We'll focus on setting up a Foreground Service to host our BLE operations and implementing robust connection logic.

1. Permissions (Manifest & Runtime)

Declare necessary permissions in your AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.yourapp.ble">

    <!-- Permissions for BLE scanning & connecting -->
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />

    <!-- Required for BLE scans on Android 9 (API 28) and below -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" android:maxSdkVersion="30" />
    <!-- Required for BLE scans on Android 10 (API 29) and above -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <!-- Required for background BLE scans on Android 10 (API 29) and above -->
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

    <!-- Android 12 (API 31) and above: New BLE permissions -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

    <!-- Required for Foreground Services -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <!-- Required for Foreground Services connecting to external devices on Android 14 (API 34) and above -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" />

    <!-- Required for showing Foreground Service notifications on Android 13 (API 33) and above -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <application
        ...
        <service
            android:name=".BleService"
            android:enabled="true"
            android:exported="false"
            android:foregroundServiceType="connectedDevice" /> <!-- API 34+ specific type -->
    </application>
</manifest>

Runtime Permissions: You must request ACCESS_FINE_LOCATION (or ACCESS_BACKGROUND_LOCATION if targeting API 29+) and BLUETOOTH_SCAN/BLUETOOTH_CONNECT at runtime. For Android 13+, POST_NOTIFICATIONS is also a runtime permission.

2. Foreground Service Setup

// In your BleService.kt (or similar service class)
class BleService : Service() {

    private val NOTIFICATION_ID = 101
    private val NOTIFICATION_CHANNEL_ID = "ble_service_channel"
    private lateinit var notificationManager: NotificationManager

    // ... other BLE related properties: bluetoothAdapter, bluetoothLeScanner, bluetoothGatt, etc.

    override fun onCreate() {
        super.onCreate()
        notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
        createNotificationChannel()
    }

    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        val notification = buildNotification("BLE Service Running", "Maintaining connection to device...")
        startForeground(NOTIFICATION_ID, notification)

        // Initialize and start your BLE operations here
        // e.g., startScanningForDevice() or attemptConnectToKnownDevice()
        Log.d("BleService", "Foreground service started.")

        // We want the service to continue running until it is explicitly stopped.
        return START_STICKY
    }

    override fun onBind(intent: Intent?): IBinder? {
        return null // Not using binding for this example
    }

    override fun onDestroy() {
        super.onDestroy()
        stopForeground(STOP_FOREGROUND_REMOVE)
        // Clean up BLE resources (close gatt, stop scan)
        Log.d("BleService", "Foreground service stopped.")
    }

    private fun createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val serviceChannel = NotificationChannel(
                NOTIFICATION_CHANNEL_ID,
                "BLE Service Channel",
                NotificationManager.IMPORTANCE_LOW
            )
            notificationManager.createNotificationChannel(serviceChannel)
        }
    }

    private fun buildNotification(title: String, content: String): Notification {
        val pendingIntent: PendingIntent =
            Intent(this, MainActivity::class.java).let { notificationIntent ->
                PendingIntent.getActivity(this, 0, notificationIntent, PendingIntent.FLAG_IMMUTABLE)
            }

        return NotificationCompat.Builder(this, NOTIFICATION_CHANNEL_ID)
            .setContentTitle(title)
            .setContentText(content)
            .setSmallIcon(R.drawable.ic_bluetooth) // Replace with your icon
            .setContentIntent(pendingIntent)
            .setOngoing(true)
            .setPriority(NotificationCompat.PRIORITY_LOW)
            .build()
    }

    // Methods for starting/stopping BLE scans and connections will reside here
}

To start this service from your Activity:

// In your Activity or Application class
fun startBleService() {
    val serviceIntent = Intent(context, BleService::class.java)
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
        // For API 34+, ensure FOREGROUND_SERVICE_CONNECTED_DEVICE is declared and handled.
        // Also, POST_NOTIFICATIONS for API 33+
        context.startForegroundService(serviceIntent)
    } else {
        context.startService(serviceIntent)
    }
}

fun stopBleService() {
    val serviceIntent = Intent(context, BleService::class.java)
    context.stopService(serviceIntent)
}

3. Robust `BluetoothGatt` Management and Reconnection Logic

This is where autoConnect: true truly shines, especially when managed within a Foreground Service.

// Inside your BleService class or a dedicated BleManager class instantiated within the service
class BleService : Service() {
    // ... (previous code)

    private var bluetoothGatt: BluetoothGatt? = null
    private var isConnecting = false
    private val deviceAddress = "XX:XX:XX:XX:XX:XX" // Your peripheral's MAC address

    // Define a retry mechanism for failed connections
    private val handler = Handler(Looper.getMainLooper())
    private var retryCount = 0
    private val MAX_RETRY_ATTEMPTS = 5
    private val INITIAL_RETRY_DELAY_MS = 5000L // 5 seconds
    private val retryRunnable = Runnable { attemptConnectToKnownDevice() }

    private fun attemptConnectToKnownDevice() {
        if (isConnecting) {
            Log.w("BleService", "Already attempting to connect. Skipping.")
            return
        }

        if (!hasBlePermissions()) {
            Log.e("BleService", "Missing BLE permissions to connect.")
            return // You should handle requesting permissions upfront
        }

        val bluetoothManager = getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
        val bluetoothAdapter = bluetoothManager.adapter
        if (bluetoothAdapter == null || !bluetoothAdapter.isEnabled) {
            Log.e("BleService", "Bluetooth not enabled or adapter not available.")
            // Consider prompting user or waiting for BT to be enabled
            handler.postDelayed(retryRunnable, INITIAL_RETRY_DELAY_MS) // Retry after delay
            return
        }

        val device = bluetoothAdapter.getRemoteDevice(deviceAddress)
        if (device == null) {
            Log.e("BleService", "Device with address $deviceAddress not found.")
            // This usually means address is invalid or not seen recently.
            // You might need to initiate a background scan to rediscover.
            return
        }

        Log.i("BleService", "Attempting connection to $deviceAddress with autoConnect: true")
        isConnecting = true
        // Important: Pass 'this' (the Service context) as the context.
        // Use BluetoothDevice.TRANSPORT_LE for explicit LE transport.
        bluetoothGatt = device.connectGatt(this, true, gattCallback, BluetoothDevice.TRANSPORT_LE)
        // If connectGatt returns null (e.g., due to system resource issues), retry.
        if (bluetoothGatt == null) {
            Log.e("BleService", "connectGatt returned null. Retrying after delay.")
            isConnecting = false // Reset state
            handler.postDelayed(retryRunnable, INITIAL_RETRY_DELAY_MS)
        }
    }

    private val gattCallback = object : BluetoothGattCallback() {
        override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
            super.onConnectionStateChange(gatt, status, newState)
            Log.d("BleService", "onConnectionStateChange: status=$status, newState=$newState")

            when (newState) {
                BluetoothProfile.STATE_CONNECTED -> {
                    Log.i("BleService", "Device $deviceAddress CONNECTED.")
                    isConnecting = false
                    retryCount = 0 // Reset retry count on successful connection
                    handler.removeCallbacks(retryRunnable) // Stop any pending retries

                    // You are connected. Now discover services.
                    gatt.discoverServices()
                    updateNotification("BLE Connected", "Connected to $deviceAddress")
                }
                BluetoothProfile.STATE_DISCONNECTED -> {
                    Log.w("BleService", "Device $deviceAddress DISCONNECTED. Status: $status")
                    isConnecting = false // Allow new connection attempts

                    // Crucial: The autoConnect=true should *ideally* handle reconnections itself.
                    // However, if the status indicates a critical error (e.g., GATT_FAILURE 133),
                    // or if the auto-reconnect isn't happening quickly enough for specific reasons,
                    // you might want to explicitly re-initiate connectGatt with a delay.
                    // DO NOT call gatt.close() here unless you truly want to stop all attempts.
                    // Rely on autoConnect: true for range-based disconnects.

                    // If autoConnect fails or you want an immediate retry:
                    if (retryCount < MAX_RETRY_ATTEMPTS) {
                        val delay = INITIAL_RETRY_DELAY_MS * (1 shl retryCount) // Exponential backoff
                        Log.i("BleService", "Retrying connection in ${delay / 1000}s. Attempt: ${retryCount + 1}")
                        retryCount++
                        handler.postDelayed(retryRunnable, delay)
                    } else {
                        Log.e("BleService", "Max reconnection retries reached for $deviceAddress.")
                        updateNotification("BLE Disconnected", "Failed to connect to $deviceAddress")
                        // Potentially stop service or initiate background scan for rediscovery
                    }
                }
                // Other states like CONNECTING, DISCONNECTING are transient
            }

            if (status != BluetoothGatt.GATT_SUCCESS) {
                // Handle GATT_FAILURE or other specific error codes that prevent connection
                Log.e("BleService", "GATT operation failed with status $status.")
                if (newState == BluetoothProfile.STATE_DISCONNECTED && status == BluetoothGatt.GATT_FAILURE) {
                    // This is a specific failure during connection or operation, not just a disconnect.
                    // The retry logic above (for STATE_DISCONNECTED) will cover this, but specific
                    // handling might be needed depending on the status code.
                }
            }
        }

        override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
            super.onServicesDiscovered(gatt, status)
            if (status == BluetoothGatt.GATT_SUCCESS) {
                Log.i("BleService", "Services discovered for $deviceAddress.")
                // Proceed with reading/writing characteristics
            } else {
                Log.e("BleService", "Service discovery failed with status $status.")
                // You might want to disconnect and retry, or handle the error
            }
        }
        // ... other GATT callbacks for characteristic read/write, descriptor read/write, etc.
    }

    private fun hasBlePermissions(): Boolean {
        // Implement robust permission check for BLUETOOTH_CONNECT, BLUETOOTH_SCAN, ACCESS_FINE_LOCATION
        // based on Android version. This is simplified for brevity.
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_CONNECT) == PackageManager.PERMISSION_GRANTED &&
            ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_SCAN) == PackageManager.PERMISSION_GRANTED
        } else {
            ContextCompat.checkSelfPermission(this, Manifest.permission.ACCESS_FINE_LOCATION) == PackageManager.PERMISSION_GRANTED
        }
    }

    private fun updateNotification(title: String, content: String) {
        val notification = buildNotification(title, content)
        notificationManager.notify(NOTIFICATION_ID, notification)
    }

    // Call this to initiate the connection from onStartCommand or other entry points
    fun startBleConnection() {
        attemptConnectToKnownDevice()
    }
}

Best Practices: Avoid Common Pitfalls

Even with the right concepts, missteps can derail your background BLE reliability.

Pitfall: Relying solely on autoConnect: true without a Foreground Service.
- Problem: You implement connectGatt(..., true, ...) thinking it handles everything. Your app works perfectly when foregrounded, but connections drop mysteriously in the background and never return. This is because Android aggressively throttles background apps, even those with autoConnect: true configured, to conserve battery. The system's periodic scan for autoConnect becomes too infrequent or stops entirely.
- Fix: Always run BluetoothGatt.connectGatt (especially with autoConnect: true) within a Foreground Service when background persistence is required. The Foreground Service signals to the OS that your app's background work is critical, granting it sufficient resources to maintain the BLE connection and perform necessary re-connection scans. Additionally, for API 34+, declare android:foregroundServiceType="connectedDevice" in your manifest service tag and request FOREGROUND_SERVICE_CONNECTED_DEVICE permission.
Pitfall: Prematurely calling gatt.close() or gatt.disconnect() on every perceived disconnection.
- Problem: On receiving STATE_DISCONNECTED in onConnectionStateChange, your instinct might be to immediately call gatt.close(). While close() releases GATT resources, it also destroys the autoConnect: true mechanism. If you close() the GATT object, the system will not automatically try to reconnect. Subsequent calls to connectGatt will create a new GATT instance, potentially leading to connection delays or issues, especially if the device is momentarily out of range. Similarly, calling gatt.disconnect() only immediately tears down the current connection but doesn't stop autoConnect: true from working; however, if you then close() it, you're back to square one.
- Fix: Only call gatt.close() when you are absolutely finished with the BLE device and do not intend to connect to it again for an extended period (e.g., user unpairs device). For temporary disconnections (device moved out of range, peripheral rebooted), let autoConnect: true do its job. The system is designed to gracefully re-establish the connection when the peripheral becomes available again. Implement your own retry logic (like the exponential backoff shown) only for persistent GATT_FAILURE scenarios or when autoConnect proves insufficient after a long period.
Pitfall: Inadequate power management configuration for background scans when autoConnect: true isn't sufficient for discovery.
- Problem: You need to initially discover a peripheral or rediscover one whose address isn't known (e.g., after a factory reset). You use BluetoothLeScanner.startScan(ScanCallback) within your Foreground Service, but scan results are sporadic or non-existent in the background. While a Foreground Service helps, direct ScanCallback scans are still susceptible to system throttling.
- Fix: For persistent background discovery, leverage BluetoothLeScanner.startScan(List<ScanFilter>, ScanSettings, PendingIntent). This delegates the scanning responsibility to the OS. The system will then wake up your specified BroadcastReceiver or Service only when a ScanFilter match is found, which is significantly more power-efficient and reliable under Android's background execution limits. Use ScanSettings.SCAN_MODE_LOW_POWER or SCAN_MODE_BALANCED with MATCH_MODE_STICKY for ScanFilter to optimize for battery life and ensure persistent matching.
Pitfall: Neglecting API-level specific permission handling and runtime checks.
- Problem: Your app works on Android 11, but fails to scan or connect on Android 12+. Or your Foreground Service gets killed on Android 13/14 due to missing notification permissions. Android's permission model for BLE has evolved significantly, and older permission declarations or inadequate runtime checks lead to silent failures.
- Fix: Implement a robust, API-version-aware permission request flow.
  - Android 12+ (API 31+): Request BLUETOOTH_SCAN and BLUETOOTH_CONNECT at runtime.
  - Android 10 (API 29+): Request ACCESS_BACKGROUND_LOCATION at runtime for background scanning, in addition to ACCESS_FINE_LOCATION.
  - Android 13+ (API 33+): Request POST_NOTIFICATIONS at runtime for your Foreground Service notification.
  - Android 14+ (API 34+): Declare FOREGROUND_SERVICE_CONNECTED_DEVICE in your manifest and potentially request it, although it's typically granted with other necessary permissions. Always check if a permission is granted before attempting a BLE operation, and gracefully handle cases where permissions are denied (e.g., guiding the user to settings).

Conclusion

Taming Android's BLE background reconnection challenges requires a deep understanding of its OS restrictions and a disciplined approach to implementation. You've seen that the combination of a well-configured Foreground Service, intelligent use of BluetoothGatt.connectGatt(..., autoConnect: true), and strategic handling of BluetoothGattCallback is non-negotiable for reliable, persistent connections. Supplement this with PendingIntent-based scanning for robust background discovery and meticulous, API-version-aware permission management.

Review your existing BLE background logic against these strategies. Prioritize robust state management, aggressive error handling with sensible retry mechanisms, and always design with Android's battery-saving behaviors in mind. The path to truly resilient BLE in production apps demands this level of attention to detail.

Conquering Elusive Android BLE `GATT_FAILURE` and Connection Timeouts in Kotlin

Ble Advertiser — Sun, 26 Apr 2026 11:02:09 +0000

Your Android BLE application functions flawlessly during development and testing on a few devices. Then it hits production, and suddenly, users report infuriatingly inconsistent GATT_FAILURE errors or frustrating connection timeouts. These are not just minor bugs; they represent fundamental communication breakdowns that can cripple your connectivity solution. If you've spent hours staring at logcat, feeling lost in a sea of generic error codes, you're in the right place.

Debugging Bluetooth Low Energy (BLE) on Android is notoriously challenging. The asynchronous nature of the API, the complex interplay with the underlying Bluetooth stack, and myriad device-specific quirks make GATT_FAILURE a cryptic adversary. This article dissects the common culprits behind these elusive errors and connection dropouts. You'll gain a systematic, advanced debugging methodology, complete with code examples and best practices, to stabilize your BLE connections and finally achieve predictable behavior.

Core Concepts: Understanding the Battlefield

Before we dive into the trenches, let's establish a clear understanding of the core BLE concepts that often lead to these issues.

The Android BLE State Machine: More Like a Minefield

Your application interacts with a remote BLE device through a series of asynchronous steps, each with potential failure points.

       [Start Scan]
             |
             V
  [Device Discovered]
             |
             V
    [connectGatt(device, autoConnect, callback)]
             |
             V
  onConnectionStateChange(STATE_CONNECTED)
             |
             V
    [discoverServices()]
             |
             V
  onServicesDiscovered(status)
             |
             V
[requestMtu(value)] (Optional, but recommended)
             |
             V
  onMtuChanged(mtu, status)
             |
             V
[Read/Write/Notify operations]
             |
             V
onCharacteristicRead(char, status) / onCharacteristicWrite(char, status) / onDescriptorWrite(desc, status)
             |
             V
    [disconnect()]
             |
             V
onConnectionStateChange(STATE_DISCONNECTED)
             |
             V
    [close()] <--- CRITICAL RESOURCE RELEASE

Every arrow represents a potential point of failure. The status parameter in the BluetoothGattCallback methods is your first indicator, but GATT_FAILURE often obscures the true root cause.

`BluetoothGatt.GATT_FAILURE`: The Generic Culprit

When you see status = BluetoothGatt.GATT_FAILURE (or its integer value, typically 133) in onConnectionStateChange, onServicesDiscovered, or other callbacks, it's a generic catch-all indicating an error in the underlying Bluetooth stack. It could mean:

Resource Exhaustion: The Android Bluetooth stack has run out of resources (e.g., too many pending connections, BluetoothGatt objects not properly closed). This is a common cause for 133.
Protocol Violation: Your device or the peripheral violated the BLE specification.
Internal Stack Error: A bug or transient issue within the Android or peripheral's Bluetooth firmware.
Timeout: While not always explicit, some GATT_FAILURE codes can indicate an operation timed out at a lower level.
Specific Error Codes: While GATT_FAILURE is 133, you might encounter others:
- 19: Often seen during connection attempts, indicating a connection failed due to an internal error or the device was unreachable.
- 257: Less common, but can appear during service discovery, signaling an internal stack error or timeout.

Connection Timeouts: The Silent Killer

A connection timeout isn't a direct error code but the absence of an expected callback within a reasonable timeframe. It could manifest as:

connectGatt() returning null.
onConnectionStateChange with STATE_CONNECTED never being called.
onServicesDiscovered never firing after discoverServices().
A GATT operation (read/write) never getting its corresponding callback.

Timeouts often stem from RF interference, a peripheral going out of range, or the underlying stack being stuck or unresponsive.

Android BLE Stack Nuances

Single BluetoothGatt Instance: Android's BLE stack generally expects one active BluetoothGatt object per remote device. Violating this rule is a major source of GATT_FAILURE.
Asynchronous & Single-Threaded Nature: All BluetoothGatt methods (e.g., readCharacteristic, writeCharacteristic) are asynchronous and must be called sequentially, waiting for the previous operation's callback to complete before initiating the next.
Bluetooth Adapter State: The BluetoothAdapter can change state (e.g., user turns Bluetooth off/on). Your app must react to these changes.
Android Version Variations: BLE behavior and stability can vary significantly between Android versions and OEM implementations. Test on a range of devices!

Implementation: A Systematic Debugging Approach

When GATT_FAILURE strikes, panic leads nowhere. You need a structured approach.

Prerequisites

Android API Level: Target API 21 (Lollipop) or higher for modern BLE APIs. Kotlin is assumed for code examples.

Permissions: Crucial for BLE operations.

android.permission.BLUETOOTH_SCAN (Android 12+)
android.permission.BLUETOOTH_CONNECT (Android 12+)
android.permission.BLUETOOTH_ADVERTISE (Android 12+, if advertising)
android.permission.ACCESS_FINE_LOCATION (Android 11 and below, for scanning)
android.permission.ACCESS_COARSE_LOCATION (Deprecated, but sometimes included for older devices)

Always request these at runtime:

// Example for Android 12+
private val requestBluetoothPermissions = registerForActivityResult(
    ActivityResultContracts.RequestMultiplePermissions()
) { permissions ->
    if (permissions[Manifest.permission.BLUETOOTH_SCAN] == true &&
        permissions[Manifest.permission.BLUETOOTH_CONNECT] == true
    ) {
        // Permissions granted, proceed with BLE
        startBleScan()
    } else {
        // Handle permission denial
        Toast.makeText(this, "Bluetooth permissions are required.", Toast.LENGTH_SHORT).show()
    }
}

fun checkAndRequestBlePermissions() {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        if (checkSelfPermission(Manifest.permission.BLUETOOTH_SCAN) != PackageManager.PERMISSION_GRANTED ||
            checkSelfPermission(Manifest.permission.BLUETOOTH_CONNECT) != PackageManager.PERMISSION_GRANTED) {
            requestBluetoothPermissions.launch(
                arrayOf(
                    Manifest.permission.BLUETOOTH_SCAN,
                    Manifest.permission.BLUETOOTH_CONNECT
                )
            )
        } else {
            startBleScan()
        }
    } else {
        // For older Android versions, ACCESS_FINE_LOCATION is sufficient
        if (checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
            requestBluetoothPermissions.launch(arrayOf(Manifest.permission.ACCESS_FINE_LOCATION))
        } else {
            startBleScan()
        }
    }
}

Indispensable Debugging Tools

adb logcat with Strategic Filtering:
This is your frontline. Filter aggressively to cut through the noise.
```
# Filter for common BLE tags and 'GATT'
adb logcat -s "BluetoothGatt:V" "BluetoothAdapter:V" "BluetoothManager:V" "BtGatt:V" "GATT:V" "System.err:V" "*:W"

# Filter for specific error codes, e.g., 133
adb logcat | grep -E "BluetoothGatt|BluetoothAdapter|GATT|status=133"
```
Look for:
- Sequence of events: Does onConnectionStateChange with STATE_CONNECTED always precede discoverServices()?
- status codes: Log every status value you receive.
- Delays: Long gaps between expected callbacks.
- Stack tracebacks: Especially from System.err.
Bluetooth HCI Snoop Log (The Holy Grail):
This is the most powerful tool for low-level BLE debugging. It captures all Bluetooth Host Controller Interface (HCI) packets, letting you see the raw BLE air traffic between your Android device and the peripheral.

How to enable:
1. Go to Android Developer Options (Settings -> About Phone -> Tap Build Number 7 times).
2. Scroll down to "Networking" or "Bluetooth" section.
3. Enable "Enable Bluetooth HCI snoop log".
4. Restart Bluetooth on your device (turn off/on).
5. Reproduce the GATT_FAILURE or timeout issue.
How to retrieve & analyze:
1. Connect your device to your computer via USB.
2. Pull the log file:
```
adb pull /sdcard/Android/data/btsnoop_hci.log .
```
  (Location may vary slightly between Android versions/OEMs, try /sdcard/btsnoop_hci.log or /data/misc/bluetooth/logs/btsnoop_hci.log if the first path doesn't work).
3. Open btsnoop_hci.log with Wireshark.
4. Apply Wireshark filters:
  - btle (shows all BLE packets)
  - btatt (shows Attribute Protocol packets, including GATT operations)
  - btgap (shows Generic Access Profile, e.g., advertisements, connection requests)
  - btatt.opcode == 0x01 (Error Response)
  - btatt.handle == 0xXXXX (Filter by specific attribute handle)
The HCI snoop log will reveal exactly what packets were exchanged, any lost packets, retransmissions, and the exact error codes returned at the ATT (Attribute Protocol) level, which is far more granular than GATT_FAILURE.
External BLE Sniffer (Advanced Hardware):

For the most intractable issues, an external hardware sniffer (e.g., Nordic nRF Sniffer, Ellisys, Frontline) captures BLE packets directly from the air, allowing you to see traffic from both sides (Android and peripheral) without modifying the Android device. This helps diagnose issues like peripheral misbehavior or RF interference.

Robust GATT Lifecycle Management

The BluetoothGatt object is precious and must be managed diligently.

// In your BleManager or similar class
private var bluetoothGatt: BluetoothGatt? = null
private val gattOperationsQueue = ConcurrentLinkedQueue<() -> Unit>()
private var isGattOperationInProgress = false

// ... inside your BleManager class

// Call this to initiate connection
fun connectToDevice(device: BluetoothDevice, context: Context) {
    if (bluetoothGatt != null) {
        Log.w(TAG, "Already connected or connecting to a device. Call disconnect() first.")
        disconnect() // Ensure previous connection is torn down
        return
    }

    // Set autoConnect to false for direct connections where you manage retries.
    // true is for background connections/wakeups which can be less predictable.
    bluetoothGatt = device.connectGatt(context, false, gattCallback)
    Log.i(TAG, "Attempting to connect to GATT client: ${device.address}")
}

// Ensure proper disconnection and resource release
fun disconnect() {
    bluetoothGatt?.let { gatt ->
        gatt.disconnect() // Trigger onConnectionStateChange with STATE_DISCONNECTED
    }
    // Don't close immediately here. Let onConnectionStateChange handle it.
}

private fun closeGatt() {
    bluetoothGatt?.let { gatt ->
        gatt.close() // Release native resources
        bluetoothGatt = null // Clear reference
        isGattOperationInProgress = false
        gattOperationsQueue.clear() // Clear any pending operations
        Log.i(TAG, "BluetoothGatt closed and resources released.")
    }
}

// Example of how to add operations to the queue
fun writeCharacteristic(characteristic: BluetoothGattCharacteristic, value: ByteArray) {
    val operation = {
        bluetoothGatt?.let { gatt ->
            characteristic.value = value
            if (!gatt.writeCharacteristic(characteristic)) {
                Log.e(TAG, "Failed to initiate characteristic write.")
                // Handle failure to initiate, maybe requeue or error out.
                signalOperationComplete() // Proceed to next operation in queue
            } else {
                Log.d(TAG, "Initiated characteristic write to ${characteristic.uuid}")
            }
        } ?: run {
            Log.e(TAG, "Gatt not connected, cannot write characteristic.")
            signalOperationComplete()
        }
    }
    queueGattOperation(operation)
}

// Function to manage the queue
private fun queueGattOperation(operation: () -> Unit) {
    gattOperationsQueue.offer(operation)
    if (!isGattOperationInProgress) {
        processNextGattOperation()
    }
}

private fun processNextGattOperation() {
    if (isGattOperationInProgress) {
        return // Wait for current operation to complete
    }

    val operation = gattOperationsQueue.poll()
    if (operation != null) {
        isGattOperationInProgress = true
        // Execute the operation on the main thread or a dedicated handler thread
        // (BluetoothGatt methods should be called from the thread that created the BluetoothGatt object)
        Handler(Looper.getMainLooper()).post {
            operation.invoke()
        }
    } else {
        isGattOperationInProgress = false
    }
}

// Call this from ALL BluetoothGattCallback methods after processing (e.g., onCharacteristicWrite, onCharacteristicRead, onServicesDiscovered, onMtuChanged)
private fun signalOperationComplete() {
    isGattOperationInProgress = false
    processNextGattOperation()
}

private val gattCallback = object : BluetoothGattCallback() {
    override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
        val deviceAddress = gatt.device.address
        if (status != BluetoothGatt.GATT_SUCCESS) {
            // Log generic GATT_FAILURE (133) or other errors
            Log.e(TAG, "Connection state change error, status: $status for $deviceAddress")
            closeGatt() // Always close on errors to release resources
            // Notify UI of connection error
            return
        }

        when (newState) {
            BluetoothProfile.STATE_CONNECTED -> {
                Log.i(TAG, "Connected to GATT client: $deviceAddress")
                // Start service discovery
                queueGattOperation { gatt.discoverServices() }
            }
            BluetoothProfile.STATE_DISCONNECTED -> {
                Log.i(TAG, "Disconnected from GATT client: $deviceAddress")
                closeGatt() // Important: Always close GATT after disconnection
                // Notify UI of disconnection
            }
        }
    }

    override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
        if (status == BluetoothGatt.GATT_SUCCESS) {
            Log.i(TAG, "Services discovered for ${gatt.device.address}")
            // Optional: Request MTU after services discovered
            queueGattOperation { gatt.requestMtu(23 /* or higher, max 517 */) }
        } else {
            Log.e(TAG, "Service discovery failed with status: $status for ${gatt.device.address}")
            closeGatt()
        }
        signalOperationComplete() // Always signal completion
    }

    override fun onMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int) {
        if (status == BluetoothGatt.GATT_SUCCESS) {
            Log.i(TAG, "MTU changed to $mtu for ${gatt.device.address}")
            // Now you can safely perform other operations
            // For example, read a characteristic:
            // queueGattOperation { readCharacteristic(yourCharacteristic) }
        } else {
            Log.e(TAG, "MTU change failed with status: $status for ${gatt.device.address}")
            closeGatt()
        }
        signalOperationComplete() // Always signal completion
    }

    override fun onCharacteristicRead(
        gatt: BluetoothGatt,
        characteristic: BluetoothGattCharacteristic,
        status: Int
    ) {
        if (status == BluetoothGatt.GATT_SUCCESS) {
            val value = characteristic.value // Process data
            Log.d(TAG, "Read char ${characteristic.uuid}: ${value.toHexString()}")
        } else {
            Log.e(TAG, "Characteristic read failed with status: $status for ${characteristic.uuid}")
        }
        signalOperationComplete()
    }

    override fun onCharacteristicWrite(
        gatt: BluetoothGatt,
        characteristic: BluetoothGattCharacteristic,
        status: Int
    ) {
        if (status == BluetoothGatt.GATT_SUCCESS) {
            Log.d(TAG, "Characteristic ${characteristic.uuid} written successfully.")
        } else {
            Log.e(TAG, "Characteristic write failed with status: $status for ${characteristic.uuid}")
        }
        signalOperationComplete()
    }

    // ... handle other callbacks like onCharacteristicChanged, onDescriptorRead, onDescriptorWrite
}

// Extension function for easier logging
fun ByteArray.toHexString(): String = joinToString(separator = " ", prefix = "0x") { String.format("%02X", it) }

This code snippet demonstrates:

Queueing GATT operations: gattOperationsQueue ensures all operations are executed serially, preventing race conditions that often lead to GATT_FAILURE.
Explicit closeGatt(): Calling close() releases native Bluetooth stack resources. Failure to do so will result in resource leaks and subsequent GATT_FAILURE (especially 133) on new connection attempts.
Error handling in callbacks: Every callback checks status. If status is not GATT_SUCCESS, the error is logged, and closeGatt() is called to reset the state.
MTU request: Demonstrates how requestMtu is just another queued GATT operation.

Best Practices: Avoiding the Pitfalls

Pitfall 1: Multiple `BluetoothGatt` Instances for the Same Device

Creating multiple BluetoothGatt objects for the same remote device without properly closing previous ones is a direct path to GATT_FAILURE 133. The underlying stack gets confused, resource handles are leaked, and subsequent operations fail.

Fix: Implement a strict "one BluetoothGatt instance per remote BluetoothDevice" policy.

Maintain a Map<String, BluetoothGatt> or similar to track active connections by device address.
Before initiating a new connectGatt(), always check if an existing BluetoothGatt object for that device exists. If so, close() it and set the reference to null before proceeding.
Ensure closeGatt() is always called on onConnectionStateChange when newState is STATE_DISCONNECTED or on any critical GATT_FAILURE.

Pitfall 2: Overlapping/Unqueued GATT Operations

Calling gatt.readCharacteristic(), gatt.writeCharacteristic(), or gatt.requestMtu() in rapid succession without waiting for their respective callbacks (onCharacteristicRead, onCharacteristicWrite, onMtuChanged) will lead to unpredictable behavior, dropped operations, and GATT_FAILURE. The Android Bluetooth stack is fundamentally asynchronous and single-threaded in its GATT operation processing.

Fix: Implement a strict serial queue for all GATT operations.

As shown in the code example, use a ConcurrentLinkedQueue<() -> Unit> or similar to hold your GATT operations.
Only execute the next operation from the queue after the current operation's callback has been received and processed (signalOperationComplete()). This ensures proper serialization.
Consider a timeout mechanism for operations stuck in the queue or waiting for a callback. If an operation times out, you might need to disconnect and reconnect to reset the GATT state.

Pitfall 3: Not Handling `BluetoothGatt.close()` Correctly or in Time

Many developers correctly call disconnect(), but forget the critical gatt.close() call, or call it too early/late. gatt.close() is what releases the native resources held by the Android Bluetooth stack. Without it, these resources accumulate, leading to resource exhaustion (GATT_FAILURE 133) and preventing future connections.

Fix:

Always call gatt.disconnect() first.
Crucially, call gatt.close() only after onConnectionStateChange returns with newState == BluetoothProfile.STATE_DISCONNECTED or if a severe, unrecoverable GATT_FAILURE occurs during connection or service discovery. This ensures the stack has completed its graceful shutdown.
Set the BluetoothGatt reference to null immediately after close() to prevent accidental reuse.
Implement a connection timeout for connectGatt(). If a connection doesn't establish within, say, 10-15 seconds, assume failure, call disconnect() (if bluetoothGatt is not null), then close(), and attempt a retry.

Pitfall 4: Ignoring Bluetooth Adapter State Changes

The user can turn Bluetooth on or off at any time. If your app is connected or scanning, and the adapter suddenly powers down, your connection will break, and your scan will stop. Ignoring these events leads to a broken user experience and can leave your app in an inconsistent state.

Fix: Register a BroadcastReceiver for BluetoothAdapter.ACTION_STATE_CHANGED.

When STATE_OFF is received, gracefully disconnect any active connections, stop scans, and update UI.
When STATE_ON is received, you can re-enable scanning and prompt the user to reconnect.

// In your Activity or Service
private val bluetoothStateReceiver = object : BroadcastReceiver() {
    override fun onReceive(context: Context?, intent: Intent?) {
        val state = intent?.getIntExtra(BluetoothAdapter.EXTRA_STATE, BluetoothAdapter.ERROR)
        when (state) {
            BluetoothAdapter.STATE_OFF -> {
                Log.w(TAG, "Bluetooth Adapter OFF. Disconnecting all GATT clients.")
                bleManager.disconnectAll() // Implement a method to close all connections
                // Stop scanning, update UI, etc.
            }
            BluetoothAdapter.STATE_ON -> {
                Log.i(TAG, "Bluetooth Adapter ON. Ready for BLE operations.")
                // Potentially restart scanning or prompt user to connect
            }
        }
    }
}

override fun onStart() {
    super.onStart()
    val filter = IntentFilter(BluetoothAdapter.ACTION_STATE_CHANGED)
    registerReceiver(bluetoothStateReceiver, filter)
}

override fun onStop() {
    super.onStop()
    unregisterReceiver(bluetoothStateReceiver)
}

Conclusion

Debugging GATT_FAILURE and connection timeouts in Android BLE is a test of patience and methodical investigation. You've learned that GATT_FAILURE is a generic symptom often rooted in improper BluetoothGatt lifecycle management, overlapping operations, or resource exhaustion. The key to conquering these issues lies in a systematic debugging approach: leveraging adb logcat, employing the powerful Bluetooth HCI snoop log with Wireshark, and meticulously managing your BluetoothGatt instances and operations through a serialization queue. By adhering to these best practices, you can build more robust and predictable BLE applications. Your next step should be to integrate a GATT operation queue and HCI snoop logging into your standard BLE development workflow.

How to Keep Your BLE Scan Alive: Overcoming Android 10+ Background Restrictions for Persistent Discovery

Ble Advertiser — Sun, 26 Apr 2026 10:54:34 +0000

Ever found your meticulously crafted BLE background scanner abruptly terminating on modern Android versions? You're not alone. Android 10 (API 29) and subsequent releases introduced stringent background execution limits, fundamentally changing how apps can perform long-running tasks, including persistent Bluetooth Low Energy (BLE) scanning. If your IoT solution relies on discovering nearby devices continuously, these OS restrictions become a critical hurdle. This article cuts through the noise, providing a direct, actionable guide to building robust, always-on BLE discovery, even on the latest Android iterations.

The Problem: Android's Enforcement on Background Operations

Before Android 10, performing background BLE scans was relatively straightforward: start a service, initiate BluetoothLeScanner.startScan(), and process results. Post-Android 10, the landscape changed dramatically. The operating system now aggressively manages resources, putting a cap on how long an app can execute in the background if it's not performing a "user-perceptible" task. For BLE scans, this means:

Limited Scan Duration: Background scans initiated via ScanCallback are severely limited, often terminating after a few minutes, sometimes even faster depending on device OEM optimizations and battery saver modes.
No Implicit Service Restart: Services that are killed due to background restrictions or system memory pressure are less likely to be automatically restarted, especially if they are not foreground services.
Location Access Nuances: BLE scanning relies on location permissions. While ACCESS_FINE_LOCATION covers foreground scanning, persistent background scanning needs a mechanism that the OS trusts to be running continuously.

The core issue is simple: the OS considers an invisible, long-running BLE scan a potential battery drain and privacy risk. To bypass these restrictions and signal "this task is important and user-aware," you must elevate your app's process priority.

Core Concepts: Elevating Your BLE Game

To achieve persistent BLE discovery, we leverage two fundamental Android APIs in conjunction:

Foreground Service: This is Android's explicit mechanism for performing long-running operations that are noticeable to the user. A ForegroundService runs with elevated priority, making it less likely for the OS to kill your process. It must display a persistent notification, informing the user that your app is actively running a background task. This notification serves as a user's control point, enabling them to stop the service if desired.

+-----------------------+
|   Your Application    |
|                       |
|  +-----------------+  |
|  | Foreground      |  |
|  | Service         |  |
|  | (elevated prio) |  |
|  |                 |  |
|  |  +------------+ |  |
|  |  | Persistent | |  |
|  |  | Notification| |  |
|  |  +------------+ |  |
|  +-----------------+  |
|           ^           |
|           |           |
| +-------------------+ |
| | BluetoothLeScanner| |
| | .startScan() with | |
| | PendingIntent     | |
| +-------------------+ |
|           |           |
|           v           |
|  +-----------------+  |
|  | BroadcastReceiver | |
|  | (handles results) |  |
|  +-----------------+  |
+-----------------------+

BluetoothLeScanner.startScan(List<ScanFilter>, ScanSettings, PendingIntent): This specific overload of the startScan method is crucial. Instead of providing a ScanCallback that runs directly within your app's process (and is therefore susceptible to OS termination), you provide a PendingIntent. The system then takes ownership of the scan. When scan results are available, the system fires your PendingIntent, typically targeting a BroadcastReceiver. This decouples the scan execution from your app's immediate process lifecycle, making it much more resilient. The OS handles the scan, and only wakes your app up when there's data to deliver.

Why PendingIntent?
- Resilience: The OS manages the scan, not your app directly. If your app process is killed, the scan continues at the system level.
- Efficiency: Your app is only woken up when results are batched or a significant event occurs, conserving battery.
- Permission Delegation: The PendingIntent carries your app's permissions, allowing the system to perform the scan on your behalf.

Implementation: Building a Persistent BLE Scanner

Let's walk through the steps to implement this robust BLE scanning mechanism.

API Requirements and Permissions

Minimum API Level: Android 10 (API 29) for ForegroundService stability and background restrictions. Android 12 (API 31) for BLUETOOTH_SCAN permission.

Manifest Permissions:

<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" /> <!-- Required for Android 12 (API 31) and above -->
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" /> <!-- If your app also advertises, Android 12+ -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /> <!-- If your app connects to devices, Android 12+ -->

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<!-- ACCESS_BACKGROUND_LOCATION is NOT strictly required *just* for persistent BLE scanning via PendingIntent
     if your app doesn't need to know the actual geographic location of the scan itself,
     but rather just needs to discover devices. However, if your use case involves deriving
     location information from BLE, you will need it for Android 10/11. On Android 12+,
     BLUETOOTH_SCAN implicitly requires ACCESS_FINE_LOCATION for scanning. -->

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" /> <!-- Required for Android 13 (API 33) and above -->

Manifest Declarations:

<application ...>
    <service
        android:name=".BleScanForegroundService"
        android:foregroundServiceType="connectedDevice" <!-- Android 10+ requires foregroundServiceType -->
        android:enabled="true"
        android:exported="false" />

    <receiver
        android:name=".BleScanResultReceiver"
        android:enabled="true"
        android:exported="true" /> <!-- Exported to receive system broadcasts -->
</application>

android:foregroundServiceType="connectedDevice": For API 29-33, this is the most appropriate type for BLE scanning. For API 34+, specialUse (with FOREGROUND_SERVICE_SPECIAL_USE permission) or shortService might be considered, but connectedDevice remains generally applicable.

Step-by-Step Implementation

Define your BroadcastReceiver: This receiver will be the target of your PendingIntent and will process the scan results.

// BleScanResultReceiver.kt
package com.example.mybleapp

import android.bluetooth.le.ScanResult
import android.bluetooth.le.BluetoothLeScanner
import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.os.Build
import android.util.Log

class BleScanResultReceiver : BroadcastReceiver() {

    companion object {
        const val ACTION_BLE_SCAN_RESULT = "com.example.mybleapp.ACTION_BLE_SCAN_RESULT"
        private const val TAG = "BleScanResultReceiver"
    }

    override fun onReceive(context: Context?, intent: Intent?) {
        if (intent?.action == ACTION_BLE_SCAN_RESULT) {
            // Extract scan results from the intent
            val callbackType = intent.getIntExtra(
                BluetoothLeScanner.EXTRA_CALLBACK_TYPE,
                -1
            )
            // ScanResult.CREATOR is @NonNull so results will not be null if EXTRA_LIST_SCAN_RESULT is present.
            // However, to be safe, check if the list is not null before proceeding.
            val scanResults: List<ScanResult>? = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
                intent.getParcelableArrayListExtra(
                    BluetoothLeScanner.EXTRA_LIST_SCAN_RESULT,
                    ScanResult::class.java
                )
            } else {
                @Suppress("DEPRECATION")
                intent.getParcelableArrayListExtra(BluetoothLeScanner.EXTRA_LIST_SCAN_RESULT)
            }

            scanResults?.forEach { result ->
                Log.d(TAG, "Found BLE device: ${result.device.address}, Name: ${result.device.name ?: "N/A"}")
                // TODO: Process your scan results here
                // e.g., filter, store in database, notify UI, connect to device
            }

            // If you are batching results, you might get a list of results at once.
            // handleBatchScanResults(scanResults)
        }
    }
}

Create your ForegroundService: This service will initiate and manage the BLE scan via the PendingIntent.

// BleScanForegroundService.kt
package com.example.mybleapp

import android.app.Notification
import android.app.NotificationChannel
import android.app.NotificationManager
import android.app.PendingIntent
import android.app.Service
import android.bluetooth.BluetoothAdapter
import android.bluetooth.BluetoothManager
import android.bluetooth.le.ScanCallback
import android.bluetooth.le.ScanFilter
import android.bluetooth.le.ScanSettings
import android.content.Context
import android.content.Intent
import android.content.pm.PackageManager
import android.os.Build
import android.os.IBinder
import android.util.Log
import androidx.core.app.ActivityCompat
import androidx.core.app.NotificationCompat

class BleScanForegroundService : Service() {

    private lateinit var bluetoothAdapter: BluetoothAdapter
    private var bluetoothLeScanner = BluetoothAdapter.getDefaultAdapter()?.bluetoothLeScanner
    private var scanPendingIntent: PendingIntent? = null

    companion object {
        const val NOTIFICATION_CHANNEL_ID = "BleScanServiceChannel"
        const val NOTIFICATION_ID = 1001
        private const val TAG = "BleScanFwdService"
    }

    override fun onCreate() {
        super.onCreate()
        val bluetoothManager = getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
        bluetoothAdapter = bluetoothManager.adapter
        bluetoothLeScanner = bluetoothAdapter.bluetoothLeScanner
        createNotificationChannel()
    }

    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        Log.d(TAG, "Service onStartCommand")

        // Start the foreground service with a notification
        startForeground(NOTIFICATION_ID, createNotification())

        // Initiate BLE scan
        startBleScan()

        // START_STICKY ensures that if the service is killed by the system,
        // it will be re-created and onStartCommand will be called again.
        return START_STICKY
    }

    override fun onDestroy() {
        super.onDestroy()
        Log.d(TAG, "Service onDestroy")
        stopBleScan()
    }

    override fun onBind(intent: Intent?): IBinder? {
        return null // Not a bound service
    }

    private fun createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val serviceChannel = NotificationChannel(
                NOTIFICATION_CHANNEL_ID,
                "BLE Scan Service Channel",
                NotificationManager.IMPORTANCE_LOW // Low importance to be less intrusive
            )
            val manager = getSystemService(NotificationManager::class.java)
            manager.createNotificationChannel(serviceChannel)
        }
    }

    private fun createNotification(): Notification {
        // Optional: Create an intent to open your main activity when the notification is tapped
        val notificationIntent = Intent(this, MainActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TASK
        }
        val pendingIntent = PendingIntent.getActivity(
            this,
            0,
            notificationIntent,
            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT // Use FLAG_IMMUTABLE for security
        )

        return NotificationCompat.Builder(this, NOTIFICATION_CHANNEL_ID)
            .setContentTitle("BLE Scan Active")
            .setContentText("Scanning for nearby IoT devices...")
            .setSmallIcon(R.drawable.ic_bluetooth_searching) // Replace with your icon
            .setContentIntent(pendingIntent)
            .build()
    }

    private fun startBleScan() {
        if (!bluetoothAdapter.isEnabled) {
            Log.w(TAG, "Bluetooth is not enabled.")
            // Consider prompting user or stopping service if Bluetooth is essential
            return
        }

        if (bluetoothLeScanner == null) {
            Log.e(TAG, "BluetoothLeScanner not available.")
            return
        }

        // Check for necessary permissions
        if (ActivityCompat.checkSelfPermission(this, android.Manifest.permission.BLUETOOTH_SCAN) != PackageManager.PERMISSION_GRANTED ||
            ActivityCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
            Log.e(TAG, "BLE scan permissions not granted.")
            // You should handle permission requests in your Activity before starting the service
            return
        }

        // Define scan settings
        val scanSettings = ScanSettings.Builder()
            .setScanMode(ScanSettings.SCAN_MODE_LOW_POWER) // Optimize for battery life
            .setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES) // Receive all advertisements
            .setMatchMode(ScanSettings.MATCH_MODE_STICKY) // Matches devices even if they move out of range briefly
            .setNumOfMatches(ScanSettings.MATCH_NUM_ONE_ADVERTISEMENT) // Report each advertisement
            .build()

        // Define scan filters (optional but recommended for efficiency)
        val scanFilters = listOf(
            // Example: Filter for devices advertising a specific service UUID
            // val filter = ScanFilter.Builder()
            //     .setServiceUuid(ParcelUuid(UUID.fromString("0000180A-0000-1000-8000-00805f9b34fb")))
            //     .build()
            // filter
        )

        // Create a PendingIntent for the BroadcastReceiver
        val intent = Intent(this, BleScanResultReceiver::class.java).apply {
            action = BleScanResultReceiver.ACTION_BLE_SCAN_RESULT
        }
        scanPendingIntent = PendingIntent.getBroadcast(
            this,
            0, // Request code
            intent,
            PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_MUTABLE // FLAG_MUTABLE is required for system to fill in scan results
        )

        try {
            bluetoothLeScanner?.startScan(scanFilters, scanSettings, scanPendingIntent)
            Log.d(TAG, "BLE scan started via PendingIntent.")
        } catch (e: Exception) {
            Log.e(TAG, "Failed to start BLE scan: ${e.message}", e)
        }
    }

    private fun stopBleScan() {
        if (bluetoothLeScanner == null) {
            Log.e(TAG, "BluetoothLeScanner not available for stopping scan.")
            return
        }

        // Check for necessary permissions again before stopping
        if (ActivityCompat.checkSelfPermission(this, android.Manifest.permission.BLUETOOTH_SCAN) != PackageManager.PERMISSION_GRANTED) {
            Log.e(TAG, "BLE scan permissions not granted, cannot stop scan gracefully.")
            return
        }

        scanPendingIntent?.let { pendingIntent ->
            try {
                bluetoothLeScanner?.stopScan(pendingIntent)
                Log.d(TAG, "BLE scan stopped via PendingIntent.")
            } catch (e: Exception) {
                Log.e(TAG, "Failed to stop BLE scan: ${e.message}", e)
            }
            scanPendingIntent = null // Clear the reference
        }

        stopForeground(Service.STOP_FOREGROUND_REMOVE) // Remove notification
        stopSelf() // Stop the service
    }
}

Starting the Service from your Activity/Application:

// In your MainActivity or Application class
package com.example.mybleapp

import android.content.Context
import android.content.Intent
import android.content.pm.PackageManager
import android.os.Build
import android.os.Bundle
import android.widget.Button
import android.widget.Toast
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AppCompatActivity
import androidx.core.content.ContextCompat

class MainActivity : AppCompatActivity() {

    private val requestPermissionsLauncher = registerForActivityResult(
        ActivityResultContracts.RequestMultiplePermissions()
    ) { permissions ->
        val allGranted = permissions.entries.all { it.value }
        if (allGranted) {
            Toast.makeText(this, "Permissions granted. Starting scan service.", Toast.LENGTH_SHORT).show()
            startBleScanService()
        } else {
            Toast.makeText(this, "Required permissions not granted.", Toast.LENGTH_LONG).show()
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main) // Assuming you have a layout with buttons

        findViewById<Button>(R.id.startButton).setOnClickListener {
            checkAndRequestPermissions()
        }

        findViewById<Button>(R.id.stopButton).setOnClickListener {
            stopBleScanService()
        }
    }

    private fun checkAndRequestPermissions() {
        val permissionsToRequest = mutableListOf<String>()

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { // Android 12+
            if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.BLUETOOTH_SCAN) != PackageManager.PERMISSION_GRANTED) {
                permissionsToRequest.add(android.Manifest.permission.BLUETOOTH_SCAN)
            }
            if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.BLUETOOTH_CONNECT) != PackageManager.PERMISSION_GRANTED) {
                permissionsToRequest.add(android.Manifest.permission.BLUETOOTH_CONNECT)
            }
        } else { // Android 10/11
            if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.BLUETOOTH_ADMIN) != PackageManager.PERMISSION_GRANTED) {
                permissionsToRequest.add(android.Manifest.permission.BLUETOOTH_ADMIN)
            }
        }

        if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
            permissionsToRequest.add(android.Manifest.permission.ACCESS_FINE_LOCATION)
        }

        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) { // Android 13+
            if (ContextCompat.checkSelfPermission(this, android.Manifest.permission.POST_NOTIFICATIONS) != PackageManager.PERMISSION_GRANTED) {
                permissionsToRequest.add(android.Manifest.permission.POST_NOTIFICATIONS)
            }
        }

        if (permissionsToRequest.isNotEmpty()) {
            requestPermissionsLauncher.launch(permissionsToRequest.toTypedArray())
        } else {
            startBleScanService()
        }
    }

    private fun startBleScanService() {
        val serviceIntent = Intent(this, BleScanForegroundService::class.java)
        ContextCompat.startForegroundService(this, serviceIntent) // Correct way to start foreground service
    }

    private fun stopBleScanService() {
        val serviceIntent = Intent(this, BleScanForegroundService::class.java)
        stopService(serviceIntent)
        Toast.makeText(this, "BLE scan service stopped.", Toast.LENGTH_SHORT).show()
    }
}

*   Permission Handling: Crucially, request runtime permissions before starting the service. The service itself should only check if permissions are granted.


  ContextCompat.startForegroundService(): This is the correct way to start a ForegroundService. If your app is in the background when this is called, it will still be allowed to start the service (within a short grace period).

Best Practices

Implementing persistent BLE scanning requires careful consideration to avoid battery drain, ANRs, and poor user experience.

Refined Scan Filters and Settings:
- Pitfall: Scanning for all BLE devices continuously with SCAN_MODE_LOW_LATENCY rapidly drains battery and generates excessive callbacks.
- Fix: Always use ScanFilter to narrow down the devices you're interested in (e.g., by service UUID, device name, or manufacturer data). For ScanSettings, prefer SCAN_MODE_LOW_POWER or SCAN_MODE_BALANCED. If you only need periodic updates, leverage setReportDelay(long) to batch results, significantly reducing app wake-ups. This is especially effective with PendingIntent scans.
- Example ScanSettings for batching:
```
val scanSettings = ScanSettings.Builder()
    .setScanMode(ScanSettings.SCAN_MODE_LOW_POWER)
    .setCallbackType(ScanSettings.CALLBACK_TYPE_ALL_MATCHES)
    .setReportDelay(5000L) // Report results every 5 seconds (batching)
    .build()
```
Robust Service Lifecycle Management:
- Pitfall: Forgetting to properly stop the ForegroundService when it's no longer needed leads to continuous notification display, battery drain, and user frustration.
- Fix: Ensure you call stopForeground(Service.STOP_FOREGROUND_REMOVE) to dismiss the notification and stopSelf() to terminate the service. Implement clear UI controls (e.g., start/stop buttons) in your app. Handle Bluetooth adapter state changes (e.g., Bluetooth turned off) within your service or receiver to gracefully stop the scan and potentially the service itself. Use START_STICKY for resilience, but pair it with explicit stop logic.
Correct PendingIntent Flags and Security:
- Pitfall: Using incorrect PendingIntent flags can lead to security vulnerabilities (FLAG_IMMUTABLE vs. FLAG_MUTABLE) or prevent the intent from working as expected.
- Fix: On Android 12 (API 31) and above, you must explicitly declare FLAG_IMMUTABLE or FLAG_MUTABLE. For intents that will be filled by the system (like BLE scan results), FLAG_MUTABLE is necessary as the system needs to inject the ScanResult data. Always combine it with FLAG_UPDATE_CURRENT to ensure subsequent startScan calls update the existing PendingIntent instead of creating new ones.
- Correct flags for PendingIntent to BroadcastReceiver receiving system data:
```
PendingIntent.getBroadcast(
    context,
    REQUEST_CODE,
    intent,
    PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_MUTABLE
)
```
Bluetooth State Monitoring:
- Pitfall: Not handling Bluetooth adapter being disabled or unavailable can cause your scan to silently fail or crash.
- Fix: Register a BroadcastReceiver for BluetoothAdapter.ACTION_STATE_CHANGED to detect when Bluetooth is turned off or on. If Bluetooth is off, stop your BLE scan service and notify the user. Restart the service/scan once Bluetooth is enabled again. This ensures your app reacts gracefully to system-level changes.

Conclusion

Overcoming Android 10+ background restrictions for persistent BLE scanning boils down to strategically leveraging ForegroundService with a PendingIntent-based BluetoothLeScanner API. This approach elevates your app's priority, allowing the OS to manage the continuous scanning process while providing results reliably to your BroadcastReceiver. By meticulously handling permissions, service lifecycle, PendingIntent flags, and scan configurations, you can build robust and battery-efficient BLE discovery solutions. Your next step should be to integrate thorough error handling for Bluetooth state changes and explore scan result batching for further efficiency.

BLE Advertiser: iBeacon, Eddystone & GATT Simulation on One Android Phone

Ble Advertiser — Wed, 08 Apr 2026 17:51:23 +0000

Bluetooth Low Energy (BLE) is one of the most powerful tools for building proximity-based apps, IoT systems, and smart environments.

In this guide, I’ll show you how you can simulate iBeacon, Eddystone, and GATT server—all on a single Android device 🔥

And yes — you can do it instantly using my app 👉 BLE Advertiser 😉

📌 What You’ll Learn
How BLE Advertising works
Difference between iBeacon, Eddystone, and GATT
How to simulate all of them on one Android phone
Real-world use cases
📲 Try It Instantly (No Hardware Needed)

Instead of building everything from scratch, you can use:

👉 BLE Advertiser App

🔥 Features:
iBeacon simulation (UUID, Major, Minor)
Eddystone (UID, URL, TLM)
Custom BLE advertising packets
GATT Server support
Works on a single Android device

💡 Perfect for:

Developers testing BLE apps
IoT prototyping
Students learning BLE
🧠 Understanding BLE Basics

BLE devices communicate in two main ways:

Advertising (Broadcast Mode) One-to-many communication No connection required Used by beacons
GATT (Connected Mode) One-to-one communication Requires connection Used for data exchange 📡 What is iBeacon? Developed by Apple Broadcasts a UUID, Major, Minor Used for proximity detection

👉 Example use case:

Retail store notifications
Indoor navigation
🌐 What is Eddystone?
Developed by Google
More flexible than iBeacon
Supports multiple frame types:
UID → Unique ID
URL → Broadcast website
TLM → Telemetry data
🔗 What is GATT?

GATT (Generic Attribute Profile) is used when:

You need two-way communication
You want to expose services & characteristics
💡 The Problem

Usually, you need:

One device → Advertiser
Another device → Scanner

But what if you only have one phone? 🤔

✅ The Solution

With Android, you can:

Act as a BLE Advertiser
Act as a GATT Server
Simulate beacon formats

👉 Or simply use the BLE Advertiser app to do all of this in seconds ⚡

Start BLE Advertising

Use:

BluetoothLeAdvertiser
AdvertiseSettings
AdvertiseData

Create GATT Server Open BluetoothGattServer Add services & characteristics Handle read/write
Combine Both

Run:

Advertising + GATT Server

🎯 Now your device becomes a complete BLE simulator

📱 Why Use BLE Advertiser App?

Instead of spending hours coding basic setup:

✅ Save development time
✅ No extra BLE hardware needed
✅ Easy testing & debugging
✅ Clean UI for quick experiments

👉 It’s basically a BLE lab in your pocket

Real Use Cases
Testing BLE apps without hardware
Prototyping IoT systems
Indoor navigation
Asset tracking
Smart automation
Final Thoughts

Simulating iBeacon + Eddystone + GATT on one Android phone is a game-changer for developers.

And with tools like the BLE Advertiser app, you can skip the setup and start building immediately 🚀

💬 Let’s Connect

If you're working on BLE, Android, or IoT — I’d love to hear what you’re building!

BLE Advertiser Is Now Live on Google Play — Turn Your Android Into Any BLE Device

Ble Advertiser — Mon, 06 Apr 2026 15:45:28 +0000

We just launched BLE Advertiser on the Play Store, and I want to walk you through exactly what it does — because the concept takes five seconds to explain but the depth of what you can do with it is easy to underestimate.

Every BLE project hits the same bottleneck: you’re writing code but waiting on hardware. A dev board to ship. A sensor to arrive. Someone’s test device to borrow. The frustrating part is that most of what you need to test has nothing to do with the hardware itself — you just need something on the Bluetooth spectrum that looks like the device your app expects.

BLE Advertiser fixes that. It turns your Android phone into a real Bluetooth peripheral — not a simulation inside a test framework, but actual BLE advertisement packets going over the air. Open nRF Connect or any scanner on another device, and your phone shows up as a Heart Rate Monitor, an iBeacon, a Smart Lock, or anything else you configure it as. No firmware. No hardware. No waiting.

Here’s every feature, explained properly.

20+ Predefined Profiles — Pick One and Start Broadcasting
The fastest way to get something advertising is the predefined profile list. BLE Advertiser ships with 20+ ready-to-use device types across every major BLE category:

Beacons — iBeacon (Apple), Eddystone (Google), AltBeacon. All three formats are supported with the correct advertisement structure, so beacon-scanning apps pick them up correctly.

Health and Medical — Heart Rate Monitor, Blood Pressure Monitor, Glucose Monitor, Pulse Oximeter, Thermometer, Weight Scale. Each profile follows the official Bluetooth GATT specification for that device type, so health apps that expect standard service UUIDs get exactly what they’re looking for.

Fitness — Cycling Speed and Cadence Sensor, Running Speed and Cadence Sensor.

Environment — Temperature Sensor, Humidity Sensor, Barometric Pressure Sensor, Air Quality Sensor.

Motion — Accelerometer, Proximity Sensor, Light Sensor.

Smart Home — Smart Lock, Smart Bulb, Smart Switch.

Wearables — Smart Watch, Fitness Band, Smart Speaker.

You don’t need to know anything about Bluetooth UUIDs, GATT profiles, or advertisement packet formats. Pick a profile, tap Advertise, and your phone is broadcasting. Another device scanning for a Heart Rate Monitor will find it immediately.

Custom BLE Profile Builder — Design Any Device You Can Imagine
The predefined profiles cover the standard cases. The custom builder is for everything else.

If you’re building a BLE device with your own service structure — proprietary UUIDs, custom data formats, non-standard characteristic layouts — you can design it visually inside BLE Advertiser without writing a single line of code.

Here’s what you control:

Services and Characteristics — Add as many services as you need. Under each service, define individual characteristics with any UUID (standard 16-bit or custom 128-bit). You choose what data each characteristic exposes: a number, a text string, or raw byte sequences.

Permissions — Set each characteristic as readable, writable, or subscribable (notify/indicate). If your app subscribes to notifications, BLE Advertiser can simulate the peripheral sending updates.

Device Identity — Name the device exactly as it should appear to scanners. Add manufacturer data attached to any company ID — Apple, Google, Samsung, Nordic, or your own.

Advertisement Data — Control exactly what’s in the broadcast packet: which services are advertised, what manufacturer data is included, whether a scan response is available.

The result is a complete virtual Bluetooth device. If your app connects to it and tries to read a characteristic, it gets back the data you configured. This is the fastest way to iterate on BLE integration before your actual hardware is ready.

Full Signal Control — BLE 5.0, Legacy 4.x, and Everything in Between
Different testing scenarios need different signal configurations. BLE Adv gives you control over every parameter that matters.

BLE Version Support

Extended Advertising (BLE 5.0) — up to 251 bytes per packet, faster data rates, longer range on the Coded PHY. If your phone supports BLE 5.0, the app uses it automatically.
Legacy Advertising (BLE 4.x) — standard 31-byte packets with optional scan response, compatible with all devices. Falls back to this automatically on older phones.
PHY Selection — Manually choose 1M PHY (standard range and speed), 2M PHY (faster, shorter range), or Coded PHY (longer range, lower speed). Useful when you’re testing how your app handles devices at different signal qualities.

TX Power — Four presets from Ultra Low to Ultra High, or set a custom value. Simulating a weak device signal or testing RSSI-based distance estimation is straightforward.

Advertising Interval — Fast (100ms), Balanced (500ms), Slow (1000ms), or a custom interval in milliseconds. Slower intervals use less battery; faster ones make the device more discoverable.

Connectable vs. Non-connectable — Control whether scanners can actually connect and read characteristics, or just see the advertisement.

Scannable — Decide whether devices can request additional data via scan response.

Timeout — Set the advertising to stop automatically after a defined duration. Useful for timed test scenarios.

Smart Triggers — Advertising That Runs Itself
This is the feature that surprised me most when I was building it, because once you use it, going back to manually starting and stopping advertising feels painful.

Triggers let you define conditions that automatically start or stop broadcasting. You set it up once and forget about it.

Time Triggers Schedule advertising at a specific date and time. Set a duration so it stops automatically. Create recurring daily or weekly schedules. Useful for simulating a device that’s only active during certain hours.

WiFi Triggers Start advertising when your phone connects to a specific WiFi network. Stop when it disconnects. This one is genuinely useful for office or lab setups — your phone starts behaving as a BLE device the moment you’re on the right network, without any manual action.

Location Triggers (Geofencing) Define a location and a radius. BLE Advertiser starts advertising when you enter that area and stops when you leave. You can set up multiple locations with different profiles — walk into a store, your phone starts simulating a proximity beacon; leave, it stops.

Battery Triggers Start or stop advertising based on battery percentage or charging state. Prevents the app from draining your battery on a long test run.

Boot Trigger Advertising resumes automatically after your phone restarts. No need to reopen the app and restart everything manually.

A setup that combines these: iBeacon profile, WiFi trigger for the office network, active between 9am and 6pm daily. Once configured, the phone handles it entirely on its own.

Background Operation — It Keeps Running
Android is aggressive about killing background processes to save battery. Most Bluetooth tools stop working the moment you lock your screen or switch apps. BLE Advertiser runs as a foreground service, which means it operates continuously regardless of what else your phone is doing.

Advertising keeps going when:

The screen is off
You’re using other apps
The phone has been restarted (if the boot trigger is enabled)
A persistent notification stays visible so you always know what’s active and can stop any profile with a single tap. You’re not left guessing whether the app is still running.

You can also run multiple profiles simultaneously — useful for testing how your app handles several nearby BLE devices at the same time, or for setting up a multi-beacon indoor positioning test.

Live Activity Log — See Exactly What’s Happening
BLE Advertiser shows you a real-time log of every advertising event as it happens. This is more useful than it sounds when you’re debugging.

The log shows:

When advertising starts and stops for each profile
Errors and warnings (failed advertisement attempts, permission issues)
Event timestamps
You can filter the log by individual profile or view the global feed across all active profiles. Pause the live feed when you need to read something without it scrolling past. Export the full log as a file to share with your team or attach to a bug report. Auto-cleanup keeps old entries from piling up.

Profile Management — Organize, Back Up, Share
Once you’ve built a configuration that works, you probably don’t want to rebuild it from scratch every time. BLE Advertiser has a full profile management system.

Save any profile — predefined or custom — with a name. Saved profiles appear in your list and can be started with a single tap.

Duplicate an existing profile and modify the copy. Fast way to create variations of a configuration without starting from zero.

Import and Export profiles as files. Export a profile to your phone storage, send it to a teammate, or back it up. They import it in BLE Advertiser on their device and have the exact same configuration. No manual re-entry.

Quick Toggles — start or stop any saved profile from the profile list without navigating into it.

The Interface
BLE Advertiser uses Material Design with smooth transitions and a layout that works on both phones and tablets. Dark Mode is fully supported — Light, Dark, or follow-system setting, your choice. An interactive tutorial walks you through the app on first launch so you know where everything is. Multiple languages are supported.

It’s designed to feel like a tool, not a demo app. The controls you need are accessible without digging through menus.

Real-World Use Cases
BLE App Development — Test your app’s Bluetooth integration without physical hardware. Simulate the exact device your app expects, including edge cases like weak signals, unexpected characteristic values, or devices that go offline mid-session.

IoT Prototyping — Validate your app’s behavior against a simulated peripheral before your firmware is ready. Iterate on the BLE service structure in BLE Advertiser instead of flashing the device every time you change a UUID.

Healthcare App Testing — Simulate a glucose monitor, pulse oximeter, or heart rate cuff to test every scenario your health app needs to handle — bad readings, out-of-range values, dropped connections — without needing the physical medical device.

Indoor Positioning / Navigation — Place several phones running different iBeacon configurations around a building. Prototype and tune your positioning algorithm before purchasing any hardware.

QA and Edge Case Testing — Reproduce specific device behaviors that are hard to control with real hardware: specific RSSI values, malformed data, simultaneous device collisions, rapid connect-disconnect cycles.

Learning BLE — The fastest way to understand how Bluetooth Low Energy advertising actually works is to create a device, broadcast it, and scan it from another phone. BLE Advertiser makes that loop immediate and hands-on.

Getting Started

Download BLE Advertiser on Google Play

The quickest test: pick Heart Rate Monitor from the predefined profiles, tap Advertise, then open nRF Connect on another device. Your phone appears in the scan list immediately.

For custom devices: tap Custom BLE, add your services and characteristics, configure the advertisement data, set any triggers you want, and hit Advertise.

Follow tutorials and updates at @bleadvertiserapp on Medium.

If BLE Adv saves you time, a rating on the Play Store helps other developers find it.

Bluetooth #BLE #Android #iBeacon #Eddystone #IoT #SmartHome #DeveloperTools #IndoorNavigation #HealthTech #MobileApp #AndroidDev

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

Ble Advertiser — Sun, 05 Apr 2026 10:35:28 +0000

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:

Call BluetoothGatt.setCharacteristicNotification(characteristic, true) on your local BluetoothGatt object. This prepares the Android stack to receive notifications.
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).

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.

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
}

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
}

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.

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
    }
}

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) }
}

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()
    }
}

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:

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.
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.
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.
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.
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.

Solving the Android BLE GATT Race Condition: Reliable Sequential Operations with Kotlin Coroutines

Ble Advertiser — Sun, 05 Apr 2026 10:33:42 +0000

Your users complain about intermittent BLE failures. Devices connect, then mysteriously stop responding. Writes fail, reads time out, and notifications are sporadic. You've checked the peripheral firmware, meticulously reviewed your byte arrays, and still, the flakiness persists. Sound familiar? If you've been building serious Android BLE applications, you've almost certainly encountered the dreaded GATT race condition. It's a silent killer of reliability, often manifesting as non-deterministic failures that are incredibly hard to debug.

This article cuts through the noise. We'll diagnose the root cause of these race conditions in Android's BluetoothGatt API and then engineer a robust, production-grade solution using Kotlin Coroutines to enforce reliable, sequential GATT operations. No more guessing, no more random disconnections – just predictable, rock-solid BLE communication.

Core Concepts: The Silent Killer – Android's GATT Race Condition

At the heart of the problem lies the fundamental mismatch between Android's BluetoothGatt API design and the inherently sequential nature of GATT operations.

When you interact with a BLE peripheral, you're performing a series of operations: discover services, read characteristics, write characteristic values, enable notifications, and so on. Each of these operations is a "transaction" that the peripheral (and your Android device's Bluetooth stack) must process in order.

Consider the typical flow for writing a characteristic:

Call bluetoothGatt.writeCharacteristic(characteristic).
Wait for the onCharacteristicWrite callback in BluetoothGattCallback.
Process the result.

The critical detail here is that bluetoothGatt.writeCharacteristic() (and readCharacteristic(), setCharacteristicNotification(), requestMtu(), etc.) are non-blocking methods. They return immediately. The actual operation is then queued internally by the Android Bluetooth stack and executed asynchronously. The result arrives much later via the BluetoothGattCallback.

The Race: The problem arises when you call multiple BluetoothGatt methods in rapid succession without waiting for the previous operation's completion callback. For example:

// DANGER: Race condition highly probable!
bluetoothGatt.writeCharacteristic(char1) // Call 1
bluetoothGatt.readCharacteristic(char2)  // Call 2
bluetoothGatt.setCharacteristicNotification(char3, true) // Call 3

What happens here? All three calls are immediately dispatched to the Android Bluetooth stack. The internal state machine of the BluetoothGatt object is not designed to handle multiple concurrent operations. If you call writeCharacteristic while a previous readCharacteristic is still pending (i.e., onCharacteristicRead hasn't fired yet), the stack might:

Drop the new operation: Simply ignore your second call.
Corrupt its internal state: Lead to incorrect callback responses for unrelated operations.
Return false: Indicating the operation could not be enqueued. This is a clear signal of an overloaded or busy GATT queue.
Trigger a disconnect: The most frustrating outcome, as the stack gets into an unrecoverable state.

This effectively creates a race condition: which operation finishes first? Will the BluetoothGatt object be ready for the next command when you issue it? The answer is often "no," leading to the intermittent, hard-to-debug issues you've likely faced.

The Solution: A Synchronized Operation Queue

To eliminate this race, you must impose strict sequential execution. Only one GATT operation should be active at any given time. We achieve this by:

Defining Discrete Operations: Encapsulating each GATT command (read, write, notify, MTU request) into a distinct, identifiable object.
Queuing Operations: Submitting these operations to a single, ordered queue.
Serial Processing: Consuming operations from the queue one at a time, ensuring the previous operation's BluetoothGattCallback completes before initiating the next.
Asynchronous Awaiting: Allowing the calling code to suspend until its requested GATT operation has completed or timed out.

Here's an ASCII diagram illustrating this reliable flow:

+----------------+       +-------------------+       +---------------------+
|  Application   |       | GATT Operation    |       |  Android Bluetooth  |
|   (Coroutines) |       |       Queue       |       |       Stack         |
+----------------+       +-------------------+       +---------------------+
        |                        |                             |
        |  1. Request Op A       |                             |
        |----------------------->|                             |
        |                        | 2. Dequeue Op A             |
        |                        |---------------------------->|
        |                        |                             | 3. Execute Op A
        |                        |                             |    (e.g., writeCharacteristic)
        |  Suspend               |                             |
        |<-----------------------|                             |
        |                        |                             | 4. Op A Result
        |                        |                             |<---------------------+
        |                        |                             |  (e.g., onCharacteristicWrite)
        |                        |                             |
        |                        | 5. Mark Op A complete      |
        |                        |<----------------------------|
        |                        |                             |
        |  Resume (Op A done)    |                             |
        |----------------------->|                             |
        |  6. Request Op B       |                             |
        |----------------------->|                             |
        |                        | 7. Dequeue Op B             |
        |                        |---------------------------->|
        |                        |                             | 8. Execute Op B
        |                        |                             |
        ... and so on ...

Kotlin Coroutines, particularly Channel and suspendCancellableCoroutine, provide the perfect primitives to build this robust system.

Implementation: Building the GATT Operation Processor

We'll build a GattClient class that encapsulates all BluetoothGatt interactions, manages the operation queue, and bridges the callback-based API to a suspendable Coroutine API.

Requirements & Setup

Android API Level: 21+ (for BLE)
Kotlin Coroutines: org.jetbrains.kotlinx:kotlinx-coroutines-core:1.7.x (or latest stable)

Permissions (Android Manifest):

<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />
<uses-feature android:name="android.hardware.bluetooth_le" android:required="true" />

(Note: ACCESS_FINE_LOCATION is required for BLE scanning on Android 11 and below. BLUETOOTH_SCAN and BLUETOOTH_CONNECT are for Android 12+.)

The Core Components

GattOperation sealed class: Defines the types of operations we support.
BluetoothGattManager (or GattClient): The central class managing the BluetoothGatt instance, its callback, and the operation queue.
Channel for the queue: A Channel is an excellent choice for sending a stream of operations.
suspendCancellableCoroutine: The crucial piece to convert callback-based GATT operations into suspendable functions.
Timeouts: Every GATT operation needs a timeout to prevent indefinite waiting.

Gotchas and Considerations

BluetoothGattCallback Thread: The BluetoothGattCallback methods are typically invoked on the main application thread if BluetoothDevice.connectGatt() is called without specifying a Handler. However, if you pass a Handler to connectGatt, callbacks will be on that Handler's thread. Regardless, avoid blocking this thread. Always dispatch heavy processing or UI updates to appropriate dispatchers (Dispatchers.Default, Dispatchers.Main).
Error Propagation: You need a mechanism to propagate GATT errors (e.g., GATT_FAILURE status codes) from the BluetoothGattCallback back to the awaiting suspend function.
Connection State: The operation queue should only process commands when the GATT connection is established and stable. Operations submitted during a disconnected state should either be queued for later, rejected, or trigger a connection attempt.

Code Examples

Let's build out the GattClient class.

Snippet 1: Defining Operations and the `GattClient` Skeleton

First, we define our GattOperation types. These encapsulate the characteristic, value, and any other data required for the operation.

// GattOperation.kt
package com.example.ble.client

import android.bluetooth.BluetoothGattCharacteristic
import java.util.UUID

/**
 * Represents a single, discrete GATT operation to be performed.
 * This sealed class helps ensure all possible operations are handled explicitly.
 */
sealed class GattOperation {
    data class ReadCharacteristic(val characteristic: BluetoothGattCharacteristic) : GattOperation()
    data class WriteCharacteristic(val characteristic: BluetoothGattCharacteristic, val value: ByteArray) : GattOperation() {
        // Essential for proper array comparison in data classes
        override fun equals(other: Any?): Boolean {
            if (this === other) return true
            if (javaClass != other?.javaClass) return false

            other as WriteCharacteristic

            if (characteristic != other.characteristic) return false
            if (!value.contentEquals(other.value)) return false

            return true
        }

        override fun hashCode(): Int {
            var result = characteristic.hashCode()
            result = 31 * result + value.contentHashCode()
            return result
        }
    }
    data class SetCharacteristicNotification(val characteristic: BluetoothGattCharacteristic, val enable: Boolean) : GattOperation()
    data class RequestMtu(val mtu: Int) : GattOperation()
    // Add other operations as needed, e.g., ReadDescriptor, WriteDescriptor
}

Now, the GattClient skeleton, which includes the BluetoothGattCallback and the Channel for our operation queue.

// GattClient.kt
package com.example.ble.client

import android.bluetooth.*
import android.content.Context
import android.util.Log
import kotlinx.coroutines.*
import kotlinx.coroutines.channels.Channel
import kotlinx.coroutines.flow.*
import java.util.concurrent.ConcurrentHashMap
import java.util.concurrent.TimeoutException

class GattClient(
    private val context: Context,
    private val device: BluetoothDevice,
    private val scope: CoroutineScope // Parent scope for GATT operations
) {
    private val TAG = "GattClient"

    private var bluetoothGatt: BluetoothGatt? = null
    private val operationChannel = Channel<GattOperation>(Channel.UNLIMITED) // Unbuffered channel for operations
    private val operationCompletions = ConcurrentHashMap<GattOperation, CompletableDeferred<Unit>>() // To link operations to their completion

    // State flow for connection status
    private val _connectionState = MutableStateFlow(BluetoothProfile.STATE_DISCONNECTED)
    val connectionState: StateFlow<Int> = _connectionState.asStateFlow()

    // Listener for characteristic notifications
    private val _characteristicChanges = MutableSharedFlow<Pair<BluetoothGattCharacteristic, ByteArray>>()
    val characteristicChanges: SharedFlow<Pair<BluetoothGattCharacteristic, ByteArray>> = _characteristicChanges.asSharedFlow()

    private val gattCallback = object : BluetoothGattCallback() {
        override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
            Log.d(TAG, "onConnectionStateChange: status=$status newState=$newState")
            if (status == BluetoothGatt.GATT_SUCCESS) {
                _connectionState.value = newState
                if (newState == BluetoothProfile.STATE_CONNECTED) {
                    // Start service discovery only after successful connection
                    gatt.discoverServices()
                } else if (newState == BluetoothProfile.STATE_DISCONNECTED) {
                    // Clean up on disconnect
                    closeGatt()
                }
            } else {
                Log.e(TAG, "Connection failed with status $status, closing GATT.")
                _connectionState.value = newState // Update to DISCONNECTED
                closeGatt()
            }
        }

        override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
            Log.d(TAG, "onServicesDiscovered: status=$status")
            if (status == BluetoothGatt.GATT_SUCCESS) {
                // Services discovered. We can now proceed with operations.
                // This doesn't directly complete a specific operation,
                // but signals readiness for the queue processor.
                // You might have a Deferred specifically for service discovery if needed.
            } else {
                Log.e(TAG, "Service discovery failed with status $status")
            }
        }

        override fun onCharacteristicRead(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray, status: Int) {
            Log.d(TAG, "onCharacteristicRead for ${characteristic.uuid}: status=$status")
            val operation = GattOperation.ReadCharacteristic(characteristic)
            completeOperation(operation, status) {
                // Here, you'd typically pass the value to the caller
                // For simplicity, we just complete the operation.
                // A more advanced design would have `CompletableDeferred<ByteArray>`
                // tied to the operation.
            }
        }

        override fun onCharacteristicWrite(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, status: Int) {
            Log.d(TAG, "onCharacteristicWrite for ${characteristic.uuid}: status=$status")
            // Note: The value written is not available here, so we must rely on our stored operation.
            // This is why we created a data class for WriteCharacteristic with the value.
            // However, for completing the deferred, the value itself isn't needed, only the characteristic.
            // We need a way to link back to the exact operation that was initiated.
            // A more robust solution might pass an 'id' with each operation.
            // For this example, we'll try to match by characteristic, which works IF only one write per char is pending.
            val operation = GattOperation.WriteCharacteristic(characteristic, byteArrayOf()) // Dummy value for lookup, problematic if multiple writes to same char
            completeOperation(operation, status) { /* value not returned by callback */ }
        }

        // Newer Android 13+ API for characteristic writes with response
        override fun onCharacteristicWrite(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray, status: Int) {
            Log.d(TAG, "onCharacteristicWrite (API 33) for ${characteristic.uuid}: status=$status")
            val operation = GattOperation.WriteCharacteristic(characteristic, value) // Value is now available!
            completeOperation(operation, status) { /* value handled implicitly */ }
        }

        override fun onCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray) {
            Log.d(TAG, "onCharacteristicChanged for ${characteristic.uuid}: value=${value.toHexString()}")
            scope.launch {
                // Dispatch characteristic changes asynchronously
                _characteristicChanges.emit(characteristic to value)
            }
        }

        override fun onCharacteristicChanged(gatt: BluetoothGatt, characteristic: BluetoothGattCharacteristic, value: ByteArray, status: Int) {
            Log.d(TAG, "onCharacteristicChanged (API 33) for ${characteristic.uuid}: value=${value.toHexString()} status=$status")
            scope.launch {
                if (status == BluetoothGatt.GATT_SUCCESS) {
                    _characteristicChanges.emit(characteristic to value)
                } else {
                    Log.e(TAG, "Characteristic change failed with status $status for ${characteristic.uuid}")
                }
            }
        }

        override fun onMtuChanged(gatt: BluetoothGatt, mtu: Int, status: Int) {
            Log.d(TAG, "onMtuChanged: mtu=$mtu status=$status")
            val operation = GattOperation.RequestMtu(mtu)
            completeOperation(operation, status) { /* MTU changed */ }
        }

        // Add other relevant callbacks like onDescriptorRead, onDescriptorWrite, onPhyUpdate, etc.
    }

    init {
        // Start the operation processor coroutine
        scope.launch {
            processGattOperations()
        }
    }

    private suspend fun processGattOperations() {
        for (operation in operationChannel) {
            // Ensure GATT is connected before processing operations
            while (connectionState.value != BluetoothProfile.STATE_CONNECTED || bluetoothGatt == null) {
                Log.w(TAG, "Gatt not connected, waiting for connection before processing operation: $operation")
                // Wait for connection state to change, or implement a timeout/retry
                // For simplicity, we just delay. A real app might re-queue or fail.
                delay(1000)
            }

            Log.d(TAG, "Processing operation: $operation")
            val gatt = bluetoothGatt ?: run {
                Log.e(TAG, "BluetoothGatt is null while processing operation. Skipping.")
                // If GATT is null, the operation cannot be performed.
                // We should complete the associated Deferred with an error.
                operationCompletions[operation]?.completeExceptionally(IllegalStateException("BluetoothGatt not initialized"))
                operationCompletions.remove(operation)
                continue
            }

            val success = when (operation) {
                is GattOperation.ReadCharacteristic -> gatt.readCharacteristic(operation.characteristic)
                is GattOperation.WriteCharacteristic -> {
                    operation.characteristic.value = operation.value
                    gatt.writeCharacteristic(operation.characteristic)
                }
                is GattOperation.SetCharacteristicNotification -> {
                    val descriptor = operation.characteristic.getDescriptor(UUID.fromString("00002902-0000-1000-8000-00805f9b34fb")) // Client Characteristic Configuration
                        ?: run {
                            Log.e(TAG, "CCC descriptor not found for ${operation.characteristic.uuid}")
                            false
                        }

                    val result = gatt.setCharacteristicNotification(operation.characteristic, operation.enable)
                    if (result) {
                        descriptor.value = if (operation.enable) {
                            BluetoothGattDescriptor.ENABLE_NOTIFICATION_VALUE
                        } else {
                            BluetoothGattDescriptor.DISABLE_NOTIFICATION_VALUE
                        }
                        gatt.writeDescriptor(descriptor) // Writing the descriptor is also an async op!
                        // For simplicity, we are not queueing descriptor write as a separate op here.
                        // A truly robust solution would queue descriptor writes as well.
                        true
                    } else {
                        false
                    }
                }
                is GattOperation.RequestMtu -> gatt.requestMtu(operation.mtu)
            }

            if (!success) {
                Log.e(TAG, "Failed to enqueue GATT operation: $operation")
                // If `bluetoothGatt` method returns false, it means the operation was not even accepted by the stack.
                // We should immediately complete the deferred with an error.
                operationCompletions[operation]?.completeExceptionally(IllegalStateException("Failed to enqueue GATT operation with Bluetooth stack"))
                operationCompletions.remove(operation)
            }

            // The operation will be completed by the gattCallback
            // We now wait for the callback to complete the associated Deferred
        }
    }

    /**
     * Completes a deferred GATT operation based on the callback status.
     * Must be called from the `BluetoothGattCallback` thread.
     */
    private fun completeOperation(operation: GattOperation, status: Int, onGattSuccess: () -> Unit) {
        val deferred = operationCompletions[operation]
        if (deferred == null) {
            Log.w(TAG, "No deferred found for completed operation: $operation. Likely an unsolicited callback or already handled.")
            return
        }

        if (status == BluetoothGatt.GATT_SUCCESS) {
            onGattSuccess()
            deferred.complete(Unit)
        } else {
            deferred.completeExceptionally(GattOperationException("GATT operation failed with status: $status", status))
        }
        operationCompletions.remove(operation) // Remove once completed
    }

    /**
     * Connects to the GATT server.
     */
    fun connect() {
        if (_connectionState.value == BluetoothProfile.STATE_CONNECTED) {
            Log.w(TAG, "Already connected, skipping connect()")
            return
        }
        Log.d(TAG, "Attempting to connect to GATT server for ${device.address}")
        bluetoothGatt = device.connectGatt(context, false, gattCallback)
        // AutoConnect=false is generally recommended for explicit control.
        // If true, the device will try to reconnect automatically after disconnect.
    }

    /**
     * Disconnects from the GATT server and closes resources.
     */
    fun disconnect() {
        Log.d(TAG, "Disconnecting GATT for ${device.address}")
        bluetoothGatt?.disconnect() // Will trigger onConnectionStateChange
    }

    /**
     * Closes the GATT client and releases resources.
     * Called after disconnect or on connection failure.
     */
    private fun closeGatt() {
        Log.d(TAG, "Closing GATT client for ${device.address}")
        bluetoothGatt?.close()
        bluetoothGatt = null
        // Fail any pending operations
        operationCompletions.forEach { (_, deferred) ->
            deferred.completeExceptionally(IllegalStateException("GATT connection closed unexpectedly"))
        }
        operationCompletions.clear()
        _connectionState.value = BluetoothProfile.STATE_DISCONNECTED
    }

    /**
     * Suspends until a characteristic read operation completes or times out.
     */
    suspend fun readCharacteristic(characteristic: BluetoothGattCharacteristic): ByteArray = withContext(Dispatchers.IO) {
        val operation = GattOperation.ReadCharacteristic(characteristic)
        // Use suspendCancellableCoroutine to bridge callback-based API with coroutines
        val result = suspendCancellableCoroutine<ByteArray> { continuation ->
            // Store the deferred completion for this specific operation
            val deferred = CompletableDeferred<Unit>().also { operationCompletions[operation] = it }

            scope.launch {
                try {
                    // Send the operation to the queue
                    operationChannel.send(operation)
                    // Wait for the operation to complete via callback or timeout
                    withTimeout(GATT_OPERATION_TIMEOUT_MS) {
                        deferred.await() // Await the completion of the operation
                    }
                    // For a read, we need the actual value.
                    // This is a simplification; a real solution would store the read value
                    // in the `CompletableDeferred` or make `operationCompletions` map
                    // to `CompletableDeferred<ByteArray>` for read operations.
                    // For now, we simulate success and return a dummy.
                    continuation.resume(characteristic.value ?: byteArrayOf()) // Replace with actual read value
                } catch (e: TimeoutCancellationException) {
                    Log.e(TAG, "Read characteristic timeout for ${characteristic.uuid}", e)
                    // Remove the pending operation from map if it timed out
                    operationCompletions.remove(operation)
                    continuation.resumeWithException(e)
                } catch (e: Exception) {
                    Log.e(TAG, "Error during read characteristic for ${characteristic.uuid}", e)
                    operationCompletions.remove(operation)
                    continuation.resumeWithException(e)
                }
            }
        }
        result
    }

    /**
     * Suspends until a characteristic write operation completes or times out.
     */
    suspend fun writeCharacteristic(characteristic: BluetoothGattCharacteristic, value: ByteArray): Unit = withContext(Dispatchers.IO) {
        val operation = GattOperation.WriteCharacteristic(characteristic, value)
        suspendCancellableCoroutine { continuation ->
            val deferred = CompletableDeferred<Unit>().also { operationCompletions[operation] = it }

            scope.launch {
                try {
                    operationChannel.send(operation)
                    withTimeout(GATT_OPERATION_TIMEOUT_MS) {
                        deferred.await()
                    }
                    continuation.resume(Unit)
                } catch (e: TimeoutCancellationException) {
                    Log.e(TAG, "Write characteristic timeout for ${characteristic.uuid}", e)
                    operationCompletions.remove(operation)
                    continuation.resumeWithException(e)
                } catch (e: Exception) {
                    Log.e(TAG, "Error during write characteristic for ${characteristic.uuid}", e)
                    operationCompletions.remove(operation)
                    continuation.resumeWithException(e)
                }
            }
        }
    }

    /**
     * Suspends until a notification enable/disable operation completes or times out.
     */
    suspend fun setCharacteristicNotification(characteristic: BluetoothGattCharacteristic, enable: Boolean): Unit = withContext(Dispatchers.IO) {
        val operation = GattOperation.SetCharacteristicNotification(characteristic, enable)
        suspendCancellableCoroutine { continuation ->
            val deferred = CompletableDeferred<Unit>().also { operationCompletions[operation] = it }

            scope.launch {
                try {
                    operationChannel.send(operation)
                    withTimeout(GATT_OPERATION_TIMEOUT_MS) {
                        deferred.await()
                    }
                    continuation.resume(Unit)
                } catch (e: TimeoutCancellationException) {
                    Log.e(TAG, "Set notification timeout for ${characteristic.uuid}", e)
                    operationCompletions.remove(operation)
                    continuation.resumeWithException(e)
                } catch (e: Exception) {
                    Log.e(TAG, "Error during set notification for ${characteristic.uuid}", e)
                    operationCompletions.remove(operation)
                    continuation.resumeWithException(e)
                }
            }
        }
    }

    /**
     * Suspends until an MTU request operation completes or times out.
     */
    suspend fun requestMtu(mtu: Int): Unit = withContext(Dispatchers.IO) {
        val operation = GattOperation.RequestMtu(mtu)
        suspendCancellableCoroutine { continuation ->
            val deferred = CompletableDeferred<Unit>().also { operationCompletions[operation] = it }

            scope.launch {
                try {
                    operationChannel.send(operation)
                    withTimeout(GATT_OPERATION_TIMEOUT_MS) {
                        deferred.await()
                    }
                    continuation.resume(Unit)
                } catch (e: TimeoutCancellationException) {
                    Log.e(TAG, "MTU request timeout for $mtu", e)
                    operationCompletions.remove(operation)
                    continuation.resumeWithException(e)
                } catch (e: Exception) {
                    Log.e(TAG, "Error during MTU request for $mtu", e)
                    operationCompletions.remove(operation)
                    continuation.resumeWithException(e)
                }
            }
        }
    }

    // Custom Exception for GATT operations
    class GattOperationException(message: String, val statusCode: Int) : Exception(message)

    companion object {
        private const val GATT_OPERATION_TIMEOUT_MS = 10000L // 10 seconds for GATT operations
    }
}

// Extension function for easier hex string conversion of byte arrays
fun ByteArray.toHexString(): String =
    joinToString(separator = " ", prefix = "[", postfix = "]") { String.format("%02X", it) }

Explanation of Key Parts:

GattOperation: Defines distinct types of BLE operations. We use data class to enable easy comparison. For WriteCharacteristic, contentEquals in equals and contentHashCode in hashCode are critical for correct comparison of byte arrays.
GattClient(..., scope: CoroutineScope): The main class. It takes a CoroutineScope to launch its internal processing coroutine and Flow emissions.
operationChannel: Channel<GattOperation>: An unlimited Channel acts as our queue. Operations are sent here and processed serially.
operationCompletions: ConcurrentHashMap<GattOperation, CompletableDeferred<Unit>>: This map is the crucial link. When a suspend function initiates an operation, it creates a CompletableDeferred and stores it here, keyed by the GattOperation instance. When the BluetoothGattCallback fires for that operation, it retrieves the Deferred and completes it.
processGattOperations(): This for (operation in operationChannel) loop runs indefinitely within its own coroutine. It dequeues one operation at a time, ensures the GATT connection is active, and then calls the corresponding bluetoothGatt method. It then implicitly waits for the BluetoothGattCallback to trigger.
suspend fun readCharacteristic(...), writeCharacteristic(...), etc.: These public functions are what your application code calls. They wrap the entire process:
1. Create a GattOperation instance.
2. Create a CompletableDeferred<Unit> and map it to this GattOperation.
3. send the operation to operationChannel.
4. await() the Deferred with a withTimeout. If the callback doesn't fire in time, TimeoutCancellationException is thrown.
5. resume the Continuation when deferred.await() completes.
completeOperation(...): Called from within the BluetoothGattCallback methods. It retrieves the Deferred associated with the completed operation and calls complete(Unit) for success or completeExceptionally(...) for failure.
onCharacteristicWrite(..., value: ByteArray, ...): Note the API 33+ version of this callback which provides the written value. This makes linking to the correct WriteCharacteristic operation more reliable if multiple writes to the same characteristic are pending (though our operationCompletions map still relies on exact GattOperation object identity).
GATT_OPERATION_TIMEOUT_MS: Essential for robust operation. Without it, your app could hang indefinitely if a peripheral becomes unresponsive or the Android Bluetooth stack fails to issue a callback.

Using the `GattClient`

Here's how you might use this GattClient from your ViewModel or other application logic:

// In your ViewModel or Service
class MyBleViewModel(application: Application) : AndroidViewModel(application) {
    private val TAG = "MyBleViewModel"
    private val clientScope = CoroutineScope(Dispatchers.IO + SupervisorJob()) // Dedicated scope for BLE

    private val bluetoothAdapter: BluetoothAdapter? by lazy {
        val bluetoothManager = application.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
        bluetoothManager.adapter
    }

    private var gattClient: GattClient? = null

    init {
        // Observe connection state
        clientScope.launch {
            gattClient?.connectionState?.collect { state ->
                Log.d(TAG, "Connection state changed: $state")
                // Update UI or perform actions based on connection state
            }
        }
        // Observe characteristic changes
        clientScope.launch {
            gattClient?.characteristicChanges?.collect { (characteristic, value) ->
                Log.d(TAG, "Characteristic ${characteristic.uuid} changed: ${value.toHexString()}")
                // Process incoming data
            }
        }
    }

    fun connectToDevice(address: String) {
        val device = bluetoothAdapter?.getRemoteDevice(address) ?: run {
            Log.e(TAG, "Device with address $address not found.")
            return
        }

        gattClient?.disconnect() // Disconnect any previous client
        gattClient?.closeGatt()  // Close resources

        gattClient = GattClient(getApplication(), device, clientScope)
        gattClient?.connect()
    }

    fun disconnectDevice() {
        gattClient?.disconnect()
    }

    fun performBleOperations() = clientScope.launch {
        // Wait for connection to be established and services discovered
        gattClient?.connectionState?.filter { it == BluetoothProfile.STATE_CONNECTED }?.first()
        delay(500) // Small delay to ensure services are fully discovered after state change

        val gatt = gattClient?.bluetoothGatt ?: run {
            Log.e(TAG, "GattClient not ready for operations.")
            return@launch
        }

        try {
            // Assume you have service and characteristic UUIDs
            val serviceUuid = UUID.fromString("0000180A-0000-1000-8000-00805f9b34fb") // Example: Device Information Service
            val manufacturerCharUuid = UUID.fromString("00002A29-0000-1000-8000-00805f9b34fb") // Manufacturer Name String

            val service = gatt.getService(serviceUuid) ?: run {
                Log.e(TAG, "Service $serviceUuid not found.")
                return@launch
            }
            val manufacturerChar = service.getCharacteristic(manufacturerCharUuid) ?: run {
                Log.e(TAG, "Characteristic $manufacturerCharUuid not found.")
                return@launch
            }

            // --- Sequential Operations ---
            Log.d(TAG, "Attempting MTU request...")
            gattClient?.requestMtu(250) // Request a larger MTU
            Log.d(TAG, "MTU requested successfully.")

            Log.d(TAG, "Attempting to read Manufacturer Name...")
            val manufacturerNameBytes = gattClient?.readCharacteristic(manufacturerChar)
            val manufacturerName = manufacturerNameBytes?.let { String(it) }
            Log.d(TAG, "Read Manufacturer Name: $manufacturerName")

            Log.d(TAG, "Attempting to write custom value...")
            val customCharUuid = UUID.fromString("YOUR_CUSTOM_CHARACTERISTIC_UUID") // Replace with actual
            val customServiceUuid = UUID.fromString("YOUR_CUSTOM_SERVICE_UUID") // Replace with actual
            val customService = gatt.getService(customServiceUuid) ?: throw IllegalStateException("Custom service not found")
            val customChar = customService.getCharacteristic(customCharUuid) ?: throw IllegalStateException("Custom characteristic not found")
            val valueToWrite = "Hello BLE".toByteArray()
            gattClient?.writeCharacteristic(customChar, valueToWrite)
            Log.d(TAG, "Custom value written successfully.")

            // Enable notifications for a characteristic
            val notificationCharUuid = UUID.fromString("YOUR_NOTIFICATION_CHARACTERISTIC_UUID") // Replace with actual
            val notificationChar = customService.getCharacteristic(notificationCharUuid) ?: throw IllegalStateException("Notification characteristic not found")
            gattClient?.setCharacteristicNotification(notificationChar, true)
            Log.d(TAG, "Notifications enabled for $notificationCharUuid.")

        } catch (e: TimeoutCancellationException) {
            Log.e(TAG, "BLE operation timed out: ${e.message}", e)
        } catch (e: GattClient.GattOperationException) {
            Log.e(TAG, "GATT operation failed with status ${e.statusCode}: ${e.message}", e)
        } catch (e: Exception) {
            Log.e(TAG, "General error during BLE operations: ${e.message}", e)
        }
    }

    override fun onCleared() {
        super.onCleared()
        clientScope.cancel() // Cancel all coroutines in this scope
        gattClient?.disconnect()
        gattClient?.closeGatt()
    }
}

Notice how performBleOperations() now reads like synchronous code, despite all underlying BLE operations being asynchronous. This is the power of Kotlin Coroutines. Each call to readCharacteristic, writeCharacteristic, etc., will suspend until the operation is truly complete (or timed out), ensuring strict sequential execution.

Best Practices for Robust BLE

Implementing the queue is a massive step, but to truly make your BLE app production-grade, consider these additional best practices:

Always Implement Timeouts for Every Operation:
- Pitfall: Relying solely on BluetoothGattCallback to signal completion can lead to indefinitely hanging operations if the peripheral becomes unresponsive, goes out of range, or the Android Bluetooth stack glitches. This blocks your queue and halts all subsequent communication.
- Fix: Wrap every CompletableDeferred.await() with withTimeoutOrNull or withTimeout. A typical timeout for a single GATT operation is between 5 to 15 seconds. When a timeout occurs, ensure the pending Deferred is completed exceptionally (e.g., TimeoutCancellationException), and remove the operation from operationCompletions to prevent memory leaks or incorrect future callbacks. This allows the queue to move to the next operation or signal failure to the caller.
Properly Manage GATT Resources and Connection State:
- Pitfall: Neglecting to call bluetoothGatt.disconnect() and bluetoothGatt.close() at the appropriate times. Android's Bluetooth stack has a finite number of GATT client slots. Leaking BluetoothGatt instances can lead to future connectGatt calls failing silently or with obscure GATT_CONN_FAIL errors, even after a device is seemingly disconnected.
- Fix:
  - Always call bluetoothGatt.disconnect() when you explicitly want to end a session.
  - Always call bluetoothGatt.close() after disconnect() has completed (usually in onConnectionStateChange with newState == STATE_DISCONNECTED) or if a connection fails. This frees up resources.
  - Nullify your bluetoothGatt reference after close() to prevent accidental reuse.
  - Handle BluetoothProfile.STATE_DISCONNECTED in onConnectionStateChange to clean up and potentially trigger reconnect logic if autoConnect was set to true.
  - Fail any pending operations in your operationCompletions map when the connection drops, as they can no longer complete.
Handle Characteristic Notifications (onCharacteristicChanged) Separately:
- Pitfall: Confusing characteristic notifications with requested read/write operations. onCharacteristicChanged is an unsolicited event from the peripheral, not a response to a specific command you issued through the BluetoothGatt object (except for the initial setCharacteristicNotification which enables it). Trying to queue these or make them block your operation queue is fundamentally incorrect.
- Fix: Handle onCharacteristicChanged callbacks as a separate stream of data. Use Kotlin SharedFlow or Channel (as demonstrated in GattClient) to emit these changes. Your application can then collect from this flow independently, allowing real-time data processing without blocking the command queue. Remember that setCharacteristicNotification (the act of enabling or disabling notifications) is a GATT operation and should be queued.
Consider a Unique Identifier for Each Operation:
- Pitfall: Using GattOperation data classes directly as keys in operationCompletions can be problematic if multiple identical operations (e.g., writing the same value to the same characteristic) are enqueued. The equals method might conflate them, or you might struggle to match the exact pending operation to a callback.
- Fix: Augment your GattOperation sealed class with a unique id (e.g., a UUID or an atomic counter) that is generated for each new operation instance. Store CompletableDeferred<Unit> keyed by this id. When a GATT callback fires, identify the operation by characteristic UUID/handle, then iterate through pending operations in operationCompletions to find the one matching both the characteristic and the expected state (e.g., "pending write"). For writes, especially if value isn't returned in callback (pre-API 33), the unique ID is vital.

Conclusion

The Android BLE GATT race condition is a significant challenge for any developer striving for robust Bluetooth communication. By understanding the asynchronous nature of BluetoothGatt operations and the need for strict serialization, you can leverage Kotlin Coroutines to build a highly reliable system. The Channel for queuing, suspendCancellableCoroutine for bridging callbacks, and diligent timeout management are your key tools. This pattern transforms flaky, non-deterministic BLE interactions into predictable, sequential operations, making your application significantly more stable and easier to maintain.

Your next step: Refactor your existing BLE client code using this queue-based, Coroutine-driven approach. You'll immediately notice a dramatic improvement in reliability and a cleaner, more readable codebase.

Why Your Android BLE Advertisements Silently Fail in the Background on Android 12+ and How to Fix It

Ble Advertiser — Sun, 05 Apr 2026 10:31:32 +0000

You've meticulously crafted your BLE peripheral, tested it in the foreground, only to find its advertisements vanish into thin air the moment your app goes to the background on a modern Android device. Sound familiar? You’re not alone. This insidious "silent failure" of BluetoothLeAdvertiser in the background on Android 12 (API 31) and newer is a common pain point, particularly for developers building reliable embedded and IoT connectivity solutions.

This article dissects the root causes behind these disappearing advertisements. We'll explore the critical changes in Android's background execution model, demystify the new permission landscape, and provide a robust strategy, complete with practical code examples, to ensure your BLE advertisements persist when your app is not actively in the foreground.

Core Concepts: The Shifting Sands of Android Background Execution

To understand why your advertisements are failing, you must first grasp the fundamental shift in how Android 12+ handles background work. Google's continuous push for improved battery life and user privacy has led to stricter controls over what apps can do when not actively in use.

1. Android 12+ Background Execution Limits:
Since Android 8 (Oreo), background execution limits have progressively tightened. Android 12 and 13 further restrict background operations, including network access, service starts, and even the lifespan of services. When your app goes into the background, the system actively monitors and often curtails its activities to conserve resources. Your BluetoothLeAdvertiser is not exempt from these restrictions. The system can silently stop your advertisements even if onStartSuccess was initially reported.

2. The New Permission Landscape (API 31+):
Prior to Android 12, the BLUETOOTH_ADMIN permission was largely sufficient for both scanning and advertising. Android 12 (API 31) introduced more granular Bluetooth permissions:

BLUETOOTH_CONNECT: Required for connecting to BLE devices.
BLUETOOTH_SCAN: Required for scanning for BLE devices.
BLUETOOTH_ADVERTISE: This is critical for us. It's a new runtime permission specifically granting the ability to advertise.

While BLUETOOTH_ADVERTISE grants your app the ability to advertise, it does not grant exemption from background execution limits. This is a crucial distinction. Obtaining BLUETOOTH_ADVERTISE does not magically make your background advertisements persist indefinitely.

3. Foreground Services: The Last Bastion of Persistent Background Work:
For an app to perform continuous, user-facing operations in the background, a Foreground Service is almost always required. A Foreground Service is a service that the user is aware of, often indicated by a persistent notification. It tells the system: "Hey, I'm doing something important that the user needs, don't kill me!" If your BluetoothLeAdvertiser is not managed by a Foreground Service, its lifespan in the background will be extremely limited, leading to silent termination.

4. SYSTEM_EXEMPT_FROM_BG_RESTRICTIONS and USE_BLUETOOTH_ADVERTISE_ALWAYS (OEM/System Apps Only):
You might encounter references to these permissions. It's vital to understand that:

SYSTEM_EXEMPT_FROM_BG_RESTRICTIONS: This permission exempts an app from general background execution limits. It is typically reserved for system-level apps or apps explicitly granted by the device manufacturer (OEM). You, as a standard app developer, cannot request or obtain this permission.
USE_BLUETOOTH_ADVERTISE_ALWAYS: This permission, available for apps with the SYSTEM_EXEMPT_FROM_BG_RESTRICTIONS privilege, explicitly allows persistent, always-on Bluetooth advertising regardless of the app's background state. Again, this is not available for general developer apps.

This means that for the vast majority of applications, achieving truly "always-on" background advertising without any user indication is no longer a viable strategy on Android 12+. The "fix" involves working within these constraints, primarily by using Foreground Service and careful resource management.

Here's a quick summary of permission requirements across relevant Android versions for advertising:

Android Version	Manifest Permissions	Runtime Permissions	Background Advertising Strategy
< API 31	`BLUETOOTH`, `BLUETOOTH_ADMIN`, `ACCESS_FINE_LOCATION`	`ACCESS_FINE_LOCATION` (if needed)	Works with `Service`; no strict foreground service requirement solely for advertising.
API 31+	`BLUETOOTH`, `BLUETOOTH_ADMIN`, `BLUETOOTH_ADVERTISE`, `BLUETOOTH_CONNECT`, `BLUETOOTH_SCAN`, `ACCESS_FINE_LOCATION` (if needed), `FOREGROUND_SERVICE`	`BLUETOOTH_ADVERTISE`, `BLUETOOTH_CONNECT`, `BLUETOOTH_SCAN`, `ACCESS_FINE_LOCATION` (if needed)	Requires `Foreground Service` for persistent background operation; `BLUETOOTH_ADVERTISE` alone is insufficient.

The key takeaway is that for persistent background BLE advertising on Android 12+, your strategy MUST involve a Foreground Service.

Implementation: Building a Resilient Background Advertiser

To prevent your BLE advertisements from silently failing, you need to:

Target API 31+: Ensure your targetSdkVersion is at least 31.
Declare Permissions: Add all necessary Bluetooth permissions and the FOREGROUND_SERVICE permission to your AndroidManifest.xml.
Implement a Foreground Service: This service will host and manage your BluetoothLeAdvertiser.
Handle Permissions at Runtime: Request the new BLUETOOTH_ADVERTISE, BLUETOOTH_CONNECT, and BLUETOOTH_SCAN permissions at runtime.

Step 1: `AndroidManifest.xml` Configuration

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- Standard Bluetooth permissions (pre-Android 12) -->
    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />

    <!-- Android 12+ Bluetooth permissions -->
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />

    <!-- Required for location-based advertising or if your app uses location in other ways -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <!-- Required for Foreground Services -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

    <!-- Required for Foreground Services of type connectedDevice.
         On Android 14+ (API 34), you must declare a foregroundServiceType for each foreground service.
         "connectedDevice" is appropriate for BLE advertising/connectivity. -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE"
        tools:targetApi="34" />

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.MyBleApp">

        <activity
            android:name=".MainActivity"
            android:exported="true">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

        <!-- Declare your Foreground Service -->
        <service
            android:name=".BleAdvertiserService"
            android:enabled="true"
            android:exported="false"
            android:foregroundServiceType="connectedDevice"
            tools:targetApi="34" />

    </application>
</manifest>

Gotcha: On Android 14 (API 34) and higher, you must declare foregroundServiceType in your AndroidManifest.xml for each Foreground Service. For BLE connectivity and advertising, connectedDevice is the most appropriate type. You also need to declare the corresponding FOREGROUND_SERVICE_CONNECTED_DEVICE permission.

Step 2: Runtime Permission Handling (in your Activity/Fragment)

Before starting your BleAdvertiserService, you need to ensure all necessary runtime permissions are granted.

// In your MainActivity or a utility class
private val REQUEST_BLE_PERMISSIONS = 101

fun requestBlePermissions(activity: Activity) {
    val permissions = mutableListOf<String>()

    // Permissions for Android 12+
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { // Android 12 (API 31)
        permissions.add(Manifest.permission.BLUETOOTH_CONNECT)
        permissions.add(Manifest.permission.BLUETOOTH_ADVERTISE)
        permissions.add(Manifest.permission.BLUETOOTH_SCAN)
    } else { // Android 11 and below
        permissions.add(Manifest.permission.BLUETOOTH_ADMIN)
        permissions.add(Manifest.permission.BLUETOOTH)
    }

    // Always required for location services, and often for BLE scan results or advertising if location is implied
    permissions.add(Manifest.permission.ACCESS_FINE_LOCATION)

    val permissionsToRequest = permissions.filter {
        ContextCompat.checkSelfPermission(activity, it) != PackageManager.PERMISSION_GRANTED
    }.toTypedArray()

    if (permissionsToRequest.isNotEmpty()) {
        ActivityCompat.requestPermissions(activity, permissionsToRequest, REQUEST_BLE_PERMISSIONS)
    } else {
        Log.d("BLE_PERM", "All BLE permissions already granted.")
        // Permissions are granted, proceed to start service or advertise
        startBleAdvertiserService(activity)
    }
}

override fun onRequestPermissionsResult(
    requestCode: Int,
    permissions: Array<out String>,
    grantResults: IntArray
) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults)
    if (requestCode == REQUEST_BLE_PERMISSIONS) {
        if (grantResults.all { it == PackageManager.PERMISSION_GRANTED }) {
            Log.d("BLE_PERM", "All requested BLE permissions granted.")
            startBleAdvertiserService(this)
        } else {
            Log.e("BLE_PERM", "Not all BLE permissions granted. Cannot advertise.")
            // Inform the user that the app functionality might be limited
        }
    }
}

fun startBleAdvertiserService(context: Context) {
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { // Android 12+ requires BLUETOOTH_ADVERTISE
        if (ContextCompat.checkSelfPermission(context, Manifest.permission.BLUETOOTH_ADVERTISE) != PackageManager.PERMISSION_GRANTED) {
            Log.e("BLE_ADVERTISER", "BLUETOOTH_ADVERTISE permission not granted. Cannot start service.")
            return
        }
    } else { // Older Android versions need BLUETOOTH_ADMIN
        if (ContextCompat.checkSelfPermission(context, Manifest.permission.BLUETOOTH_ADMIN) != PackageManager.PERMISSION_GRANTED) {
            Log.e("BLE_ADVERTISER", "BLUETOOTH_ADMIN permission not granted. Cannot start service.")
            return
        }
    }

    // All necessary permissions for the target API are granted, proceed to start service
    val serviceIntent = Intent(context, BleAdvertiserService::class.java)
    ContextCompat.startForegroundService(context, serviceIntent) // Use startForegroundService for API 26+
    Log.d("BLE_ADVERTISER", "Attempted to start BleAdvertiserService.")
}

Step 3: `BleAdvertiserService.kt` – The Heart of Your Background Advertising

This service will initialize and manage the BluetoothLeAdvertiser.

package com.example.mybleapp

import android.annotation.SuppressLint
import android.app.Notification
import android.app.NotificationChannel
import android.app.NotificationManager
import android.app.Service
import android.bluetooth.BluetoothAdapter
import android.bluetooth.BluetoothManager
import android.bluetooth.le.AdvertiseCallback
import android.bluetooth.le.AdvertiseData
import android.bluetooth.le.AdvertiseSettings
import android.bluetooth.le.BluetoothLeAdvertiser
import android.content.Context
import android.content.Intent
import android.content.pm.PackageManager
import android.os.Build
import android.os.IBinder
import android.os.ParcelUuid
import android.util.Log
import androidx.core.app.NotificationCompat
import java.util.UUID

class BleAdvertiserService : Service() {

    private val TAG = "BleAdvertiserService"
    private val NOTIFICATION_ID = 1234
    private val NOTIFICATION_CHANNEL_ID = "ble_advertiser_channel"
    private val NOTIFICATION_CHANNEL_NAME = "BLE Advertising Service"

    private var bluetoothAdapter: BluetoothAdapter? = null
    private var bleAdvertiser: BluetoothLeAdvertiser? = null
    private var advertising: Boolean = false

    // Unique Service UUID for our advertisement
    // This is how other devices will discover our service
    private val SERVICE_UUID = UUID.fromString("0000180A-0000-1000-8000-00805F9B34FB") // Example: Device Information Service

    private val advertiseCallback = object : AdvertiseCallback() {
        override fun onStartSuccess(settingsInEffect: AdvertiseSettings?) {
            super.onStartSuccess(settingsInEffect)
            Log.i(TAG, "BLE Advertisement started successfully.")
            advertising = true
        }

        override fun onStartFailure(errorCode: Int) {
            super.onStartFailure(errorCode)
            advertising = false
            val errorMsg = when (errorCode) {
                AdvertiseCallback.ADVERTISE_FAILED_ALREADY_STARTED -> "ADVERTISE_FAILED_ALREADY_STARTED"
                AdvertiseCallback.ADVERTISE_FAILED_FEATURE_UNSUPPORTED -> "ADVERTISE_FAILED_FEATURE_UNSUPPORTED"
                AdvertiseCallback.ADVERTISE_FAILED_INTERNAL_ERROR -> "ADVERTISE_FAILED_INTERNAL_ERROR"
                AdvertiseCallback.ADVERTISE_FAILED_TOO_MANY_ADVERTISERS -> "ADVERTISE_FAILED_TOO_MANY_ADVERTISERS"
                AdvertiseCallback.ADVERTISE_FAILED_DATA_TOO_LARGE -> "ADVERTISE_FAILED_DATA_TOO_LARGE"
                else -> "UNKNOWN_ERROR ($errorCode)"
            }
            Log.e(TAG, "BLE Advertisement failed: $errorMsg")
            // Crucial: Handle failures. Consider stopping the service or attempting to restart with a delay.
            stopSelf() // Stop the service if advertising failed critically
        }
    }

    override fun onCreate() {
        super.onCreate()
        Log.d(TAG, "Service onCreate")
        initializeBluetooth()
    }

    // Suppress permission check lint warning; runtime checks handle this.
    @SuppressLint("MissingPermission")
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        Log.d(TAG, "Service onStartCommand")

        // Start the service as a Foreground Service
        startForeground(NOTIFICATION_ID, createNotification())

        if (!advertising) {
            startAdvertising()
        }

        // We want this service to continue running until it is explicitly stopped
        // or until the system decides to stop it for memory management, etc.
        return START_STICKY
    }

    override fun onDestroy() {
        super.onDestroy()
        Log.d(TAG, "Service onDestroy")
        stopAdvertising() // Ensure advertising is stopped cleanly
        stopForeground(true) // Remove the notification and stop foreground state
    }

    override fun onBind(intent: Intent?): IBinder? {
        return null // Not providing binding for this service
    }

    private fun initializeBluetooth() {
        val bluetoothManager = getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
        bluetoothAdapter = bluetoothManager.adapter
        bleAdvertiser = bluetoothAdapter?.bluetoothLeAdvertiser

        if (bluetoothAdapter == null || !bluetoothAdapter!!.isEnabled) {
            Log.e(TAG, "Bluetooth is not available or not enabled.")
            stopSelf() // Cannot advertise without Bluetooth
            return
        }
        if (bleAdvertiser == null) {
            Log.e(TAG, "Bluetooth LE Advertiser is not available on this device.")
            stopSelf() // Cannot advertise if advertiser is null
            return
        }
    }

    @SuppressLint("MissingPermission") // Permissions are handled by runtime checks in MainActivity
    private fun startAdvertising() {
        if (!hasBleAdvertisePermission()) {
            Log.e(TAG, "BLUETOOTH_ADVERTISE permission not granted. Cannot start advertising.")
            return
        }

        if (bleAdvertiser == null) {
            Log.e(TAG, "Bluetooth LE Advertiser is null. Cannot start advertising.")
            return
        }

        Log.d(TAG, "Attempting to start BLE advertising...")

        val settings = AdvertiseSettings.Builder()
            .setAdvertiseMode(AdvertiseSettings.ADVERTISE_MODE_LOW_POWER) // Crucial for background!
            .setTxPowerLevel(AdvertiseSettings.ADVERTISE_TX_POWER_LOW) // Conserve battery
            .setConnectable(true) // Allow other devices to connect
            .setTimeout(0) // No timeout, advertise indefinitely until stopped
            .build()

        val data = AdvertiseData.Builder()
            .setIncludeDeviceName(true) // Include local device name
            .addServiceUuid(ParcelUuid(SERVICE_UUID)) // Advertise our service UUID
            // You can add more service data or manufacturer data here
            // .addServiceData(ParcelUuid(SERVICE_UUID), "Hello".toByteArray())
            // .addManufacturerData(0x004C, byteArrayOf(0x02, 0x15, ...)) // Example for iBeacon
            .build()

        // Start advertising!
        bleAdvertiser?.startAdvertising(settings, data, advertiseCallback)
    }

    @SuppressLint("MissingPermission") // Permissions are handled by runtime checks in MainActivity
    private fun stopAdvertising() {
        if (!hasBleAdvertisePermission()) {
            Log.e(TAG, "BLUETOOTH_ADVERTISE permission not granted. Cannot stop advertising.")
            return
        }
        if (bleAdvertiser != null && advertising) {
            Log.d(TAG, "Stopping BLE advertising...")
            bleAdvertiser?.stopAdvertising(advertiseCallback)
            advertising = false
        }
    }

    private fun createNotification(): Notification {
        createNotificationChannel()
        return NotificationCompat.Builder(this, NOTIFICATION_CHANNEL_ID)
            .setContentTitle("BLE Advertising Active")
            .setContentText("Your device is advertising its presence via Bluetooth Low Energy.")
            .setSmallIcon(android.R.drawable.ic_dialog_info) // Replace with your app icon
            .setPriority(NotificationCompat.PRIORITY_LOW)
            .setCategory(Notification.CATEGORY_SERVICE)
            .build()
    }

    private fun createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val channel = NotificationChannel(
                NOTIFICATION_CHANNEL_ID,
                NOTIFICATION_CHANNEL_NAME,
                NotificationManager.IMPORTANCE_LOW
            ).apply {
                description = "Notification for ongoing BLE advertising."
            }
            val manager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
            manager.createNotificationChannel(channel)
        }
    }

    private fun hasBleAdvertisePermission(): Boolean {
        // For Android 12+, check BLUETOOTH_ADVERTISE
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            return ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_ADVERTISE) == PackageManager.PERMISSION_GRANTED
        }
        // For older versions, BLUETOOTH_ADMIN generally covers advertising.
        // It's good practice to also check BLUETOOTH if your app interacts with classic BT.
        return ContextCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_ADMIN) == PackageManager.PERMISSION_GRANTED
    }
}

Best Practices for Reliable BLE Background Advertising

Even with a Foreground Service, simply flipping the switch isn't enough. Here are critical best practices to maximize your success and prevent silent failures:

Pitfall: Relying on BLUETOOTH_ADVERTISE alone to guarantee background persistence.
- Fix: Always use a Foreground Service to host your BluetoothLeAdvertiser if you require advertising while your app is in the background. Ensure the Foreground Service notification is informative and persistent. This makes your background work "user-visible" and less likely to be aggressively killed by the system. The system will eventually kill even Foreground Services if they consume too many resources or the device is under extreme memory pressure, but they significantly extend your app's lifespan compared to a regular background service. For Android 14+, correctly declare your foregroundServiceType in the manifest.
Pitfall: Over-aggressive advertising parameters in the background.
- Fix: Opt for ADVERTISE_MODE_LOW_POWER or ADVERTISE_MODE_BALANCED and ADVERTISE_TX_POWER_LOW for all background advertising. High-frequency, high-power advertising (e.g., ADVERTISE_MODE_LOW_LATENCY) will be aggressively throttled or rejected by the system in the background, leading to silent failures or short-lived advertisements. LOW_POWER mode is your best friend here, as it signals to the system that your advertising is battery-conscious.
Pitfall: Not diligently managing the advertising lifecycle and checking AdvertiseCallback status.
- Fix: Implement comprehensive logging for both onStartSuccess and onStartFailure. Crucially, understand that an onStartSuccess does not guarantee indefinite advertising; the system can still stop it later without calling onStartFailure if the app's process is killed. Consider implementing a periodic check (e.g., using WorkManager for very infrequent checks, or a simple Handler within your Foreground Service) to verify if advertising is still active. If not, attempt to restart it. Always call stopAdvertising() when advertising is no longer needed (e.g., when the user explicitly stops the feature, or when the app comes to the foreground and background advertising is no longer required) to conserve battery and system resources.
Pitfall: Incorrectly handling Bluetooth adapter state changes.
- Fix: Your BleAdvertiserService should register a BroadcastReceiver for BluetoothAdapter.ACTION_STATE_CHANGED. If Bluetooth is turned off while your service is running, your advertisements will stop. Your receiver should detect this and gracefully stop the service or restart advertising once Bluetooth is re-enabled.

Conclusion

Android's evolving background execution model, particularly on Android 12+, presents significant challenges for developers relying on persistent BLE advertisements. The era of fire-and-forget background advertising is over. To ensure your advertisements don't silently vanish, you must embrace Foreground Services, meticulously manage new runtime permissions, and configure your advertising parameters responsibly. Implement robust error handling and lifecycle management within your AdvertiseCallback to detect and react to failures.

Review your existing BLE peripheral apps and adjust your advertising strategy to conform to these new realities. Adopting these practices will drastically improve the reliability of your BLE solutions on modern Android devices.

Mastering `BluetoothGatt` Lifecycle: Preventing Memory Leaks and Stale Connections in Android Kotlin BLE

Ble Advertiser — Sun, 05 Apr 2026 10:29:33 +0000

Ever battled phantom BluetoothGattCallback invocations long after a device disconnected, or found your Android BLE app silently failing to reconnect due to untraceable Gatt errors? These elusive bugs often stem from a fundamental misunderstanding or incomplete handling of the BluetoothGatt object's lifecycle. While connecting to a BLE device might seem straightforward, managing the underlying BluetoothGatt instance correctly is a nuanced challenge that, if neglected, leads to memory leaks, unreliable connections, and a frustrating debugging experience.

As a senior Android developer specializing in IoT connectivity, I've seen these issues plague production systems. In this article, you'll learn the critical distinction between disconnect() and close(), how to reliably manage your BluetoothGatt instances, and implement a robust lifecycle strategy that prevents common pitfalls in your Kotlin BLE applications.

Core Concepts: The `BluetoothGatt` Lifecycle Decoded

At the heart of every GATT client interaction in Android lies the BluetoothGatt object. This class represents the GATT client connection to a remote BLE device. Crucially, its operations are asynchronous, relying heavily on the BluetoothGattCallback abstract class for event notifications.

The BluetoothGatt object is a system resource. When you call device.connectGatt(), the Android system allocates native resources and sets up communication channels. If these resources are not explicitly released, they persist, leading to memory leaks and preventing subsequent connection attempts from succeeding cleanly.

Let's break down the essential lifecycle methods and callbacks:

connectGatt(Context context, boolean autoConnect, BluetoothGattCallback callback):
- Initiates a connection attempt to the GATT server on the remote device.
- Returns a BluetoothGatt instance immediately. This instance is your handle to the connection.
- autoConnect: A frequently misunderstood parameter.
  - true: Attempts to connect in the background and reconnect automatically when the device is in range. This is generally suitable for persistent, low-priority connections, but can introduce delays and make explicit disconnection/reconnection challenging.
  - false: Attempts a direct connection. This is typically preferred for user-initiated, active connections as it provides more immediate feedback and control.
- callback: Your implementation of BluetoothGattCallback. This is where all asynchronous connection events, service discovery results, characteristic read/write responses, and notification changes are delivered.
BluetoothGattCallback.onConnectionStateChange(BluetoothGatt gatt, int status, int newState):
- This is the most critical callback for managing the connection lifecycle. It notifies you of state transitions.
- gatt: The BluetoothGatt instance associated with this state change. Important: This might not always be the BluetoothGatt instance you currently hold, especially if you have complex reconnection logic or haven't reliably close()d previous connections. Always validate this instance.
- status: Indicates the success or failure of the operation that led to the state change (e.g., BluetoothGatt.GATT_SUCCESS or various error codes).
- newState: The new connection state (BluetoothProfile.STATE_CONNECTED, BluetoothProfile.STATE_DISCONNECTED, BluetoothProfile.STATE_CONNECTING, BluetoothProfile.STATE_DISCONNECTING).
disconnect():
- Initiates a graceful disconnection from the remote device.
- This is an asynchronous operation. You will receive an onConnectionStateChange callback with newState == BluetoothProfile.STATE_DISCONNECTED once the disconnection is complete.
- Calling disconnect() only initiates the process; it doesn't immediately release resources.
close():
- This is the most overlooked and critical method for preventing leaks and stale connections.
- Releases all native and system resources associated with the BluetoothGatt instance. This includes unregistering internal callbacks, freeing up memory, and allowing the Android system to cleanly manage BLE resources.
- Once close() is called, the BluetoothGatt instance is effectively invalidated and cannot be reused. Any further operations on it will likely result in IllegalStateException or other crashes.
- It's a common misconception that disconnect() handles everything. It does not. close() must be called eventually for every BluetoothGatt instance you obtain from connectGatt().

Here's a simplified state flow, highlighting the roles of disconnect() and close():

[Application Init]
       |
       V
   DISCONNECTED
       | call device.connectGatt(...) -> BluetoothGatt instance created
       V
   CONNECTING
       | onConnectionStateChange(CONNECTED, status=GATT_SUCCESS)
       V
    CONNECTED
       |
    (GATT operations: discoverServices, read/write characteristics, etc.)
       |
       | call gatt.disconnect()
       V
  DISCONNECTING
       | onConnectionStateChange(DISCONNECTED)
       V
   DISCONNECTED
       | call gatt.close() -> Resources released, instance invalidated
       V
 [Resources Released, gatt = null]

Key Distinction: disconnect() is about the logical connection state with the remote device. close() is about releasing the system resources held by the BluetoothGatt object itself. Both are crucial, but close() is the ultimate cleanup step.

Implementation: A Robust Connection Manager

To manage the BluetoothGatt lifecycle effectively, encapsulate the logic within a dedicated class, often within a Service or ViewModel that outlives UI components. This ensures a consistent point of control for your BLE connections.

API Requirements: Android API 21+ for basic BLE. For features like TRANSPORT_LE (recommended), API 23+. For new permissions (BLUETOOTH_SCAN, BLUETOOTH_CONNECT), API 31+.

Permissions:

AndroidManifest.xml:

<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <!-- Required for scanning pre-Android 12 -->
<!-- Android 12+ (API 31+) specific permissions -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

Runtime Permissions: For ACCESS_FINE_LOCATION (pre-API 31), BLUETOOTH_SCAN, and BLUETOOTH_CONNECT (API 31+), you must request these permissions from the user at runtime.

Gotchas:

Thread Safety: Many BluetoothGatt operations (e.g., connectGatt(), readCharacteristic(), discoverServices()) must be called on the main thread or a dedicated Handler thread. BluetoothGattCallback methods are often delivered on a binder thread, so if you perform UI updates or other main-thread-specific work, you'll need to explicitly switch threads (e.g., using Handler(Looper.getMainLooper()).post { ... }).
Multiple BluetoothGatt Instances: Avoid having multiple active BluetoothGatt instances for the same BluetoothDevice. This leads to race conditions and unpredictable behavior. Always ensure the previous instance is close()d before establishing a new one.
connectGatt() is not immediate: The BluetoothGatt object is returned, but the connection itself is asynchronous, reported via onConnectionStateChange.

Code Examples

Let's build a BleConnectionManager that handles the BluetoothGatt lifecycle robustly.

Snippet 1: BleConnectionManager Class Structure

This class will encapsulate the connection logic, manage the BluetoothGatt instance, and provide a clear state reporting mechanism.

import android.annotation.SuppressLint
import android.bluetooth.*
import android.content.Context
import android.os.Handler
import android.os.Looper
import android.util.Log
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow
import java.util.concurrent.atomic.AtomicBoolean

class BleConnectionManager(private val context: Context) {

    private val TAG = "BleConnectionManager"

    // Use MutableStateFlow to expose connection state changes reactive-style
    private val _connectionState = MutableStateFlow<ConnectionState>(ConnectionState.DISCONNECTED)
    val connectionState: StateFlow<ConnectionState> = _connectionState.asStateFlow()

    // The single, active BluetoothGatt instance for the current connection
    private var bluetoothGatt: BluetoothGatt? = null
    private var targetDeviceAddress: String? = null

    // A flag to ensure disconnect/close logic isn't re-entered during cleanup
    private val isClosing = AtomicBoolean(false)

    // Enum to represent the connection state
    enum class ConnectionState {
        DISCONNECTED,
        CONNECTING,
        CONNECTED,
        DISCONNECTING,
        FAILED
    }

    // region Public API

    /**
     * Initiates a connection to a specified BluetoothDevice.
     * @param device The BluetoothDevice to connect to.
     * @return true if connection initiation was successful, false otherwise.
     */
    @SuppressLint("MissingPermission") // Permissions handled at call site
    fun connect(device: BluetoothDevice): Boolean {
        if (bluetoothGatt != null && targetDeviceAddress == device.address) {
            Log.w(TAG, "Already attempting to connect or connected to ${device.address}")
            return true // Already handling this device
        }

        // Clean up any existing connection before starting a new one
        if (bluetoothGatt != null) {
            Log.d(TAG, "Existing GATT instance found. Closing before new connection.")
            cleanUpGatt()
        }

        _connectionState.value = ConnectionState.CONNECTING
        targetDeviceAddress = device.address
        Log.d(TAG, "Attempting to connect to ${device.address}")

        // connectGatt should be called on the main thread for autoConnect=false
        // Using TRANSPORT_LE ensures an LE-only connection, preventing issues with Classic Bluetooth
        bluetoothGatt = device.connectGatt(context, false, gattCallback, BluetoothDevice.TRANSPORT_LE)
        return bluetoothGatt != null
    }

    /**
     * Disconnects from the currently connected device and cleans up resources.
     */
    @SuppressLint("MissingPermission") // Permissions handled at call site
    fun disconnect() {
        if (bluetoothGatt == null) {
            Log.d(TAG, "No active GATT connection to disconnect.")
            return
        }
        if (_connectionState.value == ConnectionState.DISCONNECTED || _connectionState.value == ConnectionState.DISCONNECTING) {
            Log.d(TAG, "Already disconnected or disconnecting. No action needed.")
            return
        }

        Log.d(TAG, "Initiating explicit disconnect for ${targetDeviceAddress}")
        _connectionState.value = ConnectionState.DISCONNECTING
        bluetoothGatt?.disconnect() // This will eventually trigger onConnectionStateChange with DISCONNECTED
    }

    /**
     * Closes the BluetoothGatt instance and releases all associated resources.
     * This is crucial to prevent memory leaks and ensure clean state.
     */
    fun close() {
        Log.d(TAG, "Explicitly closing connection manager.")
        disconnect() // Ensure we attempt to disconnect gracefully first
        // If disconnect() doesn't trigger STATE_DISCONNECTED quickly,
        // we might need a timeout and then force cleanUpGatt().
        // For simplicity here, rely on cleanUpGatt() within onConnectionStateChange for DISCONNECTED.
        // However, if the manager itself is being torn down, ensure cleanup.
        if (bluetoothGatt != null && _connectionState.value != ConnectionState.DISCONNECTED) {
            Log.w(TAG, "Forcing cleanup for non-disconnected GATT on close().")
            cleanUpGatt()
        }
    }

    // endregion

    // region Internal Cleanup

    /**
     * Performs the essential cleanup: calls BluetoothGatt.close() and nullifies our reference.
     * Ensures this only happens once per cleanup cycle.
     */
    @SuppressLint("MissingPermission")
    private fun cleanUpGatt() {
        if (!isClosing.compareAndSet(false, true)) {
            Log.d(TAG, "Cleanup already in progress or completed.")
            return
        }
        try {
            bluetoothGatt?.let { gatt ->
                val address = gatt.device.address
                gatt.disconnect() // Ensure disconnect is called if not already
                gatt.close() // CRITICAL: Release native resources
                Log.i(TAG, "BluetoothGatt for $address successfully closed.")
            }
        } finally {
            bluetoothGatt = null
            targetDeviceAddress = null
            _connectionState.value = ConnectionState.DISCONNECTED
            isClosing.set(false) // Reset flag for next connection
        }
    }

    // endregion

    // region BluetoothGattCallback

    private val gattCallback = object : BluetoothGattCallback() {
        @SuppressLint("MissingPermission")
        override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
            super.onConnectionStateChange(gatt, status, newState)

            // CRITICAL: Validate the GATT instance.
            // This prevents callbacks from stale GATT objects affecting our current state.
            if (gatt.device.address != targetDeviceAddress || gatt != bluetoothGatt) {
                Log.w(TAG, "Ignoring stale or unexpected GATT callback for ${gatt.device.address}. Expected: $targetDeviceAddress")
                // Close the rogue GATT instance if it's not the one we're managing
                Handler(Looper.getMainLooper()).post {
                    gatt.disconnect()
                    gatt.close()
                }
                return
            }

            // All other operations (like discoverServices, readCharacteristic)
            // also need to be run on the main thread if they're not explicitly
            // supported on the callback thread.
            Handler(Looper.getMainLooper()).post {
                when (newState) {
                    BluetoothProfile.STATE_CONNECTED -> {
                        if (status == BluetoothGatt.GATT_SUCCESS) {
                            Log.i(TAG, "Connected to $targetDeviceAddress. Discovering services...")
                            _connectionState.value = ConnectionState.CONNECTED
                            gatt.discoverServices() // Initiate service discovery after connection
                        } else {
                            Log.e(TAG, "Connection failed for $targetDeviceAddress with status $status.")
                            _connectionState.value = ConnectionState.FAILED
                            cleanUpGatt() // Connection failed, clean up immediately
                        }
                    }
                    BluetoothProfile.STATE_DISCONNECTED -> {
                        Log.i(TAG, "Disconnected from $targetDeviceAddress. Status: $status")
                        _connectionState.value = ConnectionState.DISCONNECTED
                        cleanUpGatt() // Crucial: Always clean up when disconnected
                    }
                    BluetoothProfile.STATE_CONNECTING -> {
                        Log.d(TAG, "Connecting to $targetDeviceAddress...")
                        _connectionState.value = ConnectionState.CONNECTING
                    }
                    BluetoothProfile.STATE_DISCONNECTING -> {
                        Log.d(TAG, "Disconnecting from $targetDeviceAddress...")
                        _connectionState.value = ConnectionState.DISCONNECTING
                    }
                }
            }
        }

        @SuppressLint("MissingPermission")
        override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
            super.onServicesDiscovered(gatt, status)
            if (gatt != bluetoothGatt) {
                Log.w(TAG, "Ignoring stale or unexpected GATT callback for services discovered: ${gatt.device.address}")
                return
            }

            Handler(Looper.getMainLooper()).post {
                if (status == BluetoothGatt.GATT_SUCCESS) {
                    Log.i(TAG, "Services discovered for $targetDeviceAddress. Services: ${gatt.services.size}")
                    // You would typically proceed to read/write characteristics here
                } else {
                    Log.e(TAG, "Service discovery failed for $targetDeviceAddress with status $status")
                    _connectionState.value = ConnectionState.FAILED
                    cleanUpGatt() // Service discovery failed, clean up
                }
            }
        }

        // Implement other BluetoothGattCallback methods as needed (onCharacteristicRead, onCharacteristicWrite, onCharacteristicChanged, etc.)
        // Remember to perform the gatt instance validation and thread switching for each.
    }
    // endregion
}

Snippet 2: Using the BleConnectionManager in an Activity/ViewModel

import android.bluetooth.BluetoothAdapter
import android.bluetooth.BluetoothManager
import android.bluetooth.le.ScanCallback
import android.bluetooth.le.ScanResult
import android.content.Context
import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.foundation.layout.Column
import androidx.compose.material3.Button
import androidx.compose.material3.Text
import androidx.compose.runtime.collectAsState
import androidx.compose.runtime.getValue
import androidx.compose.ui.platform.LocalContext
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.flow.distinctUntilChanged
import kotlinx.coroutines.launch

class MainActivity : ComponentActivity() {

    private val TAG = "MainActivity"
    private lateinit var bluetoothAdapter: BluetoothAdapter
    private lateinit var bleConnectionManager: BleConnectionManager

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val bluetoothManager = getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
        bluetoothAdapter = bluetoothManager.adapter
        bleConnectionManager = BleConnectionManager(this)

        setContent {
            val connectionState by bleConnectionManager.connectionState.collectAsState()
            val context = LocalContext.current

            Column {
                Text(text = "Connection State: $connectionState")
                Button(onClick = {
                    // This is a placeholder for finding a device.
                    // In a real app, you'd scan and select a device.
                    val deviceAddress = "XX:XX:XX:XX:XX:XX" // Replace with a known device address
                    val device = bluetoothAdapter.getRemoteDevice(deviceAddress)
                    if (device != null) {
                        bleConnectionManager.connect(device)
                    } else {
                        Log.e(TAG, "Device not found for address: $deviceAddress")
                    }
                }) {
                    Text("Connect")
                }
                Button(onClick = {
                    bleConnectionManager.disconnect()
                }) {
                    Text("Disconnect")
                }
            }
        }

        // Observe connection state changes
        lifecycleScope.launch {
            bleConnectionManager.connectionState
                .distinctUntilChanged()
                .collect { state ->
                    Log.d(TAG, "Observed connection state change: $state")
                    // Perform UI updates or other logic based on state
                }
        }
    }

    override fun onDestroy() {
        super.onDestroy()
        bleConnectionManager.close() // Ensure all resources are released when the Activity is destroyed
    }
}

Best Practices for Robust BLE Connections

Always Call BluetoothGatt.close():
- The Fix: Ensure gatt.close() is called in every scenario where a BluetoothGatt instance is no longer needed. This includes:
  - Upon BluetoothProfile.STATE_DISCONNECTED in onConnectionStateChange (after an explicit disconnect() or an unexpected disconnection).
  - When an initial connection attempt fails (e.g., status != BluetoothGatt.GATT_SUCCESS in onConnectionStateChange for STATE_CONNECTED).
  - On critical errors during service discovery or characteristic operations.
  - When the Android component (Activity, Fragment, Service) that owns the connection is destroyed (onDestroy).
  - Before initiating a new connection if an existing BluetoothGatt object is still referenced.
- Why: Failing to call close() leaves native resources allocated, leading to memory leaks and preventing future clean connections. The system might also be unable to reuse the Bluetooth hardware until a timeout occurs or the app process is killed.
Clear BluetoothGatt References After close():
- The Fix: Immediately after calling bluetoothGatt.close(), set your internal reference to bluetoothGatt = null.
- Why: This prevents accidental reuse of an invalid BluetoothGatt object, which would likely lead to IllegalStateException crashes. It also allows the Java garbage collector to reclaim the memory associated with the BluetoothGatt instance, further preventing leaks. Our BleConnectionManager.cleanUpGatt() method does exactly this.
Validate BluetoothGatt Instance in Callbacks:
- The Fix: In every BluetoothGattCallback method (e.g., onConnectionStateChange, onServicesDiscovered), check if the gatt object passed to the callback is the same instance you're currently managing. If it's not (e.g., gatt != bluetoothGatt or gatt.device.address != targetDeviceAddress), it's a stale or unexpected callback. Log it and, if it's a rogue instance, consider calling gatt.close() on that specific gatt object to release its resources.
- Why: Race conditions, previous failed connection attempts, or even Android system quirks can sometimes lead to callbacks being delivered for BluetoothGatt instances you thought were already closed or are no longer managing. Ignoring these can cause your state machine to become inconsistent.
Carefully Consider autoConnect in connectGatt():
- The Fix: For user-initiated, active connections, use autoConnect = false. For background, persistent, less-critical reconnections (e.g., a background service monitoring a sensor), autoConnect = true might be appropriate, but be aware of its implications.
- Why: When autoConnect is true, the system might take a long time to connect or reconnect, and explicit disconnect() calls may not immediately prevent reconnection attempts. This can make connection state management more complex and less predictable.
Adhere to Main Thread for BluetoothGatt Operations:
- The Fix: Ensure all BluetoothGatt methods (e.g., connectGatt(), discoverServices(), readCharacteristic(), writeCharacteristic()) are invoked on the main thread or a dedicated handler thread. Also, when BluetoothGattCallback methods are delivered (which often happens on a binder thread), if you need to perform subsequent BluetoothGatt operations or UI updates, switch back to the main thread using Handler(Looper.getMainLooper()).post { ... }.
- Why: Incorrect thread usage is a very common source of IllegalStateException and other hard-to-debug crashes in BLE operations. The Android Bluetooth stack often has thread affinity requirements.

Conclusion

Mastering the BluetoothGatt lifecycle is not merely about making your BLE app work; it's about making it resilient, leak-free, and predictable. The critical distinction between disconnect() for graceful communication termination and close() for vital resource deallocation is paramount. By consistently invoking close() for every BluetoothGatt instance, clearing your references, validating instances in callbacks, and adhering to threading best practices, you equip your application with the robustness required for production-grade IoT solutions. Take the time to review your existing BLE code and ensure these practices are rigorously applied. Your future self (and your users) will thank you.

Mastering Disconnection Handling in Android BLE: Robust Strategies for Reconnection and Error Recovery

Ble Advertiser — Sun, 05 Apr 2026 10:27:22 +0000

Ever built an Android BLE app that connects beautifully, only to silently die when the device moves out of range, the peripheral powers off, or the OS decides to kill your process? You’re not alone. The asynchronous, unreliable nature of Bluetooth Low Energy (BLE) on mobile makes connection stability and robust error recovery a constant battle. Failing to properly handle disconnections leads to unresponsive UIs, frustrated users, and a constant stream of bug reports.

This article dives deep into the art of mastering BLE disconnections. You will learn how to detect various disconnection types, implement intelligent reconnection strategies, manage GATT resources effectively, and gracefully recover from common BLE errors. By the end, you’ll have a clear roadmap to building production-ready BLE applications that stand up to the real world.

Core Concepts: Understanding Disconnections

Before you can fix disconnections, you need to understand why they happen and how Android communicates them. BLE connections are inherently fragile. Several factors can cause a peripheral to disconnect from your Android device:

Peripheral Initiated: The BLE peripheral itself decides to terminate the connection (e.g., powers off, goes out of range, explicit disconnect command).
Android Device Initiated: Your app or the Android OS explicitly disconnects (e.g., calling disconnect(), app process killed).
Environmental Factors: Interference, physical obstructions, or exceeding the maximum connection interval can lead to dropped packets and eventual connection termination.
BLE Stack Issues: Bugs or transient issues within the Android Bluetooth stack can sometimes cause unexpected disconnections or failures to reconnect.

The primary mechanism for receiving connection state updates is through the BluetoothGattCallback's onConnectionStateChange method. This callback provides two critical pieces of information:

newState: Indicates the new connection state (e.g., BluetoothProfile.STATE_CONNECTED, BluetoothProfile.STATE_DISCONNECTED).
status: An integer code indicating the GATT status of the operation that caused the state change. This is the most crucial piece of information for robust error handling.

Understanding `onConnectionStateChange` Status Codes

The status parameter is often overlooked, but it tells you why the connection changed. Here are some common status codes you'll encounter and their general implications:

Status Code	Constant/Meaning	Implication for Disconnection	Recovery Strategy
`0`	`GATT_SUCCESS`	Expected disconnection	Clean up, optionally prepare for immediate reconnection (e.g., user initiated)
`1`	`GATT_INVALID_HANDLE`	Internal stack error	Try reconnecting after a delay, potentially device reboot or app reinstall
`8`	`GATT_INSUF_AUTHORIZATION`	Permission issue	Ensure bonding/permissions are correct, inform user, don't auto-reconnect
`19`	`GATT_CONN_TERMINATE_LOCAL_HOST`	Android device disconnected	User initiated disconnect, or app logic; handle as expected
`133`	`GATT_ERROR` / `GATT_CONN_TERMINATE_PEER_USER`	Generic/Peer Disconnected	Peripheral disconnected unexpectedly; always attempt reconnection
`257`	`GATT_FAILURE` (rare)	Internal stack error	Similar to `1`, very low-level issue; aggressive retry with backoff

Key takeaway: Always inspect the status code. A status of 0 or 19 might indicate an expected, clean disconnection, while 133 almost always warrants an immediate reconnection attempt.

GATT Resources and Cleanup

Each successful connectGatt() call creates a BluetoothGatt object. This object holds valuable system resources. Failing to close it properly can lead to:

Resource Leaks: Preventing other apps or your own app from connecting to BLE devices.
Stale Caches: The Android BLE stack caches service discovery results. A dirty cache can prevent proper service discovery after reconnection.
Callback Issues: Callbacks might continue to be delivered to old, closed GATT objects.

Therefore, proper cleanup using BluetoothGatt.close() is crucial whenever a connection is permanently lost or explicitly terminated.

Implementation: Building a Robust Reconnection Strategy

A robust reconnection strategy involves several components:

State Management: Explicitly tracking the connection state to avoid race conditions and illogical operations.
Disconnection Detection: Listening for STATE_DISCONNECTED in onConnectionStateChange and interpreting status codes.
Intelligent Retries: Implementing a retry mechanism with exponential backoff and a maximum attempt limit.
GATT Cleanup: Ensuring BluetoothGatt resources are released correctly.

1. Permissions and API Requirements

Android 12 (API 31) and higher:
- BLUETOOTH_SCAN: For scanning for BLE devices.
- BLUETOOTH_CONNECT: For connecting to BLE devices.
Android 11 (API 30) and lower:
- ACCESS_FINE_LOCATION: Required for BLE scanning.
- BLUETOOTH, BLUETOOTH_ADMIN: Basic Bluetooth permissions.

Always request these permissions at runtime.

2. State Management with an `enum class`

Maintain a clear connection state to prevent multiple connection attempts or invalid operations.

enum class ConnectionState {
    DISCONNECTED,
    CONNECTING,
    CONNECTED,
    DISCONNECTING,
    RECONNECTING,
    ERROR // For unrecoverable states
}

3. Disconnection Detection and Reconnection Logic

When onConnectionStateChange reports STATE_DISCONNECTED, your app must react. The core idea is to schedule a reconnection attempt if the disconnection was unexpected, respecting a retry limit and backoff delay.

import android.bluetooth.BluetoothGatt
import android.bluetooth.BluetoothGattCallback
import android.bluetooth.BluetoothProfile
import android.os.Handler
import android.os.Looper
import android.util.Log
import java.util.UUID

// Assume you have a mechanism to get a BluetoothDevice from its address
// This is a simplified example focusing on the reconnection logic.

class BleConnectionManager(
    private val deviceAddress: String,
    private val onConnectionStateChanged: (ConnectionState) -> Unit,
    private val onDataReceived: (UUID, ByteArray) -> Unit // Example for data callback
) {

    private val TAG = "BleConnectionManager"
    private var bluetoothGatt: BluetoothGatt? = null
    private var connectionState: ConnectionState = ConnectionState.DISCONNECTED
    private val handler = Handler(Looper.getMainLooper())

    // Reconnection parameters
    private var reconnectAttempts = 0
    private val MAX_RECONNECT_ATTEMPTS = 5
    private val INITIAL_RECONNECT_DELAY_MS = 1000L // 1 second
    private val MAX_RECONNECT_DELAY_MS = 16000L // 16 seconds

    // Set this when a user explicitly initiates a disconnect
    var isManualDisconnect = false

    private val gattCallback = object : BluetoothGattCallback() {
        override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
            super.onConnectionStateChange(gatt, status, newState)
            Log.d(TAG, "onConnectionStateChange: status=$status, newState=$newState")

            if (newState == BluetoothProfile.STATE_CONNECTED) {
                // Connection successful
                Log.i(TAG, "Connected to GATT server.")
                connectionState = ConnectionState.CONNECTED
                onConnectionStateChanged(ConnectionState.CONNECTED)
                reconnectAttempts = 0 // Reset attempts on successful connection

                // Discover services immediately after connection
                gatt.discoverServices()
            } else if (newState == BluetoothProfile.STATE_DISCONNECTED) {
                Log.w(TAG, "Disconnected from GATT server. Status: $status")
                connectionState = ConnectionState.DISCONNECTED
                onConnectionStateChanged(ConnectionState.DISCONNECTED)

                // Crucial: Close GATT resources immediately
                closeGatt()

                if (!isManualDisconnect) {
                    // This was an unexpected disconnection, attempt to reconnect
                    handleUnexpectedDisconnection(status)
                } else {
                    Log.i(TAG, "Manual disconnect acknowledged. No reconnection.")
                    isManualDisconnect = false // Reset for next connection
                    // Optionally, inform UI that disconnect is complete
                }
            }
        }

        override fun onServicesDiscovered(gatt: BluetoothGatt?, status: Int) {
            super.onServicesDiscovered(gatt, status)
            if (status == BluetoothGatt.GATT_SUCCESS) {
                Log.i(TAG, "Services discovered for ${deviceAddress}")
                // Proceed with characteristic operations here
                // e.g., enable notifications, read/write characteristics
            } else {
                Log.e(TAG, "Service discovery failed with status: $status")
                // Handle service discovery failure - maybe disconnect and retry?
                disconnect()
            }
        }

        // ... other GATT callbacks (onCharacteristicRead, onCharacteristicWrite, onCharacteristicChanged)
        // For simplicity, omitted here, but would forward data to onDataReceived
    }

    // Connect to the BLE device
    fun connect(bluetoothDevice: android.bluetooth.BluetoothDevice) {
        if (connectionState == ConnectionState.CONNECTING || connectionState == ConnectionState.CONNECTED) {
            Log.w(TAG, "Already connecting or connected to $deviceAddress.")
            return
        }

        Log.d(TAG, "Attempting to connect to device: $deviceAddress")
        connectionState = ConnectionState.CONNECTING
        onConnectionStateChanged(ConnectionState.CONNECTING)

        // Important: autoConnect = false for active, foreground connections.
        // autoConnect = true is for background connections where the OS attempts to reconnect
        // when the peripheral is nearby again, which can take time and is not immediate.
        bluetoothGatt = bluetoothDevice.connectGatt(
            /* context = */ context, // You need to pass a valid Context here
            /* autoConnect = */ false,
            /* callback = */ gattCallback,
            /* transport = */ android.bluetooth.BluetoothDevice.TRANSPORT_LE
        )
    }

    // Disconnect from the BLE device manually
    fun disconnect() {
        Log.d(TAG, "Explicitly disconnecting from $deviceAddress.")
        isManualDisconnect = true
        if (bluetoothGatt != null) {
            if (connectionState == ConnectionState.CONNECTED || connectionState == ConnectionState.CONNECTING) {
                connectionState = ConnectionState.DISCONNECTING
                onConnectionStateChanged(ConnectionState.DISCONNECTING)
                bluetoothGatt?.disconnect()
            } else {
                // If not connected, just clean up.
                closeGatt()
            }
        } else {
            Log.w(TAG, "BluetoothGatt is null, cannot disconnect.")
            connectionState = ConnectionState.DISCONNECTED
            onConnectionStateChanged(ConnectionState.DISCONNECTED)
        }
        // Cancel any pending reconnection attempts
        handler.removeCallbacksAndMessages(null)
        reconnectAttempts = 0
    }

    // Clean up GATT resources
    private fun closeGatt() {
        bluetoothGatt?.close()
        bluetoothGatt = null
        Log.d(TAG, "BluetoothGatt resources closed for $deviceAddress.")
    }

    // Handle unexpected disconnections by scheduling retries
    private fun handleUnexpectedDisconnection(status: Int) {
        if (reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {
            reconnectAttempts++
            val delay = (INITIAL_RECONNECT_DELAY_MS * Math.pow(2.0, (reconnectAttempts - 1).toDouble())).toLong()
                .coerceAtMost(MAX_RECONNECT_DELAY_MS) // Exponential backoff with max delay

            Log.i(TAG, "Attempting reconnection $reconnectAttempts/$MAX_RECONNECT_ATTEMPTS in ${delay}ms...")
            connectionState = ConnectionState.RECONNECTING
            onConnectionStateChanged(ConnectionState.RECONNECTING)

            handler.postDelayed({
                // Re-obtain the BluetoothDevice object. Important if using device address
                // to ensure the system gets a fresh handle, though in this example it's
                // passed into connect()
                val bluetoothManager = context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
                val adapter = bluetoothManager.adapter
                val device = adapter.getRemoteDevice(deviceAddress)
                connect(device) // Attempt to reconnect
            }, delay)
        } else {
            Log.e(TAG, "Max reconnection attempts reached for $deviceAddress. Giving up.")
            connectionState = ConnectionState.ERROR // Unrecoverable state
            onConnectionStateChanged(ConnectionState.ERROR)
            // Inform the user that the device is unreachable
        }
    }
}

Explanation:

The BleConnectionManager encapsulates the connection logic, keeping track of its own state.
isManualDisconnect is a simple flag to differentiate between user-initiated and unexpected disconnections.
onConnectionStateChange:
- If newState is STATE_CONNECTED, reset reconnectAttempts and trigger service discovery.
- If newState is STATE_DISCONNECTED, call closeGatt() to free resources. Then, if isManualDisconnect is false, it triggers handleUnexpectedDisconnection.
handleUnexpectedDisconnection: Implements exponential backoff for retries. It schedules connect() calls with increasing delays up to MAX_RECONNECT_ATTEMPTS.
connect(): Uses autoConnect = false for explicit, immediate connection attempts. For context, you would pass applicationContext or a valid Activity context.
disconnect(): Sets isManualDisconnect to true, then calls gatt.disconnect(). Crucially, it also calls removeCallbacksAndMessages(null) on the handler to cancel any pending reconnection attempts.
closeGatt(): Ensures BluetoothGatt.close() is called and the reference is nulled out.

Best Practices for Robust Disconnection Handling

Here are concrete pitfalls and their solutions to further solidify your BLE connection management:

1. Pitfall: Ignoring `status` Codes in `onConnectionStateChange`

Many developers only check newState and miss the critical information conveyed by the status code. Treating all STATE_DISCONNECTED events identically is a mistake. A status=0 (success) means a clean disconnect, while status=133 (generic error, peer disconnect) implies an unexpected termination.

Fix: Always log and parse the status code. Use a when statement or a lookup table to map common status codes to appropriate recovery actions. For instance, status=8 (GATT_INSUF_AUTHORIZATION) might mean you need to prompt the user to bond with the device or grant location permissions, rather than blindly retrying the connection.

// Inside onConnectionStateChange where newState is BluetoothProfile.STATE_DISCONNECTED
when (status) {
    BluetoothGatt.GATT_SUCCESS, 19 /* GATT_CONN_TERMINATE_LOCAL_HOST */ -> {
        Log.i(TAG, "Clean disconnection or local host initiated. No auto-reconnect needed if manual.")
        if (!isManualDisconnect) { /* Potentially a peripheral-initiated clean disconnect, consider reconnect */ }
    }
    133 /* GATT_ERROR / GATT_CONN_TERMINATE_PEER_USER */ -> {
        Log.e(TAG, "Unexpected disconnection: Peer user terminated or generic error. Initiating reconnection.")
        handleUnexpectedDisconnection(status)
    }
    8 /* GATT_INSUF_AUTHORIZATION */ -> {
        Log.e(TAG, "Insufficient authorization. Check bonding/permissions. Do not auto-reconnect.")
        onConnectionStateChanged(ConnectionState.ERROR) // Indicate unrecoverable state
    }
    else -> {
        Log.e(TAG, "Unhandled disconnection status $status. Assuming unexpected. Initiating reconnection.")
        handleUnexpectedDisconnection(status)
    }
}

2. Pitfall: Not Closing `BluetoothGatt` Properly

Failing to call bluetoothGatt.close() when a connection is permanently lost, explicitly disconnected, or when the app is shut down leads to resource leaks and can prevent future connections. The underlying Android BLE stack holds onto these resources, leading to GATT_ERROR (status 133) on subsequent connection attempts.

Fix: Ensure bluetoothGatt.close() is called within your onConnectionStateChange callback when newState is STATE_DISCONNECTED. Also, call it when the user explicitly disconnects, or if your app is going to background and you decide to terminate the connection. Nullify the bluetoothGatt reference afterwards to prevent use of a closed object.

3. Pitfall: Misunderstanding `autoConnect = true`

Many developers use autoConnect = true expecting immediate reconnection. However, autoConnect = true is designed for background reconnection. It instructs the Android system to passively scan for the peripheral and reconnect when it's found without waking up your app immediately. This is energy-efficient but not suitable for active foreground reconnection attempts that require speed.

Fix: For active, immediate reconnection attempts (e.g., after an unexpected disconnection while your app is in the foreground), set autoConnect = false. Implement your own retry mechanism with exponential backoff and a maximum attempt limit as shown in the example code. Reserve autoConnect = true for scenarios where your app is in the background and you want the OS to handle intermittent reconnections without constant active scanning.

4. Pitfall: Lack of Comprehensive State Management

Without a clear state machine, your BLE logic can quickly become a tangled mess. What happens if disconnect() is called while connect() is still in progress? Or if two reconnection attempts overlap? Race conditions and undefined behavior are guaranteed.

Fix: Implement a robust state machine using an enum class as demonstrated. All connection-related operations (connect(), disconnect(), onConnectionStateChange) should reference and update this state. Before initiating any connection or disconnection, check the current state to ensure the operation is valid. For example, do not call connect() if ConnectionState.CONNECTING or ConnectionState.CONNECTED is already set.

5. Pitfall: Not Implementing Exponential Backoff for Retries

Continuously hammering connectGatt() every second after a disconnection will drain battery, overwhelm the BLE stack, and likely fail repeatedly. It's an inefficient and ineffective strategy.

Fix: Implement exponential backoff for your retry delays. Start with a short delay (e.g., 1 second) and double it for each subsequent attempt (2s, 4s, 8s, 16s, etc.) up to a sensible maximum delay and a finite number of attempts (e.g., 5-10 attempts). This gives the peripheral and the Android BLE stack time to recover, conserves battery, and prevents your app from getting stuck in an infinite retry loop. The handleUnexpectedDisconnection method demonstrates this.

Conclusion

Building robust BLE applications on Android demands careful consideration of disconnection handling. You've learned the critical importance of interpreting onConnectionStateChange status codes, the necessity of proper GATT resource cleanup, and the nuances of autoConnect. By implementing a well-defined state machine and an intelligent, exponential backoff retry mechanism, you can transform your fragile BLE connections into resilient, production-ready experiences.

Take this knowledge and review your existing BLE code. Identify areas where you can implement these strategies to make your applications more stable, user-friendly, and maintainable. Your users (and your bug tracker) will thank you.

Mastering Android 12+ BLE Permissions in Kotlin: The `BLUETOOTH_SCAN`/`CONNECT` Dance and Common Gotchas

Ble Advertiser — Sun, 05 Apr 2026 10:23:26 +0000

Have you ever deployed a perfectly functional BLE application, only for users on newer Android versions (especially Android 12/API 31+) to report that your app suddenly "lost" its ability to scan or connect, even though you meticulously requested ACCESS_FINE_LOCATION? If so, you've encountered the Android 12+ BLE permission paradigm shift, a necessary evolution that often leaves developers scrambling. This article cuts through the noise, providing a direct, no-fluff guide to navigating the new BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions in Kotlin, ensuring your BLE applications function reliably on modern Android devices.

Core Concepts: The Shift to Granular BLE Permissions

Prior to Android 12 (API level 31), the ACCESS_FINE_LOCATION permission was a ubiquitous, if often misunderstood, requirement for nearly all BLE operations. This was primarily due to the potential for BLE scans to infer a user's location. While this blanket approach simplified things in some ways, it also forced users to grant a highly sensitive location permission even when an app's BLE functionality had no actual need for location data.

Android 12 addressed this by introducing a set of new, more granular Bluetooth permissions, decoupling BLE functionality from location access. These permissions are:

BLUETOOTH_SCAN: Required for your app to find nearby Bluetooth devices. This replaces the need for ACCESS_FINE_LOCATION for most BLE scanning scenarios.
BLUETOOTH_CONNECT: Required for your app to connect to already paired Bluetooth devices or initiate new connections.
BLUETOOTH_ADVERTISE: Required for your app to make itself discoverable to other Bluetooth devices and broadcast advertisements.

These new permissions are runtime permissions, meaning you must declare them in your AndroidManifest.xml and then explicitly request them from the user at runtime, just like ACCESS_FINE_LOCATION.

Why the Change?

The primary motivations behind this shift are user privacy and control:

Granular Control: Users can now grant specific Bluetooth capabilities (scan, connect, advertise) without exposing their precise location.
Improved Transparency: It's clearer to users exactly what permissions an app needs for Bluetooth operations.
Reduced Friction: For apps that truly don't need location for BLE, users are less likely to deny permissions.

Permission Mapping and Dependencies

It's critical to understand that these new permissions only apply when your app targets Android 12 (API 31) or higher (targetSdk >= 31). If your targetSdk is 30 or lower, the system still uses ACCESS_FINE_LOCATION for BLE scanning, even on an Android 12+ device. This is a common point of confusion and a significant gotcha.

Here's a simplified mapping of old vs. new permissions and their purpose:

Operation	Android 11 (API 30) & below (if `targetSdk <= 30`)	Android 12 (API 31) & above (if `targetSdk >= 31`)	Notes
BLE Scanning	`ACCESS_FINE_LOCATION`	`BLUETOOTH_SCAN`	`ACCESS_FINE_LOCATION` might still be needed if your app requires location for other features or if specific BLE scan results require location information (e.g., `ScanFilter` for device name filtering in some specific OS versions/device manufacturers). Also, turning on location services may still be required on some devices to enable BLE scanning, even with `BLUETOOTH_SCAN` granted.
BLE Connecting	`BLUETOOTH`	`BLUETOOTH_CONNECT`	`BLUETOOTH` is a normal permission, automatically granted. `BLUETOOTH_CONNECT` is runtime.
BLE Advertising	`BLUETOOTH`	`BLUETOOTH_ADVERTISE`	`BLUETOOTH_ADVERTISE` is runtime.
Managing Paired Devices	`BLUETOOTH`	`BLUETOOTH_CONNECT`

Important Nuance: Even with BLUETOOTH_SCAN granted and targetSdk >= 31, a user might still need to have location services enabled on their device for BLE scanning to function correctly. This is a device-level setting, not an app-level permission, and its necessity can vary by Android OEM implementation. Always prompt the user to enable location services if scanning fails, even if BLUETOOTH_SCAN is granted.

Implementation: The Step-by-Step Walkthrough

Let's dive into integrating these new permissions into your Kotlin BLE application.

Prerequisites

Android Studio Arctic Fox (or newer)
Kotlin 1.5.0 (or newer)

targetSdk set to 31 or higher in your build.gradle (module-level). This is critical.

android {
    compileSdk 33 // Or higher
    defaultConfig {
        minSdk 21
        targetSdk 33 // This is the key
        // ...
    }
}

1. Manifest Declarations

You need to declare the new Bluetooth permissions in your AndroidManifest.xml. To maintain backward compatibility with devices running Android 11 (API 30) or lower, and to conditionally request ACCESS_FINE_LOCATION only when needed for older OS versions, you'll typically declare both the old and new permissions.

Crucially, for BLUETOOTH_SCAN, you'll use the android:usesPermissionFlags attribute with neverForLocation. This flag explicitly tells the system that your app does not use the permission for location features, which is key to avoiding location permission requests on Android 12+.

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <!-- Permissions for Android 11 (API 30) and below -->
    <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" android:maxSdkVersion="30" />

    <!-- Permissions for Android 12 (API 31) and above -->
    <!-- BLUETOOTH_SCAN: Needed to discover devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
        android:usesPermissionFlags="neverForLocation"
        tools:targetApi="31" />

    <!-- BLUETOOTH_CONNECT: Needed to connect to devices. -->
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" tools:targetApi="31" />

    <!-- BLUETOOTH_ADVERTISE: Needed to advertise as a peripheral. -->
    <uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" tools:targetApi="31" />

    <!-- Optionally, if your app truly *needs* location for other features or older Android versions -->
    <!-- If your minSdk < 31, ACCESS_FINE_LOCATION is still relevant for BLE scanning on older OS versions. -->
    <!-- If your app specifically needs to derive location from BLE scans (e.g., for indoor positioning) -->
    <!-- then you might still need ACCESS_FINE_LOCATION even on API 31+ for those specific scenarios, -->
    <!-- but for standard BLE proximity scans, neverForLocation covers it. -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <!-- If you target API 31+, and *only* need coarse location (e.g., for location-based services that don't need fine accuracy) -->
    <!-- <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" /> -->

    <application
        <!-- ... your application settings ... -->
    </application>
</manifest>

Explanation of Manifest Declarations:

android:maxSdkVersion="30": This attribute limits the BLUETOOTH, BLUETOOTH_ADMIN, and ACCESS_FINE_LOCATION permissions to devices running API level 30 or lower. When your app runs on API 31+, these permissions are ignored by the system, preventing conflicts.
tools:targetApi="31": This attribute is a lint directive that tells Android Studio that this permission is only relevant for API 31 and above. It helps prevent lint warnings about unused permissions on older Android versions and improves readability.
android:usesPermissionFlags="neverForLocation": This is the most crucial flag for BLUETOOTH_SCAN. It explicitly tells Android that your app does not intend to use the Bluetooth scan results to derive the user's physical location. If you omit this, even on Android 12+, the system might still require ACCESS_FINE_LOCATION for scanning.

2. Runtime Permission Request

Now that the permissions are declared, you need to request them at runtime. You should check the Android version and request the appropriate permissions.

Helper function for permission checks:

import android.Manifest
import android.content.Context
import android.content.pm.PackageManager
import android.os.Build
import androidx.core.content.ContextCompat

object BluetoothPermissions {

    // Permissions required for BLE scanning on Android 12+
    val bluetoothScanPermissions = arrayOf(
        Manifest.permission.BLUETOOTH_SCAN
    )

    // Permissions required for BLE connecting on Android 12+
    val bluetoothConnectPermissions = arrayOf(
        Manifest.permission.BLUETOOTH_CONNECT
    )

    // Permissions required for BLE advertising on Android 12+
    val bluetoothAdvertisePermissions = arrayOf(
        Manifest.permission.BLUETOOTH_ADVERTISE
    )

    // Permissions required for BLE scanning on Android 11 and below
    val bluetoothLegacyScanPermissions = arrayOf(
        Manifest.permission.ACCESS_FINE_LOCATION
    )

    /**
     * Checks if the required BLE scanning permissions are granted.
     * On Android 12+, this means BLUETOOTH_SCAN.
     * On Android 11 and below, this means ACCESS_FINE_LOCATION.
     *
     * @param context The application context.
     * @return True if all necessary scanning permissions are granted, false otherwise.
     */
    fun hasScanPermissions(context: Context): Boolean {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { // Android 12 (API 31)
            bluetoothScanPermissions.all { permission ->
                ContextCompat.checkSelfPermission(context, permission) == PackageManager.PERMISSION_GRANTED
            }
        } else { // Android 11 and below
            bluetoothLegacyScanPermissions.all { permission ->
                ContextCompat.checkSelfPermission(context, permission) == PackageManager.PERMISSION_GRANTED
            }
        }
    }

    /**
     * Checks if the required BLE connection permissions are granted.
     * On Android 12+, this means BLUETOOTH_CONNECT.
     * On Android 11 and below, BLUETOOTH (normal permission) is usually sufficient.
     *
     * @param context The application context.
     * @return True if all necessary connection permissions are granted, false otherwise.
     */
    fun hasConnectPermissions(context: Context): Boolean {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { // Android 12 (API 31)
            bluetoothConnectPermissions.all { permission ->
                ContextCompat.checkSelfPermission(context, permission) == PackageManager.PERMISSION_GRANTED
            }
        } else { // Android 11 and below
            // On older versions, BLUETOOTH is a normal permission and granted automatically.
            // No runtime request needed for connection.
            true
        }
    }

    /**
     * Checks if the required BLE advertising permissions are granted.
     * On Android 12+, this means BLUETOOTH_ADVERTISE.
     * On Android 11 and below, BLUETOOTH (normal permission) is usually sufficient.
     *
     * @param context The application context.
     * @return True if all necessary advertising permissions are granted, false otherwise.
     */
    fun hasAdvertisePermissions(context: Context): Boolean {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) { // Android 12 (API 31)
            bluetoothAdvertisePermissions.all { permission ->
                ContextCompat.checkSelfPermission(context, permission) == PackageManager.PERMISSION_GRANTED
            }
        } else { // Android 11 and below
            // On older versions, BLUETOOTH is a normal permission and granted automatically.
            // No runtime request needed for advertising.
            true
        }
    }

    /**
     * Determines the set of permissions required for BLE scanning based on the current Android version.
     *
     * @return An array of string permissions.
     */
    fun getScanPermissions(): Array<String> {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            bluetoothScanPermissions
        } else {
            bluetoothLegacyScanPermissions
        }
    }

    /**
     * Determines the set of permissions required for BLE connection based on the current Android version.
     *
     * @return An array of string permissions.
     */
    fun getConnectPermissions(): Array<String> {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            bluetoothConnectPermissions
        } else {
            // No runtime permission needed for connect on older Android versions beyond
            // the BLUETOOTH normal permission which is auto-granted.
            // Returning an empty array or a dummy is fine here if you only check for runtime permissions.
            emptyArray()
        }
    }

    /**
     * Determines the set of permissions required for BLE advertising based on the current Android version.
     *
     * @return An array of string permissions.
     */
    fun getAdvertisePermissions(): Array<String> {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            bluetoothAdvertisePermissions
        } else {
            // No runtime permission needed for advertising on older Android versions beyond
            // the BLUETOOTH normal permission which is auto-granted.
            emptyArray()
        }
    }
}

Now, integrate this into your Activity or Fragment:

import android.bluetooth.BluetoothAdapter
import android.bluetooth.BluetoothManager
import android.content.Intent
import android.content.pm.PackageManager
import android.os.Build
import android.os.Bundle
import android.provider.Settings
import android.util.Log
import android.widget.Button
import android.widget.Toast
import androidx.activity.result.contract.ActivityResultContracts
import androidx.appcompat.app.AlertDialog
import androidx.appcompat.app.AppCompatActivity

class BleScannerActivity : AppCompatActivity() {

    private val TAG = "BleScannerActivity"
    private val REQUEST_ENABLE_BT = 1

    private val bluetoothAdapter: BluetoothAdapter? by lazy(LazyThreadSafetyMode.NONE) {
        val bluetoothManager = getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
        bluetoothManager.adapter
    }

    // Register for permission results using the new Activity Result API
    private val requestPermissionLauncher =
        registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions()) { permissionsGranted ->
            if (permissionsGranted.all { it.value }) {
                Log.d(TAG, "All required BLE permissions granted.")
                // Permissions granted, proceed with BLE operations (e.g., start scan)
                startBleOperations()
            } else {
                Log.w(TAG, "Not all required BLE permissions were granted.")
                Toast.makeText(this, "BLE permissions are required to scan for devices.", Toast.LENGTH_LONG).show()
                // Handle denied permissions, perhaps disable BLE features or show a persistent rationale
            }
        }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        findViewById<Button>(R.id.start_scan_button).setOnClickListener {
            checkPermissionsAndStartScan()
        }
    }

    private fun checkPermissionsAndStartScan() {
        if (!isBluetoothEnabled()) {
            promptEnableBluetooth()
            return
        }

        // Determine which permissions are needed based on OS version
        val requiredPermissions = BluetoothPermissions.getScanPermissions()
            .filter { permission -> // Filter out permissions already granted
                ContextCompat.checkSelfPermission(this, permission) != PackageManager.PERMISSION_GRANTED
            }.toTypedArray()

        if (requiredPermissions.isNotEmpty()) {
            // Request permissions if not all are granted
            Log.d(TAG, "Requesting BLE permissions: ${requiredPermissions.joinToString()}")
            requestPermissionLauncher.launch(requiredPermissions)
        } else {
            // All necessary permissions are already granted, proceed
            Log.d(TAG, "All necessary BLE permissions already granted. Starting BLE operations.")
            startBleOperations()
        }
    }

    private fun startBleOperations() {
        // Double-check for location services enablement, especially on older Android versions or some OEMs.
        // Even with BLUETOOTH_SCAN, location services might need to be ON.
        if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S && !isLocationEnabled(this)) {
            promptEnableLocationServices()
            return
        }

        // Your BLE scanning logic goes here
        Log.i(TAG, "Starting BLE scan...")
        Toast.makeText(this, "Starting BLE scan...", Toast.LENGTH_SHORT).show()
        // Example: bluetoothAdapter?.bluetoothLeScanner?.startScan(yourScanCallback)
    }

    private fun isBluetoothEnabled(): Boolean {
        return bluetoothAdapter?.isEnabled == true
    }

    private fun promptEnableBluetooth() {
        if (bluetoothAdapter?.isEnabled == false) {
            val enableBtIntent = Intent(BluetoothAdapter.ACTION_REQUEST_ENABLE)
            startActivityForResult(enableBtIntent, REQUEST_ENABLE_BT) // Use old API for simplicity, or Activity Result API for modern approach
        }
    }

    private fun isLocationEnabled(context: Context): Boolean {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
            // On Android 9 (API 28) and above, use LocationManager
            val locationManager = context.getSystemService(Context.LOCATION_SERVICE) as LocationManager
            locationManager.isLocationEnabled
        } else {
            // On older versions, check modes (HIGH_ACCURACY, BATTERY_SAVING, DEVICE_ONLY)
            val mode = Settings.Secure.getInt(context.contentResolver, Settings.Secure.LOCATION_MODE, Settings.Secure.LOCATION_MODE_OFF)
            mode != Settings.Secure.LOCATION_MODE_OFF
        }
    }

    private fun promptEnableLocationServices() {
        AlertDialog.Builder(this)
            .setTitle("Location Services Required")
            .setMessage("For BLE scanning on this device, please enable Location Services.")
            .setPositiveButton("Enable") { _, _ ->
                val intent = Intent(Settings.ACTION_LOCATION_SOURCE_SETTINGS)
                startActivity(intent)
            }
            .setNegativeButton("Cancel") { dialog, _ ->
                dialog.dismiss()
                Toast.makeText(this, "BLE scanning disabled without Location Services.", Toast.LENGTH_LONG).show()
            }
            .show()
    }

    // You would override onActivityResult if using startActivityForResult,
    // or integrate into the Activity Result API for enabling Bluetooth.
    override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
        super.onActivityResult(requestCode, resultCode, data)
        if (requestCode == REQUEST_ENABLE_BT) {
            if (resultCode == RESULT_OK) {
                Log.d(TAG, "Bluetooth enabled by user.")
                checkPermissionsAndStartScan() // Retry permission check and start scan
            } else {
                Log.w(TAG, "User denied enabling Bluetooth.")
                Toast.makeText(this, "Bluetooth must be enabled to use BLE features.", Toast.LENGTH_LONG).show()
            }
        }
    }
}

This comprehensive example demonstrates:

Conditional Permission Checks: Uses Build.VERSION.SDK_INT to determine which set of permissions to check and request.
Activity Result API: Modern way to handle permission requests with registerForActivityResult.
Rationale: Implicitly, if a permission is denied, a Toast is shown. For a production app, you'd show a more detailed rationale via shouldShowRequestPermissionRationale() before requesting again.
Bluetooth and Location Service Checks: Essential checks for basic Bluetooth adapter state and device-level location services.

Best Practices & Common Gotchas

Navigating Android permissions, especially with BLE, comes with its share of tricky situations. Here are some best practices and common pitfalls to avoid:

Over-requesting Permissions:
- Pitfall: Declaring and requesting BLUETOOTH_SCAN, BLUETOOTH_CONNECT, and BLUETOOTH_ADVERTISE when your app only performs, say, scanning. This exposes your app to unnecessary scrutiny from users and increases the chances of denial.
- Fix: Only declare and request the specific Bluetooth permissions your app absolutely needs for its current operation. If your app only scans for devices, only request BLUETOOTH_SCAN. If it later needs to connect, request BLUETOOTH_CONNECT at that point, perhaps after a successful scan. This aligns with the principle of least privilege. Use the BluetoothPermissions helper to precisely determine the required permissions.
Forgetting neverForLocation:
- Pitfall: Declaring BLUETOOTH_SCAN in your AndroidManifest.xml without the android:usesPermissionFlags="neverForLocation" attribute. Even with targetSdk >= 31, the system might still interpret your BLE scanning as a potential source of location information and demand ACCESS_FINE_LOCATION at runtime.
- Fix: Always include android:usesPermissionFlags="neverForLocation" for BLUETOOTH_SCAN if your app does not derive location from BLE scans. This is the cornerstone of decoupling BLE from location on Android 12+.
Ignoring targetSdk:
- Pitfall: Keeping your targetSdk below 31. If your targetSdk is 30 or lower, even if your app runs on Android 12+, the system will not use BLUETOOTH_SCAN or BLUETOOTH_CONNECT. Instead, it will still rely on ACCESS_FINE_LOCATION for scanning and the normal BLUETOOTH permission for connecting. This leads to the "my app broke on Android 12" scenario if you then try to request BLUETOOTH_SCAN.
- Fix: Update your targetSdk to 31 (Android 12) or higher as soon as possible. This opts your app into the new permission model and allows you to leverage the granular controls. Incrementing your targetSdk requires careful testing, as it can introduce other behavioral changes.
Inadequate Rationale and UX:
- Pitfall: Prompting for permissions without explaining why they are needed, or failing to guide users when permissions are denied (especially "Don't ask again").
- Fix:
  - Before Requesting: Use shouldShowRequestPermissionRationale() to check if the user has previously denied the permission. If true, display a user-friendly dialog explaining why the permission is crucial for your app's functionality before making the actual permission request.
  - After Denial (Persistent): If the user denies a critical permission and checks "Don't ask again," your app won't be able to request it again. Detect this state (e.g., checkSelfPermission returns PERMISSION_DENIED and shouldShowRequestPermissionRationale returns false) and gracefully guide the user to your app's settings page (via Intent(Settings.ACTION_APPLICATION_DETAILS_SETTINGS)) to manually grant the permission. Clear communication here is key to a good user experience.
Forgetting Location Services (even with BLUETOOTH_SCAN):
- Pitfall: Assuming that BLUETOOTH_SCAN alone is sufficient to enable BLE scanning on all Android 12+ devices. Some OEMs or even specific Android versions (especially prior to S) might still require the device's Location Services to be enabled (the toggle in quick settings), even if your app has the BLUETOOTH_SCAN permission.
- Fix: Always include a check for the device's location services status (LocationManager.isLocationEnabled on API 28+ or Settings.Secure.LOCATION_MODE on older versions) before starting a scan. If location services are off, politely prompt the user to enable them, perhaps with an Intent(Settings.ACTION_LOCATION_SOURCE_SETTINGS).

Conclusion

The Android 12+ BLE permission changes, while initially challenging, represent a significant step forward for user privacy and control. By understanding the shift from ACCESS_FINE_LOCATION to BLUETOOTH_SCAN/CONNECT, correctly implementing conditional manifest declarations with neverForLocation, and rigorously requesting permissions at runtime, you can ensure your BLE applications are robust and user-friendly. Always prioritize clear user communication and thorough testing across different Android versions to catch these nuanced behavioral changes. Your next step should be to audit your existing BLE applications, update their targetSdk to 31+, and refactor your permission handling to embrace this new, more granular model.

TAGS: android, kotlin, ble, permissions

Forem: Ble Advertiser

Navigating Android 12+ BLE Permissions: A Kotlin Developer's Checklist for BLUETOOTH_SCAN, CONNECT, and ADVERTISE

Core Concepts: The Shift in Android 12+ BLE Permissions

BLUETOOTH_SCAN

BLUETOOTH_CONNECT

BLUETOOTH_ADVERTISE

The Location Conundrum (Revisited for API 31+)

Implementation: A Step-by-Step Guide for Kotlin

Step 1: Update Your AndroidManifest.xml

Step 2: Request Permissions at Runtime (Kotlin & Activity Result API)

Best Practices: Avoiding Common BLE Permission Headaches

Conclusion

Solving Elusive Android BLE Background Reconnection Issues: A Deep Dive into OS Restrictions and Robust Strategies

Core Concepts: Understanding Android's BLE Landscape

OS Restrictions: The Silent Killers of Background BLE

Robust Reconnection Strategies: Your Toolkit

Implementation: Building a Resilient BLE Stack

1. Permissions (Manifest & Runtime)

2. Foreground Service Setup

3. Robust BluetoothGatt Management and Reconnection Logic

Best Practices: Avoid Common Pitfalls

Conclusion

Conquering Elusive Android BLE `GATT_FAILURE` and Connection Timeouts in Kotlin

Core Concepts: Understanding the Battlefield

The Android BLE State Machine: More Like a Minefield

BluetoothGatt.GATT_FAILURE: The Generic Culprit

Connection Timeouts: The Silent Killer

Android BLE Stack Nuances

Implementation: A Systematic Debugging Approach

Prerequisites

Indispensable Debugging Tools

Robust GATT Lifecycle Management

Best Practices: Avoiding the Pitfalls

Pitfall 1: Multiple BluetoothGatt Instances for the Same Device

Pitfall 2: Overlapping/Unqueued GATT Operations

Pitfall 3: Not Handling BluetoothGatt.close() Correctly or in Time

Pitfall 4: Ignoring Bluetooth Adapter State Changes

Conclusion

How to Keep Your BLE Scan Alive: Overcoming Android 10+ Background Restrictions for Persistent Discovery

The Problem: Android's Enforcement on Background Operations

Core Concepts: Elevating Your BLE Game

Implementation: Building a Persistent BLE Scanner

API Requirements and Permissions

Step-by-Step Implementation

Best Practices

Conclusion

BLE Advertiser: iBeacon, Eddystone & GATT Simulation on One Android Phone

BLE Advertiser Is Now Live on Google Play — Turn Your Android Into Any BLE Device

Bluetooth #BLE #Android #iBeacon #Eddystone #IoT #SmartHome #DeveloperTools #IndoorNavigation #HealthTech #MobileApp #AndroidDev

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

Core Concepts: The Pillars of Reliable Notifications

Notifications vs. Indications

The GATT Profile and the CCCD

Android's BLE Stack & Lifecycle

MTU (Maximum Transmission Unit) Negotiation

Implementation: The Step-by-Step Guide

Prerequisites & Permissions

Core Steps to Enable Notifications

MTU Negotiation

Code Examples

Usage Example

Best Practices for Unshakeable Reliability

Conclusion

Solving the Android BLE GATT Race Condition: Reliable Sequential Operations with Kotlin Coroutines

Core Concepts: The Silent Killer – Android's GATT Race Condition

Implementation: Building the GATT Operation Processor

Requirements & Setup

The Core Components

Gotchas and Considerations

Code Examples

Snippet 1: Defining Operations and the GattClient Skeleton

Using the GattClient

Best Practices for Robust BLE

Conclusion

Why Your Android BLE Advertisements Silently Fail in the Background on Android 12+ and How to Fix It

Core Concepts: The Shifting Sands of Android Background Execution

Implementation: Building a Resilient Background Advertiser

Step 1: AndroidManifest.xml Configuration

Step 2: Runtime Permission Handling (in your Activity/Fragment)

Step 3: BleAdvertiserService.kt – The Heart of Your Background Advertising

`BLUETOOTH_SCAN`

`BLUETOOTH_CONNECT`

`BLUETOOTH_ADVERTISE`

Step 1: Update Your `AndroidManifest.xml`

3. Robust `BluetoothGatt` Management and Reconnection Logic

`BluetoothGatt.GATT_FAILURE`: The Generic Culprit

Pitfall 1: Multiple `BluetoothGatt` Instances for the Same Device

Pitfall 3: Not Handling `BluetoothGatt.close()` Correctly or in Time

Snippet 1: Defining Operations and the `GattClient` Skeleton

Using the `GattClient`

Step 1: `AndroidManifest.xml` Configuration

Step 3: `BleAdvertiserService.kt` – The Heart of Your Background Advertising

Core Concepts: The `BluetoothGatt` Lifecycle Decoded

Understanding `onConnectionStateChange` Status Codes

2. State Management with an `enum class`

1. Pitfall: Ignoring `status` Codes in `onConnectionStateChange`

2. Pitfall: Not Closing `BluetoothGatt` Properly

3. Pitfall: Misunderstanding `autoConnect = true`