Android应用设置ScanFilter报错：BLE设备扫描过滤配置求助

Hey there! Let's work through this ScanFilter issue you're hitting. When trying to filter BLE scans by device address, there are a handful of common missteps that can cause crashes or failures—let's break them down with actionable fixes and examples.

Common Causes & Solutions #

1. Missing or Misconfigured Permissions #

This is the #1 culprit for BLE scan issues on modern Android versions:

• Android 12+: You need the BLUETOOTH_SCAN permission (declare it in your manifest with android:usesPermissionFlags="neverForLocation" if you don't need location data, or include ACCESS_FINE_LOCATION if you do).
• Android 10-11: Requires ACCESS_FINE_LOCATION + BLUETOOTH_ADMIN + BLUETOOTH.
• Always request runtime permissions for these—declaring them in the manifest isn't enough.

2. Invalid Device Address Format #

BLE device addresses must follow the standard format: 12 hexadecimal characters separated by colons (e.g., AA:BB:CC:DD:EE:FF). Double-check:

• No extra spaces or characters
• Hex values are valid (0-9, A-F/a-f)
• Some devices may require uppercase letters (though most are case-insensitive)

3. Incorrect ScanFilter Construction #

It's easy to miss a step when building the filter. Here's the correct way to target a device address, plus critical checks to add before starting the scan:

Working Code Example (Kotlin) #

import android.Manifest
import android.bluetooth.BluetoothAdapter
import android.bluetooth.BluetoothManager
import android.bluetooth.le.ScanCallback
import android.bluetooth.le.ScanFilter
import android.bluetooth.le.ScanResult
import android.bluetooth.le.ScanSettings
import android.content.Context
import android.content.pm.PackageManager
import androidx.core.app.ActivityCompat
import androidx.core.content.ContextCompat

class BleScanner(private val context: Context) {
    private val bluetoothManager by lazy {
        context.getSystemService(Context.BLUETOOTH_SERVICE) as BluetoothManager
    }
    private val bluetoothAdapter by lazy { bluetoothManager.adapter }
    private val scanCallback = object : ScanCallback() {
        override fun onScanResult(callbackType: Int, result: ScanResult?) {
            super.onScanResult(callbackType, result)
            result?.let { scanResult ->
                // Handle your target device here
                println("Found target device: ${scanResult.device.name} (${scanResult.device.address})")
                // Stop scanning once found
                stopScan()
            }
        }

        override fun onScanFailed(errorCode: Int) {
            super.onScanFailed(errorCode)
            // Debug the error code to pinpoint issues
            println("Scan failed with error code: $errorCode")
            // Common error codes to look for:
            // SCAN_FAILED_ALREADY_STARTED (1) - Scan is already running
            // SCAN_FAILED_APPLICATION_REGISTRATION_FAILED (2) - App can't register for scans
            // SCAN_FAILED_INTERNAL_ERROR (3) - System-level error
        }
    }

    fun startScan(targetAddress: String) {
        // Check if Bluetooth is enabled
        if (!bluetoothAdapter.isEnabled) {
            println("Bluetooth is disabled—please turn it on")
            // Optionally launch a request to enable Bluetooth here
            return
        }

        // Check required permissions
        val hasScanPermission = ContextCompat.checkSelfPermission(
            context,
            Manifest.permission.BLUETOOTH_SCAN
        ) == PackageManager.PERMISSION_GRANTED

        val hasLocationPermission = ContextCompat.checkSelfPermission(
            context,
            Manifest.permission.ACCESS_FINE_LOCATION
        ) == PackageManager.PERMISSION_GRANTED

        if (!hasScanPermission || (android.os.Build.VERSION.SDK_INT < 31 && !hasLocationPermission)) {
            println("Missing required permissions—requesting now")
            // Request permissions (use ActivityResultContracts in your activity/fragment)
            return
        }

        // Build the ScanFilter for the target address
        val scanFilter = ScanFilter.Builder()
            .setDeviceAddress(targetAddress)
            .build()

        // Build ScanSettings (adjust mode based on your needs)
        val scanSettings = ScanSettings.Builder()
            .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY) // Fast scan for immediate results
            .build()

        // Start the scan
        bluetoothAdapter.bluetoothLeScanner.startScan(
            listOf(scanFilter),
            scanSettings,
            scanCallback
        )
    }

    fun stopScan() {
        if (ActivityCompat.checkSelfPermission(
                context,
                Manifest.permission.BLUETOOTH_SCAN
            ) == PackageManager.PERMISSION_GRANTED
        ) {
            bluetoothAdapter.bluetoothLeScanner.stopScan(scanCallback)
        }
    }
}

Debugging Tips #

• Check Logcat: The onScanFailed callback gives you an error code—cross-reference it with Android's official documentation to understand the root cause.
• Verify Device Address: Double-check the address in your phone's Bluetooth settings (pair the device temporarily if needed to get the exact address).
• Avoid Duplicate Scans: Make sure you call stopScan() before starting a new scan to prevent SCAN_FAILED_ALREADY_STARTED errors.

内容的提问来源于stack exchange，提问作者bircastri