# 徐工项目蓝牙模块流程概览

> 整理目的：帮助快速理解蓝牙模块架构和核心流程

---

## 一、整体架构

### 1.1 模块组成

| 模块 | 说明 |
|------|------|
| **YX_BlueTooth** | 上层应用，蓝牙电话、音乐界面 |
| **YX_BluetoothSDK** | SDK模块，封装蓝牙协议 |
| **Frameworks中间件** | android.bluetooth API |
| **系统蓝牙应用** | packages/apps/Bluetooth/ |
| **蓝牙协议栈** | system/bt，底层协议实现 |
| **第三方SDK** | 顾凯芯片商提供 |

### 1.2 调用层级（从上到下）

```
┌─────────────────────────────────────────────────────────┐
│  YX_Bluetooth (上层应用)                                  │
│     ↓ android.bluetooth API                              │
│  Frameworks中间件                                         │
│     ↓ Binder IPC                                         │
│  Bluetooth Process (系统蓝牙应用)                          │
│     ↓ JNI                                                │
│  蓝牙协议栈 (system/bt)                                   │
│     ↓ HIDL                                               │
│  供应商实现 (顾凯SDK)                                      │
│     ↓ HCI                                                │
│  蓝牙芯片                                                 │
└─────────────────────────────────────────────────────────┘
```

---

## 二、蓝牙电话流程

### 2.1 电话状态（7种）

| 状态值 | 名称 | 说明 |
|--------|------|------|
| 0 | ACTIVE | 通话中 |
| 1 | HELD | 保持中 |
| 2 | DIALING | 正在拨号 |
| 3 | ALERTING | 正在响铃 |
| 4 | INCOMING | 正在来电 |
| 5 | WAITING | 等待中 |
| 7 | TERMINATED | 已挂断 |

### 2.2 状态变化图

```
          来电                        拨号
    ┌─────────→ INCOMING ─────────→ DIALING
    │              │                  │
    │          接听来电            对方接通
    │              ↓                  ↓
IDLE ─────────── ACTIVE ───────────────┘
    │              │
    │            挂断
    │              ↓
    └─────── TERMINATED
```

### 2.3 拨号调用流程

```
BluetoothHfpClient.dial()          ← 上层应用入口
    ↓
BluetoothHeadsetClient.dial()      ← Frameworks API
    ↓ Binder
BluetoothHeadsetClientBinder.dial()
    ↓
HeadsetClientService.dial()        ← 系统蓝牙服务(中转)
    ↓
HeadsetClientStateMachine.Connected.dial()
    ↓
NativeInterface.dial()             ← JNI接口
    ↓
com_android_bluetooth_hfpclient.dialNative()
    ↓
第三方SDK → 蓝牙芯片
```

### 2.4 数据回调流程（反向）

```
蓝牙芯片 → 第三方SDK
    ↓ JNI回调
NativeInterface (事件上报)
    ↓
HeadsetClientService (中转分发)
    ↓ Event.type判断
HeadsetClientStateMachine (业务处理)
    ↓ 广播
上层应用 BroadcastReceiver
```

---

## 三、蓝牙音乐流程

### 3.1 核心功能

| 功能 | 说明 |
|------|------|
| 播放控制 | 播放/暂停/上一曲/下一曲 |
| 音频焦点 | 与语音、导航、视频竞争焦点 |
| 状态同步 | 播放状态同步给Launcher/投屏 |
| 方控控制 | 方向盘按键控制音乐 |

### 3.2 焦点竞争场景

| 场景 | 处理 |
|------|------|
| 语音唤醒 | 蓝牙音乐暂停，释放焦点 |
| 导航播报 | 蓝牙音乐降低音量/暂停 |
| 视频播放 | 蓝牙音乐暂停 |
| 倒车状态 | 蓝牙音乐暂停 |

---

## 四、通讯录同步流程

### 4.1 核心协议

| 协议 | 说明 |
|------|------|
| **PBAP** | Phone Book Access Profile，通讯录访问协议 |
| **HFP** | Hands-Free Profile，电话免提协议 |

### 4.2 同步限制

| 类型 | 限制 |
|------|------|
| 通讯录 | 2500条，超出截断 |
| 通话记录 | 50条 |

### 4.3 同步流程

```
1. 连接蓝牙 → 触发PBAP连接请求
2. 手机授权 → 开始拉取通讯录
3. 分批接收 → 存入数据库
4. 完成回调 → isPhoneBookPulling=false
5. UI刷新 → 显示通讯录列表
```

### 4.4 核心类

| 类名 | 作用 |
|------|------|
| BluetoothPbapClient | PBAP协议入口 |
| BtContactsManager | 通讯录管理 |
| isPhoneBookPulling | 同步状态标志 |

---

## 五、语音与蓝牙交互

### 5.1 语音控制蓝牙功能

| 功能 | 入口类 |
|------|------|
| 语音拨打电话 | VoiceEventHelper |
| 语音拒接来电 | VoiceEventHelper |
| 语音播放蓝牙音乐 | MediaProtocol |
| 语音同步通讯录状态 | VoiceNewProtocolConst |

### 5.2 状态同步给语音

| 状态 | 同步方式 |
|------|----------|
| 蓝牙连接状态 | 广播通知语音 |
| 来电状态 | 电话信息同步 |
| 通讯录同步状态 | 页面打开/关闭状态 |

---

## 六、ACC电源处理

### 6.1 处理策略

| 场景 | 处理 |
|------|------|
| ACC OFF | 不主动断开蓝牙，保持原状态 |
| ACC ON | 恢复连接状态，校验播放状态 |
| 下电上电 | 播放按钮状态需重新同步 |

### 6.2 常见问题

| 问题 | 原因 | 解决 |
|------|------|------|
| 上电后显示播放但实际没播 | 状态未校验 | 检查实际播放状态 |
| 进蓝牙音乐界面会暂停 | 状态未同步 | 延迟校验播放状态 |

---

## 七、核心代码类索引

### 7.1 电话相关

| 类名                        | 路径           | 作用     |
| ------------------------- | ------------ | ------ |
| BluetoothHfpClient        | YX_Bluetooth | 电话功能入口 |
| HeadsetClientService      | 系统应用         | 电话服务中转 |
| HeadsetClientStateMachine | 系统应用         | 电话状态机  |

### 7.2 音乐相关

| 类名     | 作用                |
| ------ | ----------------- |
| 音频焦点管理 | AudioManager，焦点竞争 |
| 投屏数据格式 | JSON格式传输给仪表       |

### 7.3 语音交互

| 类名                    | 作用          |
| --------------------- | ----------- |
| VoiceEventHelper      | 语音事件处理入口    |
| MediaProtocol         | 媒体协议，蓝牙音乐状态 |
| VoiceNewProtocolConst | TXZ语音协议常量   |

---

## 八、常见问题快速定位

| 问题类型 | 关键类/方法 | 日志关键字 |
|----------|-------------|------------|
| 通讯录不同步 | BluetoothPbapClient.phoneBookPullRequest() | BtContactsManager, onContactsPullCompleted |
| 音乐状态异常 | 音频焦点处理 | AudioManager, onFocusChange |
| 语音拒接失败 | VoiceEventHelper拒接逻辑 | 蓝牙拒接, HFP |
| ACC状态处理 | 电源状态监听 | ACC_OFF, ACC_ON |
| 投屏数据异常 | JSON数据传输 | 投屏, DataCenter |
| ANR问题 | 主线程阻塞 | ANR, SQLiteCursor |

---

## 九、开发注意事项

### 9.1 通讯录同步

- 完成后必须设置 `isPhoneBookPulling = false`
- 同步过程需异步处理，避免阻塞UI
- 通讯录超过2500条会截断

### 9.2 音频焦点

- 语音唤醒时蓝牙音乐必须释放焦点
- 导航播报后需恢复播放状态
- 倒车暂停需在倒车结束后恢复

### 9.3 ACC电源

- 不要在ACC OFF时主动断开蓝牙
- 上电后需校验实际播放状态，避免状态不同步

### 9.4 UI适配

- 深色模式：联系人字母颜色需适配
- 右舵项目：需单独布局资源
- 12.3寸屏幕：需单独适配

---

## 十、参考文档

| 文档 | 说明 |
|------|------|
| [[蓝牙框架原理以及数据通讯交互流程.pdf]] | 蓝牙框架层级详解 |
| [[蓝牙电话交互流程解析.pdf]] | 电话状态和调用流程 |
| [[徐工项目蓝牙模块主流程.xlsx]] | 主流程表格 |
| [[徐工项目蓝牙模块交接说明.docx]] | 交接说明文档 |
| [[bluetooth_git_summary.md]] | Git提交记录汇总 |

---

## 十一、Git提交统计

> 统计时间: 2024-01-01 ~ 2026-05-06
> 提交总数: 230条

| 功能模块 | 提交数 | 主要内容 |
|----------|--------|----------|
| 语音与蓝牙交互 | 35条 | 语音控制、状态同步、音频焦点 |
| 蓝牙音乐 | 25条 | 播放状态、投屏、焦点控制 |
| 蓝牙电话 | 40条 | 来电/去电、通话状态、投屏 |
| 通讯录同步 | 30条 | 同步流程、UI交互 |
| 连接状态管理 | 20条 | ACC处理、可见性、配对 |
| UI适配 | 35条 | 深色模式、右舵、国际化 |
| 国际化 | 15条 | 翻译、多语言 |
| 代码优化 | 15条 | 工具类统一、构建优化 |
| Bug修复 | 15条 | ANR、崩溃、空指针 |