Forem: Ble Advertiser

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

Robust BLE: Preventing Disconnections and Implementing Auto-Reconnect on Android 12+ with Foreground Services

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

Ever had your critical BLE connection drop silently in the background on Android, only to realize your IoT device stopped syncing data? You've spent countless hours debugging, only to find the OS simply killed your background process. This isn't just frustrating; it's a critical reliability issue for any serious IoT application. On Android 12 and beyond, the operating system's aggressive power management significantly tightens background execution limits, making persistent BLE connections even more challenging.

This article dives deep into the strategic use of Foreground Services, coupled with a robust auto-reconnection mechanism, to ensure your Android application maintains a reliable BLE connection to your IoT devices, even when your app isn't actively in use. You'll learn how to leverage the system correctly, not fight it.

Core Concepts: Why BLE Connections Die and How to Keep Them Alive

Before we dive into code, let's understand the underlying challenges. BLE connections are inherently fragile. Several factors can lead to an unexpected disconnection:

Physical Environment: Distance from the peripheral, physical obstructions, and electromagnetic interference.
Peripheral Behavior: The IoT device itself might temporarily lose power, reset, or intentionally disconnect.
Android OS Process Management: This is where most developers struggle. Android aggressively manages background processes to conserve battery and memory.
- Prior to Android 8 (Oreo): Background services had more leeway.
- Android 8-11: Background execution limits were introduced, curtailing services that weren't "user-perceivable."
- Android 12+: Further restrictions apply. Services started from the background are often killed quickly unless they elevate to a Foreground Service within a few seconds. Moreover, even Foreground Services are subject to specific types to clarify their purpose.

When your app is in the background and not holding a Foreground Service, the OS can terminate its process at any time, leading to an immediate and silent BLE disconnection.

Foreground Services: Your Lifeline for Persistent BLE

A Foreground Service tells the Android OS, "Hey, this app is doing something important that the user is actively aware of, even if the app isn't open on screen." This "user awareness" is crucial and is conveyed via a persistent notification in the status bar. The OS is far less likely to kill a process running a Foreground Service.

For BLE, a Foreground Service is the only reliable way to maintain connections in the background on modern Android versions. Specifically for Android 12+, a new foreground service type, connectedDevice, is highly relevant. It signifies that your service is interacting with a connected hardware device, which further clarifies its purpose to the system.

How Foreground Services work for BLE:

[Your App Process]
      |
      +---- Starts Foreground Service (with Notification)
      |
[Foreground Service] ---- (BLE Connection Logic)
      |                         |
      +---- BluetoothManager ---- BluetoothAdapter ---- BluetoothGatt (Connection to Peripheral)
      |
      +---- System Notification (User awareness)

The service runs your BLE connection logic. If the connection drops, your service's logic is still active, allowing you to implement a robust auto-reconnect strategy.

Auto-Reconnect: Beyond `autoConnect=true`

The BluetoothGatt.connectGatt(..., autoConnect = true) parameter is often misunderstood. When autoConnect is true, the system attempts to connect to the device whenever it becomes available, even if it's not nearby initially. This is useful for passive, power-efficient reconnection attempts but can be slow and less predictable for immediate re-establishment after an unexpected disconnection. For a responsive IoT application, you need a more proactive approach.

A robust auto-reconnect mechanism involves:

Detecting Disconnection: Relying on BluetoothGattCallback.onConnectionStateChange.
Implementing Retry Logic: A loop with delays, possibly exponential backoff, attempting to re-establish the connection using connectGatt(..., autoConnect = false).
Proper BluetoothGatt Management: Closing and nulling out old GATT instances before attempting a new connection to avoid stale states.

Implementation: Building a Robust BLE Service

You'll need minSdkVersion 23 (for BluetoothGatt functionality) and targetSdkVersion 31 (for Android 12+ features and stricter checks). We'll use Kotlin.

1. Permissions and Manifest Configuration

First, declare necessary permissions in your AndroidManifest.xml:

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

    <!-- Pre-Android 12 BLE Permissions -->
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <!-- Needed for scanning if location isn't explicitly disabled for BLE -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

    <!-- Android 12+ BLE Permissions -->
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN"
        android:usesPermissionFlags="neverForLocation" /> <!-- Important if not using location for scanning -->
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

    <!-- Foreground Service Permission -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <!-- Android 12+ Foreground Service Type -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE" />

    <application
        ... >
        <service
            android:name=".services.BleConnectionService"
            android:foregroundServiceType="connectedDevice" />
        <!-- Declare service type for Android 12+ -->
    </application>
</manifest>

Key Points:

BLUETOOTH_SCAN with android:usesPermissionFlags="neverForLocation" is crucial if your app doesn't actually need location for BLE scans but needs to bypass the location requirement on some devices/Android versions. If you perform location-dependent scans, omit this flag and handle location permissions.
BLUETOOTH_CONNECT is required for connecting to BLE devices on Android 12+.
FOREGROUND_SERVICE_CONNECTED_DEVICE is the specific type for services managing hardware connections on Android 12+. This helps the OS understand your service's intent and prioritize it correctly.

2. Runtime Permissions

For Android 12+, BLUETOOTH_SCAN and BLUETOOTH_CONNECT are runtime permissions. You must request these from the user before initiating any BLE operations.

// In your Activity where BLE operations are initiated
fun requestBlePermissions() {
    val permissions = mutableListOf<String>()
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        permissions.add(Manifest.permission.BLUETOOTH_SCAN)
        permissions.add(Manifest.permission.BLUETOOTH_CONNECT)
        permissions.add(Manifest.permission.FOREGROUND_SERVICE_CONNECTED_DEVICE) // Not runtime, but good to check if declared
    } else {
        permissions.add(Manifest.permission.BLUETOOTH)
        permissions.add(Manifest.permission.BLUETOOTH_ADMIN)
        permissions.add(Manifest.permission.ACCESS_FINE_LOCATION) // if pre-S and scanning
    }

    // Add generic Foreground Service permission (not runtime but good for clarity)
    permissions.add(Manifest.permission.FOREGROUND_SERVICE)

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

    if (permissionsToRequest.isNotEmpty()) {
        ActivityCompat.requestPermissions(this, permissionsToRequest, REQUEST_BLE_PERMISSIONS)
    } else {
        // Permissions already granted, proceed with BLE operations
        startBleConnectionService()
    }
}

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 }) {
            startBleConnectionService()
        } else {
            // Handle cases where permissions are not granted
            Toast.makeText(this, "BLE permissions are required.", Toast.LENGTH_SHORT).show()
        }
    }
}

3. The `BleConnectionService`

This is the heart of your persistent BLE connection.

// services/BleConnectionService.kt
package com.yourpackage.bleapp.services

import android.Manifest
import android.app.Notification
import android.app.NotificationChannel
import android.app.NotificationManager
import android.app.PendingIntent
import android.app.Service
import android.bluetooth.*
import android.content.Context
import android.content.Intent
import android.content.pm.PackageManager
import android.os.*
import android.util.Log
import androidx.annotation.RequiresApi
import androidx.core.app.ActivityCompat
import androidx.core.app.NotificationCompat
import com.yourpackage.bleapp.MainActivity
import com.yourpackage.bleapp.R // Assume you have a layout/drawable

class BleConnectionService : Service() {

    private val TAG = "BleConnectionService"
    private var bluetoothAdapter: BluetoothAdapter? = null
    private var bluetoothGatt: BluetoothGatt? = null
    private var deviceAddress: String? = null
    private var reconnectAttempts = 0
    private val MAX_RECONNECT_ATTEMPTS = 5
    private val RECONNECT_DELAY_MS = 5000L // Initial delay
    private val NOTIFICATION_CHANNEL_ID = "BleConnectionChannel"
    private val NOTIFICATION_ID = 101

    // Handler for managing reconnect attempts
    private val handler = Handler(Looper.getMainLooper())

    private val reconnectRunnable = Runnable {
        attemptReconnect()
    }

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

    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        Log.d(TAG, "Service onStartCommand")
        deviceAddress = intent?.getStringExtra("DEVICE_ADDRESS")
        if (deviceAddress == null) {
            Log.e(TAG, "Device address not provided. Stopping service.")
            stopSelf()
            return START_NOT_STICKY
        }

        // Start Foreground Service
        startForeground(NOTIFICATION_ID, createNotification("Connecting to $deviceAddress"))

        // If not already connected, attempt connection
        if (bluetoothGatt == null || bluetoothGatt?.readPhy() == null) { // Simple check if GATT is active
            connectToDevice(deviceAddress!!)
        }

        return START_REDELIVER_INTENT // If service is killed, try to restart with last intent
    }

    override fun onDestroy() {
        super.onDestroy()
        Log.d(TAG, "Service destroyed")
        disconnectGatt()
        handler.removeCallbacks(reconnectRunnable)
        // Stop foreground service without removing notification, allowing system to clean up
        stopForeground(STOP_FOREGROUND_DETACH)
        // For older Android versions (< API 24), use stopForeground(true)
    }

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

    private fun initializeBluetooth(): Boolean {
        if (bluetoothAdapter == null) {
            val bluetoothManager = getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
            bluetoothAdapter = bluetoothManager.adapter
            if (bluetoothAdapter == null) {
                Log.e(TAG, "Bluetooth not supported on this device.")
                stopSelf()
                return false
            }
        }
        return true
    }

    // --- BLE Connection Logic ---

    private fun connectToDevice(address: String) {
        if (!initializeBluetooth()) return

        if (bluetoothAdapter?.isEnabled == false) {
            Log.e(TAG, "Bluetooth is not enabled.")
            // Consider sending a broadcast to UI to prompt user to enable Bluetooth
            scheduleReconnect(RECONNECT_DELAY_MS)
            return
        }

        if (ActivityCompat.checkSelfPermission(this, Manifest.permission.BLUETOOTH_CONNECT) != PackageManager.PERMISSION_GRANTED) {
            Log.e(TAG, "BLUETOOTH_CONNECT permission not granted.")
            // This should ideally be handled before service starts, but good to check
            stopSelf()
            return
        }

        val device = bluetoothAdapter?.getRemoteDevice(address)
        if (device == null) {
            Log.e(TAG, "Device not found with address: $address")
            stopSelf()
            return
        }

        disconnectGatt() // Ensure any existing GATT connection is closed
        Log.d(TAG, "Attempting to connect to $address")

        // autoConnect = false for direct, immediate connection attempt
        bluetoothGatt = device.connectGatt(this, false, gattCallback)
        updateNotification("Connecting to ${device.name ?: device.address}...")
    }

    private fun disconnectGatt() {
        bluetoothGatt?.apply {
            Log.d(TAG, "Closing existing GATT connection.")
            if (ActivityCompat.checkSelfPermission(this@BleConnectionService, Manifest.permission.BLUETOOTH_CONNECT) == PackageManager.PERMISSION_GRANTED) {
                disconnect() // Explicitly disconnect
            }
            close()
        }
        bluetoothGatt = null
    }

    private val gattCallback = object : BluetoothGattCallback() {
        override fun onConnectionStateChange(gatt: BluetoothGatt, status: Int, newState: Int) {
            super.onConnectionStateChange(gatt, status, newState)
            val deviceName = gatt.device.name ?: gatt.device.address
            Log.d(TAG, "Connection state changed for $deviceName, status: $status, newState: $newState")

            if (status == BluetoothGatt.GATT_SUCCESS) {
                when (newState) {
                    BluetoothProfile.STATE_CONNECTED -> {
                        Log.i(TAG, "Connected to $deviceName")
                        reconnectAttempts = 0 // Reset attempts on successful connection
                        updateNotification("Connected to $deviceName")
                        // Discover services after connection, and update UI
                        gatt.discoverServices()
                    }
                    BluetoothProfile.STATE_DISCONNECTED -> {
                        Log.w(TAG, "Disconnected from $deviceName. Attempting reconnect.")
                        updateNotification("Disconnected from $deviceName. Reconnecting...")
                        scheduleReconnect(RECONNECT_DELAY_MS)
                    }
                }
            } else {
                Log.e(TAG, "Connection state change error for $deviceName. Status: $status, new state: $newState. Attempting reconnect.")
                updateNotification("Connection error with $deviceName. Reconnecting...")
                disconnectGatt() // Close GATT on error to avoid stale state
                scheduleReconnect(RECONNECT_DELAY_MS)
            }
        }

        override fun onServicesDiscovered(gatt: BluetoothGatt, status: Int) {
            super.onServicesDiscovered(gatt, status)
            if (status == BluetoothGatt.GATT_SUCCESS) {
                Log.i(TAG, "Services discovered for ${gatt.device.name ?: gatt.device.address}")
                // Here you would typically read/write characteristics, subscribe to notifications
                // For example: readCharacteristic(someCharacteristic)
            } else {
                Log.e(TAG, "Service discovery failed with status $status for ${gatt.device.name ?: gatt.device.address}")
            }
        }

        // Implement other callbacks like onCharacteristicRead, onCharacteristicWrite, onCharacteristicChanged etc.
    }

    private fun attemptReconnect() {
        if (reconnectAttempts < MAX_RECONNECT_ATTEMPTS) {
            reconnectAttempts++
            val currentDelay = RECONNECT_DELAY_MS * reconnectAttempts // Simple linear backoff
            Log.d(TAG, "Reconnect attempt $reconnectAttempts of $MAX_RECONNECT_ATTEMPTS with delay $currentDelay ms.")
            updateNotification("Reconnecting (attempt $reconnectAttempts)...")
            handler.postDelayed({
                deviceAddress?.let { connectToDevice(it) } ?: stopSelf()
            }, currentDelay)
        } else {
            Log.e(TAG, "Max reconnect attempts reached. Stopping service.")
            updateNotification("Failed to connect. Tap to retry.", true) // Indicate failure, allow user to interact
            stopSelf() // Stop service if unable to reconnect
        }
    }

    private fun scheduleReconnect(delay: Long) {
        handler.removeCallbacks(reconnectRunnable) // Remove any pending reconnects
        handler.postDelayed(reconnectRunnable, delay)
    }

    // --- Foreground Service Notification ---

    private fun createNotification(message: String, isError: Boolean = false): Notification {
        createNotificationChannel()

        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 // Required for Android S+
        )

        val builder = NotificationCompat.Builder(this, NOTIFICATION_CHANNEL_ID)
            .setContentTitle("BLE Connection Service")
            .setContentText(message)
            .setSmallIcon(R.drawable.ic_ble_connected) // Replace with your icon
            .setContentIntent(pendingIntent)
            .setOngoing(!isError) // Keep ongoing unless it's an error state
            .setPriority(NotificationCompat.PRIORITY_LOW) // Use LOW for background connection
            .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE) // For Android 12+

        return builder.build()
    }

    private fun updateNotification(message: String, isError: Boolean = false) {
        val notification = createNotification(message, isError)
        val notificationManager = getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
        notificationManager.notify(NOTIFICATION_ID, notification)
    }

    private fun createNotificationChannel() {
        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
            val serviceChannel = NotificationChannel(
                NOTIFICATION_CHANNEL_ID,
                "BLE Connection Service Channel",
                NotificationManager.IMPORTANCE_LOW
            )
            val manager = getSystemService(NotificationManager::class.java)
            manager.createNotificationChannel(serviceChannel)
        }
    }

    companion object {
        const val REQUEST_BLE_PERMISSIONS = 1001

        fun startService(context: Context, deviceAddress: String) {
            val startIntent = Intent(context, BleConnectionService::class.java).apply {
                putExtra("DEVICE_ADDRESS", deviceAddress)
            }
            // Use ContextCompat.startForegroundService to ensure correct behavior on modern Android
            ContextCompat.startForegroundService(context, startIntent)
        }

        fun stopService(context: Context) {
            val stopIntent = Intent(context, BleConnectionService::class.java)
            context.stopService(stopIntent)
        }
    }
}

4. Starting and Stopping the Service (from your Activity/Fragment)

// In your MainActivity.kt (or relevant Activity/Fragment)
import com.yourpackage.bleapp.services.BleConnectionService

// ... inside your activity or fragment
private fun startBleConnectionService() {
    val deviceAddress = "XX:XX:XX:XX:XX:XX" // Replace with your actual device address
    BleConnectionService.startService(this, deviceAddress)
}

private fun stopBleConnectionService() {
    BleConnectionService.stopService(this)
}

// Call startBleConnectionService() after permissions are granted and you have the device address.

Best Practices: Sharpening Your BLE Implementation

Merely implementing the above isn't enough for a production-grade solution. You need to consider edge cases and common pitfalls.

Don't rely solely on BluetoothGatt.connectGatt(..., autoConnect = true) for immediate reconnects.
- Pitfall: While autoConnect=true seems convenient, it tells the system to passively scan for the device in the background and connect when found. This process can be slow and less predictable, especially after an active disconnection from a previously connected device. It's designed for situations where the device might not be immediately available (e.g., waking up later).
- Fix: For robust and immediate auto-reconnection attempts after an unexpected disconnect, always use BluetoothGatt.connectGatt(..., autoConnect = false). Implement a manual retry loop with a backoff strategy, as shown in the attemptReconnect() function. If several direct attempts fail, you could then fall back to a single autoConnect=true attempt to passively wait for the device, but this should be a secondary strategy.
Improper BluetoothGatt Instance Management.
- Pitfall: Developers often forget to call bluetoothGatt.close() or call connectGatt() multiple times on the same BluetoothGatt object without proper cleanup. This leads to stale connections, resource leaks, and unpredictable BLE behavior (e.g., callbacks not firing, inability to connect).
- Fix: Always ensure that bluetoothGatt.close() is called when the service is destroyed, or when explicitly attempting to reconnect after a failure. Before initiating a new connection with connectGatt(), ensure any existing BluetoothGatt instance is close()d and nulled out. This resets the internal state and allows for a clean connection attempt. The disconnectGatt() helper function in the example demonstrates this.
Ignoring Connection status Codes in onConnectionStateChange.
- Pitfall: Many implementations only check newState (e.g., STATE_CONNECTED, STATE_DISCONNECTED) and ignore the status parameter in onConnectionStateChange. The status provides critical information about why the connection state changed (e.g., GATT_FAILURE, GATT_INSUFFICIENT_AUTHENTICATION, specific error codes).
- Fix: Log and, if necessary, react differently to specific status codes. A GATT_FAILURE (status 133) or similar error might indicate a more severe issue (e.g., peripheral went out of range abruptly, bonding issue) that warrants a longer backoff, a different type of retry (e.g., full BLE power cycle if severe enough, though this is disruptive), or even prompting the user to restart the peripheral. Distinguishing between a clean disconnect (GATT_SUCCESS status with STATE_DISCONNECTED) and an error-driven one can inform your reconnection strategy.
Not handling BluetoothAdapter state changes.
- Pitfall: Your service might be running, but the user could disable Bluetooth from Quick Settings. Your service would keep trying to connect without success.
- Fix: Register a BroadcastReceiver in your BleConnectionService to listen for BluetoothAdapter.ACTION_STATE_CHANGED intents. When Bluetooth is turned off, stop your connection attempts, update your notification to inform the user, and perhaps restart connection attempts only when Bluetooth is re-enabled.

Conclusion

Maintaining robust BLE connections on Android 12+ requires a deep understanding of the OS's background execution limits and a deliberate strategy. By leveraging Foreground Services with the connectedDevice type and implementing a meticulous manual auto-reconnect mechanism, you can significantly enhance the reliability of your IoT applications. Remember to manage your BluetoothGatt instances judiciously and pay attention to specific status codes to build a truly resilient system.

Your next step should be to integrate this service into your existing application, adapting the reconnection logic and error handling to your specific IoT device's behavior. Consider adding a mechanism to notify the UI of connection status changes (e.g., via LocalBroadcastManager or a SharedFlow/LiveData) for a richer user experience.

Secure Boot on ESP32: Fortifying Your IoT Devices Against Firmware Attacks

Ble Advertiser — Sat, 04 Apr 2026 06:01:07 +0000

Secure Boot Implementation on ESP32: A Practical Guide to Preventing Firmware Tampering

Ever built an IoT device and then discovered a vulnerability allowing attackers to overwrite its firmware? You're not alone. Firmware tampering is a significant threat to IoT devices, leading to compromised functionality, data breaches, and potentially even physical harm. Traditional firmware updates are often insufficient, leaving your devices vulnerable to sophisticated attacks. This article details a practical approach to implementing secure boot on the ESP32, dramatically enhancing your device’s resilience against malicious firmware overwrites.

Core Concepts

Secure boot is a security mechanism that verifies the integrity of the firmware before it's executed. It ensures that only trusted firmware can run on the device, preventing attackers from injecting malicious code. Here's a breakdown of the key concepts:

Bootloader: The first code that runs when the device powers on. It's responsible for loading the verified firmware.
TrustZone (optional, but highly recommended): A hardware-based security extension that isolates sensitive operations in a protected region of memory. ESP32 doesn't have a full TrustZone, but you can leverage its hardware security features for some aspects of secure boot.
Hashing: A cryptographic function that produces a fixed-size "hash" (also known as a digest) of the firmware. This hash is used to verify the firmware’s integrity. Common hashing algorithms include SHA-256.
Digital Signatures: Firmware is digitally signed using a private key. The device then verifies the signature using the corresponding public key. This ensures that the firmware hasn't been tampered with since it was signed.
Key Management: Securely storing and managing the private key used for signing and verification. This is crucial for preventing unauthorized firmware updates.

Diagram illustrating the boot process:

+-----------------+      +-----------------+      +-----------------+
| Power On        |------>| Bootloader       |------>| Verified Firmware|
+-----------------+      +-----------------+      +-----------------+
        ^                     |                     |
        |                     |                     |
        +---------------------+                     |
                                                        |
                                                        V
                                               +-----------------+
                                               | Executable Code |
                                               +-----------------+

Table comparing different secure boot approaches:

Approach	Complexity	Hardware Required	Key Management	Security Level
Basic Hashing	Low	Minimal	Simple	Medium
TrustZone-based	Medium	Required	Strong	High
Hardware Root of Trust	High	Required	Very Strong	Highest

Implementation

Implementing secure boot on the ESP32 involves several steps. You’ll need to consider the choice of hardware root of trust (HRoT) and how to securely store the key. This guide focuses on a practical approach using a combination of hashing and software-based verification, providing a solid foundation for enhanced security.

Tools & Libraries:

ESP-IDF: The official Espressif IoT Development Framework, providing APIs for managing the bootloader and secure boot functionality.
OpenSSL: A widely used cryptography library. You can integrate OpenSSL for hashing, digital signature verification and key management.
TinyCrypt: A lightweight cryptographic library for ESP32 specifically designed to be efficient.

Configuration:

You’ll need to configure the bootloader to perform the integrity check before executing the firmware. This involves setting up a custom bootloader that utilizes hashing and digital signatures. This process typically modifies the boot.h file in your ESP32 project.

Permissions & API Usage:

The ESP32 bootloader provides APIs to access the flash memory and perform integrity checks. You’ll need to understand the permission model to avoid accidentally writing to protected memory regions. The esp_bootloader_verify_firmware() API is crucial for verifying the integrity of the firmware.

Gotchas:

Key Storage: Securely storing the private key is paramount. If the key is compromised, the secure boot mechanism becomes ineffective. Consider using hardware security modules (HSMs) or secure elements for key storage if your device requires higher security. Storing the key in a secure partition of flash is also a good practice.
Firmware Updates: You must ensure that firmware updates are also signed and verified before being flashed to the device. This prevents malicious updates from bypassing the secure boot mechanism.
Bootloader Vulnerabilities: The bootloader itself can be a target for attackers. Regularly update the bootloader to patch any security vulnerabilities.

Code Examples

1. Hashing Firmware:

This example demonstrates how to hash the firmware before storing it in flash memory.

#include "esp_log.h"
#include "esp_err.h"
#include "snprintf.h"

void hash_firmware(const char *firmware_data, size_t firmware_len, char *hash, size_t hash_len) {
  ESP_LOGI("SecureBoot", "Hashing firmware...");
  const char *firmware_buffer = firmware_data;
  const char *firmware_end = firmware_data + firmware_len;

  // Allocate memory for the hash
  char *hash_buffer = (char *)malloc(hash_len + 1);
  if (hash_buffer == NULL) {
    ESP_LOGE("SecureBoot", "Failed to allocate memory for hash");
    return;
  }

  // Calculate the hash using SHA256
  size_t hash_calculated = esp_sha256_calculate_digest(firmware_buffer, firmware_end, hash_buffer, hash_len);

  if (hash_calculated != ESP_OK) {
    ESP_LOGE("SecureBoot", "SHA256 hash calculation failed");
    free(hash_buffer);
    return;
  }

  // Null-terminate the hash
  hash_buffer[hash_calculated] = '\0';

  ESP_LOGI("SecureBoot", "Hash: %s", hash_buffer);
  free(hash_buffer);
}

2. Verifying Firmware with Hash:

This example shows how to verify the firmware using the previously calculated hash.

#include "esp_log.h"
#include "esp_err.h"
#include "snprintf.h"
#include "esp_bootloader.h"

int verify_firmware_hash(const char *firmware_data, size_t firmware_len, const char *expected_hash, size_t expected_hash_len) {
  ESP_LOGI("SecureBoot", "Verifying firmware hash...");

  // Calculate the hash of the firmware
  char firmware_hash[expected_hash_len + 1];
  hash_firmware(firmware_data, firmware_len, firmware_hash, expected_hash_len);

  // Compare the calculated hash with the expected hash
  if (esp_memcmp(firmware_hash, expected_hash, expected_hash_len) == 0) {
    ESP_LOGI("SecureBoot", "Firmware hash verification successful!");
    return ESP_OK;
  } else {
    ESP_LOGE("SecureBoot", "Firmware hash verification failed!");
    return ESP_FAIL;
  }
}

Important notes:

Remember to include the necessary headers in your code.
Use esp_log.h for logging messages.
Handle potential errors (e.g., memory allocation failures).
The verify_firmware_hash() function demonstrates the basic verification process. In a real-world application, you'd also need to consider digital signature verification (covered in the next section).

Best Practices

Use a Hardware Root of Trust (HRoT): A HRoT provides a secure foundation for secure boot. Consider using an external hardware security module (HSM) or a dedicated secure element for storing cryptographic keys and performing sensitive operations.
Implement Key Rotation: Regularly rotate your cryptographic keys to mitigate the risk of key compromise. This involves generating new keys and updating the bootloader with the new keys.
Secure Key Storage: Never store your private key in flash memory. Use a secure partition, hardware security module, or secure element to store the key.
Integrate with Firmware Update Mechanisms: Secure boot must be integrated with your firmware update mechanism. Only allow signed and verified firmware updates to be flashed to the device.
Regularly Update the Bootloader: Keep your bootloader up to date to patch any security vulnerabilities.

Conclusion

Implementing secure boot on ESP32 significantly strengthens your IoT device's security posture. By employing hashing, digital signatures, and a robust key management system, you can prevent firmware tampering and protect your devices from malicious attacks. The combination of hashing and software verification provides a solid starting point, but integrating a hardware root of trust, implementing key rotation, and securely

Scaling Flutter: Mastering State Management with Riverpod and Provider

Ble Advertiser — Sat, 04 Apr 2026 05:59:06 +0000

Implementing a Robust State Management Strategy with Riverpod and Provider for Large-Scale Flutter Apps

You've built a beautiful Flutter app, but as it grows, managing state becomes a tangled mess – duplicated logic, hard-to-debug inconsistencies, and a growing fear of refactoring. You're likely facing a situation where your current approach is simply not sustainable for your app’s future. This article will dive deep into two popular Flutter state management solutions, Riverpod and Provider, providing practical guidance to choose the right tool and implement it effectively for large-scale projects. We’ll analyze their strengths, weaknesses, and offer best practices to ensure a maintainable and scalable architecture.

Core Concepts

Before diving into implementation, let’s understand the fundamental concepts underpinning both Riverpod and Provider.

State Management: The Foundation

State management is the process of handling the data that influences the UI of your application. Effective state management ensures that changes in the application's data are reflected in the UI predictably and efficiently. Poor state management often leads to unpredictable UI updates, difficult debugging, and increased complexity.

Provider: The Established Solution

Provider is a widely used state management package in Flutter, built on the InheritedWidget pattern. It provides a straightforward way to share data down the widget tree without manually passing it through each level. It excels at simple to moderately complex applications.

How it works: Provider uses ChangeNotifier or StateNotifier to represent the state. You create a provider, register it with a widget, and then access the provider's data from any widget in the tree.
Key Features:
- Easy to set up and use.
- Good for simple to moderate state.
- Uses the InheritedWidget pattern for cross-widget data sharing.
- Offers a Consumer widget to access data from providers.

Riverpod: The Modern Alternative

Riverpod is a reactive state management library that builds upon Provider. It offers a more type-safe and testable approach. It aims to address some of Provider’s limitations, particularly around testability and dependency injection. Riverpod is becoming increasingly popular for larger, more complex applications.

How it works: Riverpod utilizes a reactive framework based on Provider but adds type safety and improved testability through its Provider and Obx widgets. It leverages the InheritedWidget pattern but with enhanced type safety.
Key Features:
- Type-safe and testable, reducing boilerplate.
- Improved dependency injection capabilities.
- More robust and less prone to errors.
- Offers Provider for data and Obx for observing data changes.

Choosing Between Provider and Riverpod

The choice between Provider and Riverpod depends on the size and complexity of your project. For smaller apps or projects with simple state, Provider might suffice. However, for larger, more complex apps, Riverpod's type safety, testability, and improved dependency injection make it the more suitable choice.

Implementation

Let's walk through a practical implementation of both Provider and Riverpod using a simple counter app. We'll cover setup, configuration, and common pitfalls.

Provider Implementation

Add the provider package to your pubspec.yaml:

dependencies:
  provider: ^6.0.0 # Use the latest version

Create a CounterProvider:

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

class CounterProvider with ChangeNotifier {
  int _count = 0;

  int get count => _count;

  void increment() {
    _count++;
    notifyListeners(); // Notify listeners that the state has changed
  }
}

Register the provider in your main.dart:

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';
import './counter_provider.dart'; // Import the CounterProvider class

void main() {
  runApp(
    ChangeNotifierProvider(
      create: (context) => CounterProvider(), // Create a new instance of CounterProvider
      child: const MyApp(),
    ),
  );
}

Riverpod Implementation

Add the riverpod package to your pubspec.yaml:

dependencies:
  flutter:
    sdk: flutter
  riverpod: ^2.0.0 # Use the latest version

Create a CounterProvider:

import 'package:flutter/material.dart';
import 'package:riverpod/riverpod.dart';

final counterProvider = Provider<int>((context) => 0); // Default value

class Counter extends State<Counter> {
  int _count = 0;

  void increment() {
    setState(() {
      _count++;
    });
  }
}

Register the provider in main.dart:

import 'package:flutter/material.dart';
import 'package:riverpod/riverpod.dart';

void main() {
  runApp(
    RiverpodProvider<int>(
      builder: (context, provider) => Counter(), // Build Counter widget
      value: counterProvider, // Provide the counterProvider
    ),
  );
}

Gotchas

Context: Be mindful of the context in which you’re accessing providers. Incorrect context usage can lead to unexpected behavior or errors.
notifyListeners() (Provider): Always call notifyListeners() after modifying the state to inform listeners about the change. For Riverpod, changes are automatically propagated via the Provider instance.
Dependencies: When using dependency injection (particularly with Riverpod), ensure that you’re correctly injecting dependencies into your providers.

Code Examples

Provider Example (Counter App)

import 'package:flutter/material.dart';
import 'package:provider/provider.dart';

class CounterProvider with ChangeNotifier {
  int _count = 0;

  int get count => _count;

  void increment() {
    _count++;
    notifyListeners(); // Notify listeners that the state has changed
  }
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: CounterScreen(),
    );
  }
}

class CounterScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Counter App')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Count: ${Provider.of<int>(context, listen: false).count}'),
            ElevatedButton(
              onPressed: () => Provider.of<CounterProvider>(context, listen: false).increment(),
              child: const Text('Increment'),
            ),
          ],
        ),
      ),
    );
  }
}

Riverpod Example (Counter App)

import 'package:flutter/material.dart';
import 'package:riverpod/riverpod.dart';

final counterProvider = Provider<int>((context) => 0);

class Counter extends State<Counter> {
  int _count = 0;

  void increment() {
    setState(() {
      _count++;
    });
  }
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: CounterScreen(),
    );
  }
}

class CounterScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Counter App')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Count: $_count'), //Use $_count for reactive updates
            ElevatedButton(
              onPressed: () => increment(),
              child: const Text('Increment'),
            ),
          ],
        ),
      ),
    );
  }
}

Best Practices

Avoid Deeply Nested State: While Provider and Riverpod offer ways to manage deeply nested state, they can quickly become difficult to debug. Consider breaking down your application into smaller

Mitigating Supply Chain Risks in Embedded Firmware: A Guide to Secure Boot and Firmware Updates

Ble Advertiser — Sat, 04 Apr 2026 05:57:06 +0000

Mitigating Supply Chain Risks in Embedded Firmware: A Guide to Secure Boot and Firmware Updates

Did you recently experience a device bricked due to a compromised firmware update? You're not alone. Modern embedded systems are increasingly reliant on complex supply chains, making them vulnerable to malicious actors seeking to inject compromised code. A compromised firmware update can render your device unusable, steal sensitive data, or even control physical functionality – a scenario avoided by robust secure boot and secure firmware update strategies. This article delves into mitigating these risks by implementing a layered approach to secure boot and firmware updates.

Core Concepts

Before diving into implementation, it’s crucial to understand the underlying principles. Let’s break down secure boot and secure firmware updates:

Secure Boot: Secure boot is the process of verifying the integrity of the firmware before it's executed. It prevents the execution of unauthorized or malicious code. It operates at the hardware/firmware level, ensuring that only trusted firmware can run on the device.

Secure Firmware Updates (SFU): SFU involves securely transferring and installing updated firmware onto the device, protecting it from malicious updates during the process. This protects against attackers modifying the firmware before deployment.

Key Components of a Secure Boot System:

Bootloader: The first code executed when the device powers on. It’s responsible for verifying the integrity of the next stage of the boot process.
Hardware Root of Trust (HRoT): Typically a dedicated hardware component (e.g., a secure element, Trusted Platform Module – TPM) that provides a secure foundation for the entire system. It’s responsible for generating and storing cryptographic keys.
Cryptographic Keys: Used to sign and verify the integrity of the firmware image. These keys are protected by the HRoT.
Firmware Image: The actual code that runs on the device.
Verification Chain: A chain of checks performed by the bootloader to verify the integrity and authenticity of each component in the boot process.

Diagram:

graph TD
    A[Power On] --> B(HRoT);
    B --> C{Key Verification};
    C -- Valid --> D[Bootloader];
    C -- Invalid --> E[Device Failure];
    D --> F{Firmware Verification};
    F -- Valid --> G[Execution];
    F -- Invalid --> H[Device Failure];

Secure Firmware Update Process:

SFU typically involves these stages:

Image Signing: The firmware image is digitally signed using a private key stored in the HRoT. The signature ensures the integrity and authenticity of the image.
Image Storage: The signed firmware image is stored securely (e.g., on a secure flash memory).
Update Request: A trigger (e.g., a software update mechanism) initiates an SFU process.
Secure Transfer: The signed firmware image is securely transferred to the device (e.g., over a network or via a physical medium).
Image Verification: The device verifies the signature of the received image using its public key (also stored in the HRoT).
Image Installation: If the verification is successful, the firmware image is installed onto the device.

Implementation

Let's explore how to implement secure boot and SFU. This example focuses on using a hypothetical, but common, approach.

Hardware Requirements:

A microcontroller or SoC with secure boot capabilities (often built into newer ARM Cortex-M series).
A hardware root of trust (HRoT) – a dedicated secure element or TPM. This is not a common requirement for very low-cost devices but is critical for high-security applications.
Secure flash memory for storing the firmware and signing keys.

Software Considerations:

Bootloader: A customized bootloader that handles secure boot and SFU.
Cryptographic Libraries: Libraries for cryptographic operations (e.g., RSA, ECC) to sign and verify firmware images.
Key Management System (KMS): A system for securely storing and managing cryptographic keys.

Step-by-Step Walkthrough:

Hardware Setup: Ensure your microcontroller/SoC has secure boot features enabled. If using a TPM, configure it for key storage and cryptographic operations.
Bootloader Development: Develop a custom bootloader that performs the following tasks:
- Key Loading: Loads the public key from the HRoT.
- Signature Verification: Verifies the signature of the firmware image.
- Firmware Installation: Installs the verified firmware image.
Firmware Signing: Use a cryptographic library to sign the firmware image with a private key stored in the HRoT.
Secure Image Storage: Store the signed firmware image securely in flash memory.
SFU Implementation: Implement the SFU process, including secure transfer, verification, and installation.

Gotchas:

Key Rotation: Regularly rotate cryptographic keys to mitigate the impact of key compromise.
Firmware Updates During Operation: Avoid updating firmware while the device is running critical operations, as this could lead to data corruption or device instability.
Secure Storage: Ensure that cryptographic keys are stored securely and are protected from unauthorized access.

Code Examples

Here are two code snippets illustrating key aspects of secure boot and SFU. These are illustrative and may need adaptation for your specific hardware and software environment.

1. Firmware Signing (using OpenSSL):

#include <stdio.h>
#include <openssl/rsa.h>
#include <openssl/evp.h>
#include <openssl/err.h>

int main() {
    RSA *rsa;
    EVP_PKEY *pkey;
    FILE *fp;
    char *filename = "firmware.bin";
    char *private_key_filename = "private.pem";
    char *public_key_filename = "public.pem";

    // Load the private key
    pkey = PEM_read_bio_PrivateKey(stdin, NULL, RSA_PKCS1_KEYTYPE, NULL);
    if (!pkey) {
        fprintf(stderr, "Error loading private key: %s\n", ERR_error_string(ERR_get_error(), NULL));
        return 1;
    }
    rsa = RSA_import_key(RSA_PKCS1_KEYTYPE, pkey, 0, NULL);

    // Load the firmware image
    FILE *fp = fopen(filename, "rb");
    if (!fp) {
        fprintf(stderr, "Error opening firmware image: %s\n", filename);
        return 1;
    }
    unsigned char firmware_data[4096];
    size_t bytes_read = fread(firmware_data, 1, sizeof(firmware_data), fp);
    fclose(fp);

    // Sign the firmware data
    int status = RSA_sign(rsa, firmware_data, bytes_read, NULL, NULL);
    if (status != 1) {
        fprintf(stderr, "Error signing firmware: %s\n", ERR_error_string(ERR_get_error(), NULL));
        return 1;
    }

    // Write the signed data to a new file
    fp = fopen("signed_firmware.bin", "wb");
    if (!fp) {
        fprintf(stderr, "Error opening file for writing: %s\n", "signed_firmware.bin");
        return 1;
    }
    fwrite(firmware_data, 1, bytes_read, fp);
    fclose(fp);

    printf("Firmware signed and saved to signed_firmware.bin\n");
    return 0;
}

2. Secure Firmware Update (simplified):


c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

// Placeholder for secure transfer (e.g., over network)
void secure_transfer(const char *firmware_data, size_t size) {
    // In a real implementation, this would handle secure transfer of the firmware image
    printf("Securely transferring firmware data...\n");
}

int main() {
    const char *firmware_file = "signed_firmware.bin";
    size_t firmware_size = 4096;
    char *destination_file = "new_firmware.bin";

    // Read the firmware data
    FILE *fp = fopen(firmware_file, "rb");
    if (!fp) {
        fprintf(stderr, "Error opening firmware file: %s\n", firmware_file);
        return 1;
    }
    unsigned char firmware_data[firmware_size];
    size_t bytes_read = fread(firmware_

Forem: Ble Advertiser

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

Best Practices for Reliable BLE Background Advertising

Conclusion

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

Core Concepts: The BluetoothGatt Lifecycle Decoded

Implementation: A Robust Connection Manager

Code Examples

Best Practices for Robust BLE Connections

Conclusion

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

Core Concepts: Understanding Disconnections

Understanding onConnectionStateChange Status Codes

GATT Resources and Cleanup

Implementation: Building a Robust Reconnection Strategy

1. Permissions and API Requirements

2. State Management with an enum class

3. Disconnection Detection and Reconnection Logic

Best Practices for Robust Disconnection Handling

1. Pitfall: Ignoring status Codes in onConnectionStateChange

2. Pitfall: Not Closing BluetoothGatt Properly

3. Pitfall: Misunderstanding autoConnect = true

4. Pitfall: Lack of Comprehensive State Management

5. Pitfall: Not Implementing Exponential Backoff for Retries

Conclusion

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

Core Concepts: The Shift to Granular BLE Permissions

Why the Change?

Permission Mapping and Dependencies

Implementation: The Step-by-Step Walkthrough

Prerequisites

1. Manifest Declarations

2. Runtime Permission Request

Best Practices & Common Gotchas

Conclusion

Robust BLE: Preventing Disconnections and Implementing Auto-Reconnect on Android 12+ with Foreground Services

Core Concepts: Why BLE Connections Die and How to Keep Them Alive

Foreground Services: Your Lifeline for Persistent BLE

Auto-Reconnect: Beyond autoConnect=true

Implementation: Building a Robust BLE Service

1. Permissions and Manifest Configuration

2. Runtime Permissions

3. The BleConnectionService

4. Starting and Stopping the Service (from your Activity/Fragment)

Best Practices: Sharpening Your BLE Implementation

Conclusion

Secure Boot on ESP32: Fortifying Your IoT Devices Against Firmware Attacks

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`

Auto-Reconnect: Beyond `autoConnect=true`

3. The `BleConnectionService`