蓝牙设备扫描与连接：BluetoothAdapter、扫描回调、GATT 连接建立

蓝牙设备发现与连接是离线数据上云流的第一个物理链路。本章从系统 API 层剥解扫描原理、连接握手流程，并给出可复用的接入代码与调试思路。

1. 核心原理与角色分层

2. 扫描流程与 GATT 连接建立步骤

1. 检查权限 – 确认 BLUETOOTH_SCAN、BLUETOOTH_CONNECT、ACCESS_FINE_LOCATION 已授予。
2. 获取适配器 – 通过 BluetoothAdapter.getDefaultAdapter() 获得本地适配器实例。
3. 启动扫描 – 构造 ScanFilter（按设备名/UUID 过滤），调用 bluetoothLeScanner.startScan(filters, settings, callback)。
4. 扫描回调 – 在 onScanResult 中收到 ScanResult，取出 BluetoothDevice 并记录。
5. 停止扫描 – 找到目标设备后立即调用 stopScan(callback)，避免电量与射频开销。
6. 发起 GATT 连接 – 使用 device.connectGatt(context, autoReconnect, callback) 建立连接。
7. 服务发现 – GATT 连接成功后，在回调中显式调用 BluetoothGatt.discoverServices()。
8. 交互 – 根据业务 UUID 订阅通知（setCharacteristicNotification）、读写特征值。

3. 核心 API 与代码骨架

扫描器初始化与过滤

BluetoothAdapter adapter = BluetoothAdapter.getDefaultAdapter();
BluetoothLeScanner scanner = adapter.getBluetoothLeScanner();

ScanFilter filter = new ScanFilter.Builder()
        .setDeviceName("SensorCloud")      // 按名称过滤
        .build();
ScanSettings settings = new ScanSettings.Builder()
        .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)
        .setReportDelay(0)                  // 实时回调
        .build();

扫描回调

private final ScanCallback scanCallback = new ScanCallback() {
    @Override
    public void onScanResult(int callbackType, ScanResult result) {
        BluetoothDevice device = result.getDevice();
        int rssi = result.getRssi();
        // 匹配目标设备后停止扫描并保存引用
        if ("SensorCloud".equals(device.getName())) {
            targetDevice = device;
            scanner.stopScan(this);
        }
    }

    @Override
    public void onScanFailed(int errorCode) {
        // 错误码 1 = SCAN_FAILED_ALREADY_STARTED  2 = 应用被限制  3 = 内部错误
    }
};

发起 GATT 连接

BluetoothGatt gatt = targetDevice.connectGatt(
        context,                         // 需是 Application 或 Activity context
        false,                            // autoReconnect 通常关闭，手动重连更可控
        new MyGattCallback()             // 自定义回调实现
);

GATT 回调示例

private class MyGattCallback extends BluetoothGattCallback {
    @Override
    public void onConnectionStateChange(BluetoothGatt gatt, int status, int newState) {
        if (status == BluetoothGatt.GATT_SUCCESS) {
            if (newState == BluetoothProfile.STATE_CONNECTED) {
                gatt.discoverServices();   // 连接成功，开始服务发现
            } else if (newState == BluetoothProfile.STATE_DISCONNECTED) {
                // 触发重连逻辑
            }
        } else {
            // status != GATT_SUCCESS，例如 133（GATT_ERROR）或 8（设备断开）
        }
    }

    @Override
    public void onServicesDiscovered(BluetoothGatt gatt, int status) {
        if (status == BluetoothGatt.GATT_SUCCESS) {
            // 通过 gatt.getService(UUID) 获取目标服务
        }
    }
}

4. 调试与常见错误

5. 性能与稳定性优化

• 扫描窗口控制 – 使用 ScanSettings.Builder 的 setScanMode(SCAN_MODE_LOW_POWER) 在日常巡检中降耗，按需切换到 LOW_LATENCY。
• 一次性扫描 – 找到目标设备后立即停止扫描，避免持续广播干扰。
• GATT 重连策略 – 记录 local 和 remote 的 bonding 状态；断连后延迟 1s、2s、4s… 指数退避重连，最多 5 次。
• MTU 协商 – 在 onConnectionStateChange 成功后调用 gatt.requestMtu(512)，提升大数据包传输效率。
• 多设备并发 – 维护 Map<String, BluetoothGatt>，每个设备独立回调线程，避免串行阻塞。

6. 扫描与连接完整流程