1. 系统架构概述

OpenHarmony蓝牙系统采用分层架构设计，基于HDF（Hardware Driver Foundation）驱动框架和系统能力管理（System Ability）机制实现。

1.1 架构层次

┌─────────────────────────────────────────────────────────────┐
│                    应用层 (Application)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   C API     │  │  ArkTS API  │  │  C++ API    │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
├─────────────────────────────────────────────────────────────┤
│                    框架层 (Framework)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │  适配器层    │  │  IPC通信    │  │  接口管理   │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
├─────────────────────────────────────────────────────────────┤
│                    服务层 (Service)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │Host Server  │  │Profile服务  │  │GATT服务     │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
├─────────────────────────────────────────────────────────────┤
│                    驱动层 (Driver)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   HDF驱动   │  │  芯片适配   │  │  协议栈     │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└─────────────────────────────────────────────────────────────┘

1.2 核心组件

1.2.1 蓝牙框架仓库

• 路径: foundation/communication/bluetooth
• 功能: 提供C/C++/JS API接口和框架实现
• 关键模块:
  • frameworks/inner/: 内部框架实现
  • frameworks/c_api/: C语言接口实现
  • frameworks/js/napi/: JS/ArkTS接口实现
  • interfaces/: API接口定义

1.2.2 蓝牙服务仓库

• 路径: foundation/communication/bluetooth_service
• 功能: 系统服务实现，系统能力ID为1130
• 关键配置:
  • sa_profile/1130.json: 系统能力配置
  • services/bluetooth/server/: 服务实现

2. 系统能力管理

2.1 系统能力配置

系统能力ID: 1130 (bluetooth_service)

配置文件: foundation\communication\bluetooth_service\sa_profile\1130.json

{"process": "bluetooth_service","systemability": [{"name": 1130,"libpath": "libbluetooth_server.z.so","run-on-create": true,"distributed": false,"dump_level": 1}]
}

2.2 服务启动流程

1. Init进程解析1130.json配置文件
2. 加载libbluetooth_server.z.so库
3. 创建BluetoothHostServer实例
4. 注册系统能力到SystemAbilityManager

3. 核心接口定义

3.1 C API接口

头文件: foundation\communication\bluetooth\interfaces\c_api\include\oh_bluetooth.h

3.1.1 蓝牙开关状态查询

/*** @brief 获取蓝牙开关状态* @param state 输出参数，返回当前状态* @return 0表示成功，非0表示错误码*/
Bluetooth_ResultCode OH_Bluetooth_GetBluetoothSwitchState(Bluetooth_SwitchState *state);

3.1.2 状态枚举定义

foundation\communication\bluetooth\interfaces\c_api\include\oh_bluetooth.h

typedef enum Bluetooth_SwitchState {BLUETOOTH_STATE_OFF = 0,           // 蓝牙关闭BLUETOOTH_STATE_TURNING_ON = 1,    // 蓝牙开启中BLUETOOTH_STATE_ON = 2,            // 蓝牙已开启BLUETOOTH_STATE_TURNING_OFF = 3,   // 蓝牙关闭中BLUETOOTH_STATE_BLE_TURNING_ON = 4, // BLE模式开启中BLUETOOTH_STATE_BLE_ON = 5,        // BLE模式已开启BLUETOOTH_STATE_BLE_TURNING_OFF = 6  // BLE模式关闭中
} Bluetooth_SwitchState;

3.2 系统服务接口

头文件: foundation\communication\bluetooth_service\services\bluetooth\server\include\bluetooth_host_server.h

3.2.1 核心服务方法

class BluetoothHostServer : public SystemAbility {int32_t EnableBt() override;                    // 启用蓝牙int32_t DisableBt() override;                   // 禁用蓝牙int32_t GetBtState(int32_t &state) override;    // 获取蓝牙状态int32_t EnableBle(bool noAutoConnect = false);  // 启用BLEint32_t DisableBle() override;                  // 禁用BLE
};

4. 实现原理

4.1 蓝牙状态管理

4.1.1 状态转换图

[OFF] → [TURNING_ON] → [ON]↑           ↓
[TURNING_OFF] ← [TURNING_OFF][OFF] → [BLE_TURNING_ON] → [BLE_ON]↑           ↓
[BLE_TURNING_OFF] ← [BLE_TURNING_OFF]

4.1.2 状态同步机制

实现位置: foundation\communication\bluetooth\frameworks\inner\src\bluetooth_host.cpp

// 状态同步实现
void BluetoothHost::impl::BluetoothHostObserverImp::OnStateChanged(int32_t transport, int32_t status) {// 同步随机地址到服务if (status == BTStateID::STATE_TURN_ON) {host_.SyncRandomAddrToService();}// 通知所有观察者host_.observers_.ForEach([transport, status](auto observer) {observer->OnStateChanged(transport, status);});
}

4.2 服务发现机制

4.2.1 SystemAbilityManager交互

init进程可以通过SystemAbilityManager获取蓝牙服务

// 加载蓝牙服务
bool BluetoothHost::impl::LoadBluetoothHostService() {auto samgr = SystemAbilityManagerClient::GetInstance().GetSystemAbilityManager();if (samgr == nullptr) {return false;}// 异步加载系统能力int32_t ret = samgr->LoadSystemAbility(BLUETOOTH_HOST_ABILITY_ID, nullptr);return ret == ERR_OK;
}

4.3 进程间通信(IPC)

4.3.1 IPC接口定义

接口文件: frameworks/inner/ipc/interface/

核心接口:

• IBluetoothHost: 主机服务接口
• IBluetoothGattClient: GATT客户端接口
• IBluetoothGattServer: GATT服务器接口
• IBluetoothBleAdvertiser: BLE广播接口

5. 关键源码路径

5.1 框架实现

5.1.1 主机管理

• 文件: foundation/communication/bluetooth/frameworks/inner/src/bluetooth_host.cpp
• 功能: 蓝牙主机状态管理、服务发现

5.1.2 C API实现

• 文件: foundation/communication/bluetooth/frameworks/c_api/src/oh_bluetooth.cpp
• 功能: C语言接口的具体实现

5.2 服务实现

5.2.1 主机服务

• 文件: foundation/communication/bluetooth_service/services/bluetooth/server/src/bluetooth_host_server.cpp
• 功能: 系统服务的主要实现

5.2.2 Profile服务

• 路径: foundation/communication/bluetooth_service/services/bluetooth/server/src/
• 包含: A2DP, AVRCP, GATT, HID等Profile服务

5.3 配置文件

5.3.1 系统能力配置

• 文件: foundation/communication/bluetooth_service/sa_profile/1130.json
• 功能: 定义蓝牙服务的系统能力参数

5.3.2 构建配置

• 文件: bluetooth/bundle.json
• 功能: 定义组件依赖和构建参数

6. 调试方法

6.1 日志系统

6.1.1 日志标签

• 框架日志: bt_fwk_host
• C API日志: bt_c_api_ohbluetooth
• 服务日志: bluetooth_service

6.1.2 日志查看命令

# 查看蓝牙框架日志
hilog | grep bt_fwk# 查看蓝牙服务日志
hilog | grep bluetooth_service# 查看C API调用日志
hilog | grep bt_c_api

6.2 系统调试

6.2.1 服务状态检查

# 进入设备shell
hdc shell# 在设备shell中执行以下命令：
# 查看蓝牙服务状态
ps -ef | grep bluetooth_service# 查看系统能力
samgr list | grep bluetooth# 查看蓝牙开关状态
param get persist.sys.bluetooth.enable# 查看蓝牙相关日志
hilog | grep bluetooth

6.2.2 配置文件调试

# 检查系统能力配置
hdc shell cat /system/etc/sa_profile/1130.json# 检查服务配置
hdc shell cat /system/etc/init/bluetooth_service.cfg

6.3 开发调试

6.3.1 构建调试版本

# 构建带调试信息的版本
./build.sh --product-name xxx --gn-args="is_debug=true"# 启用蓝牙调试日志
./build.sh --product-name xxx --gn-args="bt_debug_level=3"

6.3.2 运行时调试

# 设置调试参数
hdc shell param set bluetooth.debug.level 3# 重启蓝牙服务
service_control restart bluetooth_service

7. 常见问题与解决

7.1 服务启动失败

• 症状: 蓝牙服务无法启动
• 检查: 查看1130.json配置是否正确
• 解决: 确认libbluetooth_server.z.so存在且权限正确

7.2 状态同步问题

• 症状: 状态显示不一致
• 检查: 查看bt_fwk_host日志
• 解决: 重启bluetooth_service服务

7.3 API调用失败

• 症状: C API返回错误码
• 检查: 确认参数有效性和权限
• 解决: 检查蓝牙服务是否已启动

8. 传统蓝牙设备实现原理

8.1 蓝牙耳机实现原理

8.1.1 系统架构

蓝牙耳机协议栈架构：

┌─────────────────────────────────────────────────────────────┐
│                    应用层 (音乐APP)                         │
├─────────────────────────────────────────────────────────────┤
│                    框架层 (AVRCP)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ 媒体控制    │  │  音量管理   │  │  状态同步   │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
├─────────────────────────────────────────────────────────────┤
│                    服务层 (A2DP/AVRCP)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ A2DP Source │  │ AVRCP CT    │  │ 音频路由    │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
├─────────────────────────────────────────────────────────────┤
│                    协议栈 (蓝牙协议)                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   L2CAP     │  │    AVDTP    │  │   AVCTP     │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└─────────────────────────────────────────────────────────────┘

8.1.2 关键源码文件

A2DP源端实现：

• 文件路径: foundation/communication/bluetooth_service/services/bluetooth/server/src/bluetooth_a2dp_source_server.cpp
• 核心类: BluetoothA2dpSourceServer
• 功能: 音频流传输、编码配置、连接管理

AVRCP控制器实现：

• 文件路径: foundation/communication/bluetooth_service/services/bluetooth/server/src/bluetooth_avrcp_ct_server.cpp
• 核心类: BluetoothAvrcpCtServer
• 功能: 媒体控制、音量调节、状态同步

8.1.3 连接流程

8.1.4 音频编码配置

支持的编码格式：

编码格式	采样率	位深度	通道数
SBC	44.1kHz	16bit	立体声
AAC	48kHz	16bit	立体声
aptX	48kHz	16bit	立体声

配置流程：

// 在bluetooth_a2dp_source_server.cpp中的配置流程
void OnConfigurationChanged(const RawAddress &device, const A2dpSrcCodecInfo &info, int error) {// 处理编解码器配置变更BluetoothA2dpCodecInfo tmpInfo {};tmpInfo.bitsPerSample = info.bitsPerSample;tmpInfo.channelMode = info.channelMode;tmpInfo.codecType = info.codecType;tmpInfo.sampleRate = info.sampleRate;// 通知应用层配置已更新
}

8.2 蓝牙遥控器实现原理

8.2.1 HID协议实现

HID主机实现：

• 文件路径: foundation/communication/bluetooth_service/services/bluetooth/server/src/bluetooth_hid_host_server.cpp
• 核心类: BluetoothHidHostServer
• 功能: HID设备连接、按键事件处理、电池状态监控

8.2.2 遥控器按键映射

标准HID按键码：

功能键	HID码	功能描述
0x01	0x30	电源键
0x02	0x31	音量+
0x03	0x32	音量-
0x04	0x33	频道+
0x05	0x34	频道-
0x06	0x35	静音
0x07	0x36	主页
0x08	0x37	返回

8.2.3 连接和事件处理

8.2.4 低功耗管理

省电模式：

// 在bluetooth_hid_host_server.cpp中的状态管理
void OnConnectionStateChanged(const RawAddress &device, int state) {if (state == BTConnectState::CONNECTED) {// 激活高功耗模式SetPowerMode(HIGH_POWER);} else if (state == BTConnectState::DISCONNECTED) {// 切换到低功耗模式SetPowerMode(LOW_POWER);}
}

8.3 蓝牙音箱实现原理

8.3.1 A2DP接收端实现

A2DP接收端：

• 文件路径: foundation/communication/bluetooth_service/services/bluetooth/server/src/bluetooth_a2dp_sink_server.cpp
• 核心类: BluetoothA2dpSinkServer
• 功能: 音频接收、解码播放、音量控制

8.3.2 音频路由管理

音频路径配置：

手机(A2DP Source) → 蓝牙协议栈 → 音箱(A2DP Sink) → 音频解码 → DAC → 扬声器

8.3.3 音量同步机制

绝对音量控制：

• AVRCP绝对音量: 支持0-100级音量调节
• 本地音量存储: 断电记忆音量设置
• 同步机制: 双向音量状态同步

8.4 设备兼容性分析

8.4.1 设备类型识别

设备类别码(Class of Device):

设备类型	CoD值	主要服务类
耳机	0x200404	Audio
音箱	0x200414	Audio
遥控器	0x002508	HID

8.4.2 能力交换机制

SDP服务发现：

// 服务发现流程
void DiscoverServices(const RawAddress &device) {// 查询A2DP服务DiscoverA2dpService(device);// 查询AVRCP服务DiscoverAvrcpService(device);// 查询HID服务DiscoverHidService(device);
}

8.5 问题诊断与调试

8.5.1 连接问题分析

常见问题排查：

问题现象	可能原因	调试命令
无法发现设备	设备未进入配对模式	hcitool scan
配对失败	PIN码错误或兼容性	bluetooth_manage get_paired_devices
连接断开	信号强度弱或电量低	hilog | grep bluetooth
音频卡顿	带宽不足或干扰	cat /proc/bluetooth/stats

8.5.2 性能优化

音频延迟优化：

1. 缓冲区大小: 调整为最小延迟模式
2. 编解码器: 优先选择低延迟编解码器
3. 连接参数: 优化连接间隔和超时

功耗优化：

1. 扫描间隔: 降低非连接时的扫描频率
2. 连接参数: 调整连接间隔平衡功耗和响应
3. 深度睡眠: 支持空闲时的深度睡眠模式

8.5.3 调试工具

专用调试命令：

# 查看A2DP连接状态
hdc shell bluetooth_manage get_a2dp_connections# 查看AVRCP能力
hdc shell bluetooth_manage get_avrcp_capabilities# 查看HID设备列表
hdc shell bluetooth_manage get_hid_devices# 查看音频路由状态
hdc shell cat /sys/class/bluetooth/hci0/audio_state# 实时监控蓝牙数据
hdc shell hcidump -w /data/bluetooth.log

8.6 实际配置示例

8.6.1 蓝牙耳机配置

配置文件路径: /vendor/etc/bluetooth/audio_policy.conf

<audio_policy><a2dp_sink><supported_codecs><sbc bitrate="328000" sampling="44100" channels="2"/><aac bitrate="320000" sampling="48000" channels="2"/></supported_codecs></a2dp_sink>
</audio_policy>

8.6.2 遥控器按键映射

HID描述符配置:

// 标准遥控器HID描述符
static const uint8_t remote_hid_descriptor[] = {0x05, 0x01,        // Usage Page (Generic Desktop)0x09, 0x05,        // Usage (Game Pad)0xa1, 0x01,        // Collection (Application)0x85, 0x01,        // Report ID (1)0x05, 0x09,        // Usage Page (Button)0x19, 0x01,        // Usage Minimum (Button 1)0x29, 0x20,        // Usage Maximum (Button 32)0x15, 0x00,        // Logical Minimum (0)0x25, 0x01,        // Logical Maximum (1)0x75, 0x01,        // Report Size (1)0x95, 0x20,        // Report Count (32)0x81, 0x02,        // Input (Data, Variable, Absolute)0xc0               // End Collection
};

openharmony蓝牙开发常见问题分析

1. 蓝牙服务启动失败 / 反复重启

现象

• system log 中不断出现 bluetooth_service 崩溃或 Service stopped (2900001)。
• 设置界面点击“打开蓝牙”无响应或立即回弹。

根因

• 进程 bluetooth_service 中的线程 OS_IPC_10_25363 因 libbluetooth_server.z.so 触发 cppcrash。
• init 配置未正确拉起服务或 SELinux 权限拒绝。

解决办法

• 临时规避：在 shell 执行 start bluetooth_service 强制拉起；若仍失败，重启设备可恢复。

2. 反复开关蓝牙导致内存泄漏

现象

• 连续开关蓝牙 20 次以上，系统内存上涨 15 MB～180 MB 不等；settings 应用出现 appfreeze。
• 设备长时间运行后出现 OOM，蓝牙功能不可用。

根因

• 蓝牙适配层未释放 bt_hci、bt_core 相关句柄。

解决办法

• 临时：重启设备即可恢复。
• 永久：
  1. 将 libbluetooth_server.z.so 更新到补丁中。
  2. 如使用外置蓝牙芯片，改用芯片自带协议栈，减少 OpenHarmony host 栈资源占用 。

---

3. BLE 扫描失败，错误码 2900099 / Fails to start scan

现象

• 调用 startBLEScan 返回 Operation failed 或 Fails to start scan as it is out of hardware resources.

根因

• 硬件扫描通道被占满（其他应用/系统组件未释放）。
• 权限不足：缺少 ohos.permission.DISCOVER_BLUETOOTH 或 ohos.permission.LOCATION。

解决办法

1. 检查并动态申请权限：

   abilityAccessCtrl.requestPermissionsFromUser(['ohos.permission.DISCOVER_BLUETOOTH', 'ohos.permission.LOCATION'])
   

2. 扫描前先调用 stopBLEScan() 释放通道；必要时重启蓝牙服务：

   stop bluetooth_service && start bluetooth_service
   

3. 若仍失败，查看 /var/log/hilog 是否有 hardware resource busy，重启设备即可恢复 。

---

4. GATT 特征值读写失败，错误码 2900005 / 2900008

现象

• 已连接设备，调用 readCharacteristicValue / writeCharacteristicValue 返回 Device not connected 或 Proxy is nullptr。

根因

• 对端设备异常断开，但本地 proxy 对象未及时清理。
• 应用在前一次异步操作未完成时又发起下一次操作，导致状态错乱。

解决办法

1. 每次读写前判断 connectionState === 'STATE_CONNECTED'。
2. 等待上一次操作的 callback / promise 返回后再执行下一次读写。
3. 出现 Proxy is nullptr 时，主动断开连接并重新执行配对流程 。

---

5. 打开蓝牙后设置界面卡死（appfreeze）

现象

• 进入设置 → 蓝牙，UI 假死 6 s 以上，系统提示 THREAD_BLOCK_6S。

根因

• systemui 进程在 libsamgr_proxy.z.so 中发生线程阻塞。

解决办法

• 临时：下拉状态栏 → 关闭再打开蓝牙，或重启设备。
• 永久：升级至 4.1.2 之后版本，官方已合入修复补丁 。

---

6. 蓝牙固件/串口适配失败

现象

• 系统启动后 bluetooth_service 不停重启，dmesg 出现 ttyS* probe fail 或 bt_firmware not found。

根因

• init.<board>.cfg 中串口节点与原理图不一致；
• vendor/<vendor>/<board>/bluetooth/ 下固件名或路径错误；
• BUILD.gn 中 p_name 与 hardware.c 不匹配。

解决办法

1. 对照原理图确认 UART 管脚，修改：

   device/<vendor>/<board>/cfg/init.<board>.cfg
   

   确保串口拥有者为 blue_host。
2. 核对固件文件名：

   vendor/<vendor>/<board>/bluetooth/BUILD.gn
   

   与

   vendor/<vendor>/<board>/bluetooth/src/hardware.c
   

   中 p_name 完全一致 。
3. 确认 ohos.build 中已包含 bluetooth 部件：

   "parts": { "bluetooth": { "module": "//bluetooth/..." } }
   

---

快速排查清单（Checklist）

检查点	命令/路径	预期结果
服务是否运行	`ps -ef	grep bluetooth_service`
串口是否匹配	`dmesg	grep tty`
固件是否存在	ls /vendor/firmware/*.bin	存在对应芯片固件
权限是否授予	aa check -p ohos.permission.DISCOVER_BLUETOOTH	granted
日志是否有 crash	`hilog	grep bluetooth_service`