Android BLE Scanning — Complete Guide

// No scan filter — returns ALL BLE devices in range
val scanner = BluetoothAdapter.getDefaultAdapter().bluetoothLeScanner
scanner.startScan(callback) // Thousands of scan results!

class BleScanner(private val context: Context) {
    private val bluetoothLeScanner: BluetoothLeScanner?
    private val scanResults = mutableMapOf<String, ScanResult>()

    // Scan callback
    private val scanCallback = object : ScanCallback() {
        override fun onScanResult(callbackType: Int, result: ScanResult) {
            scanResults[result.device.address] = result
            onDeviceFound?.invoke(result)
        }

        override fun onBatchScanResults(results: List<ScanResult>) {
            results.forEach { scanResults[it.device.address] = it }
        }

        override fun onScanFailed(errorCode: Int) {
            Log.e("BleScan", "Scan failed with error: $errorCode")
            onScanError?.invoke(errorCode)
        }
    }

    var onDeviceFound: ((ScanResult) -> Unit)? = null
    var onScanError: ((Int) -> Unit)? = null

    init {
        val adapter = BluetoothAdapter.getDefaultAdapter()
        bluetoothLeScanner = adapter?.bluetoothLeScanner
    }

    // Filtered scan for specific service
    fun startScan(serviceUuid: String? = null) {
        if (!hasPermissions()) {
            requestPermissions()
            return
        }

        val filters = if (serviceUuid != null) {
            listOf(
                ScanFilter.Builder()
                    .setServiceUuid(ParcelUuid(UUID.fromString(serviceUuid)))
                    .build()
            )
        } else emptyList()

        val settings = ScanSettings.Builder()
            .setScanMode(ScanSettings.SCAN_MODE_LOW_POWER) // Low power for background
            .setReportDelay(0) // Immediate results
            .build()

        bluetoothLeScanner?.startScan(filters, settings, scanCallback)
    }

    fun stopScan() {
        bluetoothLeScanner?.stopScan(scanCallback)
    }

    // Parse advertisement data
    fun getDeviceName(result: ScanResult): String {
        return result.device.name ?: "Unknown"
    }

    fun getRssi(result: ScanResult): Int {
        return result.rssi
    }

    fun hasServiceData(result: ScanResult, serviceUuid: String): Boolean {
        return result.scanRecord?.serviceData?.containsKey(ParcelUuid(UUID.fromString(serviceUuid))) ?: false
    }

    private fun hasPermissions(): Boolean {
        return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
            ContextCompat.checkSelfPermission(context, Manifest.permission.BLUETOOTH_SCAN) == PERMISSION_GRANTED &&
            ContextCompat.checkSelfPermission(context, Manifest.permission.BLUETOOTH_CONNECT) == PERMISSION_GRANTED
        } else {
            ContextCompat.checkSelfPermission(context, Manifest.permission.ACCESS_FINE_LOCATION) == PERMISSION_GRANTED
        }
    }
}