技术长文 · 基于 AOSP Bluetooth 模块 · 适合开发者与系统工程师

打开手机蓝牙开关，点一下「连接」，看起来只是一眨眼的事。真正发生的，是一条从 Java Framework、蓝牙系统服务、协议栈、HCI，一直穿透到 Controller 固件的完整链路。 本文沿着AOSP 公开源码，把这条链路拆开讲清楚——不谈具体业务 SDK，只谈系统本身。

一、为什么要读源码，而不是只看 API 文档

官方文档告诉你「调用 BluetoothLeScanner.startScan() 可以扫描」。 源码告诉你：扫描请求如何进入蓝牙服务、如何变成 HCI LE Set Scan Parameters / Enable、 广告报文如何回传、为什么空过滤器会变成「全量扫描」、为什么后台扫描会被系统节流。

对做外设联调、功耗优化、连接稳定性排查的工程师来说，Framework 只是入口，协议栈与 HAL 才是真相。 Android 自 Android 13 起，蓝牙实现以 Mainline 模块形式独立演进，公开仓库为：

https://android.googlesource.com/platform/packages/modules/Bluetooth

HAL 接口定义则在另一个公开仓库：

https://android.googlesource.com/platform/hardware/interfaces└── bluetooth/aidl/.../IBluetoothHci.aidl

隐私说明：下文引用的类名、路径、接口均来自 AOSP 公开代码。 不涉及任何厂商私有协议、业务 SDK、设备标识或现场日志。

二、经典蓝牙与 BLE：先把角色说清

Android 上同时承载两套世界：

BLE 里两个最容易混淆的角色：

• Central（中心）：发起扫描与连接，通常是手机；应用侧多为 GATT Client。
• Peripheral（外设）：广播并等待被连，应用侧多为 GATT Server。

GATT 树形结构可以记成一句话：Service 装 Characteristic，Characteristic 可挂 Descriptor； 其中 CCCD（0x2902）决定 Notify/Indicate 是否真正推送给对端。

三、Android 蓝牙分层全景

把一次 BLE 读写拆开，大致经过这些层（自上而下）：

1. Application：第三方 App 或系统应用，调用 android.bluetooth*。
2. Framework API：公开 Java/Kotlin API，做权限校验、参数封装、Binder 代理。
3. Bluetooth System Service：系统进程中的蓝牙服务（GATT、扫描、适配器状态等）。
4. JNI / BTIF：Java 与 Native 协议栈的边界。
5. Fluoride Stack：BTA（应用适配）、GATT、L2CAP、SMP、HCI 等协议实现。
6. HCI HAL：只搬运 HCI 命令/事件/ACL/SCO/ISO，不关心上层 Profile。
7. Vendor HAL + Controller：芯片厂商实现；再往下是固件与射频。

这条分层的设计哲学很清晰：上层管业务语义，HCI 只管字节流，HAL 把 Host 与 Controller 解耦。

四、AOSP 源码目录地图

注意：这个模块不包含各芯片厂商的 HCI HAL 具体实现，也不包含完整 Linux Kernel 驱动。 读栈时心里要有边界——你看到的是 Host 侧；芯片侧在 vendor 分区。

五、应用层：扫描、连接、GATT

5.1 扫描：BluetoothLeScanner

入口在 framework/java/android/bluetooth/le/BluetoothLeScanner.java。 应用侧典型用法：

BluetoothLeScanner scanner =        BluetoothAdapter.getDefaultAdapter().getBluetoothLeScanner();ScanSettings settings = new ScanSettings.Builder()        .setScanMode(ScanSettings.SCAN_MODE_LOW_LATENCY)        .build();List filters = new ArrayList<>();filters.add(new ScanFilter.Builder()        .setServiceUuid(new ParcelUuid(TARGET_UUID))        .build());scanner.startScan(filters, settings, scanCallback);

工程上有几条「源码级」经验：

• 有意义的 ScanFilter 能显著降低回调噪声与功耗；空过滤接近全量扫描。
• SCAN_MODE_LOW_LATENCY
   适合前台短时发现；后台应改用平衡/低功耗模式。
• Android 12+ 需要细粒度蓝牙权限（如 BLUETOOTH_SCAN），并结合定位策略理解可见性限制。

5.2 连接：BluetoothDevice.connectGatt

在较新的 AOSP 中，多个重载最终收敛到基于 BluetoothGattConnectionSettings 的实现。简化后的语义如下：

framework/java/android/bluetooth/BluetoothDevice.java

public BluetoothGatt connectGatt(        Context context, boolean autoConnect, BluetoothGattCallback callback) {    return connectGatt(            new BluetoothGattConnectionSettings.Builder()                    .setAutoConnectEnabled(autoConnect)                    .setTransport(TRANSPORT_AUTO)                    .setAutomaticMtuEnabled(false)                    .build(),            new BluetoothUtils.SynchronousExecutor(),            callback);}

关键参数的含义，几乎每个做 BLE 的人都会踩坑：

• autoConnect = false
  ：直接连接（direct），超时相对短，适合已知设备、前台主动连。
• autoConnect = true
  ：交由栈在设备可见时自动连，更「后台友好」，但时机不可精确预期。
• transport
  ：双模设备上可强制 TRANSPORT_LE，避免走到 BR/EDR。

5.3 GATT 操作：发现、MTU、通知

framework/java/android/bluetooth/BluetoothGatt.java

// 服务发现public boolean discoverServices() {    if (!mClientRegistered) return false;    mService.discoverServices(mBluetoothGattCallback, mDevice, mAttributionSource);    return true;}// 请求更大 MTU（ATT 层）public boolean requestMtu(int mtu) {    if (!mClientRegistered) return false;    mService.configureMTU(mBluetoothGattCallback, mDevice, mtu, mAttributionSource);    return true;}// 打开本地通知开关（通常还要写 CCCD）public boolean setCharacteristicNotification(        BluetoothGattCharacteristic characteristic, boolean enable) { ... }

一次「能稳定收 Notify」的常见正确顺序是：

1. onConnectionStateChange → STATE_CONNECTED
2. （可选）requestMtu，等 onMtuChanged
3. discoverServices
   ，等发现完成
4. setCharacteristicNotification(true)
5. 写入 CCCD（0x2902）为 Notify/Indicate enable
6. 再进行业务读写

易错点：只调用 setCharacteristicNotification 而不写 CCCD， 很多外设端不会真正推送数据。这是 API 语义与协议语义不一致导致的经典坑。

六、系统服务与 JNI 边界

Framework 里的 BluetoothGatt / BluetoothLeScanner 并不直接碰协议栈，而是通过 Binder 进入蓝牙系统服务。 服务进程里再经 JNI 下探到 Native（BTIF）。

可以把它理解成：

App 进程  └─ android.bluetooth.*（客户端代理）        │ Binder        ▼蓝牙系统服务进程  ├─ GattService / 扫描管理 / AdapterService  └─ JNI → libbluetooth → BTIF / BTA / Stack

调试时如果只在 App 里打 log，往往只能看到「回调失败」。 真正要定位「为什么 HCI 没发出去 / 对端没回 Event」，必须下到服务与 native 日志。

七、Fluoride：BTIF / BTA / Stack

Android 蓝牙 Host 栈常被称作 Fluoride。粗分三层：

• BTIF（system/btif）：对外 C 接口与回调，对齐 Java 侧期望的事件模型。
• BTA（system/bta）：Profile/应用适配状态机，例如 bta/gatt。
• Stack（system/stack）：GATT、ATT、SMP、L2CAP、BTM、HCI 等协议细节。

一条 GATT 写请求的「概念路径」可以概括为：

BluetoothGatt.writeCharacteristic  → GattService（Java）  → BTIF GATT  → BTA GATT  → stack/gatt（ATT Write）  → L2CAP → HCI ACL  → HAL → Controller

新代码更多落在 system/gd/（GD = 新模块化架构）， HCI 收发、部分控制器交互会走这里的 hci/ 与 hal/。 老路径与新路径并存，读代码时以调用栈为准，不要只看目录名。

八、HCI 与 HAL：AIDL 优先，HIDL 兜底

HCI（Host Controller Interface）是蓝牙规范定义的 Host ↔ Controller 边界。 Android 把这条边界做成 HAL：栈只认 HCI 包，不关心芯片怎么初始化、怎么省电。

8.1 AIDL 接口长什么样

hardware/interfaces/bluetooth/aidl/.../IBluetoothHci.aidl

@VintfStabilityinterface IBluetoothHci {    void close();    void initialize(in IBluetoothHciCallbacks callback);    void sendAclData(in byte[] data);    void sendHciCommand(in byte[] command);    void sendIsoData(in byte[] data);    void sendScoData(in byte[] data);}

注释里写得很直白：只处理 HCI 包，可以简化栈，并把电源管理、硬件初始化等细节留给厂商实现。

8.2 Host 如何找到 HAL

system/gd/hal/hci_backend_aidl.cc

static constexpr char kBluetoothAidlHalInterfaceName[] =    ”android.hardware.bluetooth.IBluetoothHci”;std::shared_ptr HciBackend::CreateAidl(        const std::string& hci_instance_name) {  const std::string bluetoothAidlHalServiceName =      std::format(”{}/{}”, kBluetoothAidlHalInterfaceName,                  hci_instance_name.empty() ? ”default” : hci_instance_name);  if (AServiceManager_isDeclared(bluetoothAidlHalServiceName.data())) {    return std::make_shared(bluetoothAidlHalServiceName.data());  }  log::warn(”Bluetooth AIDL HAL service not declared”);  return std::shared_ptr();}

默认服务名是：

android.hardware.bluetooth.IBluetoothHci/default

AidlHci 构造时会 AServiceManager_waitForService， 绑定后注册 Death Recipient——HAL 挂了，Host 会主动崩溃并留日志，避免半残状态继续跑。

void sendHciCommand(const std::vector& command) override {  hci_->sendHciCommand(command);}void sendAclData(const std::vector& packet) override {  hci_->sendAclData(packet);}

若设备未声明 AIDL HCI，栈仍可回退到 HIDL 后端（hci_backend_hidl.cc）。 新平台以 AIDL 为主，HIDL 是兼容路径。

8.3 回调方向：Controller → Host

HAL 通过 IBluetoothHciCallbacks 把事件送回栈： 初始化完成、HCI Event、ACL/SCO/ISO 数据。Host 侧的 AidlHciCallbacks 再转给内部 HciBackendCallbacks。上下行都是「字节向量」，协议解析在栈内完成。

九、安全：SMP 配对模型一览

BLE 安全由 SMP（Security Manager Protocol）负责。AOSP 在 system/stack/smp/smp_int.h 中枚举了关联模型，可读性很好：

typedef enum {  SMP_MODEL_ENCRYPTION_ONLY = 0,      /* Just Works */  SMP_MODEL_PASSKEY = 1,              /* Passkey Entry */  SMP_MODEL_OOB = 2,                  /* OOB */  SMP_MODEL_KEY_NOTIF = 3,            /* Passkey display */  SMP_MODEL_SEC_CONN_JUSTWORKS = 4,   /* LE Secure Connections */  SMP_MODEL_SEC_CONN_NUM_COMP = 5,    /* Numeric Comparison */  SMP_MODEL_SEC_CONN_PASSKEY_ENT = 6,  SMP_MODEL_SEC_CONN_PASSKEY_DISP = 7,  SMP_MODEL_SEC_CONN_OOB = 8,  SMP_MODEL_OUT_OF_RANGE = 9,} tSMP_ASSO_MODEL;

对应用开发者而言，落地建议是：

• 需要防中间人时，避免依赖纯 Just Works。
• 有显示能力的设备优先 Numeric Comparison。
• 有带外通道（NFC / QR / 线缆）时，OOB 往往更稳。
• Bond 信息存在系统侧；清蓝牙缓存、换机、关「保存配对」都会影响重连体验。

十、一条 BLE 会话的生命周期

把生命周期映射回 Android API / 栈，大致是：

十一、工程实践：权限、过滤、调试

11.1 权限与可见性（应用侧清单）

• Android 12+：BLUETOOTH_SCAN / BLUETOOTH_CONNECT / 必要时 BLUETOOTH_ADVERTISE
• 若扫描结果需要定位推导，仍可能涉及位置权限与声明 neverForLocation 等策略
• 前台服务类型、后台启动限制会直接影响「杀进程后能否继续扫/连」

11.2 扫描与连接的实操原则

• 能过滤就过滤：UUID / MAC（注意随机地址）/ Manufacturer Data
• 短窗口高占空比扫描，发现后立刻停扫再连接，避免扫连争用控制器
• 已知地址可尝试直接连接；失败再回退短扫，而不是无限扫
• 写特征前确认连接状态与服务发现完成，避免「假成功」

11.3 调试工具箱（公开能力）

**隐私提醒：**对外分享抓包或日志前，务必脱敏 MAC、设备名、账号、位置与业务载荷。 HCI 日志可能包含可关联到个人的标识信息。

十二、如何继续深入阅读

若你打算系统啃源码，推荐按「问题驱动」而不是「目录遍历」：

1. 从 API 往下追一次完整调用

例如只追 startScan 或只追 writeCharacteristic，直到 HCI。2.对照规范章节

Core Spec 的 HCI / ATT / SMP 章节与 system/stack 目录一一映射。3.分清三份仓库

Bluetooth 模块（Host）、hardware/interfaces（HAL 接口）、vendor HAL（芯片实现，通常不在 AOSP 主线）。4.用 snoop 验证假设

「我以为发了 Write」→ 打开 snoop 看有没有对应 ATT 包，比争论 API 返回值更高效。

写在最后

Android 蓝牙并不神秘：它是一层层把「应用意图」翻译成「HCI 字节」， 再由控制器变成射频上的时间与频率。读懂分层，你才能在连接失败时判断： 是 App 用错了 API、是系统服务策略、是协议栈状态机，还是芯片/固件侧的问题。

本文刻意停在AOSP 公开边界之内——因为真正能公开分享、可复现、可讨论的， 正是这些与具体业务解耦的系统知识。业务协议会变，栈的骨架更长久。

参考与延伸：Android 开源项目 packages/modules/Bluetooth、 platform/hardware/interfaces（bluetooth AIDL）、Bluetooth Core Specification、 Android 开发者文档 Bluetooth / BLE 章节。

文中代码片段基于 AOSP 公开源码整理，为便于阅读做了省略；以对应分支实际文件为准。